Application Development


Chapter 45 . Customizing the User Interface

This chapter shows how to set up an interface that is suitable to a GUI platform or user environment. It also discusses strategies for writing applications for non-English-speaking users.

Two distributed files are especially important in designing the user interface:

Both files exist independently of the application; this facilitates development and deployment in several ways:


Using Message Files

Messages are stored in a binary file that is referenced by the application variable SMMSGS, and are loaded into memory at startup. SMMSGS can be set in the environment or Windows initialization file, or in a setup file. The Panther configuration directory provides a file of message defaults in source (msgfile) and binary (msgfile.bin) formats. You can edit the message file source to suit the needs of a given application, then recompile it with the msg2bin utility.

Creating and Modifying Message Files

You can edit the source of the distributed message file; you can also supplement this file with message files that contain your own application messages. If you must change the Panther message file, first create a copy of the distributed message file and edit it instead of the original. By doing so, you avoid losing changes with new releases; you also have recourse to the original message file contents.

If you create custom application messages, maintain them in a separate file for these reasons:

After you modify an ASCII message file, you must convert it to binary format with msg2bin. If the message file includes new entries, you must also create a C header file with msg2hdr.

How to Create or Add to a Message File

  1. Create or access the ASCII message file using a text editor.
  2. Edit existing entries or add new entries using the syntax described in the next section. For example:
    #user messages
    US_NOTAVAIL   = All copies of this movie are unavailable.
    US_ACTL       = Enter an actors last name.
    #administrator messages
    ADM_INVALIDRC = Invalid rating code.
  3. Convert the ASCII file to binary format with the msg2bin utility.

    If you only edit the text of existing message tags, your work is done. If you add new entries to the message file, continue with step 4.

  4. Define new message tags in a C header file. This makes the messages available to Panther functions such as sm_fquiet_err. Do this by running msg2hdr on the message source file. Messages are numbered sequentially from 0x0 to 0xF. For example:
    #define US_NOTAVAIL    0x0
    #define US_ACTL        0x1
    #define ADM_INVALIDRC  0x2
  5. In order to access your messages in JPL, define your tags as global JPL variables in a C header file. Do this by running msg2hdr with the -j option on the message source file. For example:
    global US_NOTAVAIL (1)   0
    global US_ACTL (1)       1
    global ADM_INVALIDRC (1) 2
  6. Relink the Panther executable so it includes the new header files (refer to page 42-2).

    Note: The message file only contains messages for end users; Panther developer messages are internally defined and cannot be modified.

Message Entry Syntax

Message file entries have the following format:

tag = msgString

tag
A string that can include letters, digits, and underscores; embedded blanks are invalid. An equal (=) sign must follow the tag. Blanks before and after the equal sign are optional.

If you create your own messagesdd, you can group them according to message tag prefixes. Messages with prefixes can be selectively loaded into memory with sm_msg_read. All system messages begin with a standard Panther prefix. These prefixes are reserved and can not be used for messages that you define:

SM

Messages and strings used by the Panther runtime library.

FM

Messages issued by the screen editor (prodev).

JM

Additional runtime messages used by Panther.

UT

Messages issued by some Panther utilities.

DM

Messages issued by database interactions.

TP

Messages issued by the middleware (JetNet and Oracle Tuxedo only).

msgString
If msgString defines a user message, it can contain any alphanumeric string on a single line; the string must contain at least one non-numeric character.

Note: The strings that define formats for date/time and numeric/currency have special syntax requirements.

Refer to page 45-12 for date/time syntax and page 45-19 for numeric/currency syntax.

Leading and trailing spaces are ignored. Enclose embedded and trailing spaces with quotation marks. Panther strips off the quotes when it displays the message.

For example, the distributed message file contains these entries:

SM_DAYA6       =  Fri
SM_DAYA7       =  Sat
SM_MOREDATA    =  No more data.
SM_YES         =  y
SM_NO          =  n
SM_MONL1       =  January
SM_MONL2       =  February
SM_0DEF_DTIME  =  %m/%d/%2y %h:%0M
SM_MB_HELPLABEL=  &Help
SM_YN_ERR      =  %MuPlease enter %Ky or %Kn into this field.
JM_HITACK      =  %MdHit acknowledge key to continue

Reserved Characters

The following characters have special usage in message file entries:

\

Continues the message string across multiple physical lines in the source file. For example:

PQ_FATALERR = Application unable to post your \

transaction. Contact your system manager.

\n

Forces a new line.

&

Indicates a key mnemonic for push buttons. For example, the following entry lets a user press the letter O on the keyboard instead of choosing the Oui (Yes) acknowledgment push button:

SM_MB_YESLABEL = &Oui

#

If placed in a message file line, comments out that line when msg2bin compiles the file.

Note: To use the backslash character in a message, enter two backslashes ()msgString can also contain percent sequences that specify appearance, positioning, and acknowledgment information.

Refer to page 45-8 for information on these.

Missing Entries

If there is no tag for a message or msgString is missing from the message file and a call is made to display the message, Panther displays the message section and number from the #define statement. For example, if the entry for SM_HITANY is deleted from the Panther message file, and user input invokes this particular message, the status line displays <8-27>, which is the value for SM_HITANY from the include file smerror.h.

Message Classes

You can divide messages into message classes. You can define up to eight user classes, numbered 0 to 7. Each class can contain up to 65529 characters. Within each class, you can further differentiate messages through prefixes.

Use section classes and prefixes to divide messages into useful categories. A class of messages or messages of a given prefix can be individually loaded and unloaded from memory through sm_msg_read and sm_msg_del, respectively. Unclassified messages default to class 0.

Because unclassified messages cannot exceed 65529 characters, an application that requires many messages might require you to divide them into multiple classes.

Note: Panther reserves for its own use classes 8 through 15 and the prefixes described earlier (page 45-4).

Defining a Message Class

Each message class is defined by a message class entry with this format:

"XY" = digit

"XY"
A two-character code enclosed in quotation marks. Reserved prefixes (refer to page 45-4) cannot be used.

digit
A digit between 0 and 7, inclusive, that designates the class in library functions such as sm_msg_read.

All entries below a message class entry are part of the same message class. For example, the following message file excerpt defines two message classes with prefixes U0 and U1:

"U0"= 0 
U0_BADVAL = Bad value
U0_WRONGDATE = Date must be with 30 days of current date
...
"U1" = 1
WRONGRATE = This is not the applicable rate.
...

Given these entries, you can issue a command that reads all messages in class 0 that begin with the prefix U0:

sm_msg_read ("U0", 0, MSG_FILENAME|MSG_NOREPLACE, "umsg.bin")

This command reads all messages in class 0, irrespective of prefixes:

sm_msg_read ("", 1, MSG_FILENAME|MSG_NOREPLACE, "umsg.bin")

When the message file is compiled with msg2bin, tags are used to distinguish between system and user messages. User-defined messages are numbered consecutively, starting with the class number times 0x1000. Unclassified messages are numbered from zero. For example, the fourth message in user class four is numbered 0x4004. As a developer, you must remember to maintain the order of user messages and the assignment of their identifiers.

Setting Message Display and Behavior Options

Several percent escape options let you control message content and presentation. The character or characters that follow the percent sign are case-sensitive; type them exactly as shown. This prevents conflicts with percent escape options used by printf and the tokens used by date/time formats. Some percent escape options must appear at the beginning of the message; others are valid only for display in a window or on the status line.

Table 45-1 summarizes the available escape sequences, followed by detailed information about each option.

Table 45-1 Percent escape options for messages

Option Description

%Ahhhh

Change display attributes. Valid for status line messages only.

%K

Display key label.

%B

Beep the terminal. This option must precede the message text.

%N

Use a carriage return in the message text. Forces message to display in popup window.

%W

Display message in a popup window.

%Md

Force the user to press the acknowledgment key (ER_ACK_KEY) in order to dismiss the error message. This option must precede the message text.

%Mt[time-out]

Force temporary display of message to the status line. Panther automatically dismisses the message after the specified timeout elapses and restores the previous status line display.

%Mu

Force message display to the status line and permit any key board or mouse input to serve as acknowledgment. Panther then processes the keyboard or mouse input. This option must precede the message text.

%A attr-value—Change display attributes
Valid only for status line messages, you can place %Aattr-value anywhere in the message text. It changes the display attributes of the text that follows it. attr-value is a four-digit hexadecimal value that represents one display attribute or the sum of two or more attributes.

If the string to get the attribute change starts with a hexadecimal digit (0...F), pad attr-value with leading zeros to four digits. Refer to Table 45-2 for valid attribute values.

Note: Monochrome terminals ignore color attributes. However, if you are developing for color terminals, include a color code with the %A. Otherwise, both the foreground and background colors default to black when the %A is not followed by a color code.

Table 45-2 lists the display attributes and their hexadecimal codes as defined in the include file smattrib.h.

Table 45-2 Display attributes and hexadecimal codes for status line messages

Foreground Attributes* Background Attributes

Attribute Mnemonic

Hex Code

Attribute Mnemonic

Hex Code

REVERSE

0010

B_HILIGHT

8000

UNDERLN

0020

BLINK

0040

HILIGHT

0080

DIM

1000

Foreground Colors

Background Colors

BLACK (colors are additive)

0000

B_BLACK

0000

BLUE

0001

B_BLUE

0100

GREEN

0002

B_GREEN

0200

CYAN

0003

B_CYAN

0300

RED

0004

B_RED

0400

MAGENTA

0005

B_MAGENTA

0500

YELLOW

0006

B_YELLOW

0600

WHITE

0007

B_WHITE

0700

NORMAL_ATTR

0007

B_CONTAINER (inherit color from container)

4000

*Attributes are additive. One or more foreground attributes can be added to a background attribute, foreground color and background color.

For example, the following message appears in red characters on the default black background with Warning. in blinking characters.

SM_WARNBIG= %A44Warning.\
%A0004Form is larger than screen size.

%B — Beep terminal
Place %B in a status line or message so that the terminal beeps via sm_bel when the message is displayed. This option must precede the message text.

%K—Display key label
Place %Klogical-key anywhere in the text of status line and error messages. Panther interprets logical-key as a mnemonic defined in smkeys.h. If the key translation file defines a key label for the logical key, the key label replaces the percent sequence in the message text. If there is no key label or no such logical key, %K is stripped off and logical-key remains in the message text.

Refer to page 6-2 in the Configuration Guide for more information about key translation files.

Figure 45-1 The key label is defined in the key translation file; the message file contains the message text. The result is displayed on the screen.

Note: If %K is used in a status line message, the user can push the corresponding logical key onto the input queue by mouse-clicking on the key label text.

%Md—Force user to acknowledge error message
Place %Md at the beginning of an error message so that the user is forced to press the predefined acknowledgment key ER_ACK_KEY to clear the message. If the user presses any other key, Panther displays an error message or beeps, depending on how application variable ER_SP_WIND is set. The keypress is not processed as data.

The %Md option corresponds to the default message behavior when application variable ER_KEYUSE is set to ER_NO_USE. If ER_KEYUSE is set to ER_USE—that is, your application default does not require use of the acknowledgement key—set %Md in a message in order to force the user to press the acknowledgment key to clear a message.

%M[time-out]—Display transient error message
Place %Mt at the beginning a transient status line message. Panther automatically dismisses the message after the specified timeout elapses and restores the previous status line display. Timeout specification is optional; the default timeout is one second. You can specify another timeout in units of 1/10 second with this syntax:
#(n)

where n is a numeric constant that specifies the timeout's length. If n is more than one digit, the value must be enclosed with parentheses. For example, this statement displays a message for 2 seconds:

msg emsg "%Mt(20)Changes have been saved to database."

The user can dismiss the message before the timeout by pressing any key or mouse clicking. Panther then processes the keyboard or mouse input. When the message is displayed in a window, users dismiss the message by choosing OK or by pressing the acknowledgement key; and Panther discards any keyboard input.

%Mu—Use any key to acknowledge error message
Valid only for error messages, you must place %Mu at the beginning of an error message. Panther forces message display to the status line and permits any keyboard or mouse input to serve as error acknowledgment. Panther then processes the keyboard or mouse input. In the following example, entering y or n acts as both message acknowledgment and data entry:
%MuPlease enter %Ky or %Kn into this field.

When the message is displayed in a window, users dismiss the message by choosing OK or pressing the acknowledgement key. Panther then discards any keyboard input.

%N—Insert line returns in message text
Insert one or more %N options in a message to force line returns in a windowed message. By default, message text wraps within the window.

%W—Display message in a window
Valid only for error messages, forces display in a window. Place %W at the beginning of the message.

Customizing Date and Time Formats

The Panther message file includes entries that establish date and time formats and text. It also includes substitution variables that the screen editor displays as options for a date/time widget's Format Type property.

Modify date/time entries in the message file for these reasons:

This section describes the tags and their default entries and how you can change the entries to meet the needs of both your development environment and your application.

Date/Time Defaults

When you choose Date/Time for the Data Formatting property of a widget, ten default choices for Format Type are available. The message file defines these format types: a name tag defines the name of a format type to appear on the Format Type option menu; and a corresponding format tag specifies the format associated with that name. For example FM_3MN_DEF_DT defines the name of the first format type as MON/DATE/YR4 HR:MIN2 and the corresponding format tag SM_3DEF_DTIME defines its format as %m/%d/%4y%h:%0M.

Table 45-3 lists the date/time name tags as delivered with Panther and their corresponding format type names, listed as they appear in the Properties window. The entries in Table 45-4 define the formats that correspond to the date/time tags and names in Table 45-3. (The tokens in the formats are defined in Table 45-5.)

Table 45-3 Default date/time entries

Date/Time tag Format type Formatting result

FM_3MN_DEF_DT

MON/DATE/YR4 HR:MIN2

4/1/2016 13:13

FM_4MN_DEF_DT

MON/DATE/YR4

4/1/2016

FM_0MN_DEF_DT

MON/DATE/YR2 HR:MIN2

4/1/16 13:13

FM_1MN_DEF_DT

MON/DATE/YR2

4/1/16

FM_2MN_DEF_DT

DEFAULT TIME

13:13

Tags FM_5MN_DEF_DT through FM_9MN_DEF_DT are undefined in the provided message file; The Format Type property displays them as DEFAULT5 through DEFAULT9; they have the same format specification as FM_5MN_DEF_DT. The corresponding formats are defined in the message file, as shown in Table 45-4.

Table 45-4 Default date/time formats

Date/Time format tag Tokenized format

SM_0DEF_DTIME

%m/%d/%2y %h:%0M

SM_1DEF_DTIME

%m/%d/%2y

SM_2DEF_DTIME

%h:%0M

SM_3DEF_DTIME

%m/%d/%4y %h:%0M

SM_4DEF_DTIME

%m/%d/%4y

SM_5DEF_DTIME

%m/%d/%2y %h:%0M

...

...

SM_9DEF_DTIME

%m/%d/%2y %h:%0M

Date/Time Tokens

When specifying a format in the message file or as an argument to the library functions sm_sdtime or sm_udtime, you must use some combination of tokens—not those in the Properties window (MON or DEFAULT5). In this way, Panther does not need to parse the message file, and the library functions can be used without knowing the names of substitution variables defined in the message file. When Panther performs date calculations using a format, it replaces tokens with their appropriate values. All other characters in the format such as, commas, slashes, and colons are used literally. If you wish to refer to one of the default format types, there are format tokens ranging from %0f to %9f that correspond to each of the format tags (SM_ date/time entries).

The tokens are listed in Table 45-5. Most of these substitute a numeric value; message entries are indicated for those that substitute text. For example, %4y might substitute 1999, whereas %*m would, depending on the date, substitute one of the values defined by SM_MONL1 through SM_MONL12, perhaps July, perhaps Juillet.

Table 45-5 Definitions of date and time tokens

Description Token Message entries for text

Year:

4 digit

%4y

2 digit

%2y (Use setup file to specify century break)

Month:

numeric (1 or 2 digit)

%m

numeric (2 digit)

%0m

abbreviated name (3 char)

%3m

SM_MONA1...SM_MONA12

full name

%*m

SM_MONL1...SM_MONL12

Day of the month:

numeric (1 or 2 digit)

%d

numeric (2 digit)

%0d

Day of the week:

abbreviated name (3 char)

%3d

SM_DAYA1...SM_DAYA7

full name

%*d

SM_DAYL1...SM_DAYL7

numeric

%.d

Day of the year:

numeric (1-366)

%+d

Time:

hour (1 or 2 digit)

%h

hour (2 digit)

%0h

minute (1 or 2 digit)

%M

minute (2 digit)

%0M

second (1 or 2 digit)

%s

second (2 digit)

%0s

AM and PM

%p

SM_AM, SM_PM

Ten default formats:

  1. formats specified in message file entries*

  1. %0f - %9f

  1. SM_0DEF_DTIME to SM_9DEF_DTIME

  1. Other:

  1. literal percent sign

  1. %%

  1. *Tokens provided so default formats can be used with library functions sm_sdtime and sm_udtime.

Creating Date and Time Defaults

Ten date and time entries are available to define formats and the names that specify them. The tokens for SM_5DEF_DTIME through SM_9DEF_DTIME are defined to have the same format as SM_0DEF_DTIME. You can use these additional tags to create and name your own date/time formats.

How to Change or Create a Default Date/Time Format
  1. Open the ASCII version of the message file with a text editor.
  2. Change one of the SM_ date/time entries (SM_0DEF_DTIME through SM_9DEF_DTIME) to define the desired format.

    For example, the DEFAULT5 substitution variable has this initial format:

    SM_5DEF_DTIME =  %m/%d/%4y %h:%M0
    You can change this entry as follows:
    SM_5DEF_DTIME =  %d %*m %4y %h:%M0 %p

    Widgets that have their date Format Type property set to DEFAULT5 display dates in the format:

    30 November 2016 3:40 PM
  3. Create the substitution variable with the corresponding FM_ tag:
    FM_5MN_DEF_DT = DATE and TIME
    DATE and TIME appears as an option for the Format Type property. 

    A widget whose Format Type is set to DATE and TIME displays dates in this format:

    30 November 2016 3:40 PM
  4. Convert the ASCII message file to binary format with the msg2bin utility.

    Note: Tokens are provided (refer to Table 45-5) that correspond to each of the default formats so that these defaults can be used with the library functions sm_sdtime and sm_udtime.

Defaults for Non-English Applications

To customize the date and time entries in the Panther message file for non-English applications, you can:

By translating text and changing formats, widgets using the Format Type specification described in the example shown earlier on page 45-16, DEFAULT5 might appear as:

30 Novembre 2016  3:40 PM

To develop an application for French users, translate the text assigned to SM_DAYA1...SM_DAYA7, SM_DAYL1..SM_DAYL7, SM_MONA1...SM_MONA12, and SM_MONL1...SM_MONL12, like this:

SM_DAYA1  =  Dim
SM_DAYA2 = Lun
SM_DAYA3 = Mar
...
SM_DAYL3  =  Mardi
SM_DAYL4 = Mercredi
SM_DAYL5 = Jeudi
SM_DAYL6 = Vendredi
SM_DAYL7 = Samedi
...
...
SM_MONA1  =  Jan
SM_MONA2 = Fév
SM_MONA3 = Mar
...
SM_MONL7 = Juillet
SM_MONL8 = Août
SM_MONL9 = Septembre
SM_MONL10 = Octobre
SM_MONL11 = Novembre
SM_MONL12 = Décembre

This method can be useful if you are distributing the same application to users who speak different languages. A user's SMMSGS variable in the local setup (smvars) file or system environment can specify the name of the appropriate message file and screen libraries. Date/time fields then display the date in a language and format familiar to the user, while all programming code remains independent of the user's language.

Translating Defaults for Developers

In addition to translating the text for days of the week and months of the year, and localizing formats, you can translate the names of substitution variables for non-English speaking developers, These entries are adjacent to each other in the Panther message file, beginning with FM_YR4 and ending with FM_9MN_DEF_DT.

For example, you might provide these entries for French-speaking developers:

FM_YR4  =  ANNÉE4
FM_YR2  =  ANNÉE2
FM_MON  =  MOIS
FM_MON2 =  MOIS2
FM_DATE =  JOUR
...

Given these changes, French-speaking developers using Panther can create date/time formats using substitution variables in their native language—MOIS2, ANNÉE4, and JOURA, while Spanish-speaking developers might use substitution variables like MES2, AÑO4, and DÍAA.

Literal Dates in Calculations

The Panther message file includes an entry to specify the format of literal dates used in @date calculations. The tag SM_CALC_DATE specifies the format. The default format is %m/%d/%4y (MON/DATE/YR4). For example, to count the number of days until the millennium, the library function sm_calc can be used with a literal date:

sm_calc (0,0,'days = @date(1/1/2000)- @date(today)');

Numeric Formats

When you choose Numeric for the Data Formatting (data_formatting) property of a widget, ten default choices for Format Type (numeric_type) are made available to you. The message file contains the definitions for these format types: A name tag defines the name of a format type to appear for the Format Type property in the Properties window, and a corresponding format tag specifies the format associated with that name. For example SM_0MN_CURR_DEF defines the name of the first format type as Local Currency and the corresponding format tag SM_0DEF_CURR defines its format as ".22,l$".

You can modify the message file to store ten different default numeric formats. Like the date/time message entries, one entry (SM_0DEF_CURR through SM_9DEF_CURR) defines the format, and a corresponding entry (SM_0MN_CURRDEF through SM_9MN_CURRDEF) specifies what the screen editor displays as options for a numeric widget's Format Type (numeric_type) property.

Numeric Format Syntax

Numeric formats are defined as r m x t p c c c c c:

r

Radix separator or decimal symbol (usually a period or comma)

m

Minimum number of decimal places

x

Maximum number of decimal places

t

Thousands' separator (i.e., a comma or period; b for a blank)

p

Placement of currency symbol (l = left, r = right, or m = middle)

ccccc

Currency symbol (up to 5 characters, including blank spaces)

To specify leading or trailing blanks in a format, enter blank spaces before or after the currency characters. The spaces become a part of the currency symbol.

For example, the format .22,l$ contains these specifications:

Formats in Provided Message File

Table 45-6 lists the numeric tags as delivered with Panther, their format type name, and the corresponding format tag and the default format. Description names are defined only for the first three format types. (Names for format types default to \Qdefault'). The last seven names and formats are for other types you can custom define. Therefore, the last seven format types are defined identically to SM1_DEF_CURR, which is set to two decimal places with a comma as the thousands separator.

Table 45-6 Default message entries for defining numeric formats

Numeric tag Format type name Corresponding format tag Default format

SM_0MN_CURRDEF

Local Currency

SM_0DEF_CURR

".22,l$"

SM_1MN_CURRDEF

2 decimal places with commas

SM_1DEF_CURR

".22,"

SM_2MN_CURRDEF

0 decimal places with commas

SM_2DEF_CURR

".00,"

SM_3DEF_CURR

".22,"

SM_4DEF_CURR

".22,"

...

...

SM_9DEF_CURR

".22,"

SM_0MN_CURRDEF defines the name of the format type as Local Currency, and the corresponding format tag SM_0DEF_CURR defines its format as ".22,l$". A widget with this property specification would have data formatted, for example, as $5,100.75.

Creating a Default Numeric Format

A message file can specify ten numeric format entries. You can change any or all formats to suit your application's requirements. To create a numeric format:

How to Customize a Default Numeric Format
  1. Open the ASCII version of the message file with a text editor.
  2. Change one of the SM_ numeric entries (SM_0DEF_CURR through SM_9DEF_CURR) to define the desired format.

    To specify leading or trailing blanks in a format, enter blank spaces before or after the currency character. The spaces become a part of the currency symbol.

    For example, you can add a format for the French franc with this change:

    SM_9DEF_CURR = ',22.r F'
  3. Add a descriptive definition in the corresponding SM_ numeric entry. For example:
    		SM_9MN_CURRDEF = Franc

    The Format Type property in the Properties window will display Franc as one of the values you can assign to a widget with numeric data.

  4. Convert the ASCII message file to binary format with the msg2bin utility.

    Given the previous definition, the Format Type property in the Properties window displays Franc as one of the values you can assign to widgets with numeric data. Widgets thus formatted show currency data in the form:

    999.999,99 F.

Translating Defaults for Developers

In addition to modifying the numeric formats to comply with local customs, you can translate the names that appear on the numeric format type property menu for non-English speaking developers. The first three entries are adjacent to each other in the Panther message file, beginning with SM_0MN_CURRDEF and ending with SM_3MN_CURRDEF.. SM_4MN_CURRDEF through SM_9MN_CURRDEF are also available variables but not predefined in the message file.

For example, you might provide these entries for Spanish-speaking developers:

SM_0MN_CURRDEF = DINERO
SM_1MN_CURRDEF = NUMERO

Given these changes, Spanish-speaking developers see format type choices in their own language.

Decimal Symbols

Via the message file tag SM_DECIMAL you can define a default decimal symbol (or radix separator). When you define a widget to have or accept numeric data, you can also specify any decimal symbol (or radix separator). However, the SM_DECIMAL entry enforces a default symbol. If SM_DECIMAL is not specified in the message file, Panther tries to determine the appropriate symbol from the operating system.

Panther accommodates three types of decimal symbols. These decimals differ in scope and function.

system
The character that is used by the operating system when translating characters to internal values or vise versa—for example, in C routines atof, sprintf. The default is period.

Note: Setting the system decimal symbol incorrectly can cause unexpected results when Panther processes numeric values.

local
Defined by the message file entry for SM_DECIMAL, by default set to period. This setting overrides the system symbol within a Panther application. Set SM_DECIMAL according to local customs—for example, period in English-speaking countries; comma in Europe. If the system and local symbols are different, Panther translates appropriately when interacting with system routines.

widget
Set for a specific widget through its decimal_symbol property (refer to on page 10-20 in the Using the Editors). This symbol is used only for data entry validation and for displaying widget values. Use widget-level decimal symbols when you need to handle multiple decimal conventions within a single application.

Customizing Push Button Labels for Message Boxes

The message file tags SM_MB_OKLABEL through SM_MB_HELPLABEL provide the text for message box push buttons.

Note: Microsoft Windows for other languages automatically translates standard push buttons to the appropriate language.

How to Change/Translate Push Button Labels

  1. Access the ASCII version of the message file with a text editor.
  2. Change the label text. Place an ampersand before the character to serve as the push button's key mnemonic.
  3. Convert the ASCII message file to binary format with msg2bin.

For example, if you were converting your application to Spanish, you might include the following in your message file:

SM_MB_OKLABEL      =  &Ok
SM_MB_CANCELLABEL = &Cancelar
SM_MB_YESLABEL = &Si
SM_MB_NOLABEL = &No
SM_MB_RETRYLABEL = &Re-intentar
SM_MB_IGNORELABEL = &Ignorar
SM_MB_ABORTLABEL = A&bortar
SM_MB_HELPLABEL = &Ayuda

Setting Yes/No Values

The values associated with the message tags SM_YES and SM_NO can be translated or standardized to meet your development or application's requirements. For example, you can translate the value for SM_YES to s (short for sí) for Spanish-speaking users.

Library functions such as sm_is_yes, and properties such as keystroke filter that use the SM_YES and SM_NO entries expect and return the appropriate character as defined in the message file. In the case of a Spanish-speaking user, entering s (for an affirmative response) is recognized, whereas y is ignored.

Using Alternate Message Files

The SMMSGS application variable specifies the binary file to read into memory at Panther's initialization. If you serve an international market, you can give users the option of selecting from alternate message files. At runtime the user can set the SMMSGS for the binary message file that is appropriate to his/her language.

Alternative files for an application (and for non-English versions of Panther) must be identical in terms of the number and sequencing of all messages (refer to page 45-4 for information about adding messages).


Configuration Map File

The configuration map file contains definitions for screens and widgets—colors, fonts, lines and box styles—that you can tailor to different platforms. The file is divided into several sections:

By defining these elements in GUI-specific files and using their names for screen and widget properties, you can create applications that are easy to port across different platforms. Instead of creating multiple instances of the same screens or reports that use GUI-specific font and color names, you can create multiple configuration map files—one for each platform on which your applications run. For example, you can create a color alias PanicButtonRed that resolves to different colors in different configuration maps.

Panther is installed with at least one configuration map file (*cmap) that suits your environment. You can edit these or create your own with an ASCII text editor, then run the utility cmap2bin to convert it to binary format.

During initialization, Panther looks for the application variable SMCOLMAP which can be defined in the environment or in an SMVARS file. This variable gives the full path name of the binary configuration map file.

Defining Colors

When you create a screen or widget, the screen editor seeks default color settings, or a scheme, for that object's type, foreground and background. The editor automatically sets the color property to Scheme and then resolves the scheme, looking first in the configuration map file. If the file provides no scheme for the object, the editor looks elsewhere for color defaults (refer to page 45-30).

Panther provides configuration map files with default schemes for screens and for each widget type. You can define your own color schemes that suit your environment, style preferences, or development and application requirements. Or you can rely on the local GUI to assign colors to your application objects.

You can set the Color Type property to one of these three settings:

Defining Color Aliases

The [Colors] section defines GUI-independent color aliases that you can use in the Color Name property of screens and widgets. All color names, including Panther palette color names like hilight_red, must be added to the list of color aliases. Each entry appears on its own line in the following format: aliasColor = color

aliasColor
Any name you choose to identify a color.

color
One of the following:

The keyword CONTAINER specifies that a widget within another object has the same background color as the container. Therefore CONTAINER cannot be used to specify a foreground color. Also, because CONTAINER may contain attributes, you cannot specify any additional attributes with it.

Editor Colors

A number of predefined color aliases control the editor's appearance. All editor color aliases begin with se; entries use the same format as user-defined colors. For example, this entry in a Windows configuration map file sets the background color of the design screen:

seFormBg = "127/255/0"

Table 45-8 lists screen editor color aliases and the objects whose appearance they control:

Table 45-8 Screen editor object constants (object keywords are case sensitive)

Color alias Description

seBorderFG

Editor windows border foreground.

seCheckFG

Property window option menu foreground.

seEntryFG

Property window text field foreground.

seFormBG

Editor windows background.

seLabelFG

Label foreground.

seListBG

List background (except for Property window).

seListFG

List foreground (except for Property window).

seMultiBG

Multiline text background.

seMultiFG

Multiline text foreground.

seOptionmenuBG

Option menu background.

sePushBG

Push button background.

sePushFG

Push button foreground.

sePwListBG

Property window list background.

sePwListFG

Property window list foreground.

seTbBorderFG

Tool box border foreground.

seTbFormBG

Tool box background.

seTbTogFG

Tool box toggle button foreground.

seTextBG

Text background.

Sample Colors Section

The following examples are from ASCII configuration map files; the aliases ensure that colors specified for one platform display correctly on others without editing Color Name properties of application components. Given the appropriate configuration map file, an application displays colors that are correct for its environment.

The [Colors] section in the Motif configuration map defines these color aliases:

Slate Gray   = "#708090"
Olive Drab = "#6B8E23"
ButtonBlue = "#0938EE"

For character mode, the [Colors] section redefines these aliases with Panther color names:

Slate Gray   = HILIGHT WHITE
Olive Drab = GREEN
ButtonBlue = BLUE

For a Windows configuration map, these aliases are redefined with RGB values:

Slate Gray   = "112/128/144"
Olive Drab = "107/142/35"
ButtonBlue = "09/38/240"

If you specify Slate Gray on the three platforms, the correct color is displayed. If you alias the Motif color to map to a Panther-specific color, you ensure that when your application runs in character-mode Panther, Slate Gray is displayed as the Panther color hilight white.

Defining Color Schemes

You can decide on a set of default colors for each newly created object in the screen editor. When the Color Type property is set to Scheme, Panther uses the configuration map file to resolve the object's foreground and background colors, according to its type.

The Schemes section of the configuration map file can include explicit settings or defer to the GUI's resource database or initialization file.

Default Schemes

If the configuration map file omits a [Schemes] section, Panther uses the following default schemes:

Scheme Syntax

Each entry in the[Schemes] section appears on its own line in the following format:

object = color

object
Any widget type, including lines and boxes, screen, and borders, followed by either a foreground (FG) or background (BG) mnemonic; for example, ToggleButtonFG and ListBoxBG. Refer to Table 45-9 for a list of valid object specifications.

color
One of the following specifications:

Defining Line and Box Styles

[Lines] section entries map character-mode styles for lines and boxes to GUI styles. Character-mode line and box styles are defined in the box and border entries of your terminal's video file.

Each entry appears on its own line in the following format:

styleName = styleContent

styleName
A predefined or new style name. Spaces are allowed and case is irrelevant.

styleContent
A predefined style name or another alias style name defined in this file. Spaces are allowed and case is irrelevant. Currently supported predefined style names include:

Dash Dashdot Dashdotdot Default

Dot

Double Dash

Double

Etched In

Etched In Dash

Etched Out

Etched Out Dash

In

None

Out

Single

Style 0

Style 1

...

Style 9

You can use this section of the configuration map file to assign the styles 0 through 9 to GUI-specific line styles. For example, you might define the following entries for Motif:

[Lines]
style 0 = etched in
style 1 = etched out

These entries tell Panther for Motif that when to interpret style 0 as an alias for etched in, and style 1 as etched out.

Character Mode Styles

Styles 0 through style 9 are native to Panther running in character mode. Style 1 is defined as the default line style. When you assign a character-specific style as the Style property value for a line or box style in the screen editor, that style is mapped to style 1 on non-character Panther applications. GUI-specific styles map to style 1 when running in character mode.

GUI Styles

The default line and box style for all GUI platforms is etched in. Table 45-10 shows which styles are supported by different platforms, and how Panther displays styles that are undefined or are not supported by the GUI. Supported styles are represented by asterisks (*). Because Windows supports the same styles for lines and boxes, the table does not differentiate between these two widgets; however, Motif supports a different set of styles for each widget type, so these are depicted separately.

Note: Under Windows, screens that have their 3D property set to No display Etched In and Etched Out as single lines.

Table 45-10 Mapping of Panther line and box styles on GUI platforms

Line styles Windows Motif line Motif box

Default

etched in

etched in

etched in

Style 0

single

no line

etched in

None

single

no line

etched in

Styles 1-9

single

etched in

etched in

Etched In

*

*

*

Etched In Dash

dash

*

etched in

Etched Out

*

*

*

Etched Out Dash

dash

*

etched in

Single

*

*

etched in

Dash

*

*

etched in

Dot

*

dash

etched in

Dashdot

*

dash

etched in

Dashdotdot

*

dash

etched in

In

single

etched in

*

Out

single

etched out

*

Double

single

*

etched in

Double Dash

single

*

etched in

* Style is supported by the GUI platform.

To control mapping, assign the desired specification in the configuration map file.

Setting Display and Printing Fonts

Display font defaults and aliases are defined in a single section—[Windows Fonts] for Windows and [Display Fonts] for other platforms.

Font defaults and aliases for printed reports are defined in one of four sections: in the [Windows Fonts] font display section for output from Windows print drivers, a [Postscript Fonts] section for PostScript and PDF output, a [PDF Fonts] section for PDF output, and a [Text Fonts] section for ASCII output. For more information about how to use fonts in reports, refer to page 8-11 in Reports.

Entries in these sections let you:

Point Sizes

You can specify the point sizes that appear on the Point Size property's drop-down menu with an entry that has this format:

point_sizes = size[ size]...

For example:

point_sizes = 8 9 10 12 14 16 18 20 24 36 48 72

Note: Panther uses the point_sizes entry only for scalable fonts. For a non-scalable font, Panther gets its available sizes from the GUI and displays these on the drop-down menu.

Default Font

You can specify the application-wide font that Panther applies when you accept Default for a screen's Font Name property with an entry that has this format:

default_font = font-spec

font-spec is a font specification that is valid for this configuration map file's environment.

For applications running on Windows, specify the font name only. For example:

default_font = Arial

For Motif applications, specify fonts with the XLFD font naming convention; substitute the wildcard character * for all weight, slant, and size properties. For example:

default_font = -*-Helvetica-*

For the PDF driver, you must specify the name of the TrueType or Type 1 font file. The file name's extension will be used to determine the type of font. The extension must be .ttf for TrueType fonts and either .pfa or .pfb for Type 1 fonts. For Type1 fonts, there must also be the corresponding .afm file in the same directory. For example, in Windows,

default_font = c:\windows\Fonts\times.ttf

and in Linux or UNIX,

default_font = /usr/share/fonts/default/Type1/n021003l.pfb

Note: At runtime, Panther uses the default font for any font specification that it cannot resolve.

Default Font Size

The default_point_size entry specifies the application-wide font size that Panther applies when you accept Default for a screen's Font Size property. Use the format:

default_point_size = size

Panther Font Aliases

Panther font aliases are especially useful in an application's portability across platforms. Each platform has its own configuration map, and Panther font aliases map to local font specifications. Panther font aliases appear on the Font Name property's drop-down menu. In GUI environments, Panther resolves these with the names of fonts supplied by the GUI itself.

Each Panther font alias is defined with the following format:

aliasName [(fontQualifier...) ] = fontSpec 
[[ (fontQualifier...) ] = fontSpec]...

You can specify different qualifiers for the same font alias on separate lines, and thereby map it to unique font specifications. For example, the following definition uses different qualifiers to map the Prolifics font Helvetica to two different fonts, depending on whether the Italic property is set:

Prolifics Helvetica (noitalic) = Arial
(italic) = ArialItalic

If more than one entry matches a widget's properties, the first matching entry determines which font is displayed.

The following sections discuss each component of a font definition.

aliasName
The name that you choose to identify a font alias. Panther font aliases are defined in the configuration map file. They appear before the GUI-specific font specifiers in the Font Name property option menu.

fontQualifier
Optionally limits usage of aliasName to those objects that also use the specified qualifiers. You can AND together space-delimited font qualifiers from each of the following columns, in any order:

bold

italic

underline

pointSize[ pointSize ]...

nobold

noitalic

nounderline

For example, a Windows configuration map file might contain two definitions for the Helvetica font, the first qualified, the second unqualified:

Prolifics Helvetica (italic 12 14) = ArialItalic 
= Arial

If a widget's Font Name property is set to Prolifics Helvetica, Panther uses Arial unless two other conditions are also true: the Italic property is set to Yes, and the Point Size property is set to either 12 or 14. In this case, Panther uses ArialItalic.

Point size qualifiers can limit the number of choices available in the Point Size property's option menu. For example, given the following Windows font definition, choosing Prolifics Times Roman as a widget's Font Name property limits the choices on the Point Size drop-down menu to Default, 8, and 10:

Prolifics Times Roman (8 10) = Times New Roman

Note: Point size qualifiers are used on the Point Size property's option menu only if they are valid for the selected font.

fontSpec
fontSpec maps the font name to a font supported by the GUI environment. For applications running on Windows, specify fonts with this syntax:
fontname[-point-size] [-bold] [-italic] [-underline]

For example:

Prolifics Helvetica    = Arial-14-bold 
Data Entry Text = Arial

For Motif applications, specify fonts with the XLFD font naming convention:

-foundry-family-weight-slant-width-style-pixel size 
-point size-x resolution-y resolution-spacing
-average width-charset registry-charset encoding

You can substitute any component in an XLFD font name with the wildcard character *. For example:

Prolifics Courier          = -*-courier-*-r-* 
Prolifics Courier (italic) = -*-courier-*-o-*

If fontSpec omits values for point size, slant, or weight, Panther supplies these values from the corresponding property settings—Point Size, Italic, and Bold. For example, the following entries for the Prolifics Helvetica font—each in separate configuration map files for Windows and Motif—specify only the font's family name:

Prolifics Helvetica  = Arial 
Prolifics Helvetica = -*-helvetica-*
Prolifics Helvetica = helvetica

Given these definitions, any widget using Prolifics Helvetica as its font can also have its Point Size, Bold, and Italic properties set; these properties are used to resolve the displayed font. So, if the widget's Bold and Italic properties are set to Yes, Panther resolves the Prolifics Helvetica to Arial-bold-italic on Windows and -*-helvetica-bold-i-* in Motif, and passes on these specifications to their respective GUIs.

Conversely, these definitions of a font named s HelvBold sets its weight to bold:

HelvBold = Arial-bold
HelvBold = -*-helvetica-bold-*

The explicit weight specifications for HelvBold override the Bold properties for a widget that uses this font; the font is always displayed as bold.

For the PDF driver, you must specify the name of the TrueType or Type 1 font file. The file name's extension will be used to determine the type of font. The extension must be .ttf for TrueType fonts and either .pfa or .pfb fir Type 1 fonts. For Type1 fonts, there must also be the corresponding .afm file in the same directory. For example, in Windows,

Prolifics Courier = c:\windows\Fonts\cour.ttf

and in Linux or UNIX,

Prolifics Courier = /usr/share/fonts/default/Type1/n022003l.pfb

Sample Configuration Map File

The following configuration map file defines colors, fonts, and line styles for Windows applications.

[Colors]
grape           = MAGENTA       # Prolifics color
Aquatic Blue = "64/32/200" # Windows-style RGB value
# The following entries in the color map are for use in the
# screen editor. If you remove them entirely, then SCHEME
# colors are used, which may be desirable in Windows.
#seFormBG       = GUI WindowBackground
#seBorderFG = Unused by Pi for Windows
#seLabelFG = GUI WindowText
#sePushFG = GUI ButtonText
#sePushBG = GUI ButtonFace
#seEntryFG = GUI WindowText
#seMultiFG = GUI WindowText
#seMultiBG = GUI WindowBackground
#sePwListFG = GUI WindowText
#sePwListBG = GUI WindowBackground
#seListFG = GUI WindowText
#seListBG = GUI WindowBackground
#seCheckFG = GUI WindowText
#seOptionmenuBG = GUI WindowBackground
#seComboboxBG = GUI WindowBackground
#seTextBG = GUI WindowBackground
# The following definitions are for the tool box
seTbFormBG      = BLACK
#seTbBorderFG = Unused by Pi for Windows
#seTbTogFG = Unused by Pi for Windows
[Schemes]
#OUTPUTFG       = GUI WindowText
#TEXTFG = GUI WindowText
#MULTITEXTFG = GUI WindowText
#PUSHBUTTONFG = GUI ButtonText
#TOGGLEBUTTONFG = GUI ButtonText
#RADIOBUTTONFG = GUI WindowText
#OPTIONMENUFG = GUI WindowText
#COMBOBOXFG = GUI WindowText
#LISTBOXFG = GUI WindowText
#SCALEFG = GUI WindowText
#LABELFG = GUI WindowText
#BOXTOPFG = GUI WindowText
#LINEFG = GUI WindowFrame
#CHECKBOXFG = GUI WindowText
#FORMBORDERFG = Unused by Pi for Windows
GRAPHFG = BLACK
#GRIDFG = GUI WindowText
#FORMBG = GUI WindowBackground
OUTPUTBG = CONTAINER
#TEXTBG = GUI WindowBackground
#MULTITEXTBG = GUI WindowBackground
#PUSHBUTTONBG = GUI ButtonFace
#TOGGLEBUTTONBG = GUI ButtonFace
RADIOBUTTONBG = CONTAINER
#OPTIONMENUBG = GUI WindowBackground
#COMBOBOXBG = GUI WindowBackground
#LISTBOXBG = GUI WindowBackground
SCALEBG = CONTAINER
LABELBG = CONTAINER
#BOXTOPBG = CONTAINER
#LINEBG = Unused by Pi for Windows
CHECKBOXBG = CONTAINER
#FORMBORDERBG = Unused by Pi for Windows
#GRAPHBG = CONTAINER
#GRIDBG = CONTAINER
ACTIVEXBG = CONTAINER
#CARDBG = Unused by Pi for Windows
#DECKBG = Unused by Pi for Windows
[Lines]
Style 1 = Single
MyFavoriteStyle = Double
[Windows Fonts]
# Point Size property drop-down
point_sizes = 8 9 10 12 13 14 16 18 20 22 24 26 28 36 48 72
# Application defaults for Font Name and Point Size
# properties
default_font       (print)   = Times New Roman
default_point_size (print) = 10
# Font Name             Qualifiers   Windows font
# ------------------- ---------- ------------
Prolifics Courier = Courier New
Prolifics Times Roman = Times New Roman
Prolifics Helvetica = Arial
Prolifics Symbol = Symbol
[PostScript Fonts]
# Rules in this section apply only to ReportWriter's editor and
# printed output.
# Point Size property drop-down
point_sizes = 8 9 10 11 12 13 14 16 18 20 22 24 26 28 36 48 72
# Application defaults for Font Name and Point Size properties
default_font                    = Times-Roman
default_point_size = 10
 
# Font Name           Qualifiers      PostScript font
# --------- ---------- ---------------
Prolifics Courier (italic bold) = Courier-BoldOblique
(italic) = Courier-Oblique
(bold) = Courier-Bold
= Courier
Prolifics Times Roman (italic bold) = Times-BoldItalic
(italic) = Times-Italic
(bold) = Times-Bold
= Times-Roman
Prolifics Helvetica   (italic bold) = Helvetica-BoldOblique
(italic) = Helvetica-Oblique
(bold) = Helvetica-Bold
= Helvetica
Prolifics Symbol                    = Symbol
[Text Fonts]
# Rules in this section apply only to ReportWriter's editor and
# printed output.
 
# Point Size property drop-down
point_sizes = 8 10 12 16 24 36
 
# Application defaults for Font Name and Point Size properties
default_font                 = Times
default_point_size = 10
 
# Font Name           Qualifiers       Text Font
# --------- ---------- ---------
Prolifics Courier (10 italic) = Courier_i_10
Prolifics Courier (10 bold) = Courier_b_10
Prolifics Courier (10) = Courier_10
Prolifics Courier (italic) = Courier_i
Prolifics Courier (bold) = Courier_b
Prolifics Courier = Courier
Prolifics Times Roman (24 italic bold) = Times_i_b_24
Prolifics Times Roman (24 italic) = Times_i_24
Prolifics Times Roman (24 bold) = Times_b_24
Prolifics Times Roman (24) = Times_24
Prolifics Times Roman (18 italic bold) = Times_i_b_18
Prolifics Times Roman (18 italic) = Times_i_18
Prolifics Times Roman (18 bold) = Times_b_18
Prolifics Times Roman (18) = Times_18
Prolifics Times Roman (10 italic bold) = Times_i_b_10
Prolifics Times Roman (10 italic) = Times_i_10
Prolifics Times Roman (10 bold) = Times_b_10
Prolifics Times Roman (10) = Times_10
Prolifics Times Roman (italic bold) = Times_i_b
Prolifics Times Roman (italic) = Times_i
Prolifics Times Roman (bold) = Times_b
Prolifics Times Roman = Times
Prolifics Helvetica                    = Helvetica
Prolifics Symbol                       = Symbol

Translating Applications

Panther provides the following capabilities for modifying application for international usage:

You can also use the Panther message file to set date and time formats (page 45-17) and currency formats (page 45-19) to conform to local usage.

8-Bit Character Data

Panther supports 8-bit character data. Video files specific to the terminal can give special instructions, if necessary, on how to display international characters. This is needed if the terminal requires shifting to a different character set to display non-ASCII characters. Most terminals used in the international market do not need to shift character sets.

The video file can also be used to translate between two different standards for international characters. Thus, screens can be created with one standard and displayed using a different one.

The use of 8-bit characters for international symbols does not necessarily preclude use of graphics in character-mode applications. Unused entries in a character set, such as 0x01 through 0x1f or 0x80 through 0x9f, can be mapped to line graphics symbols.

Unless a widget has a keystroke filter, Panther ignores the characters that are entered into it from the keyboard. Internally, it only manipulates numbers. Cursor control keys such as arrows and TAB, and function keys are all assigned logical values that are outside the range 0x00 to 0xff, and thus cannot conflict with international characters.

Keyboards that support international character sets usually produce a single 8-bit byte (perhaps with the high bit set) for each character. However, some terminals generate a sequence to represent an international character. If so, you can use a text editor to map the byte sequences to a logical value, just as the video file is used to map the logical value to the sequence required by the display terminal.

For more information on how to display non-English characters or to receive them from the keyboard, refer to page B-1 in the Upgrade Guide.

Translating Screens in Application Programs

There are a number of approaches to translating your application screens. If your application requires translation for international distribution, consider the following questions:

The answers to these questions determine which method to use. In any event you must provide the translator with the information that needs to be translated, and pictures of the screens to provide some context. In addition, screen size and spacing should be considered when translating screens to other languages.

There are essentially three different approaches you can take to provide an application to a multilingual audience. Each approach requires some up-front planning, and some development strategy. The localization process can be performed at:

There are probably several ways to approach the development of a product that needs to be translated and distributed in multiple languages. One of the most obvious methods is to simply translate application screens to each of the languages that you support.

Language-specific screens can be released in a variety of ways, regardless of when the localization process takes places. For example, you can create multiple libraries; each one contains a set of screens translated to a specific language. By setting the SMFLIBS application variable either at distribution, installation, or runtime, you or a user can access the desired language-specific library.

The following sections describe other methods to consider when you develop an application.

Distribution Translation

A distribution translation means that when the application leaves your facility, it is released with a specific set of screens. The end user receives exactly what you send.

Method One
Develop language-specific repositories. At distribution time, use the binherit utility to update the content of each screen by using the appropriate repository for the required language.

Method Two
At design time, define the initial text for all widgets as a variable or token, for example %Name%, %Address%, etc. When the screens are completed, use the f2asc utility to convert the binary screens to ASCII format. Provide your translator with the tokenized references. Then develop a translation script that will search the ASCII file and replace the token with the translated constant. The function of the translation utility would be to find and replace tokenized text, replacing %Name% with Name for English, or Nom for the French version.

Each ASCII translation can be easily maintained and updated as screens change.

After the ASCII translations are made, they can be converted back to screens in binary format with f2asc and distributed accordingly.

This method has these advantages and disadvantages:

Advantages

File naming conventions can be adhered to across all libraries.

Screen dimensions and widgets can be easily adjusted and repositioned to accommodate languages and sentence structure that might require more space on a screen.

Adding a new language only requires a new translation.

Drawbacks

Maintenance of many different languages can be time consuming.

You must distribute more than one library to an end user who requires more than one language.

Languages cannot be changed dynamically at runtime.

Installation Translation

In an installation translation, the application is packaged with more than one language and the desired language is installed. You can provide an installation mechanism that lets the user set SMFLIBS to point to and open a library of language-specific screens.

This method has the advantage of letting users decide which language to install. On the other hand, it requires disk space to accommodate storage of multiple sets of screens; and languages cannot be changed dynamically at runtime.

Runtime Translation

In a runtime translation, users can dynamically change languages at runtime. Depending on their requirements, users might only need to select a preferred language at start up, or they might need to change languages during a session.

Method One
A start up method can be implemented in the same way described for an installation translation: you provide a mechanism that lets users choose which language to display. For example, a logon screen can provide radio buttons that correspond to each supported language, so users can choose the desired language. Their choice sets SMFLIBS to point to and open the appropriate library of screens.

This method has the advantage of allowing multilingual organization to run the application easily; users choose their preferred language without requiring reinstallation of the software.

This method has one possible drawback, that installation requires enough disk space to accommodate all translated screens.

Method Two
Design your screens to include all translations in one screen binary. You can do this by creating dynamic labels as scrolling arrays with only one onscreen occurrence, and then synchronizing all the label arrays on the screen, you can provide an occurrence for each language you support. The user, via a programmatic call, can scroll the array to the language of choice. For example, the third occurrence might be Italian, while the fourth occurrence is Japanese. So, if the user chooses Italian, via a screen entry function the third occurrence is displayed. If Japanese is specified, the labels can be programmatically scrolled to the fourth occurrence and so on.

This method has two advantages: