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:
- Edit the messages interactively using the Synergy UI Toolkit Control Panel’s “Interactive mode.” This procedure is recommended for minor changes. See Making minor changes: Editing messages interactively.
- Unload the messages to an ASCII file, edit them, and then reload them to an ISAM file. This procedure is recommended for major changes and translating messages to another language. See Making major changes: Unloading messages to an ASCII file.
- Use the Synergy UI Toolkit Control Panel’s command line interface; see Modifying messages at the command line.
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 |
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
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. |
When customizing error and informational messages:
|
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.
|
5. | Display the message you want to change in any of the following ways: |
- Use the Find, Last, Prev, and Next entries in the Search menu.
- Enter the facility (category) code from the table below in the Facility Name field, and then press the Find shortcut (ctrl+f). Press F3 or F2 to page forwards or backwards through the messages until you find the one you want to change.
UI Toolkit
DTK
Proto
PRO
Composer
CPS
Repository
RPS
ReportWriter
RPT
Report Definition Language
RDL
Compiler
CMP
Linker
LNK
Librarian
LBR
Runtime
RNT
- Look up the number of the message you want to modify on your printout of messages. Enter the message facility code in the Facility Name field and its number in the Message Number field, and press ctrl+f.
- Look up the mnemonic of the message you want to modify on your printout of messages. Enter the name of the message facility code in the Facility Name field, 0 in the Message Number field, and the desired search string in the Mnemonic field. Then press ctrl+f.
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.) |
|
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. |
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. |
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.
|
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.
(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:
- .ism (message libraries)
- .ddf (sequential files)
- .h (C header files)
- .def (Synergy DBL definition files)
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.