Configuration Guide


Chapter 2 . Application Variables

Panther application variables can be divided into two general categories:

Unless otherwise indicated, the variables described in this chapter are valid for Panther applications running in all operating environments. Panther has other variables that are applicable to specific operating environments, such as web applications, and character-mode or GUI platforms such as Windows or Motif. These variables are described later in this manual, in one of the chapters that pertain to the supported environments.

The first section of this chapter shows how to set application variables. Variable descriptions follow, organized according to category.


Setting Application Variables

Application variables are set at application startup and affect the entire application. Most are internally set. You can either accept the default settings or explicitly set them yourself in any of these locations, listed in descending order of precedence:

  1. The system's environment.
  2. Windows initialization file or Motif resources file.
  3. The setup file named by the SMSETUP variable.
  4. The setup file named by the SMVARS variable. (If SMVARS is not set, Panther expects to find smvars.bin in the config subdirectory.)

Thus, if the application variable SMEDITOR is set in the SMSETUP file and the Windows initialization file, Panther uses the initialization file setting.

Setup Files

You can create or edit a setup file with any text editor. The Panther distribution contains thesmvars setup file in its config directory, which you can copy and modify. After you modify setup files, you must convert them to binary format with the var2bin utility.

After you create a setup file and convert it to binary format, set the SMVARS variable to the name of the binary file. If you supplement the SMVARS file with another setup file, you should set the SMSETUP variable to the name of that file.

SMSETUP settings supersede SMVARS settings. Use the SMSETUP file for variable settings that are specific to a particular terminal-type, project, or user. SMVARS typically contains application-wide settings that should be true for all users.

Depending on your platform, you can set an application's SMVARS variable in its environment and in its Windows initialization file. SMSETUP is typically set in the SMVARS file.

Setup File Syntax

Setup file entries use this format:

variable = value

value can be a string or keyword, depending on the variable's type (string or integer). For example:

TOOLBAR_DISPLAY = TOOLBAR_OFF

To continue an entry across multiple lines, end each unfinished line with a backslash (\). To comment out an entry, start it with a pound character (#).

If an application supports multiple terminal types, you might need to qualify some variable settings according to specific terminal types with this format:

variable = (term [ | term]...) value

variable is set to value only for those terminals listed within parentheses; term is a terminal-type mnemonic as defined by the application variable SMTERM. For example, the distributed SMVARS file contains these SMKEY settings:

SMKEY = (ibm)   $SMBASE/config/ibmkeys.bin
SMKEY = (hp|hp2392) $SMBASE/config/hpkeys.bin
SMKEY = $SMBASE/config/xtermkeys.bin

Thus, if SMTERM is set to ibm, Panther reads the first entry and sets SMKEY accordingly.

You can provide, along with a number of terminal-specific entries of the same type (for example, SMKEY files), one entry that is not terminal-qualified. This serves as the default and it must be last in the list.

Warning: Use terminal mnemonics only if the application runs on different terminal types.

Display Attribute Settings

Some behavior variables take display attributes as parameters. To define a display attribute, select one color and any other attributes through the keywords in Table 2-1. In a setup file, separate the OR'd attributes with blanks, commas, or semicolons, as in this example:

STEXTATT = REVERSE HILIGHT GREEN

Table 2-1 Display attribute keywords

Foreground Color Background Color Attribute

B_HILIGHT

NORMAL_ATTR

BLACK

B_BLACK

BLANK

BLUE

B_BLUE

REVERSE

GREEN

B_GREEN

UNDERLN

CYAN

B_CYAN

BLINK

RED

B_RED

HILIGHT

MAGENTA

B_MAGENTA

DIM

YELLOW

B_YELLOW

WHITE

B_WHITE

B_CONTAINER

Portable Settings

When you install Panther, the installation program asks for the base directory for your installation—for example, /usr/panther. This path is used to set the application variable SMBASE. Other variables that point to files in the Panther installation can then use $SMBASE in their file path settings. For example, given the earlier definition of SMBASE, $SMBASE/config/sunkeys.bin expands to /usr/panther/config/sunkeys.bin. If the installation moves, you can update all file pointer settings by changing the value of SMBASE alone.

Runtime Changes

In many cases, you can change application behavior at runtime by setting the appropriate variable with sm_option (for integer variables) or sm_soption (for string variables). For example, this JPL statement disables display of tool bars:

call sm_option (TOOLBAR_DISPLAY, TOOLBAR_OFF)

To ascertain an integer variable's current setting, call sm_option and supply an argument of NOCHANGE. For example, this statement returns the current value of TOOLBAR_DISPLAY—either TOOLBAR_ON or TOOLBAR_OFF:

retval = sm_option (TOOLBAR_DISPLAY, NOCHANGE);

To change variables that are set to display attributes, call sm_option and use vertical bars to OR attributes together. For example:

call sm_option (STEXTATT, REVERSE | HILIGHT | GREEN)

Setup Variables

SMBASE
Points to the root of your Panther installation. In the web initialization file, this variable points to the location of the web application server installation on the HTTP server. SMBASE is set in one or more of the following locations:

SMCOLMAP
Points to the binary cmap file. The cmap file defines the default colors, or scheme, for your application, font, color and line style aliases, and the Editor color scheme. You can include a terminal mnemonic in the entry that matches the terminal type designated in your SMTERM variable or system TERM variable. In this way you can assign color schemes that will take advantage of GUI-specific colors. Refer to "Configuration Map File" in Application Development Guide for more information on creating and modifying configuration map files.

SMDICNAME
(Development only) Identifies the development repository to open when a Panther editing session begins. Only one repository can be open at a time. Panther automatically opens a repository with the name data.dic. Specify the repository name. For example:
SMDICNAME = /usr/app/dev.dic

To specify a remote repository, include the host name with this format:

host!repositoryName

For example:

SMDICNAME = aspen!myapp.dic

SMEDITOR
Specifies the name of the text editor that can be invoked to edit JPL instead of the JPL edit window. If you do not indicate a value for SMEDITOR, Panther' text editor is available. For example, your entry might look like:
SMEDITOR = vi

Use terminal-specific syntax to run the desired editor on a given platform. If you run Panther on Motif, spawn a new window for your editor; otherwise, it runs in the same window used to invoke Panther:

SMEDITOR = (xterm) "xterm -e vi"
SMEDITOR = (mswin) notepad.exe %s
SMEDITOR = (ibm) edit

You can define SMEDITOR in a setup file or the environment, and you can change it at runtime with the library routine sm_soption.

SMFEXTENSION
(Backwards compatibility only) Since previous versions of Panther used a default screen extension of jam, set this variable in order to automatically append the specified file extension to any screen name that does not already contain an extension. By default, a period separates the filename from the extension.
SMFEXTENSION = scr

SMFLIBS
Identifies the libraries to open on startup of Panther or your Panther application in three-tier processing (or in two-tier processing using remote library access). On UNIX you can set SMFLIBS in smvars, smsetup, or in the environment. Under Windows you must set it in the initialization file.
In three-tier applications, set this variable in the server environment file (proserv.env) to ensure that server-specific libraries are open.
To specify multiple libraries, separate their names with a vertical bar ( | ) or colon, a semicolon under Windows, or the convention used by your operating system. The following examples describe client access to local libraries:
SMFLIBS =/usr/appl/common.lib|/usr/appl/client.lib
SMFLIBS =D:\dev\client.lib;D:\usr\my.lib;C:\dev\common.lib

To open remote libraries, SMFLIBS should include the host name on which the libraries reside; for example:

SMFLIBS =host!client.lib;host!server.lib;host!common.lib

Refer to the functions sm_l_open and sm_r_window for information on opening libraries at runtime.

Note: Separators are platform-specific. The vertical bar (|) can generally be used on any platform. A semi-colon (;) can also be used on Windows; a colon (:) on UNIX. Panther defines path name and command line argument separators for each platform in smcommon.h.

SMIBMVJAVA
Specifies the path for IBM's Visual Age for Java program.

SMIBMWSADMIN
Specifies the path for IBM's Administrative Console program. For Windows, if SMIBMWSADMIN is not set, it will look in the registry settings for WebSphere.

SMINITJPL
Specifies the JPL files to open in the server's client.lib library.
On startup of web applications, the web application broker runs this file's web_startup procedure. On shutdown, the application runs the file's web_shut down procedure.

Use the SMINITJPL-specified JPL for two reasons:

SMJAVACOMPILE
Specifies the command used to compile Java. If it is unspecified, it defaults to
javac -deprecation "%s"

On Windows, the default value is overridden by a setting in smvars.bin:

cmd /c javac "%s" || pause

SMJAVAEDITOR
Specifies the editor to use when writing Java programs. If not specified, it defaults to the text editor defined in SMEDITOR.

SMJAVAFACTORY
Specifies the name of the class factory to use for Java programs. If not specified, it defaults to com.prolifics.jni.ClassTagFactory.

SMJAVALIBRARY
(optional) Specifies the location of Java libraries. If set in the environment, the specified library will override the default location.

SMJVMOPT
Specifies the options for the JVM (Java Virtual Machine).

SMKEY
Identifies the binary file containing a key translation table for your terminal. You can include a terminal mnemonic in the entry that matches the terminal type designated in your SMTERM variable or system TERM variable.
SMKEY = (vt100) $SMBASE/config/vt100keys.bin

SMLDBLIBNAME
Names the libraries whose contents are to be used by sm_ldb_init for local data block (LDB) initialization. The library files are loaded and activated at application startup. To specify multiple libraries, separate their names with a vertical bar ( | ) or colon, a semicolon under Windows, or the convention used by your operating system. Refer to "Using Local Data Blocks," in Application Development Guide for information on using LDBs.
SMLDBLIBNAME = cust.lib|const.lib
SMLDBLIBNAME = my.lib:/u/dev/cust.lib

or under Windows:

SMLDBLIBNAME = c:\graphics.lib;c:\my\dev.lib

SMLDBNAME
Names the screens to be used by sm_ldb_init for local data block (LDB) initialization. To specify multiple libraries, separate their names with a vertical bar ( | ) or colon (:) under UNIX, a semicolon under Windows, or the convention used by your operating system. The listed files are loaded and activated at application startup after any libraries specified with SMLDBLIBNAME are loaded. Refer to "Using Local Data Blocks," in Application Development Guide for information on using LDBs.
SMLDBNAME = ldb1.scr|ldb2.scr|ldb3.scr

SMMSGS
Identifies the binary file that contains messages and other printable strings used by the Panther runtime system and utilities. This variable is set to the full path name of the binary message file. For example:
SMMSGS    = $SMBASE\config\msgfile.bin

Refer to "Using Message Files," in Application Development Guide for details about message files, and to library functions sm_msg_get and sm_msg_read.

SMPATH
Lists the directories where Panther should search for Panther files at runtime, such as screens, JPL procedures, and JDB databases. Place a vertical bar ( | ) between directory paths; do not include blank spaces.
You can include a terminal mnemonic in the SMPATH entry that matches the terminal type designated in your SMTERM variable or system TERM variable. For example, this entry specifies the search path for applications running on UNIX:
SMPATH = $SMBASE/config

An application server's environment file (such as proserv.env) can also set SMPATH to any directories that the server needs to access besides the application directory. If the environment file contains an SMPATH entry, make sure that the path includes ${SMBASE}/config.

For example, the following entry in a UNIX server environment file ensures that servers using this file have access to files in /u/myapps and ${SMBASE}/config as well as in the application directory:

SMPATH=/u/myapps:${SMBASE}/config

Note: Because a server's application directory is already set through its machine's configuration, SMPATH must not include the same directory again.

You can change SMPATH at runtime with sm_soption.

SMPROVIDERURL
(WebSphere applications only) Specifies the URL of the server running Web Sphere Application Server. Set in a runtime client environment in order to access the EJBs, as in:
iiop://machineName:portNumber

SMRBCONFIG
(JetNet/Oracle Tuxedo only) Specifies the middleware configuration file to use when a three-tier application activates. This variable must be set in the environment in which you boot an application. Set SMRBCONFIG to the full path name of the middleware configuration file—for example, /usr/myapp/broker.bin.

Also set this variable for a native client (a client that resides on an master or non-master machine) so it can connect to the middleware. Make sure that the SMRBCONFIG setting matches the value specified for the machine's local configuration file (refer to "Local JetNet Configuration File," in JetNet/Oracle Tuxedo Guide).

Note: Applications using the Oracle Tuxedo middleware adapter can use SMRBCONFIG instead of TUXCONFIG.

Panther uses SMRBCONFIG as the default value on the Connect dialog when you ask to connect to the request broker from within the screen editor.

SMRBHOST
(JetNet/Oracle Tuxedo only) Together with SMRBPORT, this variable tells a workstation client how to connect to a server machine. SMRBHOST provides the request broker with the network addresses of the machines to which the client can connect.

Set this variable in the client's initialization file. Specify the value as a comma-separated list of one or more host names (or IP addresses in dot notation, for example, 192.200.3.42), in a left-to-right order of precedence. For Oracle Tuxedo, this value is used to construct the WSNADDR string.

If the number of host name entries does not match that in SMRBPORT, the last entry in the shorter list is used to pair with the entries in the longer list. For instance, in the following example there are three host names and only two port numbers:

SMRBHOST = aspen,fir,willow 
SMRBPORT = 300,400

Therefore, aspen uses port 300, while both fir and willow use port 400.

The value you provide is displayed by default on the Connect dialog when you choose to connect to the request broker from within the screen editor. If more than one host name is listed, a connection is attempted for each host, in order of precedence, until a connection is made.

SMRBPORT
(JetNet/Oracle Tuxedo only) Together with SMRBHOST, this variable tells a workstation client how to connect to a server machine. SMRBPORT provides the request broker with the port numbers associated with the machines (SMRBHOST) to which the client can connect.

Set this variable in the client's initialization file. Specify the value (within the range of 32k and 64k) as a comma-separated list of one or more numbers, in a left-to-right order of precedence, corresponding to the port number associated with the host machines specified in SMRBHOST (obtain port numbers from the person responsible for configuring the application).

For the Oracle Tuxedo middleware adapter, this value is used to construct the WSNADDR string.

If the number of entries in SMRBPORT does not match that specified in SMRBHOST, the last entry in the shorter list is used to pair with the entries in the longer list. Refer to SMRBHOST for an example.

The value you provide is displayed by default on the Connect dialog when you choose to connect to the request broker from within the screen editor. If more than one port number is listed, a connection is attempted for each, in order of precedence, until a connection is made.

SMSETUP
Identifies an binary setup file, in addition to the SMVARS file, that contains application variable settings. If the SMVARS and SMSETUP files set the same variables, the settings in the SMSETUP file take precedence. Use the SMSETUP file for variable settings that are specific to a particular terminal-type, project, or user.
SMSETUP = (xterm) xsetup.bin

SMTERM
Defines the terminal type. Set this variable if you want Panther to recognize a terminal type mnemonic that is different from the one that is defined in the system TERM variable.

For example, while other programs might run on a terminal in VT100 emulation, you want Panther to use the features of VT220 emulation; so while TERM is set to VT100, you can set SMTERM = vt220.

Users of Motif in X Windows can set SMTERM = X. To use Panther under Windows, set SMTERM = mswin.

SMTPCLIENT
(WebSphere initialization only) Specifies whether Oracle Tuxedo connectivity will be enabled in the application. If unset, the shared libraries needed for Oracle Tuxedo will not be loaded. If Oracle Tuxedo libraries are needed, set this variable in the global section of panther.ini to native or workstation, for native or workstation clients respectively.

SMTPCLIPFILE
(JetNet/Oracle Tuxedo only) In character mode, identifies the clipboard file to be used by the JIF editor. If not set, file clip.dat will be used.

SMTPINIT
(WebSphere initialization only) Specifies the default arguments to the client_init command for Oracle Tuxedo operations in WebSphere applications. Set this variable as part of the global settings in panther.ini.

SMTPJIF
(JetNet/Oracle Tuxedo only) Identifies the JIF file to open on application startup. This file must be in an open library, by default common.lib. In a development environment, this variable determines which file to open initially when the JIF editor is invoked.

SMTRACE
Supplies a command string to pass to the sm_trace function during startup. It is new in Panther 5.30. For example:

SMTRACE=NOJAVA FRAMES=100 TRACEFILE="c:\temp\forex.trc"

would disable reporting Java events; would allocate 100 frames for trace data in dumps; and would start using c:\temp\forex.trc as the trace file.

SMUSER
Enables concurrent access to multi-user libraries. In order to control access, Panther must know each user's name. Panther also uses the value in SMUSER as the default user name when it constructs service aliases (refer to "Using Service Aliases to Test Services" in JetNet/Oracle Tuxedo Guide).

Panther looks for SMUSER in the environment or, under Windows, in the initialization file. On UNIX and Windows, Panther can identify a user from the environment if SMUSER is not set.

Panther looks for user identification in these sources, listed in descending order:

  1. SMUSER
  2. LOGNAME
  3. USER (UNIX)
  4. USERNAME (Windows)
  5. If neither SMUSER nor USERNAME is set on Windows, it calls the function GetUserName to find a user name. If none of these sources or methods provides identification, Panther prompts the user to supply a user name.

SMVARS
Identifies the binary setup file, usually smvars.bin. Panther uses the SMVARS file to find other configuration files and setup information. Set this variable in the environment or in the Windows initialization file. If SMVARS is not explicitly set, Panther uses the value of SMBASE to find smvars.bin in the config directory or, if not there, in $SMBASE itself.

A typical SMVARS file on Windows might contain these settings:

SMKEY     =  $SMBASE\config\winkeys.bin
SMMSGS    =  $SMBASE\config\msgfile.bin
SMPATH    =  $SMBASE\config 
SMEDITOR  =  notepad.exe %s.
SMCOLMAP	=	(mswin) $SMBASE\config\wincmap.bin
SMCOLMAP	=	(web) $SMBASE\config\webcmap.bin

To make an entry specific to a terminal type, include the terminal's mnemonic enclosed in parentheses—for example, (mswin) for Windows.

SMVIDEO
Identifies the binary file that contains character-mode video control sequences and parameters used by a character-mode Panther runtime system. You can include one or more terminal mnemonic in the entry that matches the terminal type designated in your SMTERM variable or system TERM variable.
SMVIDEO = (hp|hp2392) $SMBASE/config/hp2392Avid.bin

Refer to Chapter 7, "Video File," for details about video files, and to the library function sm_vinit.

Note: Video files are not required for GUI platforms, and may not be included in the Panther distribution.

SMVIEWER
Specifies the viewer for output of reports created with ReportWriter report browser. If you create PostScript reports, set this to a PostScript viewer. If this variable is not set, then SMEDITOR is used.

Behavior Variables

This section describes variables that control the behavior of a Panther client application and how users interact with it. Panther internally sets these variables to default values, as indicated in their descriptions by (d).

The variables described here apply to applications that run on GUI and character-mode platforms. For information about behavior variables that apply only to character-mode, refer to Chapter 5, "Character Mode Settings."

Note: Behavior variables that control the GUI interface are generally ignored by Web applications—for example, cursor appearance, toolbar display, and mouse cursor appearance. In cases like these, client behavior is controlled by the user's Web browser.

Cursor Appearance and Movement

These variables control how the cursor appears and moves. (d) indicates the default setting.

IN_HARROW
Sets horizontal arrow movement:

Note: Left and right arrow keys usually move the cursor to the left or right of the current field, or as indicated by the behavior variable. However, in horizontal scrolling arrays, left and right arrow keys move the cursor to the next occurrence and scroll the array to the next available occurrence. Therefore, these variable settings only control cursor movement in single-occurrence fields.

OK_FREE
Cursor moves freely.

OK_RESTRICT
The cursor moves left and right in the current field but does not leave the field.

OK_COLM
The cursor is positioned to the closest field on the current line.

OK_SWATH
Same as OK_COLM.

OK_NXTLINE
The cursor is positioned to the nearest field in the column closest to the current column. Wrapping is observed, if set.

OK_NXTFLD
The cursor is positioned to the field closest to the current line and column. The calculation uses the diagonal distance, assuming a 5 to 2 aspect ratio.

OK_TAB (d)
Left-arrow backtabs to the end of the previous field, and right-arrow tabs to the first character in the next field. Wrapping is observed if set. The next and previous field properties are not observed.

OK_TABNXT
Like OK_TAB, but the next field and previous field properties are observed.

IN_VARROW
Sets vertical arrow movement:

Note: Using the up and down arrow keys usually causes the cursor to move up or down to the next field, or as indicated by the behavior variable. However, using up and down arrow keys in scrolling arrays moves the cursor to the next occurrence, and causes the array to scroll to the next available occurrence. Therefore, these variable settings only control cursor movement in fields having a single occurrence.

OK_FREE
Cursor moves freely.

OK_RESTRICT
Vertical arrow keys ignored in current field.

OK_COLM
The cursor is positioned to the nearest field that overlaps the current column. Wrapping is observed, if set.

OK_SWATH
The cursor is positioned to the closest field that overlaps the swath containing the current field. Wrapping is observed if set.

OK_NXTLINE (d)
The cursor is positioned to the nearest field whose line is closest to the current line. Wrapping is observed, if set.

OK_NXTFLD
The cursor is positioned to the field nearest the current line and column.

OK_TAB
Down arrow tabs to the first character in next field; up arrow backtabs to last character in the previous field. The next and previous field properties are not observed.

OK_TABNXT
Like OK_TAB, but the next field and previous field properties are observed.

IN_ENDCHAR
Specifies treatment of last character in a widget whose autotab property is set to PV_NO:

OK_ENDWRITE
Last character is repeatedly overwritten if the cursor is in overwrite mode and the widget's autotab property is set to PV_NO.

OK_ENDBEEP (d)
Terminal beeps when user attempts to overwrite last character in a widget whose autotab property is set to PV_NO.

IN_RESET
Sets options for field-reset:

Note: IN_RESET is ignored on word-wrapped fields.

OK_NORESET
Arrow keys can enter the middle of a field.

OK_RESET
When field is entered, cursor always goes to first character position, based on justification and punctuation properties.

OK_TO_END (d)
When field is entered, cursor always go to the first available blank after (or before in the case of right-justification) the data.

IN_VALID
Sets conditions for validation on field exit:

OK_VALID
Validation is performed whenever field is exited (NL, TAB, BACKTAB, arrows, mouse click).

OK_NOVALID (d)
Validation is performed only when TAB or NL is pressed. Using arrow keys or a mouse click to leave a field does not validate the field.

IN_WRAP
Sets options for arrow wrapping:

OK_WRAP (d)
Arrow keys wrap. Vertical arrows wrap from top to bottom. Right arrows wrap to the beginning of next line (or first line). Left arrows wrap to end of previous line (or last line).

OK_NOWRAP
Arrow keys do not wrap. Terminal beeps if user tries to move the cursor past the edge of the active screen.

Numeric Format and Display

DECIMAL_PLACES
Sets default decimal places for real number display:

PLACES_VARIABLE (d)
Sets the default number of decimal places used by sm_dtofield to equal the number of significant digits in the number, to a maximum of 20. Panther uses sm_dtofield to display real numbers.

number
Sets the default number of decimal places used by sm_dtofield to number.

OCTAL_SUPPORT
Specifies to interpret numbers with leading zero as octals:

OCTAL_SUPPORT_ON
Numbers with a leading zero are treated as octal unless they begin with 0x, 0X, 0b, or 0B.

OCTAL_SUPPORT_OFF (d)
Numbers with a leading zero are treated as decimal unless they begin with 0x, 0X, 0b,or 0B.

Text Selection Appearance

The following variables set attributes for text selected in a single or multiline text widget. Refer to Table 2-1 for a list of attribute keywords.

TXT_SELECT_ATTR
Sets desired attributes for the selected text. These attributes are added to those already assigned to the text widget. This defaults to HILIGHT REVERSE.

TXT_SELECT_MASK
Masks any attributes that should not be added to the selected text. If you assign a color as the selected text attribute, add NORMAL_ATTR to TXT_SELECT_MASK. Attributes of the occurrence are used unless they are masked out.

Function Keys

SMINICTRL
Associates control strings with function keys.

Each Panther screen contains a table of control strings associated with functions keys. You can also set default control strings for specified function keys either in the SMVARS file or in the environment. Panther uses absence of a control string for a given function key.

By including multiple SMINICTRL entries in your SMVARS file (or in the environment), you can define system-wide actions for specific function keys. The syntax for including SMINICTRL variables is as follows:

SMINICTRL = function_key = control_string

For example:

SMINICTRL = PF1 = &system_help
SMINICTRL = PF2 = ^toggle_mode
SMINICTRL = PF7 = ^jm_keys SPGD
SMINICTRL = PF8 = ^jm_keys SPGU

You can change application control strings at runtime through the application property control_string. For more information, refer to "Multi-item Properties" in Application Development Guide.

To disable a Panther-supplied default function key, map it to a control string function that does nothing.

Menus and Toolbars

These variables control the behavior and display of menu bars and toolbar items and their corresponding tooltips. You can define them in a setup file and at runtime with sm_option. (d) indicates the default setting.

TOOLBAR_DISPLAY
Enables or disables tool bar display:

TOOLBAR_OFF
Disables display of tool bars. Panther continues to update the underlying data structures.

TOOLBAR_ON (d)
Allows display of tool bars.

TOOLTIP_DISPLAY
Enables or disables tool tip text display:

TOOLTIP_OFF
Disables display of tool tip text.

TOOLTIP_ON (d)
Enables display of tool tip text.

Message Display

These variables control message display. You can define them in a setup file, in the environment, and at runtime with sm_option.

Note: The BLANK attribute keyword is ignored for messages.

MESSAGE_WINDOW
Controls when messages appear in a window:

WHEN_REQUIRED (d)
Messages appear on the status line unless they are too large to fit. Oversize messages appear in a window. (Messages never appear on the status line in GUI environments).

ALWAYS
Messages always appear in a window unless they are explicitly sent to the status line—for example, with sm_d_msg_line and sm_msg.

SMSGPOS
Sets position of message line:

number
Sets the position for the message line by specifying a single number (1 is the top line of the display). This variable is ignored if the terminal has a hardware status line.

SMSGBKATT
Sets background attributes for message line. The default is SMSGBKATT=B_BLACK. The keywords for SMSGBKATT take the format B_color. Refer to Table 2-1 for a list of attribute keywords.

STEXTATT
Sets the default display attribute for field status text. Refer to Table 2-1 for a list of attribute keywords. The default is STEXTATT=WHITE.

Note: If you change the attributes but do not specify a color, the default color becomes BLACK. For example, if you use the entry STEXTATT = BLINK, status messages display with the foreground attributes BLINK and BLACK. Then, if you use the default message line background (see SMSGBKATT), status messages are not visible because they have black text on a black background. Always specify a foreground or background color when setting attribute for text. If this is not convenient, you can set the variable SMSGBKATT to a color other than B_BLACK.

EMSGATT
Sets the display attributes of message text displayed with sm_femsg and sm_ferr_reset, and the tag portion of sm_fquiet_err and sm_fqui_msg messages. The content of the tag is specified in the message file entry SM_ERROR (the default is ERROR:). The default is:
EMSGATT=WHITE BLINK HILIGHT B_HILIGHT

Refer to Table 2-1 or a list of attribute keywords.

If you change this variable without specifying a foreground color, the default foreground color becomes BLACK. Refer to the note on STEXTATT for more information.

QUIETATT
Sets the display attributes of message text displayed with sm_fquiet_err messages. The default is QUIETATT=WHITE. See EMSGATT for changing the attributes of the tag portion of these messages. Refer to Table 2-1 for a list of attribute keywords.

If you change this variable without setting a foreground color, the default foreground color becomes BLACK. Refer to the note on STEXTATT for more information.

Message Acknowledgment

These variables control how your application responds to user input when a message appears. (d) indicates the default setting.

ER_ACK_KEY
Defines the error acknowledgment key. This variable's value must be specified explicitly, either as a number (in decimal, hex, or octal) representing an ASCII character, as an ASCII mnemonic (SP, SOH, ETX), as a quoted character ('.', '_'), or as a logical key defined in smkeys.h. The default is ER_ACK_KEY=' ', the space key. If you define a value other than the spacebar, refer to ER_SP_WIND.

ER_KEYUSE
Specifies whether to use or discard error acknowledgment key:

ER_NO_USE (d)
Forces acknowledgment of all window-displayed error messages with either ER_ACK_KEY, space bar, or OK; error messages that are displayed to the status line must be acknowledged with either ER_ACK_KEY or spacebar. The valid keypress is immediately discarded.

All invalid responses to a window-displayed error message cause the terminal to beep (through calls to sm_bel). All invalid key presses to a status line message cause Panther to display an error window or beep, depending on how ER_SP_WIND is set.

ER_USE
Any keypress acknowledges a status line error message; this setting has no effect on window-displayed error messages. The type-ahead buffer is flushed when the message is displayed, and the acknowledging keypress is saved for data-entry. If you set this as the default, you can force users to acknowledge a message by putting %Md at the beginning of the message text. Refer to "Using Message Files" in Application Development Guide for more information.

ER_SP_WIND
Reminds user to acknowledge message (valid only for status-line error messages):

ER_YES_SPWIND (d)
If ER_KEYUSE = ER_NO_USE and the user presses another key when ER_ACK_KEY is expected, a window appears. The default message is Please hit the space bar after reading this message from the message file entries SM_P1 and SM_P2. If you are using this option and a key other than the space bar for message acknowledgement, modify the message file entry SM_SP1.

ER_NO_SPWIND
If ER_KEYUSE = ER_NO_USE, and the user presses another key when ER_ACK_KEY is expected, the terminal beeps (by calling sm_bel). A visual bell can be used if the video file has a BELL entry.

Shifting and Scrolling

These variables can help you establish standards for handling scrolling and shifting arrays and fields. You can define them in a setup file, in the environment, and at runtime with sm_option. If you change these defaults at runtime, call sm_option before opening the screen. (d) indicates the default setting.

ZM_DISPLAY
Specifies zoom window size preference:

ZM_ONSCREEN
Displays expanded zoom window at the display size of the operating system window (for example, in the xterm or jterm window). Useful for character-mode applications.

ZM_MAXIMUM
Displays expanded zoom window at its maximum physical display. Useful for applications running in GUI environment.

ZM_SC_OPTIONS
Sets zoom scroll options:

ZM_NOSCROLL
No scroll expansion on arrays.

ZM_SCROLL
Scrolls the current array and display as many occurrences as possible.

ZM_PARALLEL (d)
Scrolls all parallel or synchronized arrays. Display as many occurrences as possible.

ZM_1STEP
Scrolls and shift in one step.

ZM_SH_OPTIONS
Sets zoom shift options:

ZM_NOSHIFT
No shift expansion. Fields shift, but no horizontal zooming takes place.

ZM_SCREEN (d)
Shifting arrays have as many on-screen elements as the previous form, which is the original form if ZM_SC_OPTIONS = ZM_NOSCROLL is used. Otherwise, ZM_SCREEN displays as many items as possible. All synchronized arrays are shifted together.

IND_OPTIONS
Sets shift/scroll indicator options:

IND_NONE
No indicators.

IND_SHIFT
Shift indicators only.

IND_SCROLL
Scroll indicators only.

IND_BOTH (d)
Shift and scroll indicators.

SCR_KEY_OPT
Sets scroll field priority:

SCR_NEAREST (d)
Nearest scrolling array to current field scrolls when scrolling keys are used (PGUP and PGDN).

SCR_CURRENT
Scrolling keys (PGUP and PGDN) have no affect unless current field is a scrolling array.

SB_OPTIONS
Sets scroll options for virtual windows:

SB_NONE
No scroll bars or corner arrows.

SB_BARS (d)
Shows scroll bars.

SB_CORNERS
Shows corner arrows.

IND_PLACEMENT
Sets position of shift and scroll indicators:

IND_FULL (d)
Full width of field.

IND_FLDENTRY
Left or right corner, according to the field's justification.

IND_FLDLEFT
Left corner of field.

IND_FLDCENTER
Center of field.

IND_FLDRIGHT
Right corner of field.

Filename Conventions and Search

The following variables control how Panther builds and parses file names.

FCASE
Sets case sensitivity for filename searches. This variable's setting is recognized only on UNIX applications:

CASE_INSENS (d)
Ignore case when searching for a file.

CASE_SENS (d)
Use case when searching for a file.

F_EXTREC
Specifies whether to recognize screen and utility I/O file extensions. The default value is the value of EXTMULTS for the system as defined in smcommon.h.

FE_IGNORE
Ignore extensions.

FE_RECOGNIZE
Recognize extensions.

F_EXTOPT
Sets placement of screen and utility I/O file extensions:

FE_FRONT
The extension is before the filename.

FE_BACK (d)
The extension is after the filename.

F_EXTSEP
Specifies the character used as a screen and utility I/O file extension separator. The default is a period (.). A separator character can be a number (decimal, hex, or octal) which represents an ASCII character, an ASCII mnemonic (SOH, ETX), or as quoted character ('.', '_').

Display Attributes for Grouped Items

These variables control the attributes of the cursor and selected items in groups. You can define them in a setup file, in the environment, and at runtime with sm_option. Refer to Table 2-1 for a list of attribute keywords.

GA_CURATT
Sets desired attributes for the occurrence under the cursor. These attributes are added to those already assigned. The default is BLINK B_HILIGHT.

GA_CURMASK
Masks any attributes that should not be added to the cursor attributes. If you are assigning a color as the cursor attribute, add NORMAL_ATTR to GA_CURMASK. Attributes of the occurrence are used if they are not masked out.

GA_SELATT
Sets desired attributes for a selected group occurrence. These attributes are added to those already assigned to the occurrence. The default is HILIGHT REVERSE.

GA_SELMASK
Masks the attributes that should not be added to the attributes for the selected group occurrence. If you assign a color to GA_SELATT, add NORMAL_ATTR to GA_SELMASK. Attributes of the occurrence are used if they are not masked out.

Panther Mouse Cursor Appearance and Behavior

These variables control mouse cursor appearance and behavior only when the mouse is being run by Panther. In most cases, the mouse is under control of the native environment and mouse behavior is determined by the environment, not Panther.

CLICK_TIME
Sets the maximum amount of time between two mouse clicks that defines a double mouse click. The default setting is 250 ms.

MOUS_CRSR_CHAR
Sets the character used to display mouse cursor. The default setting is a block character.

MOUS_CRSR_ATTR
Sets the desired attributes for the occurrence under the cursor. These attributes are added to those already assigned to the occurrence. The default setting is REVERSE. Refer to Table 2-1 for a list of attribute keywords.

MOUS_CRSR_MASK
Masks any attributes that should not be added to the cursor attributes. If you are assigning a color as the cursor attribute, add NORMAL_ATTR to MOUS_CRSR_MASK. Attributes of the occurrence are used if they are not masked out. Refer to Table 2-1 for a list of attribute keywords.

Miscellaneous Variables

These variables control a variety of customization issues. They can be defined in a setup file or in the environment as well as at runtime with sm_option. (d) indicates the default setting.

CHAR_VAL_OPT
Sets keystroke filter validation option:

CHAR_BEEP (d)
Causes a beep if user keyboard input does not pass character validation as defined in the keystroke_filter property for a data entry field.

CHAR_MSG
Displays message if user keyboard input does not pass character validation as defined in the keystroke_filter property for a data entry field.

CLOSELAST_OPT
Specifies whether to exit base form without exiting application:

OK_CLOSELAST (d)
Allows base form to close without exiting the application.

NO_CLOSELAST
Application ends when user exits base form.

DA_CENTBREAK
Sets the default century for two-digit dates through a two-digit number between 00 and 99. Use this option to specify the breaking year between the twentieth and twenty-first centuries when Panther formats two-digit year to four-digit year specifications.

This option lets you specify that all two-digit year entries less than the number specified should be in the twenty-first century. For example, if you specify 45. then all two-digit year entries between 00 and 44 indicate the years 2000 to 2044, while those between 45 and 99 indicate 1945 to 1999.

The default value is 50.

ENTEXT_OPTION
Sets how to process screen entry:

LDB_FIRST (d)
LDBs are examined first for the value of a field, then the screen, on screen entry. On screen exit, this order is reversed.

FORM_FIRST
Screen is examined first for the value of a field, then LDBs, on screen entry. On screen exit, this order is reversed.

EXPHIDE_OPTION
Sets screen expose/hide options:

OFF_EXPHIDE
Processes screen entry or exit functions only when screen is explicitly opened or closed.

ON_EXPHIDE (d)
Processes screen functions when screen is explicitly opened or closed, when screen is exposed by closing an overlying window, or when screen is hidden by opening an overlying window.

JAVA_USE
Sets the Java initialization option during Panther start-up:

JAVA_IS_USED (d)
Initializes Java.

JAVA_NOT_USED
Does not initialize Java. Set in development executables. For distributed executables, remove the call to sm_java_init in jmain.c, or edit the makefile to remove SM_JAVA.

LISTBOX_SELECTION
Enables extended selection in list boxes:

EXTENDED_SELECTION (d)
Enables extended selection.

SIMPLE_SELECTION
Allows only one selection at a time.

STARTSCREEN
Specifies the name of the Panther screen that the application first displays. Panther searches open libraries. If no screen is found, Panther reports an error.

STARTSCREEN is not supported in the application's initialization/resource file or in the environment. It must be set in the file specified by SMVARS or SMSETUP. You can also specify the start screen by setting start_screen_name in jmain.c or jxmain.c.

WWTAB
Sets the number of spaces to move when the TAB key is pressed in a word wrap multiline text field. The default is 5. On Motif, this option is ignored.

WW_COMPATIBLE
Determines whether word wrap arrays are to be validated when the user moves from one occurrence to another.

WW_COMPATIBLE_OFF
Do not validate. This is the default.

WW_COMPATIBLE_ON
Validate when the user moves from one occurrence to another within a word wrap array.

XMIT_LAST
Sets NL or TAB to act like XMIT on last field of screen (triggering screen validation):

XMIT_NL
NL (New Line) logical key behaves like XMIT on last field of a screen.

XMIT_TAB
TAB logical key behaves like XMIT on last field of a screen.

XMIT_NL_TAB
NL and TAB behave like XMIT on last field of a screen.

XMIT_DISABLE (d)
NL and TAB respond as defined and do not emulate the XMIT key when used in the last field of a screen.

Sample Setup File

The following sample file illustrates the syntax for setting most of the variables discussed in this chapter. These variables can be designated in the environment or, as recommended, in a setup file, and can be altered at runtime with specific library functions.

SMKEY = (vt100 | x100) /usr/panther/config/vt100keys.bin
SMMSGS = /usr/config/msgfile.bin
SMPATH = /usr/app/forms|/usr/me/testforms
SMSETUP = hpsetup.bin
SMVIDEO = (vt100 | x100)/usr/panther/config/vt100vid.bin
SMINICTRL= PF2 = ^toggle_mode
SMINICTRL = PF3 = &popwin(3,28)
SMINICTRL = XMIT = ^commit all
IN_BLOCK = OK_NOBLOCK
IN_WRAP = OK_WRAP
IN_RESET = OK_NORESET
IN_ENDCHAR = OK_ENDWRITE
IN_VALID = OK_VALID
IN_VARROW = OK_FREE
IN_HARROW = OK_TAB
ER_ACK_KEY = PF12
ER_KEYUSE = ER_NO_USE
ER_SP_WIND = ER_YES_SPWIND
EMSGATT = RED; RED, REVERSE
QUIETATT = CYAN HILIGHT BLINK
STEXTATT = WHITE REVERSE
QMSGATT = CYAN REVERSE
SMSGBKATT = RED
SMSGPOS = 25
ZM_SC_OPTIONS = ZM_SCROLL
IND_OPTIONS = IND_BOTH
IND_PLACEMENT = IND_FLDRIGHT
SB_OPTIONS = SB_CORNERS
F_EXTREC = FE_RECOGNIZE
F_EXTOPT = FE_BACK
F_EXTSEP = '.'
DW_OPTIONS = DW_OFF
ENTEXT_OPTION = LDB_FIRST
FCASE = CASE_SENS