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. 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:

Before you begin

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.

If you want to use syntxt.ism from a directory other than DBLDIR, set the SYNTXT environment variable to the desired directory.

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 specifiers are replaced when the message is generated. 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.

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. Run Synergy UI Toolkit Control Panel as follows:

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

To modify one message at a time,

1. Print a list of messages as instructed in Before you begin.
2. From the Text messages menu, select Interactive mode.
3. At the Message Library prompt, enter the name of your text message library. (Synergy/DE messages are in DBLDIR:syntxt, which is the default.)
4. From the Interactive menu, select 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 in 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 Unload messages from the Text messages menu.
2. From the Unloads menu, select 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.
4. Using your favorite text editor (for example, Wordpad on Windows), 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 ever modify information in the first 18 bytes of the record.

2. Unloading messages.

5. In Synergy UI Toolkit Control Panel, select Remove messages from the Text messages menu to clear messages from the ­syntxt.ism file.
6. Enter the desired information in each input field in the displayed dialog box, and press enter to remove the messages.
7. To load syntxt.ism from your modified sequential ASCII file, select Load messages from the Text messages menu.
8. From the Loads menu, select Sequential file.
9. Enter the desired information in each input field in the displayed dialog box, and press enter to load the messages.
Note

Your distribution includes the dtktxt.ddf, protxt.ddf, wdtxt.ddf, rpstxt.ddf, rpttxt.ddf, and rdltxt.ddf files, which contain the unloaded Toolkit, Proto, Repository, ReportWriter, and Report Definition Language text messages, respectively. If your syntxt.ism file becomes corrupted, follow step 4 using these .ddf files as your sequential input 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 Create new library from the Text messages menu.
2. At the Message Library prompt, enter the name of the library file you’d like to create, 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 commands or by loading an existing sequential file using the Load messages command.
4. Generate your message definitions to a definition file by selecting Generate defines from the Text messages menu.

A dialog box is displayed. 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. For the subroutine syntax, see U_GETTXT.

3. Generating definitions to an include file.

Modifying messages at the command line

You can modify messages at the command line without invoking the Synergy UI Toolkit Control Panel’s menu interface 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, which is analogous to UNIX’s PATH.

Arguments

option

(optional) One or more of the following command line options:

‑?

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.

On OpenVMS, Synergy DBL does not use the Synergy UI Toolkit Control Panel directly, and the syntxt.ism file distributed with Synergy DBL does not have the linker and librarian errors loaded into it. As a result, when customizing those messages on OpenVMS, you must perform a few extra steps before your changes are reflected. Enter the following at the command line:

$ 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

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.