Translating Strings in Memory Files

One of the problems with porting an application from one machine or operating system to another is the difference in what key or keys the user has to press to achieve the same task. For instance, you may specify that pressing F5 will print the contents of a window when the user is using the IBM PC. However, the VT100 does not have more than four function keys and the user must press Esc 5 to do the same thing. The Wyse 50 terminal may have a different keystroke sequence to use. These differences make it necessary to write help text for each operating system and for each terminal type that the program will run on. Maintaining several help files can be time consuming and prone to errors.

To help solve this problem, Vermont Views provides a string translation facility for memory files. This facility was particularly designed to translate the generic name of a key, say PRT_WN, to the proper key for the current operating environment. Thus, a help string that says "Press <<PRT_WN>> to print the contents of the window." could be translated to "Press <F5> to print the contents of the window." when running under PCDOS; "Press <Esc><5> to print the contents of the window." when running under VMS using a VT100; and "Press <Ctrl-P> to print the contents of the window." when running under VMS using a VT220. To assist you in determining the keystroke sequences for the current system, you can use key_getlabel(), which returns a string that shows the sequence of keys needed to generate a certain keycode based on the vvtermcap entry for the terminal in use.

With string translation, you can create one generic help file, with each difference marked out. In your program, you would create a translation table for use based on the operating environment the program is running under. After you read the help file into a memory file, you can translate each marked substitution based on the translation table.

The following explanation details, step-by-step, how to use the string translation facility. Translating generic key names to keys is used in the examples. You may find other uses for this utility.

Step 1: Write the text file, marking the strings to be translated.

Strings that are to be translated should be between the two translation delimiter strings. The default beginning delimiter is two left-angled brackets "<<" and the ending delimiter is two right-angled brackets ">>". You can change these defaults with the set translation delimiter function, se_trdelim():

void se_trdelim(beg_stp, end_stp)

UCHAR *beg_stp;

/* Beginning translation delimiter

*/

UCHAR *end_stp;

/* Ending translation delimiter

*/

You can specify one or more characters as the delimiters.

The string translation utility cannot replace the string to be translated with a longer string. For this reason, the number of characters in the string to be replaced plus the number of characters in the delimiters should be at least as long as its longest replacement string. If the replacement string is shorter, the extra blanks will be deleted and the line in the memory file closed up. Some examples follow:

If "H" is mapped to "<Esc>P", then:

Press <<H>> for help.

is translated to:

The "P" is truncated in the translation because <<H>> has 5 characters and <Esc>P has 6. To prevent this, use "HELP" instead of "H" as the string to be translated. Thus:

Press <<HELP>> for help.

is translated to:

Press <Esc>P for help.

The extra 2 spaces are deleted.

Step 2: Create a string translation table.

To translate strings in a memory file, you must first allocate and initialize a string translation table. This should be done before you need to do any translation. It can be done before or after you create a memory file to be translated. The string translation table is a two-dimensional array. Each row of the array contains pointers to strings. The first column (column 0) of the string translation table contains a list of the strings that you want translated. The second column (column 1) contains what you want these strings translated to. You would initialize the contents of the second column based on the operating system and/or terminal type in use.

To allocate and initialize a blank string translation table, use trt_def():

UCHAR *(*) trt_def(size)[ ][2]

int size;        /* Number of entries to allow in table        */

trt_def() returns a pointer to a two-dimensional array of pointers to UCHAR variables. trt_def() creates a table with the specified number of entries plus one extra entry for the end-of-table marker. An end of table marker is installed and all other entries in the table are cleared.

To fill the entries in the table, use the translation table replace string function, trt_rplst():

UCHAR *trt_rplst(old_stp, new_stp, trtp)

UCHAR *old_stp;

/* String in memory file to translate

*/

UCHAR *new_stp;

/* String to place in memory file

*/

UCHAR *(*trtp)[][2];

/* Translation table to operate on    

*/

The source of the strings can be a memory file created specifically for use with the current operating environment.

For example, the following reads in two text files into two separate memory files. The first text file contains the list of strings to be substituted for. The second contains the replacement strings specific to the VT100 terminal. (The second text file could be done with conditional code, reading in the file appropriate for the terminal type the machine is running on.) Then, a translation table is created based on the information is these memory files.

MFILEPTR gen_mfp, sub_mfp;

UCHAR *old_stp, *new_stp;

UCHAR *trtp[][2];

int i = 0;

...

...

gen_mfp = mf_def(3, 80);

mf_rd("generic_names", gen_mfp);

sub_mfp = mf_def(3, 80);

mf_rd("vt100_subs", sub_mfp);

trtp = trt_def(3);

for (i = 0; i < 3; i++)  

{

    old_stp = mf_rowp(i, gen_mfp);

    new_stp = mf_rowp(i, sub_mfp);

    trt_rplst(old_stp, new_stp, trtp);

}

...

...

Step 3: Read in the text file to a memory file.

You need to define a memory file and fill it with contents from the text file before doing translations. Translations are done only on the part of the memory file existing in memory. If you are using automatic or manual loading of keyworded sections, you will have to make sure you translate the sections as you need them, since sections that are not currently in memory are not translated, and the translations are lost each time a section is unloaded from memory.

Step 4: Translate the memory file.

Now that you have a string translation table and a memory file to translate, you are ready to translate the memory file with the translate memory file function, tr_mf():

int tr_mf(mfp, trtp)

MFILEPTR mfp;

/* Memory file to translate

*/

UCHAR *(*trtp)[ ][2];

/* Translation table to use

*/

tr_mf() goes through each line in the memory file searching for the translation delimiters. When the delimiters are found, the first column in the translation table is searched for a match with the string between the delimiters. If a match is found, the appropriate string is substituted in place of the original string. If the string substituted in is shorter than the string it replaces, including delimiters, the extra characters are deleted.

Step 5: Free the translation table.

You can free the translation table when you are done translating the necessary memory files with the translation table free function, trt_free():

void trt_free(trtp)

UCHAR *(*trtp)[ ][2];    /* String translation table to free            */

More:

Translating One String

Modifying the Translation Table