Documents
User Generated
Resources
Learning Center

# Itt

VIEWS: 12 PAGES: 49

• pg 1
									Table of Contents

Introduction

Chapter 1    Customising Ingres to Your Local Language
Before you begin
Toolkit Contents
Ingres Test Files
Run Time Environment

Chapter 2    Translating Ingres Forms, Messages and Help Files
Forms Translation
Message Translation
Help File Translation

Converting Character Sets
Converting Files Between UNIX and VMS

Appendix A   Message Style Guide

Appendix B   Ingres Glossary

1
Introduction

Purpose of this Guide

The Translation Toolkit is a set of procedures used to translate forms, help text, and
messages in the Ingres Product to a local language. In this Guide, you will find guidelines
to translate Ingres text, and instructions for using the scripts and executables included in
the toolkit.

To facilitate the process of "internationalisation," all displayable text, such as prompts,
error messages, and menu items, have been extracted from the Ingres product and
placed in separate message files rathar then scattered throughout the source code. In
addition all Ingres forms have been extracted in the same manner. At run time, Ingres
retrieves the appropriate text string or form. This approach provides an easy way to
translate forms and messages, allowing language selection at execution time.

2
How to Use this Guide

Please keep this Guide on hand at all times. Refer to it whenever you translate Ingres
forms and messages to your local language.

Audience

This Guide and the procedures contained within it are intended for use by a technical
Support Representative or equivalent Technical Staff Member. Some experience with the
Visual-Forms-Editor (VIFRED) is assumed. The instructions for the translator assume no
knowledge of Ingres.

The examples in this Guide use French as the local language, although no knowledge of
French is necessary to understand the intended content.

Organisation of this Guide

This Guide is divided into three chapters, each of which contains subsections. The
chapters are:

   Chapter 1, Customising Ingres to Your Local Language:
   Provides requirements for using the Toolkit, describes its contents, and discusses
Ingres run time environment settings.

   Chapter 2, Translating Ingres Forms, Messages, and Help
   Files: Provides steps and guidelines to translate Ingres text to your local language.

   Chapter 3, Upgrading/Converting the Ingres Toolkit: Provides guidelines to converting
INGKES text between the UNIX and VMS Operating Systems and handling system

   Appendix A: Message Style Guide: Lists rules and guidelines for creating translated
error messages.

   Appendix B: Ingres Glossary: Lists Ingres-specific terms for consistency in translating
Ingres text.

3
Conventions
Procedures and descriptions in this Guide contain the following conventions:

   Key words are in bold type. When you use a key word, type it exactly as shown. Key
words include commands, keys, required symbols, and punctuation.

   Words in italics introduce the definition of a term or represent a generic term for which
you supply a specific value; for example, filename.

Prompts and information you enter are shown in a special typeface, exactly as they would
appear on the screen. For example:

$unloadform translatedb /tk/french Operating Systems The Ingres Translation Toolkit can be used on the UNIX, Windows NT and VMS Operating Systems. Where separate text is needed, as in a command line to the operating system, this Guide shows an icon to indicate which text applies to your operating system. For example: WNT \tk\french UNIX /tk/french VMS [tk.french] 4 Chapter 1 Customising Ingres to Your Local Language Before You Begin System Requirements Standard Procedures Toolkit Contents Ingres Text Files Form Files Message Files Help Files Run Time Environment 5 Before You Begin Please review the following sections to ensure:  Your system meets the Toolkit's resource requirements.  You are aware of the procedures required to translate Ingres text files. System Requirements The toolkit contains a directory structure and executables for either the Windows NT, UNIX or VMS Operating systems. Before you unload the toolkit tape and compile the messages and forms, be sure you have:  A machine that supports the operating system (Windows NT, UNIX or VMS) designed for your toolkit. Note: Since the Ingres text files (help files, message files, and form files) contained in your toolkit are ASCII files, you can copy them another machine's Operating Systems for translation. To use translated files between the Windows NT, UNIX and VMS Operating Systems, see Chapter 4, "Upgrading/Converting Ingres Text Files."  Approximately 5 megabytes of disk storage for the contents of the toolkit.  An Ingres Release 6 installation with required local language support if you are planning to translate forms created through the Visual-Forms-Editor (VIFRED). Standard Procedures The steps required to translate Ingres forms, help text, and messages to your local language are described in detail in the following chapters. Please note that after you have completed the translation, you are required to send all translated text files to the Ingres Development Manager at Computer Associates International Inc. Briefly the steps are:  Set up the Ingres run time environment.  Translate the forms, help text, and message files.  Store each of the files in a single working/target directory. For example: WNT c:\tk\french UNIX /tk/french VMS [tk.french] When all text files are translated, the contents of this directory will contain a complete Ingres translation. 6 Send Computer Associates International Inc. a copy of the directory and its contents (translated files) on either magnetic media, or CDROM. 7 Toolkit Contents The following directory structure is provided on the toolkit tape. Windows NT Directories NT Directory and Files Contents \tk Contains subdirectories, and the files toolit.kit and version.rel (contain Ingres version associates with the toolkit). \tk\commands Contains these scripts: difftext Script for detecting and reporting differences in the text files between two versions of the toolkit. ergen Script for generating the entire set of new fully translated message files for a new release. ervalid Script for validating the entire set of new fully translated message files for a new release frmcompile Unloads a form from a given database and compiles it into the form index file. loadform Loads all forms into a given database using the copyform command. setup.bat Setup script for a DOS Command Prompt. stagemsg Compiles all messages 8 UNIX Directory and Files Contents Unloadform Unloads all translated forms from a given database into new form files. \tk\bin Contains all these executable files: ercompile Used by stagemsg to compile individual message files. ergenf Generates a partially translated message file for a new release. Works on one file only. ervalidf Validates a new fully translated message file for a new release. Works on one file only. formindex Used by frmcomple to move a form from VIFRED to the form index file. transcod Converts a decimal character set code the another decimal character set code. \tk\text Contains complete set of text files for translation  9 Unix Toolkit Directories UNIX Directory and Files Contents /tk Contains subdirectories, and the files toolit.kit and version.rel (contain Ingres version associates with the toolkit). /tk/commands Contains these scripts: difftext Script for detecting and reporting differences in the text files between two versions of the toolkit. ergen Script for generating the entire set of new fully translated message files for a new release. ervalid Script for validating the entire set of new fully translated message files for a new release frmcompile Unloads a form from a given database and compiles it into the form index file. loadform Loads all forms into a given database using the copyform command. setup.csh Setup script for C-shell. stagemsg Compiles all messages 10 UNIX Directory and Files Contents Unloadform Unloads all translated forms from a given database into new form files. /tk/bin Contains all these executable files: ercompile Used by stagemsg to compile individual message files. ergenf Generates a partially translated message file for a new release. Works on one file only. ervalidf Validates a new fully translated message file for a new release. Works on one file only. formindex Used by frmcomple to move a form from VIFRED to the form index file. transcod Converts a decimal character set code the another decimal character set code. /tk/text Contains complete set of text files for translation  11 VMS Directory and Files Contents [tk] Contains subdirectories, and the files toolkit.doc and version.rel (contains Ingres release associated with the toolkit). Tk.commands Contains these scripts: difftext.com Script for detecting and reporting differences in the text files between two versions of the toolkit. ergen.com Script for generating the entire set of new partially translated message files for a new release. ervalid.com Script for validating the entire set of new fully translated message files for a new release. frmcompile.com Unloads a form from a given database and compiles it into the form index file. loadform.com Loads all forms into a given database using the copyform command. stagemsg.com Compiles all messages. symbols.com Defines symbols. unloadform.com Unloads all translated forms from a given database into new form files. [tk.bin] Contains all these executable files: ercompile.exe Used by stagemsg to compile individual message files ergenf.exe Generates a partially translated message file for a new release. Works in one file only. ervalidf.exe Validates a new fully translated message file for a new release. Works in one file only. transcod.exe Convert a decimal character set code to another decimal character set code. [tk.text] Contains the complete set of text files for translation  12 Ingres Text Files There are 3 different types of INCRES text files that require translation:  Form Files  Message Files  Help Files Each of these files is described below. Form Files The form files are the files with extension ".frm". Form files of the format provided ill thC· toolkit are the output of the Ingres copyform command. These files define the forms used in the standard Ingres product set. They are compiled into an Ingres form index file (rtiforms.fnx). Message Files Message files are the files with extension ".msg". The prefix of these files is constructed in the format er+facility-code.msg. The facility code is the facility responsible for generating the error; for example, ervf.msg, where vf represents VIFRED (Visual-Forms-Editor). Message files are the source for Ingres informational, warning, and error messages, as well as menu selection text, They are compiled for fast (for example, fast_v4mnx) or slow (for example, slow_v4.mnx) retrieval at run time. A message file contains all of the nlessages associated with a facility. Each message consists of a: 1. Message definition identifier 2. Actual message text 3. Explanatory text in comments The explanatory text associated with each message is used to document error messages. 13 Help Files Tile help tiles arc~ those files with extension ".hlp". All available help file classes are listed in the table below. In general, the first two letters of the help file prefix represent an interactive tool and the remaining letters represent the function name, The help files contain the text displayed when "help" is selected by a menu option, The help files are ASCII text and do not get compiled. Help File Classes Prefix Function ab*.hlp Application-By-Forms (ABF fg*.hlp Frame Generation fs*.hlp Terminal Monitor h*.hlp Help ic*.hlp accesssdb im*.hlp Ingres/MENU mc*.hlp Erconvert utility (used internally) oo*.hlp Object Management q*.hlp Query-by-Forms (QBF) r*.hlp Report-by-Forms(RBF) and Ingres/REPORTS sw*.hlp Information form for ABF tu*.hlp Table Management tw*.hlp Ingres/DBD vf*.hlp VIFRED (Visual-Forms-Editor) vg*.hlp VIGRAPH (Visual-Graph-Editor) vq*.hlp Vision 14 Run Time Environment The Ingres run time environment uses environment variables (Windows NT & UNIX) or logicals (VMS) for accessing displayed objects. These environment variables or logicals can be defined to access objects in another language by specifying a different directory and language.  The default directory for objects is: WNT %II_SYSTEM%\ingres\files\enqlish  UNIX$II_SYSTEM/ingres/files/enqlish 

VMS           II_SYSTEM: [ingres.files.enqlish] 

II_CONFIG specifies the directory containing the different dedicated language directories.
The default is:

WNT           %II_SYSTEM%\ingres\files 

UNIX          $II SYSTEM/ingres/files  VMS II SYSTEM:[ingres.files]   II_LANGUAGE defines the language used. This logical, used in combination with II_CONFIG will construct the directory in which a foreign language set of messages can be found. For example, if II LANGUAGE is set to FRENCH, then the files directory then the files directory is: WNT %II SYSTEM%\ingres\files\french UNIX$II SYSTEM/ingres/files/french

VMS           II_SYSTEM: [ingres.files.french]

   II_MSGDIR specifies the path for the message files directory only (default =
II_CONFIG + II_LANGUAGE).

For example, if II_LANGUAGE is set to FRENCH, Ihen the path is:

WNT           %II SYSTEM%\ingres\files\french 

UNIX          $II SYSTEM/ingres/files/french  VMS IISYSTEM: [ingres.files.french]  15  II_MSG_TEST allows messages to be looked up first in an individual message file if II_MSG_TEST=’Y’, The file is compiled with the ercompile utility program with the -f option. This is used to test message modification without recompiling all Ingres messages (default = undefined.) 16 II_FORMFILE specifies the path for the compiled form index file (default = II_CONFIG + II_LANGUAGE + rtiforms.fnx). For example: WNT %II_MSGDIR%\rtiforms.fnx  UNIX$II_MSGDIR/rtiforms.fnx 

VMS           11 MSGDIR:rtiforms.fnx 

II_HELPDIR specifics the path for the help files directory.

For example, if II_LANGUACE is set to FRENCH, then the path is:

WNT           %II_SYSTEM%\ingres\files\ french 

UNIX          $II_SYSTEM/ingres/files/ french  VMS II_SYSTEM: [ingres.files.french]  17 Chapter 2 Translating Ingres Forms, Messages and Help Files Forms Translation Translator Instructions Message Translation Translator Instructions Text Not Required for Translation Text Required for Translation Compiling Messages Help File Translation Translator Instructions 18 Forms Translation All forms are created with the Visual-Forms-Editor (VIFRED). The form files provided in the toolkit are the output of the Ingres copyform command. This section provides instructions for the following tasks which are required to translate VIFRED forms: 1. Load the form files into an Ingres Release ~ database that is dedicated to the task. 2. Use VIFRED to translate the forms and to design them in a format suitable to your local language. Note: Only an experienced INGRES user, such as a Technical Support Representative should perform the forms translation. This is to ensure the integrity of forms design, validation checks and associated error messages. 3. Use the frmcompile command to compile the form and update the form index file. Before you translate the forms, please note the following guidelines:  To maintain product integrity, do NOT change any of the following item:  video attributes  field internal name  color  display format  datatype  To accommodate your translated text, you may change the following items:  field title  default values  screen position  number of rows in a table field  amount of trim 19 Translator Instructions Perform the following steps to translate the forms: 1. To access and execute the scripts, follow the instructions below that apply to Your Operating System: WNT At the command prompt, type: C:\> cd \tk\commands Define the search path for translation toolkit executables. SET PATH=c:\tk\bin;%PATH% UNIX At the prompt, type:$ cd /tk/commands

Define the search path for translation toolkit executables.

If you are a C-Shell user:

$source setup.csh If you are a Bourne-Shell user:$ path=/tk/bin:$path; export PATH  VMS At the prompt, type:$ set def [tk.commands]

Then define symbols needed for form compilation.

$@symbols  2. Create a working database that is dedicated for use with VIFRED.$ createdb dbname

For example:

$createdb translatedb 3. Load all source forms (.frm files) from the source directory into the database.$ loadform dbname source_directory

For example:

20
WNT c:\> loadform translatedb \tk\text 

UNIX $loadform translatedb /tk/text  VMS$ loadform translatedb [TK.TEXT] 

4. Access VIFRED to translate the forms.

$vifred dbname 21 For example: S vifred translatedb In VIFRED, edit the forms to fit your target language needs and then save them. 5. Unload the forms from the database and compile them into the form index file. Perform this step for each form.$ frmcompile formname dbname formindex

For example:

WNT C:\> frmcompile imtopfr translatedb \tk\french\rtiforms.fnx 

UNIX $frmcompile imtopfr translatedb /tk/french/rtiforms.fnx  VMS$ frmcompile imtopfr translatedb [TK.FRENCH]rtiforms.fnx 

Note: For testing purposes, create a new rtiforms.fnx so that the English release
%II_SYSTEM%\ingres\files\english\rtiforms.fnx on Windows NT or
$II_SYSTEM/ingres/files/english/rtiforms.fnx in UNIX or IISYSTEM:[ingres.files.english]rtiforms.fnx in VMS remains uncorrupted. You may want to test forms design periodically by compiling all forms and updating your new rtiforms.fnx. Use the logical (VMS) or environment variable (Windows NT/UNIX) II_FORMFILE to point to your new compiled forms index file. 6. When you are satisfied with the way all the forms are translated, copy the translated forms to new .frm files in the target directory$ unloadform dbname target_directory

This command will process all forms.

For example:

WNT C:\> unloadform translatedb \tk\french 

UNIX $unloadform translatedb /tk/french  VMS$ unloadform translatedb [TK.FRENCH) 

22
Message Translation
Message files contain all the English text strings extracted from the code for possible
translation. They are contained in directory:

WNT \tk\text\*.msg 

UNIX /tk/text/*.msg 

VMS     [tk.text*f.msg 

Using the style guide in Appendix A and the translation instructions contained in this
section, a professional translator may translate the message files with no knowledge of
Ingres. Message files can be translated using ally text editor.

Translator Instructions

Ingres Message files consist of several types of text. This section describes which parts of
the message text require translation and which do not.

Text Not Required for Translation

You do NOT translate the following text:

   Comments. A comment is explanatory text inserted anywhere within the file. A
comment is all text between /* and */.

For example:

/* this is a comment */

/*    this
**    is
**    a comment
*/

   Definition Lines. A definition line begins with #define in the first column.

For example:

#define_QF_CLASS             91

23
   Identifiers. An identifier is a sequence of letters, underscores (_) and digits. An
identifier appears in the first column of a line and begins with the letter S, F, E, or I.

For example:

S_QF_0008_Inserting_new_row_
^

   Special Embedded Characters. These are formatting characters or parameters that
are inserted within the text. This definition includes any character preceded by a
backslash (\), and all characters preceded by a percent (%).

For example:

\n
\t
\r
%0c
%1c

Do not remove any of the formatting characters or parameters from your translation. They
are required for parameter substitution at runtime. Make sure that you understand what
each parameter represents and that you use the parameter in a context appropriate to
the message.

For example:

E_F1203E_8254 "Row number '%Od' out of range in table field ‘%c’."

The first Parameter represents the row number; and the second parameter represents the
tablefield. You must preserve these parameters and use them in a meaningful way·.

for assistance.

   Internal Messages. These messages are always followed by /*DIAG*/. The internal
messages generally indicate software defects and are examined by a Technical
Support representative.

For example:

E_TE0003_error_opening
"TERMCAP: error (%d) inopening %s\n"                    /*DIAG*/

24
Text Required for Translation

Text that requires translation always follows an identifier.

For example:

S_VF0013_Retrievingforms "Retrieving form ‘%0c’...
^^^^^^^^^^^^^^^^^^^^

The text in the example above ^^^^ needs to be translated. A French translation of the
example above might be:

S_VF0013_Retrieving_forms- "Extraction de '%Oc'…”

Note: The identifier is NEVER translated.

When translating error messages, note the following size limitations:

   Summary Line. The first line of text must have no more than 44 characters including
parameter substitution (for example, text substituted for %Oc) and other embedded
characters (see Special Embedded Characters in the section, Text Not Required for
Translation.

   Total Text. A single message (including identifier) must have no more than 1000
characters.

Please read Appendix A, "Message Style Guide" and Appendix B, "Ingres Glossary" for
guidelines in translating messages.

25
Compiling Messages

Ingres Community provides compiled messages in fast and slow format with each foreign
language version. The toolkit contains tools to create these compiled messages so that a
working version of the message files for the target language may be developed and
tested.

Perform the following steps to create the fast (for example, fast_v2.mnx) and slow (for
example, slow_v2.mnx) message files from the full set of .msg files:

1. To access and execute scripts, follow the instructions below that apply to your
Operating System:

WNT At the prompt, type:

C:\> cd \tk\commands

Then define the search path for translation toolkit executables:

SET PATH=c:\tk\bin;%PATH%

UNIX At the prompt, type:

$cd /tk/commands Then define the search path for translation toolkit executables. If you are a C-Shell user:$ source setup.csh

If you are a Bourne-Shell user:

$path=/tk/bin:$path; export PATH 

VMS At the prompt, type:

$set def [tk.commands] Define symbols needed for compiling messages.$ @symbols 

2. Move the message text to, a separate directory (for example, /tk/french). Perform the
translation and convert each message file.

You can Edit the message files for translation with any text editor.

3. Use the following script to validate the translated message files.

$ervalid eng_msg_dir target_msg_dir 26 For example: WNT c:\> ervalid \tk\25\text \tk\25\french  UNIX$ ervalid /tk/63/text /tk/63/french 

VMS $@ervalid [tk.63.text] [tk.63.french]  Each translated message file is compared against the english message file to verify:  Message class number is defined and is correct  All messages exist  Text for each message contains the necessary parameters  Format for the parameters are accurate  Obsolete messages are deleted While performing the comparison, ervalid ignores comments in the message files. 4. Use the following environment variables (Windows NT/UNIX) or logicals (VMS) to test changes. WNT set II_MSG TEST=y If you are a C-Shell user: UNIX$ ;setenv II_MSG TEST "y"

$setenv II MSGDIR "/tk/french" If you are a Bourne-Shell user:$ II_MSG_TEST = "y”; export II_MSG_TEST

$II_MSGDIR = ·”/tk/french"; export II_MSGDIR  VMS$ define II_MSG_TEST "Y"

$define II_MSGDIR [tk.french]  5. Use the following script to validate the translated message files.$ ervalid eng_oldmsg_dir new_engtar_dir

For example:

WNT ervalid \tk\63\text \tk\63\french

27
UNIX ervalid /tk/63/text /tk/63/french

VMS @ervalid [tk.63.text) [tk.63.french]

Each translated message file is compared against the english message file to verify:

   Message class number is defined and is correct
   All messages exist
   Text for each message contains the necessary parameters
   Format for the parameters are accurate
   Obsolete messages are deleted

While performing the comparison, ervalid ignores comments in the message files.

6. Compile all messages in the target directory into the fast (for example, fast_v2.mnx)
and slow (for example, slow_v2.mnx) message files.

$stagemsg target_directory For example: WNT stagemsg \tk\french UNIX stagemsg /tk/french VMS stagcmsg [tk.french] stagemsg will create the two compiled message files in the target directory. 28 Help File Translation Help files are text files. They have the extension .hip. They are not compiled, but are displayed as text on the screen when "help" is selected as a menu option. The Ingres help processor is called automatically for formatting the displayed text file. Help files are ASCII files end can be edited for translation with any text editor. See the "Ingres Glossary" in Appendix B for use of Ingres terminology. Translator Instructions Follow these guidelines when translating the help files: 1. While translating the help files, try to keep the same display format as the English release. 2. After you translate the help files, put the files in the working/target directory: WNT \tk\french  UNIX /tk/french  VMS [tk. french]  3. To test a translated help file, set II_HELPDIR to the local language directory. For example, if II_LANGUAGE = FRENCH, then the path is: WNT %II_SYSTEM%\ingres\files\french  UNIX$II_SYSTEM/ingres/files/french 

VMS II_SYSTEM: (ingres.files.french] 

29
Chapter 3

Translated Text

Converting Character Sets

Converting Files Between UNIX and VMS
Converting Translated Form Files
UNIX to VMS
VMS to UNIX
Converting Translated Message Files
UNIX to VMS
VMS to UNIX
Converting Translated Help Files
UNIX to VMS
VMS to UNIX

30
For every Ingres upgrade, you will receive a new set of files on magnetic media that
correspond to the upgraded Ingres release. There may also be new scripts and
executables under the existing toolkit directory name and structure for your operating
system.

1. Check to see the release number in the new toolkit matches the release rrumber of
your Ingres installation. If it does not, contact your technical support representative for
assistance.

2. Install the new toolkit under a DIFFERENT directory name.

3. Use the following script to get a comprehensive listing of files (form, message, help)
added, deleted, and changed since the last release:

WNT c:\tk\commands\difftext \tk\20\text \tk\25\text 

UNIX /tk/commands/difftext /tk/62/text /tk/63/text 

VMS [tk.commands]ditftext.com [tk.62.text] [tk.63.text] 

This script compares the current English release against the previous one.

4. Use the following script to generate the upgraded message files for the release:

ergen eng_oldmsg_dir eng_newdmsg_dir target_oldmsg_dir target_newmsg_dir [-report]

An optional report flag can be specified with the above script. This flag instructs ergen to
generate a report of all the new messages, changed messages, and obsolete messages
for each message file as it is being translated.

For example:

WNT c:\tk\bin\ergen /tk/62/text /tk/63/text /tk/62/french /tk/67/french 

UNIX $ergen /tk/62/text /tk/63/text /tk/62/french /tk/67/french  VMS$ ergen [tk.62.text] [tk.63.text] [tk.62.french] [tk.63.french] 

For each message file, the two versions of the english message file are compared to
determine which messages have changed and which ones have been added or deleted in
the current release.

With this information, and using the old version of the translated message file, ergen
produces a new translated message file for the current release. All unchanged messages
remain in the new message file, while obsolete messages are omitted. Those messages
that were added or changed in the current release are not converted.

31
5. Manually translate those messages that were added or changed in the current release.

6. Use the following script to validate the translated message files.
$ervalid eng_msg_dir target_msg_dir For example: WNT c:\ ervalid \tk\63\text \tk\63\french  UNIX$ ervalid /tk/63/text /tk/63/french 

VMS $ervalid [tk.63.text] [tk.63.french]  Each translated message file is compared against the english message file to verify.  The message class number is defined and is correct  All messages exist  The text for each message contains the necessary parameters  The format for the parameters are accurate  Obsolete messages are deleted While performing the comparison, ervalid ignores comments in the message files. 32 Converting Character Sets In the translation process, the transcod utility program allows you to convert a decimal character set code to another decimal character set code. You can use transcod for conversion between the VMS, Windows NT and UNIX text files. For example, once you have performed the translation on a SUN/UNIX machine, you can use transcod to move the translated files to a VMS/VAX machine for final testing and distribution. You are required to use an input file to define a conversion table. The table contains equivalence codes for character values that differ between the input text file and the output text file. (The other codes are assumed to be equal.) The following is the format for the conversion table file: XXX YYY ccc... where:  XXX is the DECIMAL input character code (beginning at col 1).  YYY is the DECIMAL output character code (beginning at col 4).  ccc is a comment zone up to 70 characters (beginning at col 8). For example: 253 255 "Lowecase y with umlaut (diaersis), DEC-MULTI to 8859-1" Command Line svntax.$ transcod equivalencetablefile inputfile outputfile

where:

   equivalencetablefiIe is the conversion file table described above.
   inputfile is the input file to convert.
   OutputfiIe is the converted file te be generated.

33
Converting Files Between UNIX and VMS
If you have a current set of UNIX or VMS translated files, the procedures in this section
will allow the form, message, and help files to be used between the UNIX and VMS
environments.

Converting Translated Form Files

UNIX To VMS

1. At the UNIX prompt, copy all translated forms from the database to new .frm files in a
target directory.

$unloadform dbname target_directory For example:$ unloadform translatedb /tk/french

2. Use the transcod utility (see "Converting Character Sets" in this chapter for details) to
convert the dissimilar decimal character codes between UNIX and VMS for all the
translated form files.

3. Use an available transfer program (for example, ftp) to copy converted form files to
VMS. You will also have to transfer the .frm files from the English text directory (used
in the next step by he difftext command). Make sure to copy the .frm files into a
separate directory.

4. Log on to VMS.

5. Execute the difftext command to determine the differences in text between the two
sets of English form files.

$difftext unix_eng_frm_directory vms_eng_frmdirectory For example:$ difftext [tk.unixeng] [tk.vmseng]

6. Load all UNIX translated forms to a VMS database.

$loadform dbname unix_translated_form_directory For example:$ loadform translatedb [tk.unixtransfrms]

34
7. Based on the differences found in Step 3, use VTFRED to add, modify, and delete
forms.

8. Compile all translated forms and move them to the formindex file. For each form in the
database perform:

$frmcompile formname dbname formindex For example:$ frmcompile imtopfr translatedb [tk.french]rtiforms.fnx

VMS to UNIX

1. At the VMS prompt, copy all translated forms from the database to new .frm files in a
target directory .

$unloadform dbname target_directory For example:$ unloadform translatedb [tk.french]

2. Use the transcod utility (sec "Converting Character Sets" in this chapter for details) to
convert the dissimilar decimal character codes between VMS and UNIX for all the
translated form files.

3. Use an available lransfer program (far example, Eta) to copy the converted form files
to UNIX under different directories. You will also have to transfer the .frm files from the
English text directory (used in the next step by the difftext command). Make sure to
copy the .frm files into a separate directory.

4. Log on to UNIX.

5. Execute the difftext command to determine the difference in text between the two sets
of form directories.

$difftext vms_eng_frm_directory unix_eng_frm_directory For example:$ difftext /tk/vmseforms/ tk/suneforms

6. Load all VMS translated forms to a UNIX database.

$loadform dbname vms_translated_form directory For example: 35$ loadform translatedb /tk/vmstransforms
7. Based on the differences found in Step 3, use VIFRED to add, modify, and delete
forms.

8. Compile all translated forms and move them to the formindcx file.

For each form in the database, perform:

$frmcompile formname dbname formindex For example:$ frmcompile imtopfr translatedb /tk/french/rtiforms.fnx

Converting Translated Message Files
extension (.msg).

UNIX To VMS

1. At the UNIX prompt, access the transcod utility (see "Converting Character Sets" in
this chapter) to convert the dissimilar character code between UNIX and VMS for all
the translated message files.

2. Use an available transfer program (for example, ftp) to copy the converted messages
files to VMS. You will also have to transfer the .msg files from the English text directory
(used in the next step by the difftext command). Make sure to copy the .msg files into
a separate directory.

3. Log on to VMS.

4. Execute the difftext command to determine the differences irr text between the two
sets of message directories.

$difftext unix_eng_msg_directory vmseng_msg_directory For example.$ difftext [tk.unixmsgs] [tk.vmsmsgs]

5. Based on the differences found in Step 4, use your text editor to add, modify, and
delete message text.

6. Compile all messages in the target directory into fast (for example, fast_v2.mnx) and
slow (for example, slow_v2.mnx) message files.

36
$stagemsg target_directory For example:$ stagemsg [tk.french]

VMS to UNIX

1. At the VMS prompt, access the transcod utility (sec "Converting Character Sets" in this
chapter) to convert the dissimilar decimal character codes between VMS and UNIX for
all the translated message files.

2. Use an available transfer program (for example, ftp) to copy the converted message
files to UNIX. You will also have to transfer the .msg files from the English text
directory (used in the next step by the difftext command). Make sure to copy the .msg
files into a separate directory.

3. Log on to UNIX.

4. Execute the difftext command to determine the differences in text between the two
sets of message files.

$difftext vms_english_msg_directory unix_english_msg_directory For example:$ difftet /tk/vmsmsgs /tk/sunmsgs

5. Based on the differences found in Step 4, use your text editor to add, modify, and
delete message text.

6. Compile all the messages in the target directory into fast (for example, fast_v2.mnx)
and slow (for example, slow_v2.mnx) message files.

$staqemsg target_directory For example:$ stagemsg /tk/french

Converting Translated Help Files

UNIX To VMS

37
1. At the UNIX prompt, access the transcod utility (see "Converting Character Sets" in
this chapter) to convert the dissimilar decimal character codes between UNIX and
VMS for all the translated message files.

2. Use an available transfer program (for example, ftp) to copy converted help files to
VMS. You will also have to transfer the .hlp files from the English text directory (used in
the next step by the difftcxt command). Make sure to copy the .hlp files into a separate
directory.

3. Log on to VMS.

4. Execute the difftext command to determine the differences in text between the two
sets of help files.

$difftextt unix_english_hlp_directory vmsenglish_hlp_directory For example:$ difftext [tk.unixeng] [tk.vmseng]

5, Based on the differences found in Step 4, use your text editor to add, modify, and
delete help text.

VMS to UNIX

At the UNIX prompt, access the transcod utility (sec "Converting Character Sets" in this
chapter) to convert the dissimilar decimal character codes between VMS and UNIX for all
the translated message files.

Use the available transfer program (for example, ftp) to copy the converted help files to
UNIX under different directories. You will also have to trilnsfcr the .hip files from the
English text directory (used in the next step by the difftcxt command). Make sure to copy
the .hip fies into a separate directory.

Log on to UNIX,

Execute the difftext command to determine the differences in text between the two, sets of
help files.

$difftext vms _english_hlp_directory unix_english_hlp_directory For example:$ dirftext /tk/vmshlp /tk/sunhlp

Based on the differences found in Step 4, use your text editor to add, modify, and delete
help text,

38
Appendix A

Message Style Guide

Standards and Requirements

1. Translate the English message wording carefully. Avoid ambiguity. Strive for a literal
translation of the text, but keep in mind the cultural nuances of your own language.

2. Write sentences that are clear, concise, and informative. For example, error messages
should tell users:

   What is wrong
   How to fix it

3. Choose words that are understandable to novice computer users. Be consistent in
using Ingres terms (see Appendix B, "Ingres Glossary").

4. Consider the system constraints on the format and display of error messages. These
constraints will affect how you choose to word the message text (see "Error Message
Rules" below).

5. Present text in a professional manner. Follow the spelling, punctuation, and grammar
rules of your language. Use grammar and spell-checking tools if they are available in

6. Present the message in the same format as the English version. The format is
determined by the category of the message. (See "Message Types" in this Appendix to
review how messages are categorized.)

39
Error Message Rules
The message routine imposes certain constraints on the format and display of error
messages. Messages are displayed as a single line (less than or equal to 44 characters)
at the bottom of the screen. Users have the choice of pressing the More key to see the
rest of the message or pressing Return or End to ignore the rest of the message.

Message Display and Content

The purpose of error messages is to provide two levels of information. Each level
provides more detail for the user. You are required to translate at least the first level of
information. The levels are:

Summary Line (required) - A single summary line displayed on the bottom of the screen
that provides a concise description of the problem.

A fuller description displayed on the bottom of the screen after the user requests "more"
by pressing the More key.

Below is a detailed description of each message level along with translation rules.

Summary Line

The first line of all error messages is a required summary line. This line's length must be
no more than 44 characters, followed by "\n" to force a line break. This allows the
message routine to display the whole summary on the screen. The summary identifies the
error that occurred.

Note that failure to keep the text within 44 characters will cause the message routine to
insert a break and a set of ellipses Lhal will hide important information. The user will then
need to request the rest of the text.

For example:

There was an error while attempting ... End(PF3) More(PF2)

To keep text within the 44-character maximum:

   Trim off all excess blank characters.

   Avoid parameters with unknown length. If you must use parameters in the summary
line, determine their maximum length to make sure the summary will be within the 44-
character maximum.

40
   Violate the rules of your local language only if your text would otherwise exceed the
44-character maximum. You can use sentence fragments and leave out punctuation
marks that would make the summary too long (for example, a period in the 45th
position).

However, use discretion when creating shortened messages. Be sure you use
shortened messages consistently throughout the product and that they are clear and
understandable.

Explanatory Text

Explanatory text follows the summary line. Unless the error is minor, most error messages
will require more detail explanation than the 44 characters allotted in the summary line.
Therefore, when users press the More key while the summary line is displayed additional
explanatory text is displayed.

The maximum length of a complete error message, both summary and explanatory text, is
1000 characters. The ideal message can be contained in a one-line summary and three to
seven lines of text.

The explanatory text must follow all the grammar rules of your language. It is a fuller
description of the error, not a re-wording of the summary line. Be sure your text provides
the following information to the user:

   Why the error occurred

   The source of the problem

   How to fix the problem

   How to escape without affecting any~hing even if the problem cannot be fixed

   Ways to avoid the problem in the future

41
Message Types
There are two categories of messages:

   User Error Messages

   Informational Messages

Each of these message types is described in detail below. Note that both categories of
messages are intended for the users. While error messages inform the users of a data
entry or system error, informational messages merely inform the user about the status of
the system.

Error Messages

There are two classes of error messages:

   User error messages

   Internal Diagnostic Messages

User Error Messages

Error messages are intended for the user. From these messages, the user should be able
to understand the error and correct it. User error messages should inform the user:

   What is wrong or what Ingres attempted to do

   Steps to correct the error

The error usually occurs from bad user input. An English example is:

E QF002B_Place_cursor_over_nam
"Place cursor over name of column you wish to delete\n
You need to move the cursor into the tablefield containing
the name or the column you wish to delete."

An example of the French translation for the above message is:

E QF002B_Place cursor_over nam
"Placez le curseur sur le nom de la colonne\n qu vous voulez
supprimer\n
Vous dever deplacer le curseur dans le tableau qui contient
le nom de Ia colonne que vous voulez supprimer."

42
Internal Diagnostic Messages

Internal diagnostic messages are intended for technical personnel. These messages are
NOT translated and should rarely occur. They result from an internal error where a fatal
state occurred and cannot be exited.

You can identify diagnostic messages in two ways:

   In general, the summary starts with "Call your STC", followed by text that describes the
error.

   In general, the text always ends with "please call your Site Technical Contact."

In addition, facility directories, designated by all upper case or routine names may be
included in a diagnostic message.

An English example is:

E_TE0003_error_opening
"TERMCAP: error (%d) in opening %s\n”                    /*DIAG*/

Informational Messages

Informational Messages use a different routine and unlike error messages, display system
status information. These messages are used to pass information on to the user about the
current state of the system; for example, delays in processing.

Informational messages allow the user to continue to use the system. While the user
reads the message, processing continues even if processing overwrites the message
before the user reads it. In contrast, error messages halt processing and generally require
the user to press the Return key to read the message. Never confuse these two
categories of messages.

Informational messages are formatted so that all information appears in the summary line.

An English example is:

S_VF0013_Retrieving_forms
"Retrieving form '%0c'…”

An example of the French translation for the above message is:

S_VF0013 Retrieving forms
"Extraction de '%0c'…”

43
Appendix B

Ingres Glossary

Term                 Definition

ABF                  ABF (Applications-By-Forms) is a programmer’s workbench
designed to create Ingres applications.      From ABF,
programmers can call Ingres subsystems, the editor,

Abstract data type   An abstract data type is a data type that is not native to the
operating system, but is implemented with a data structure
and a set of operators. Ingres supports two abstract data
types: date and money. Examples of abstract operators are
the interval function for the data datatype and the addition
function for the money data type.

Aggregate            In SQL, an aggregate is a computation that operates on a set

Attribute            In VIRFRED, an attribute is a characteristic, such as
highlighting or a validation check, that affects the display and
behaviour of a field.

Base Table           A base table is a physical table (not a view). Also used in

Break Column         In a report, a break column for which a special action, such as
a subtotal, occurs when data values change.

Btree                Btree is a storage structure characterises by a dynamic index.

Catalog              A catalog is a table that tracks database objects.

Cell                 A cell is the intersection of a row and a column in a table field
(or, more rarely, in a table).

Checkpoint           A checkpoint is a static backup Ingres creates of a database.

Column               A column is a vertical section of data in a table or table field.

44
Correlation name         In SQL, a correlation name is an alternative name for a table,
variable.

Data Manager             The Data Manager is the part of Ingres which actually
retrieves and manipulates data. Also called a server.

Data window              A data window is the area on a form where information can be
entered.

Database                 A database is a collection of tables.

Database Administrator   The Database Administrator is the Ingres user who owns the
database.

Dataset                  A dataset is the set of records retrieved by a query statement,
in particular, the set of records associated with a table field by
a query in an ABF application.

DBA                      The DBA is the Database Administrator.

Default                  A default is a selection provided automatically by Ingres, such
as a form in QBF or a default report.

Dynamic SQL              Dynamic SQL is a part of Embedded SQL that enables users
to build queries at runtime.

Embedded SQL             Embedded SQL is an Ingres application development tool in
which SQL commands are placed in a program written in a
host third-generation language, such as FORTRAN or
COBOL.

Field                    A field is an area of a form used for data entry and retrieval; it
Column, Simplefield, Table field.

Form                     A form is the computerised equivalent of a paper form, where
users can enter, store and retrieve data.

Frame                    In an application, a frame is the combination of a form and a

FRS                      FRS (Forms-Run-Time System) is the part of Ingres that
controls the display of forms and users’ manipulation of forms

FRS constant             A value maintained by FRS that can be retrieved through a
standard key word.

FRSkey                   FRSkey is a logical key used in Ingres application code to

45
refer to a physical (keyboard) key.

Hash                    Hash is a storage structure characterised by a number of
“buckets” (primary pages) where records are placed according
to the value of a random function applied to their keys.

Heap                    Heap is the default storage structure. Heap has no index and
no ordering.

Inconsistent database   An inconsistent database is a database corrupted by query
execution failure.

Index                   See secondary index.

access all Ingres capabilities.

Integrity               Integrity is a test performed by Ingres to ensure that data
matches certain specifications.

ISAM                    ISAM (Indexed sequential Access Method) is a storage
structure characterised by a static index tree.

JoinDef                 A JoinDef journal is a log of transactions since the last static
backup. For each transaction, Ingres journals show changes,
users who made changes, and dates and times of changes.

Key                     A key is a part of a record that uniquely identifies it (logical
key). A column(s) of a table on which the storage structure is
built (the heap storage structure has no key).

data.

MST                     An MST (multi-statement transaction) is a transaction that
includes several statements that are identified and executed

Null value              A null value is a special value that represents unknown or
missing information.

Object                  An object is any database entity: a table, form QBF name,
application, frame of an ABF application, procedure of an ABF
application, JoinDef, graph or report.

Optimiser               The optimiser (Query optimiser) is the part of Ingres which
finds the fastest way to execute queries in the Data Manager.

Page                    An Ingres page is a 2048-byte structure, 2010 bytes of which
are available for storing user data.

46
Permit            A permit enables users other than a database’s DBA to
access that database.

QBF               QBF (Query-By-Forms) is an Ingres user interface tool that
performs:
Query Execution – appends, retrieves or modifies data in
table(s)
Join Definition – specifies a set of tables for a query.

QBFname           A QBFname is a mapping of a form to a table, or a form to a
JoinDef.

Query             A query is a data statement of adding, viewing, changing or
deleting data.

Query target      A query target is an object used in QBF.           Query targets
include tables, JoinDefs and QBF names.

Range variable    IN QUEL, a range variable is an alternative name for a table,
name.

RBF               RBF (Report-By-Forms) is the Ingres user interface tool for
customising reports.

Record            A record is a set of related data in a table, a tuple or a row.

Relation          A relation is the technical term for table. See also Table.

Report            A report is data from a database displayed in an easy-to-
understand manner.

Report-Writer     Report-Writer is an Ingres tool for designing and running
reports.

Row               A row is a set of related data in a table; also called a tuple or a
record. Also used to refer to a row in a table field.

Secondary index   A secondary index is a table composed of a key and a pointer
to the records of the base table. Ingres automatically
maintains the index as records are added or updated in the
base table.

Server            The server is a process which provides particular services to a
number of processes. The Data Manager is a server in Ingres
Release 6.

Set Function      In SQL, a set function is a computation that operates on a set

47
Simple field        A simple field is a field on a form containing a single piece of

SQL                 SQL (Structured Query Language) is a language used to

Storage structure   A storage structure is a way of arranging the pages of a table.
Ingres supports four storage structures: heap, hash, ISAM and
Btree.

Subquery            A subquery is an SQL subselect.

Subselect           A subselect is an SQL select statement nested within another
SQL statement. A subselect is used to build a search
condition for the main query.

System catalog      See Catalog.

Table               A table is a set of data arranged in rows and columns.

Table field         A table field is a field on a form containing several pieces of
field.

Terminal Monitor    The Terminal Monitor is a user interface to which the user can
enter query language commands.

Timeout             A timeout begins a timeout block activation if there is no user
response within a time period.

Title               A title is a character string used to identify a field on a form.

Transaction         A transaction is a set of statements that function as a unit:
either all statements are executed or none of them are. A
transaction may consist of a single statement or several
statements grouped in an MST (multi-statement-transaction).

Trim                Trim is a string of characters on a form used to instruct or
decorate.

Tuple               A tuple is a row or record in a table.

User interface      A user interface is one of the Ingres tools, usually forms-
based, that the user uses to communicate with Ingres.

Validation check    IN VIFRED, a validation check is a test to ensure that data
entered in a field matches certain specifications.

View                A view is a combination of columns from one or more tables to

48
from the appearance of a new table.

VIFRED    VIFRED (Visual-Forms-Editor) is the Ingres menu-based
editor for customising forms.

VIGRAPH   VIGRAPH (Visual-Graphics-Editor) is an Ingres tool for
creating, modifying and running graphs.

49


To top