Configuration Guide

Chapter 2. Application Variables

Panther application variables can be divided into two general categories:

Setup variables describe the operating environment and point to the Panther installation and specific setup files, and other files required by the application such as libraries.
Behavior variables control the behavior of a Panther application and how users interact with it—for example, message display, cursor behavior, and numeric format.

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:

The system's environment.
Windows initialization file or Motif resources file.
The setup file named by the SMSETUP variable.
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 the smvars 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:

For a three-tier JetNet/Oracle Tuxedo application, in the server environment file machine.env.
On a client, in the environment or in a Windows initialization file.
For a web application, in its web initialization file (refer to "Setup Variables," in the Web Development Guide).

For example, you might set SMBASE in a client's UNIX environment as follows:
```
export SMBASE=/usr/panther
```
Similarly, a Windows initialization file can define SMBASE as follows:
```
SMBASE=o:\win32\panther
```
Setting SMBASE facilitates an application's portability across different installations; subsequent definitions of all other variables that point to files can be relative to SMBASE. For example, given the previous SMBASE definition, a client's initialization file can set the SMVARS file as follows:
```
SMVARS=$SMBASE\config\smvars.bin
```

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:

web_startup can declare any JPL globals required by the Web application.
In three-tier configurations, web_startup initializes the Web application server as a client by calling client_init; web_shutdown calls client_exit to disconnect from the middleware.

In two-tier configurations, web_startup establishes database connections; web_shutdown cancels all connections.

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:

SMUSER

LOGNAME

USER (UNIX)

USERNAME (Windows)

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.

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: Do 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.

JAVA_USE_CODESET

Sets the Java String to codeset conversion option for Panther's Java APIs

:CODESET_NOT_USED (d)

When passing String data to Panther's Java API, only the low order byte of each Unicode Character is used to form a single-byte-per-character character array, without regard for the value of the codeset application property. String data is returned by constructing a String such that each byte of application data forms the low order byte of a Unicode Character in the Java String, without regard for the current codeset. The high order byte is always set to 0.

CODESET_IS_USED: Enables the codeset property to be used by Panther's Java API. Methods that take String arguments as parameters will encode them into the specified codeset for processing. Methods that return String instances will convert application data to be returned into Unicode in accordance with the specified codeset.

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