____________________________________________________ DECforms Run-Time Message Translation July 1989 This document describes how to translate DECforms run-time messages for local language support. Operating System: VMS 5.1 Software Version: DECforms V1.1 ________________________________________________________________ © Digital Equipment Corporation 1989. All Rights Reserved. ACMS ULTRIX VAX DATATRIEVE DEC VMScluster VAXcluster DEC/CMS VAX FMS DEC/MMS DECforms VMS DECintact VT DECnet RSTS ReGIS Work Processor DECUS DIBOL DIGITAL TDMS This document was prepared using VAX DOCUMENT, Version 2.1. 1 DECforms Modifiable Run-Time Message Procedure The following instructions describe the use of the message procedure to modify message files for DECforms V1.1. This procedure is used to create the non-executable message file used by the DECforms Form Manager. The SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES] directory contains the DECforms Form Manager message source files. The following steps are required to modify the DECforms message files: 1. Edit and modify the message source file. 2. Build the modified DECforms message file. 3. Put the new message file in SYS$COMMON:[SYSMSG]. The procedure to rebuild the message files supplied in the directory SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES] parallels the procedures used in the DECforms V1.1 kit. Altering the procedures supplied in this directory may cause unpredictable results. 2 Prerequisites If modifications to the DECforms run-time messages are required, you must answer "YES" to the question, "Do you wish to install modifiable message file procedures?" during the installation of DECforms. If the message files are not found in the directory SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES], re-install DECforms and answer YES to this question. 3 Using the DECforms Message Procedures This section describes how to use the supplied message files to generate translated run-time messages. 3.1 Modifying the Message File The source file for all DECforms Form Manager messages is located in SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES]FORMS$MSG_ RUN_TIME.MSG. The message text found in this file may be modified with the exception the following restrictions: o Do not modify message names. 1 o Do not modify control text messages. o Do not delete messages. o Do not add messages. o Do not change the order of messages. o Do not change the names of the source message files. o Do not drastically increase the length of the message text. You should only modify the message text of a given message. Here is an sample message from the FORMS$MSG_RUN_TIME.MSG message source file: ALPHA_ONLY "invalid character; enter only letters in this position." - /INFORMATIONAL The message could be modified as follows: ALPHA_ONLY "caractère invalide; entrez seulement du caractère alphabétique dans cette position." - /INFORMATIONAL DECforms accesses the messages using message names. When DECforms is compiled and linked, the names are converted to offsets into the message files. Any modification of message names, deletion or addition of messages, or rearrangement of their order will cause incorrect messages to appear when using DECforms. For convenience in modifying these files, they may be copied to other directories; however, please allow SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES] to remain intact until the final versions of the message files have been built, successfully tested, and installed in SYS$COMMON:[SYSMSG]. Please note that the message source file and the command procedure to build the non-executable image for the messages must be in the same directory (SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES]) when FORMS$MSG_BUILD.COM is executed. Do not change the name of the message source file. 2 3.2 Building the Message Files After the message source file has been edited (message text only), be sure that the most recent edited version of FORMS$MSG_RUN_TIME.MSG is in SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES]. This directory should contain the following files: o FORMS$MSG_RUN_TIME.MSG - The run-time message source file. o FORMS$MSG_BUILD.COM - The command procedure to build the non-executable run-time message image. o DECFORMS_MESSAGES.TXT - Instructions on modifying the DECforms run-time messages. To build a new message file, do the following steps: 1. Log in to the system manager's account, and set your default directory to the directory containing all of the above files (SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES]). 2. Execute the procedure FORMS$MSG_BUILD.COM by typing the following command: $ @FORMS$MSG_BUILD.COM This procedure MUST be executed interactively. This comand file does not prompt for any information; Instead, the procedure checks for the name of the directory in which it is being executed. All work compiling and linking the DECforms non-executable image message files is done in this default directory. The procedure takes approximately one minute to complete execution. All files resulting from this procedure are output to this default directory. 3. Test the output of this procedure. To test the correctness of the modified message files, define the following logical names: $ DEFINE/PROCESS FORMS$MSGMGRSHR - SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES]FORMS$MSGMGRSHR.EXE 3 You can now invoke a DECforms application, and check to see that the messages work correctly and that the messages correspond to the errors or confirmations you cause to occur during your testing. Be sure to purposely generate errors during your testing. 4. Deassign the FORMS$MSGMGRSHR logical name so that your temporary assignment to the testing directory will be deleted. $ DEASSIGN FORMS$MSGMGRSHR 3.3 Using One Message Translation Per Machine To replace the current DECforms message file installed on your system, you must place your new copy of FORMS$MSGMGRSHR.EXE in SYS$COMMON:[SYSMSG]: (SYS$SYSDEVICE:[SYSMSG]) using the following command: $ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES]FORMS$MSGMGRSHR.EXE - SYS$COMMON:[SYSMSG]: 3.3.1 Installing the Message File If you have installed the DECforms V1.1 Form Manager, FORMS$MANAGER.EXE, and its message file FORMS$MSGMGRSHR.EXE, as shareable images, (note that the command procedure FORMS$STARTUP installs the Form Manager and its message file as shareable images by default), you should now install the new Form Manager message file that you have created using this procedure. To install the new Form Manager message file do the following: 1. Log in to the System Manager's account. 2. Execute the DECforms startup command procedure: $ @SYS$STARTUP:FORMS$STARTUP This completes the installation of your modified DECforms run-time message file. 4 3.4 Using Multiple Message Translations Per Machine If you wish to maintain multiple translations of the DECforms run-time messages, you must maintain separate message files in SYS$COMMON:[SYSMSG] and determine, by use of a logical name which message file to use before invoking your DECforms application. Follow these instructions to maintain separate message files for multiple message translation support: 1. Copy FORMS$MSGMGRSHR.EXE to SYS$COMMON:[SYSMSG], giving it a name other than FORMS$MSGMGRSHR.EXE. For example, if you have translated all of the run-time message text from English to French, and wish to allow a user access to either translation, you might call the French message file FORMS$MSGMGRSHR_FRENCH.EXE. $ COPY SYS$SYSROOT:[SYSHLP.EXAMPLES.FORMS.MESSAGES]FORMS$MSGMGRSHR.EXE - SYS$COMMON:[SYSMSG]:FORMS$MSGMGRSHR_FRENCH.EXE 2. Before a DECforms application is invoked, you must define the logical name FORMS$MSGMGRSHR to point to the desired message file. For example, if you wished to select French messages, you would define the logical the following way: $ DEFINE/PROCESS FORMS$MSGMGRSHR - SYS$COMMON:[SYSMSG]:FORMS$MSGMGRSHR_FRENCH.EXE Note that once the DECforms application is invoked, the same message file will be used throughout the running of the application. This completes the installation of multiple DECforms run- time message file support. 5