Application Development


Chapter 18. Programming Control Strings

User interaction with an application generally consists of entering data and making choices with function keys and menus, and with action widgets such as push buttons. You associate actions with these application objects through control strings.

Control strings can perform these tasks:

For a table for user-initiated events, refer to Table 17-2.


Associating Control Strings with the Application

A Panther application has various hooks from which it can execute control strings. You can associate control strings with push buttons, list boxes, and menu items through their Control String property. Some widget types can be double-clicked on; their Double Click property also takes a control string: dynamic labels, single- and multiline text widgets, list boxes, and combo boxes. For example, a push button widget specifies to exit the current screen when it is pressed if its Control Strings property is set to execute the built-in function jm_exit:

^jm_exit

You can also attach control strings to function keys. Each screen has its own Control Strings property, which lets you list Panther logical keys and a corresponding control string. For example, the following control string list lets users open two screens as windows through the logical keys PF1 and PF2, and leave the current screen through EXIT:

PF1     = &custInfo
PF2 = &orderDetail
EXIT = ^jm_exit

You can globally associate control strings with function keys at application startup through the setup variable SMINICTRL. For example, the following statement in your setup file globally associates the EXIT key with your own exit routine:

SMINICTRL = EXIT = ^myExit

Control String Types

Panther uses the leading character of a control string to determine what type of action to perform—whether to open a screen, execute a function, or invoke a system command. Table 18-1 summarizes these leading characters and actions.

Table 18-1 Control string types and leading characters

Character Action Example

None

Open screen as a form.

mainmenu

&

Open screen as a stacked window.

&(5,20)status

&&

Open screen as a sibling window.

&&(5,20)status

^

Execute C function or JPL procedure.

^drop acctno

!

Invoke operating system command.

!ls "*.jpl"

The following sections explain each type in detail.


Displaying Screens

A control string can open a client screen as a form, as a stacked window, or as a sibling window. Control strings that open screens have the following syntax:

*[leadChar] [(viewportArgs)] screenName

If you omit leadChar, Panther opens the screen as a form. A single ampersand (&) opens the screen as a stacked window, while a double ampersand (&&) opens it as a sibling window.

Refer to Chapter 13, "Developing Client Screens," and Chapter 24, "Setting the Screen Sequence," for more information about how Panther manages screens as forms and windows.

Search Path

Panther looks for the named screen in the following places in this order:

If all searches fail, Panther displays an error message and returns.

Viewport Arguments

You can optionally specify arguments for the screen's viewport—that is, the window in which the screen is displayed. Viewport arguments determine the screen's position on the physical display, the viewport's dimensions, and the offset of the screen's contents within its viewport as follows:

(row, col, len, width, vRow, vCol)

Note: All viewport arguments are optional. However, if you specify any one argument, you must supply all leading arguments; trailing arguments are optional.

row, col
The position of the viewport's top left corner on the physical display, where row and col are one-based offsets from the physical display's top left corner. The physical display excludes any area already used either by the screen manager, such as a base window border, or by the application's menu bar. Thus, arguments of 1,1 start the screen at the first line and leftmost column that are available.

Signed integer values (negative or positive) specify the viewport's position relative to the previously active screen. For example, the following control string invokes newWindow.scr as a sibling window whose viewport is two rows higher and two rows left of the current screen's viewport:

&&(-2,-2)newWindow.scr
If the window does not fit on the display at the specified location, Panther adjusts it as needed. Panther does not allow viewports to be positioned completely offscreen.

len, width
The viewport's dimensions in rows and columns. A value of 0 or less specifies to use the screen's actual dimensions if the physical display is large enough. Note that the border is counted as part of the screen.

vRow, vCol
The row and column of the screen to display on the viewport's first row and column.

If you specify vRow or vCol, the cursor appears in the upper-left corner of the viewport, whether or not a field is there. The cursor responds to the cursor keys until it encounters an unprotected field, or the TAB key is pressed. When it is in a field, the cursor uses the normal tabbing order among fields.

Table 18-2 contains several examples of control strings that open screens.

Table 18-2 Control strings that open screens

Control string Action

mainmenu

Open mainmenu as a form at the physical display's top left corner.

&(5,20)custInfo

Open custInfo as a stacked window at row 5, column 20 of the physical display.

&&(1,1,10,40,5,5)detail

Open detail as a sibling window in a 10 row x 40 column viewport at the physical display's top left corner. Row 5, column 5 of the screen is initially displayed at the top left corner of the viewport.


Executing Functions

A control string that executes a function has the following syntax:

^ [(targetString  [; targetString] )] funcName [(arglist)]

funcName
The name of an installed or built-in function or a JPL procedure or module. An installed function can be one of Panther's library functions or your own. For information about function installation, refer to "Installing Functions." Built-in functions are preinstalled in Panther and begin with the prefix jm_. For descriptions of built-in functions, refer to Table 18-4 or Chapter 3, "Built-in Control Functions," in Programming Guide.

Panther looks first among the installed functions for funcName, then among the JPL procedures modules. For detailed information about this search algorithm, refer to "Precedence of Called Objects."

The function must return an integer. If the integer corresponds to the value of a Panther logical key, then that key is processed. For example, if a function returns PF4, then Panther behaves as if PF4 had been pressed by the user. The function should return 0 if there is no key to process.

arglist
One or more arguments to pass to parameters in funcName. Arguments for installed functions—Panther library functions and your own—must be enclosed in parentheses and delimited by commas or spaces. Arguments supplied to the built-in function jm_keys should not be enclosed in parentheses.

targetString
The control string can optionally test the return value against one or more semicolon-delimited target strings. Each target string has this syntax:
[testValue =] controlString

Panther compares funcName's return value to each testValue, reading from left to right. If it finds a match, it processes the specified control string. If you omit a test value, Panther processes the control string unconditionally. The control string can itself contain a JPL call with its own target strings; you can thereby nest multiple control strings with recursive calls.

For example, given this control string:

^(-1=^(^jm_exit)cleanup; 1=&welcome_scr)process

Panther processes the string as follows:

  1. Calls the JPL module or procedure process.
  2. Evaluates the return value from process to determine its next action:

Table 18-3 shows several control strings that call functions:

Table 18-3 Control strings that call functions

Control string Action

^verify(name,idnum)

Execute the user-written function verify, passing variables name and idnum as arguments.

^sm_cl_unprot()

Execute the library function sm_cl_unprot.

^jm_exit

Execute the built-in function jm_exit.

Using Built-in Functions

Table 18-4 lists a summary of the built-in functions. For detailed information on each function, refer to Chapter 3, "Built-in Control Functions," in Programming Guide.

Table 18-4 Built-in function summary

Function Description

jm_exit

Close active screen and return to previous screen.

jm_gotop

Return to the top level screen.

jm_goform

Open a window that prompts for the name of a screen to display.

jm_keys logicalKey/strings

Place the specified Panther logical keys on the keyboard input queue, to be processed by Panther as if each logical key were pressed in order.

jm_system

Open a window that prompts for a program to be executed by the operating system.

jm_winsize

Allow user to interactively resize a screen.

Note: The control string jm_keys XMIT when attached to a push button causes an infinite loop, This occurs because the act of pressing XMIT actually activates a push button.


Invoking Operating System Commands

A control string that starts with an exclamation point (!) temporarily passes control to the operating system. At runtime, Panther passes the string after the exclamation point to the operating system for execution. After program execution is complete, control returns to the application.

Note: In character-mode, Panther displays a message that the user must acknowledge before control returns to the application.

If you include variables in the control string, they must be prefixed by a colon(:). Panther's colon preprocessor expands colon-prefixed variables to their literal values before passing the string to the operating system.

Table 18-5 shows several operating system control strings:

Table 18-5 Control strings that call system commands

Control String Action

!ls

Display a directory listing.

!vi "newdoc"

Invoke vi to edit newdoc.

!rm :rmData

Remove the file whose name matches the contents of variable rmData.