Synergy UI Toolkit Control Panel (synctl)

WTSupported in traditional Synergy on Windows

 
USupported on UNIX
VSupported on OpenVMS

The Synergy UI Toolkit Control Panel enables you to translate or otherwise modify message text in Synergy/DE products and any Synergy application that uses UI Toolkit. All Synergy/DE error and screen messages (including the information line and application titles) reside in the file syntxt.ism. The only error message that is hard-coded into the Synergy/DE system is the “No message file found” message, for obvious reasons.

You can modify messages in one of three ways:

Running the Synergy UI Toolkit Control Panel

On

Do this

Windows

From the Windows Control Panel, select Synergy Control Panel > Synergy UI Toolkit Control Panel or go to a command prompt and type dbr DBLDIR:synctl

UNIX

Type dbr DBLDIR:synctl

OpenVMS

Type run DBLDIR:synctl

 

Important

On OpenVMS, although a syntxt.ism file is distributed with the product, the compiler and runtime do not read that file directly; rather, they read messages from the SYS$MESSAGE:DBLMF.EXE shared image. Consequently, after modifying messages (whether from the UI or the command line) you must rebuild DBLMF.EXE to reflect your changes. To do this, execute the following commands:

$ synctl:==$dbldir:synctl.exe
$ synctl -g all_errors.msg -v DBLDIR:syntxt.ism
$ message/nosymbols/obj=all_errors.obj all_errors.msg
$ link/shareable=sys$message:dblmf.exe all_errors.obj
$ install replace sys$message:dblmf/open/header/share

Note that on OpenVMS, the linker and librarian messages are not included in syntxt.ism since the dblink and dblibr commands are not supported on OpenVMS.

Before you begin

Note

On Windows, the syntxt.ism file resides in DBLDIR by default, which is in the Program Files (or Program Files (x86)) directory tree. Consequently, you cannot write to the file unless you have administrator privileges. When attempting to access this file in the Synergy UI Toolkit Control Panel, you’ll see the message “File DBLDIR:syntxt is read-only.” To avoid this error, you can either run the utility as an administrator (not recommended) or move the syntxt.ism and syntxt.is1 files temporarily to a writable location and set the SYNTXT environment variable to point to that directory.

On UNIX and OpenVMS, set SYNTXT if you want to use syntxt.ism from a directory other than DBLDIR.

Before using the Synergy UI Toolkit Control Panel to change Synergy messages, make a copy of the syntxt.ism and syntxt.is1 files.

We also recommend that you print a list of the messages in syntxt.ism before you translate or modify anything, so you’ll have a reference of what you’re changing. To do so,

1. Follow steps 1 through 3 in Making major changes: Unloading messages to an ASCII file.
2. Print the file that is created.
Important

When customizing error and informational messages:

  • Do not remove any Synergy messages.
  • Be careful when changing messages that contain “%” followed by one or two characters (for example, c, d, ld, s, or u). These are specifiers that are replaced when the message is generated. (For example, %s is replaced with an alpha string.) If you plan to change any of these messages, do not remove the “%” specifier. If there is more than one specifier, the order of the specifiers is fixed and cannot be changed.
3. (optional for Windows) Set the DTKRND and/or DTKRNDFIL environment variables to writable locations outside of Program Files if you want to change renditions (Preferences > Renditions). Otherwise, you’ll get an “Unable to update rendition file: dtkrnd Renditions file is read-only” error.

Making minor changes: Editing messages interactively

For small changes, you can use the Modify messages function of the Synergy UI Toolkit Control Panel to interactively modify the text message file syntxt.ism.

To modify one message at a time,

1. Print a list of messages as instructed in Before you begin.
2. Select Text messages > Interactive mode.
3. At the Message Library prompt, enter the name of your text message library. (The default location for Synergy/DE messages is DBLDIR:syntxt.) Press Enter.
4. Select Interactive > Modify messages. (You can also add a new message or delete a message by selecting Insert messages or Delete messages.)

A dialog box is displayed. See figure 1.

1. Modifying text messages.

5. Display the message you want to change in any of the following ways:
6. Make your changes to the message that’s displayed in the Message Text field, and press Enter.

Making major changes: Unloading messages to an ASCII file

If you are making major changes or translating text into another language, you can make your changes by unloading syntxt.ism to a sequential ASCII file, modifying the file, and then reloading it to an ISAM file.

1. In Synergy UI Toolkit Control Panel, select Text messages > Unload messages.
2. Select Unloads > Sequential file. (If you’re unloading Synergy DBL messages—Compiler, Linker, Librarian, or Runtime—select C header file from the Unloads menu.) A dialog box is displayed. See figure 2.
3. Enter the desired information in each input field and press Enter to unload the messages. (The Prefix String and Define Format fields are not used in this procedure.)

2. Unloading messages.

4. Using your favorite text editor, open the data file that’s created and modify the messages you want changed. Make sure you save the file as a text file.
Important

Don’t modify the information in the first 18 bytes of each record.
5. In Synergy UI Toolkit Control Panel, select Text messages > Remove messages. (You must clear the existing messages from ­syntxt.ism before reloading the modified messages.)
6. In the Message Library field, enter the name of the text message library to clear. If you are modifying messages for a specific facility, select Yes and then enter the facility code in the Facility Name field. Press Enter to remove the messages.
7. To load you modified messages into syntxt.ism, select Text messages > Load messages.
8. Select Loads > Sequential file.
9. Specify the message library file to load messages into and your modified data file. If you are modifying messages for a specific facility, select Yes and then enter the facility code in the Facility Name field. Press Enter to load the messages.
Note

Your distribution includes the files dtktxt.ddf, protxt.ddf, rpstxt.ddf, rpttxt.ddf, and rdltxt.ddf, which contain the unloaded Toolkit, Proto, Repository, ReportWriter, and Report Definition Language text messages, respectively. If your syntxt.ism file becomes corrupted, you can use the above procedure to reload messages from these files.

Creating your own text message files

If you want to create new messages, you can either add your messages to syntxt.ism or you can create a new message library. To create and use your own text message library,

1. In Synergy UI Toolkit Control Panel, select Text messages > Create new library.
2. At the Message Library prompt, enter a name for your library file, and press Enter. The default extension is .ism.
3. Add messages to your new library either by inserting them interactively using the Interactive mode and Insert messages option, or by loading an existing sequential file using the Load messages command.
4. Generate your message definitions to a definition file by selecting Text messages > Generate defines.

Complete the fields in the dialog box that displays. See figure 3.

3. Generating definitions to an include file.

5. .INCLUDE the definition file in your application.

You can use the U_GETTXT subroutine to retrieve lines of text from the text message library.

Modifying messages at the command line

You can modify messages at the command line by running synctl and specifying one or more options. For example, on Windows and UNIX, you’d enter

dbr DBLDIR:synctl [option ...]

On OpenVMS, add DBLDIR: to your DCL$PATH search list logical.

Options

(optional) One or more of the following:

-?

Display a help screen of valid command line options.

-a file

Append unloaded messages or generated definitions to the end of an existing sequential or C header file, where file is the name of the existing output file. If specified, this option must precede the specification of the output file.

-c library

Create a message library, where library is the name of the library you want to create.

-d library [-f facility]

Delete records in a message library, where library is the name of the library from which you are deleting records and facility is an optional code for the category of messages you are deleting.

-l library seq_file [-f facility]

Load the message library from a sequential file, where library is the name of the library to which you are loading messages, seq_file is the name of the sequential file from which the messages are being loaded, and facility is an optional code for the category of messages you are modifying.

-l library -h header_file [-f facility]

Load the message library from a C header file, where library is the name of the library to which you are loading messages, header_file is the name of the C header file from which messages are being loaded, and facility is an optional code for the category of messages you are modifying.

-u library seq_file [-f facility]

Unload messages from a library to a sequential file, here library is the name of the library from which you are unloading messages, seq_file is the name of the sequential file to which you are unloading messages, and facility is an optional code for the category of messages you are modifying.

-u library -h header_file [-f facility]

Unload messages from a library to a C header file, where library is the name of the library from which you are unloading messages, header_file is the name of the C language header file to which you are unloading messages, and facility is an optional code for the category of messages you are modifying.

-g library definition_file [-f facility] [-p prefix]

Generate a Synergy DBL definition file, where library is the name of the library from which the message definitions are being extracted, definition_file is the name of the Synergy DBL definition file you are generating, facility is an optional code for the category of messages you are modifying, and prefix is an optional prefix for the message mnemonic in the definition file.

-g library -h header_file [-f facility] [-p prefix]

Generate a C header file, where library is the name of the library from which messages are being extracted, header_file is the name of the C header file you are generating, facility is an optional code for the category of messages you are modifying, and prefix is an optional prefix for the message mnemonic in the header file.

Discussion

The default filename extensions for the different types of files specified above are as follows:

The facility names for Synergy messages are listed in the Facility Codes table above.

Examples

The following example unloads the runtime messages from the Synergy message library, syntxt.ism, into a sequential file named mymsg.ddf.

dbr synctl -u DBLDIR:syntxt mymsg -f RNT

The next example creates a message library named mytxt.ism, loads it with messages from the sequential file mytxt.ddf, and generates the definition file mymsg.def. It specifies the facility DTK and the prefix DTK_.

dbr synctl -c mytxt -l mytxt mytxt -g mytxt mymsg -f DTK -p DTK_

When combining operations as in this example, all the arguments for each option must be respecified, or the default values are used. By default, all facilities are used, and no prefix is used.