Previous Page TOC Next Page

Character User Interface (FMLI and ETI)

Frame Definition Files

Introduction


This chapter explains each of the descriptors that you can define for menu frames, for m frames, and text frames.

The first section "Menu Frame Descriptors" describes the functionality of the frame and item descriptors for menus. The following section "Examples of Menu Definition Files" presents some of the different ways you can create menu contents, and customize their appearance.

Next, "Form Frame Descriptors" covers the frame and field descriptors for forms. The section "Example Form Definition Files" gives examples of their use.

"Text Frame Descriptors" describes the frame descriptors for text frames (text frames have only frame descriptors and SLK descriptor), and "Example Text Frame Definition Files" give examples of their use.

Finally, the section "Other Useful Examples" covers some aspects of frame definition files that can be equally useful in all three types of frame definition files.

NOTE: Although SLK descriptors can be used in menu, form, and text-frame definition files, they are discussed and example given, in Chapter 4, "Application Level Definition Files". Their use as described there applies to frame definition files as well.

Menu Frame Descriptors


A menu frame definition file can begin with an optional set of frame descriptors (one set per menu), followed by at least one set of item descriptors (one set per item in the menu), and it can end with one or more optional sets of SLK descriptors defining SLKs to be displayed when the menu is current (one set per screen-labeled function key).

Some of the attributes of a menu that you can define are the following:


The descriptors in a menu definition file must follow this order:


CAUTION: Out-of-order descriptors will be ignored if this order--frame, then items, then SLKs--is not followed.

Frame Descriptors for Menus


The optional set of frame descriptors can include any valid frame descriptor, in any order. Each of these descriptors should only be used once in a menu definition file. If defined more than once in the set, the last one is used. In the following explanations, FALSE is defined as the word "false," irrespective of case, or a non-zero return code. The notation TRUE is defined as all values other than FALSE as defined above (for example, true, TRUE, yes, 0).

altslks

The altslks descriptor defines whether SLKs 9 through 16 are displayed when the frame is initially opened. If altslks evaluates to TRUE, SLKs 9 through 16 will be displayed. The default, if this descriptor is not defined, is FALSE, which causes SLKs 1 through 8 to be displayed.

begrow, begcol

The begrow and begcol descriptors define the original position of the top left corner of the menu frame in the user's work area. (begrow=0 and begcol=0 evaluates to the upper left corner of the work area.) These descriptors accept values of type position:

center

the menu frame will be centered in the work area

current

the menu frame overlaps the current frame's position (valid for begrow only)

distinct

the menu frame will not overlap the current frame if possible (valid for begrow only)

any

FMLI chooses a position with least amount of total overlap

integer

the menu frame will be positioned in an absolute position, defined by integer. Defining begrow and begcol to be integer values causes the frame to appear in the given position.

If either begrow or begcol evaluates to center, then the other can only be an integer value or center. Any other value is ignored and the descriptor defaults to center.

If neither is center, then the value of begrow determines the value of begcol; if begrow is current, distinct, any, or an illegal value, then begcol defaults to any. If begrow is a valid integer, begcol can be a valid integer; if begcol is an illegal integer in this case, it defaults to any. If integer values are supplied and either begrow or begcol are outside the screen boundary, a default value of any will be used.

close

The close descriptor is evaluated when the menu is closed and/or when the user exits from the FMLI application. The close descriptor is of type null, which means its only purpose is to obtain the side-effects of a backquoted express(s) coded in its definition.

columns

The columns descriptor defines the number of items display in a row of a menu frame. It must evaluate to a positive integer; if it doesn't, columns will be ignored. It will also be ignored if description is defined for any menu item. If neither columns nor rows is defined, menu dimensions will be determined by the interpreter. Given columns, the number of rows needed to display the items in the menu is calculated. If there is a conflict between the value provided by the rows descriptor and the calculated value, the calculated value takes precedence. Menu item names will be truncated, if required, to fit in the specified columns. (See Appendix A, "Programming Tips and Known Problems" for a complete discussion of the method used by FMLI to calculate rows and columns.)

NOTE: This descriptor should not be specified for dynamically generated menus if there is no way to guarantee that menu items will fit and therefore not be truncated.

done

The done descriptor defines the action to be executed when the user presses ENTER in a multi-select menu. This descriptor is ignored in a single-select menu.

framemsg


It can be replaced for as long as the frame is current by a message generated by the message built-in utility with the -f option. (See the message(1F) manual page.)

help

The help descriptor specifies what will happen when a user asks for help while in the menu. Since this descriptor is evaluated when the user requests help, the specification of what help is displayed can be determined through parameters that are set interactively.

init

The init descriptor defines whether the menu frame will be opened. If this descriptor is not defined, it defaults to TRUE, which means the menu frame will be opened. If init evaluates to FALSE, the menu frame will not be opened.

interrupt

The Boolean descriptor interrupt defines whether an executable that is coded in action or done descriptors can be interrupted by users (FALSE means not interruptible, TRUE means interruptible). It is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value FALSE applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information.)

If defined among the frame descriptors in a menu definition file, that value of interrupt is inherited by all sets of item descriptors and all sets of SLK descriptors in the menu, unless it is re-defined for a specific item or SLK.

lifetime

The lifetime descriptor defines when the menu frame will be closed (that is, removed from the work area). It is evaluated whenever the menu is opened, closed, made current, or made non-current. The acceptable values are:

shortterm

the menu closes whenever the user navigates to another frame or when the command line is accessed (the user presses CTRL-j or CTRL-f c)

longterm

the menu closes when the user issued a cleanup or close command.

permanent

the menu closes whenever the user issues a close command

immortal

the menu closes only when the user exits from the application

The lifetime descriptor is ignored in menu definition files given as arguments when fmli is invoked. Such menus have a lifetime of immortal. See "Example Form Definition Files" later in this chapter for an example of using this descriptor to close a frame when another is updated.

menu

The menu descriptor defines the title of a menu that appears in the frame's title bar. If not defined in the frame definition file, it defaults to Menu. It will be truncated if it is longer than DISPLAYW -6.

multiselect

The multiselect descriptor defines whether the menu is a multi-select menu. A multi-select menu allows the user to select more than one menu item. When this descriptor evaluates to TRUE, the SLK F2 will map to the mark command, and the nature of the action descriptor changes for all items (see the description of action in "Item Descriptors for Menus").

oninterrupt

The command descriptor oninterrupt defines what will happen when an interrupt signal is received. If interrupt is not coded anywhere in your application, or if it evaluates to FALSE, oninterrupt is ignored.

oninterrupt is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value `message Operation interrupted!' nop applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information.)

For example, if defined among the frame descriptors in a menu definition file, the value of oninterrupt is inherited by all sets of item descriptors and all sets of SLK descriptors in the menu, unless it is redefined for specific item or SLK.

reread

If reread is not defined, it defaults to FALSE. If reread evaluates to TRUE, the menu will be periodically updated by rereading it's description file when the checkworld command is executed. checkworld is executed when a SIGALRM alarm occurs (every $MAILCHECK seconds). Other times checkworld is executed include when a frame is opened, closed, or navigated to.

See checkworld, and "Built-in Variables" in Chapter 2. When checkworld occurs, all frames whose reread descriptor evaluates to TRUE will be updated. (However, the menu descriptor is not reread.) Execution of checkworld may cause the message line to clear.

rows

The rows descriptor defines the desired number of rows long a menu frame will be. It must evaluate to an integer value greater than 0 and less than DISPLAYH -2; if it doesn't, rows will be ignored. If neither this descriptor nor columns is defined, menu dimensions will be determined by FMLI. Given columns, the number or rows needed to display the items in the menu is calculated. If there is a conflict between the value provided by the rows descriptor and the calculated value, the calculated value takes precedence. (A table summarizing these calculations can be found in Appendix A, "Programming Tips".)

Item Descriptors for Menus


In each set of item descriptors, the name descriptor must be first; but others may be in any order. If a descriptor appears more than once in a set, the last one is used.

action

The action descriptor defines an action to be executed when the user selects this item in a single-select menu. Multiple backquoted expressions are allowed, as they are with any descriptor, but the final value of this descriptor must be a single FMLI command.

If the menu is multi-select (multiselect=true), the nature of this descriptor changes: FMLI commands are ignored if defined in this descriptor; however, backquoted expressions are executed when the item is marked.

description

The description descriptor defines a string which is displayed to the right of the item name but which is not highlighted when the cursor is on the item. When this descriptor is defined for any item in a menu, that menu will automatically display a single column of items, even if columns is defined.

inactive

The inactive descriptor defines an item as inactive when the menu is displayed. An item that is inactive cannot be navigated to, and consequently cannot be selected or unselected. If not defined inactive defaults to FALSE. If this descriptor evaluates to TRUE, the item is displayed with half bright attribute (on most terminals). In multi-select menus, an inactive item can be selected only if the selected descriptor evaluates to TRUE for the item.

interrupt

The Boolean descriptor interrupt defines whether an executable that is codes in action or done descriptors can be interrupted by users (FALSE means not interruptible, TRUE means interruptible). It is subject to an inheritance hierarchy: If not defined anywhere in your application, the default value FALSE applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information.)

If defined in a set of item descriptors in a menu definition file, that value of interrupt is inherited only by that menu item.

itemmsg

The itemmsg descriptor defines information that will be displayed on the message line when the item is navigated to. The itemmsg descriptor displays a message with transient duration. That is, it remains on the message line only until the user presses another key or a checkworld occurs.

Transient messages take precedence over frame duration messages and permanent duration messages (see the message(1F) manual page for more information).

lininfo

the lininfo descriptor defines a string which will be assigned to the local environment variable LININFO when the user selects this menu item. If lininfo is not defined, LININFO evaluates to null. In multi-select menus, when the getitems built-in utility is executed, if lininfo is defined and this item is marked, its value is output.

name

The name descriptor defines a string that will appear in the menu, identifying the menu item. This string is highlighted when the item is navigated to. For multi-select menus, when the getitems built-in utility is executed, and the lininfo descriptor has not been defined for this marked item, the value of the name descriptor is output.

oninterrupt

The command descriptor oninterrupt defines what will happen when an interrupt signal is received. If interrupt is not coded anywhere in your application, or if it evaluates to FALSE, oninterrupt is ignored.

oninterrupt is subject to an inheritance hierarchy: if not defined anywhere in your application the default value `message Operation interrupted!' nop applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information).

If defined in a set of item descriptors in a menu definition file, that value of oninterrupt is inherited only by that menu item.

selected

The selected descriptor defines whether a menu item in a multi-select menu should default to selected (TRUE) or not selected (FALSE) when the menu is opened. If selected evaluates to TRUE, the item is marked with the selected icon (an asterisk) when the menu is opened. If this descriptor is not defined, it defaults to FALSE. This descriptor is ignored when multiselect evaluates to FALSE (that is, in single-select menus).

show

The show descriptor defines whether this menu item will be displayed. If this descriptor is not defined, it defaults to TRUE, and the menu item will be displayed. If it evaluates to FALSE, the menu item will not be displayed.

NOTE: Screen labels and actions for function keys can be defined in a menu description file as well as in the initialization file. Each set of screen-labeled function key descriptors must include the name, button, and action descriptors, and name must be first. If a descriptor appears more than once in a set, the last one is used.

See Chapter 4, "Application Level File Descriptors" for a discussion of how to use the screen-labeled function key descriptors.

Examples of Menu Definition Files


The following examples show you how to write menu definition files.

Defining a Simple Menu


A menu definition file usually starts with a set of descriptors which pertain to the entire menu, known as frame descriptors. However, frame descriptors are optional in menu definition files. If you choose not to define any explicitly, their default values apply to that menu.

The following menu definition files has no frame descriptors, and defines four simple menu items. (Blank lines between logical sections of frame definition files are recommended for readability.)

Menu.items: An Example of Menu Item Descriptors


The first item definition permits the user to access a full-screen UNIX System shell. The second item definition runs find(1) to locate files whose contents have been modified within the past seven days and saves the list of filenames in a file named modfiles. The third item runs find to locate files which are executable by the owner and also saves the ouput in a file, named execfiles. The fourth menu item permits the user to exit from this FMLI application.

Because no frame descriptors were defined, nor were any SLKs defined, their default values apply: for example, menu is a frame descriptor used to define a title for a menu. Since Menu.items did not explicitly define it, the default value Menu is displayed in the title bar. This menu would appear as follows:

Undisplayed Graphic

The next example illustrates the use of several frame descriptors in the same menu definition file to change the appearance and add to the functionality of this menu:


The first group of descriptors is the frame descriptors. The frame descriptor menu defines a title for the menu, My First Menu. The begrow and begcol descriptors define the position of the top left corner of this frame in the work area. In this example, the top left corner of the frame will be located at the vertical center of the work area, and column 30 horizontally.

The framemsg descriptor defines a string that will appear on the message line when this frame is opened. It will remain on the message line until the frame is closed or made non-current, (although it can be temporarily replaced by other, shorter-term messages). The help descriptor defines what will happen when a user requests help while this menu is active. In this example, the string A help message will be displayed on the message line.

The following figure shows how Menu.frame will be displayed after these frame descriptors have been defined.

Undisplayed Graphic

Creating Multi-Column and Scrollable Menus


The columns and rows descriptors are used to change the display of a menu. When the frame descriptor rows is defined in the menu definition file as follows:

Menu.rows: An Example of a Scrollable Menu


Menu.rows will create the following menu as shown in the following figure:

Undisplayed Graphic

Because the rows descriptor defines this menu to have only one row, only one menu item can be displayed at a time: as the user navigates to any of the other defined menu items, the menu will scroll to display it.

The same menu is displayed differently when, instead of defining the rows descriptor, the columns descriptor is defined as follows:

Menu.columns: An Example of a Two-Column Menu


The following figure shows the display of the menu changes.

Undisplayed Graphic

The columns descriptor takes precedence over the rows descriptor if there is a conflict. For example. defining both rows=1 and columns=2 in this menu definition file results in the same display of the menu as shown in the previous figure. That is, the menu items are displayed in two columns but not one row.

Using the reread Descriptor


The reread descriptor in a frame definition file is used to request that a frame be reread when a checkworld is executed. One time that checkworld is executed is when a SIGALRM signal occurs (a SIGALRM occurs every MAILCHECK seconds). The frame is rebuilt if this descriptor evaluates to any value other than FALSE.

This example uses the output of the UNIX system date(1) command in the title of the menu and in the name of the first item. Recall the the menu descriptor is not re-evaluated when reread evaluates to TRUE, but the name descriptor is:

Menu.reread: An example of a Dynamically Updated Menu


This menu definition file creates the following menu shown in the following figure.

Undisplayed Graphic

After a SIGALRM occurs (for example, if MAILCHECK=180 and 3 minutes have elapsed) the date in the name of the first item changes but the date in the menu's title does not change. The following figure shows how the menu now looks.

Undisplayed Graphic

Using the interrupt and oninterrupt Descriptors


To illustrate the concepts of inheritance and scope of the interrupt and oninterrupt descriptors, the following menu definition files define them with frame descriptors and item descriptors in a menu definition file:

Menu.interrupt: An Example of Interrupt Signal Handling


When defined among the frame descriptors the value of interrupt is inherited by all process initiated in action descriptors anywhere in the menu definition file, unless it is redefined for a particular item or SLK. Thus, if the user selects either the Find Modifed Files or Find Executable Files item from this menu the named process will run till its normal completion. However, the user can interrupt either process because interrupt=true is defined among the frame descriptors for this menu. (Note that output from Find Modified Files is saved in a file named modfiles, and that output from Find Executable Files is saved in a file named execfiles)

When a user presses the interrupt key, the message Operation interrupted! appears at the bottom of the screen and the process is terminated. This is the default behavior when not other messages or actions have been defined via the oninterrupt descriptor, as is the case in this menu.

You can be more specific about what processes you want users to be able to interrupt and about what you want done when a process is interrupted. For example, you can block the interrupt mechanism for any item on the menu by setting the interrupt descriptor to FALSE for the item. A process initiated from that item cannot be interrupted, even if the frame descriptor interrupt is set to true:

Menu.,oninterr: A Further Example of Interrupt Handling


If a user selects Find Modified Files from this menu definition file the process it initiates cannot be interrupted. If a user selects Find Executable Files from this menu, it can be interrupted, and when it is, the processing defined for this item by the oninterrupt descriptor will occur.

Providing Supplementary Information for Menu Items


The item descriptor description defines supplementary information to be displayed on the same line as the menu item. You might want to use it to give your users a brief explanation of what an item does. This example shows how it is used.

Menu.descrip: An Example of the description Descriptor


This menu definition file creates the menu shown in the following figure.

Undisplayed Graphic

This is a single column menu. It will be a single column menu even if the rows or columns descriptors are defined in an attempt to make it multi-column, because when the description descriptor is explicitly defined, the columns descriptor is ignored.

Displaying an Item Message


The following example shows how to use the itemmsg descriptor to display a message specific to a single menu item.

Menu.itemmsg: An Example of the itemmsg Descriptor


Whenever the user navigates to the second menu item the message defined in the itemmsg descriptor is displayed as shown in the following figure. It will temporarily replace a frame message if one was created by the framemsg descriptor.

Undisplayed Graphic

Using the show Descriptor


When the show descriptor is defined and evaluates to FALSE the item in which it is defined does not appear on the menu. Defining the show descriptor as a variable allows you to decide dynamically whether or not to display a menu item.

In this example, the third item will not appear on the menu created by the following menu definition file if the login ID of the user running your application is not root:

Menu.show: An Example of the show Descriptor


The following figure is how Menu.show is displayed for a users logged in as joe:

Undisplayed Graphic

Creating a Dynamic Menu


Now let us take a look at some more complex menus. This example shows how to pass parameters from one frame to another and how to create a menu dynamically. This example application will be used for editing frame definition files stored in the same directory. As you know, there are three types of frame definition files: menu, form, and text frame. This application displays a "top menu" from which the user can select the type of frame definition file to edit:

Menu.edit: An Example of a Dynamically Created Menu


This menu definition file creates a screen that is shown in the following figure.

Undisplayed Graphic

From this menu a user can choose to see a menu of menu frame definition files, form definition files, or text frame definition files. The action defined for all three menu items results in the same frame definition file being opened: Menu.dynamic. The last argument to the open command is a parameter that is passed Menu.dynamic. The following example shows the contents of Menu.dynamic.

Menu.dynamic: An Example of a Dynamically Created Menu


Menu.dynamic is a dynamically built menu that uses regex. The parameter passed to Menu.dynamic by the open command is used to build a unique title for the new menu. The items on this menu are created by a stand-alone backquoted expression. Recall that stand-alone backquoted expressions are evaluated when the frame definition file is opened, reread, or updated. That means that when Menu.dynamic is opened in this case, the ls command is run in the current working directory, and its output is piped to the FMLI built-in utility regex.

The regex utility is used for pattern matching. Since this single regex pattern matches only files that begin with $ARG1, only files in the directory that have the name defined by the parameter, followed by a literal dot (.), then by any other characters, are included in the list of menu items. The menu definition file Menu.dynamic will create one of the three menus, based on the parameter that is passed to it. The items in the menu it creates are based on the files whose names match the pattern being searched for by the regex utility. The menu item template defined in this menu definition file provides that the name descriptor has the value $m0, which evaluates to the pattern enclosed in parentheses (a file name) in the regex expression. The template provides that the action descriptor invoke the defined editor on the file. All file names matched by the regex utility are passed to this menu item template, FMLI determines the size and shape of the menu frame based on the total number of items produced, and the menu frame is posted.

For example, when Menu Files is selected from the menu titled Edit Files, Menu.dynamic received the parameter Menu, regex searches for file names beginning with Menu. ("menu dot"), and displays the second menu shown in the following figure.

Undisplayed Graphic

By selecting the appropriate item from the Menu Files menu, the user is able to edit any of the menu, form or text frame definition files in the directory. If one of these types of frame definition files is not present in the directory the corresponding menu is not created.

Form Frame Descriptors


A form definition file can begin with an optional set of frame descriptors, followed by one or more sets of field descriptors (one set per field), and it can end with one or more optional sets of descriptors that define the screen-labeled function keys that will be displayed when the form is the active frame in the user's work area (one set per SLK).

Some of the attributes of a form that you can define are the following:


the descriptors in a form definition file must follow this order:


CAUTION: Out-of-order descriptors will be ignored if this order--frame, then fields, then SLKs--is not followed.

Frame Descriptors for Forms


The optional set of frame descriptors can be any valid frame descriptors for forms, in any order. If a descriptor appears more than once in the set, the last one is used.

NOTE: Although technically, none of the frame descriptors is required in a form definition file, a form which does not define the done descriptor is virtually useless, since no user input will be recorded when the SAVE key is pressed, if done is not defined.

altslks

The altslks descriptor defines whether SLKs 9 through 16 are displayed when the frame is initially opened. If altslks evaluates to TRUE, SLKs 9 through 16 will be displayed. The default, if this descriptor is not defined, is FALSE, which causes SLKs 1 through 8 to be displayed.

begrow, begcol

The begrow and begcol descriptors define the original position of the top left corner of the form frame in the user's work area. (begrow=0 and begcol-0 evaluates to accept values of type position:

center

the form frame will be centered in the work area

current

the form frame overlaps the current frame's position (valid for begrow only)

distinct

the form frame will not overlap the current frame if possible (valid for begrow only)

any

FMLI chooses a position with least amount of total overlap

integer

the form frame will be positioned in an absolute position, defined by integer. Defining begrow and begcol to be integer values causes the frame to appear in the given position.

If either begrow or begcol evaluates to center, then the other can only be an integer value or center. Any other value is ignored and the descriptor defaults to center.

If neither is center, then the value of begrow determines the value of begcol: if begrow is current, distinct, any, or an illegal value, then begcol defaults to any. If begrow is a valid integer, begcol can be a valid integer: if begcol is an illegal integer in this case, it defaults to any. If integer values are supplied and either begrow or begcol are outside the screen boundary, a default value of any will be used.

close

The close descriptor is evaluated when the form is closed and when the user exits from the FMLI application. The close descriptor is of type null, which means its only purpose is to obtain the side-effects of a backquoted expression(s) coded in its definition.

done

The done descriptor defines the command to be executed when the user selects SAVE. If done is not defined, it defaults to the FMLI command close. Note that user input is not saved automatically: user input to the form should be recorded by backquoted expressions in the done descriptor.

framemsg


form

The form descriptor defines the title of the form frame. It will be truncated if it is longer than DISPLAYW -6

help

The help descriptor specifies what will happen when the user requests help while in the form. Since this descriptor is evaluated at the time the user requests help, the specification of what help is displayed can be determined through parameters that are set interactively.

init

The init descriptor defines whether the form frame will be opened. If this descriptor is not defined, it defaults to TRUE, which means the form frame will be opened. If init evaluates to FALSE, the form frame will not be opened.

interrupt

The Boolean descriptor interrupt defines whether an executable that is codes in action or done descriptors can be interrupted by users (FALSE means not interruptible, TRUE means interruptible). It is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value FALSE applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information.)

For example, if defined among the frame descriptors in a form definition file, that value of interrupt is inherited by the frame descriptor done, and the action descriptor in all sets of SLK descriptors in the form, unless it is redefined for a specific SLK.

lifetime

The lifetime descriptor defines when the form will be closed (that is, removed from the work area). It is evaluated whenever a form is opened, closed, made current, or made non-current. The acceptable values are:

shortterm

the form closes whenever the user navigates to another frame or when the command line is accessed (the user presses CTRL-j or CTRL-f c).

longterm

The form closes when the user issues a cleanup or close command

permanent

The form closes whenever the user issues a close command

immortal

The form closes only when the user exits from the application

The lifetime descriptor is ignored in form definition files that are given as arguments when fmli is invoked: such forms have a lifetime of immortal. See "Example Form Definition Files" later in the chapter, for an example of using this descriptor to close a form when another frame is opened or updated.

oninterrupt

The command descriptor oninterrupt defines what will happen when an interrupt signal is received. If interrupt is not coded anywhere in your application, or if it evaluates to FALSE, oninterrupt is ignored.

oninterrupt is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value `message Operation interrupted!' nop applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information.)

For example, if defined with the frame descriptors in a form definition file, the value of oninterrupt is inherited by the frame descriptor done, and by the action descriptor in all sets of SLK descriptors, unless redefined for a specific SLK.

reread

If reread is not defined, it defaults to FALSE. If reread evaluates to TRUE, the form will be periodically updated by rereading it's description file when the checkworld command is executed. checkworld is executed when a SIGALRM alarm occurs (every $MAILCHECK seconds). Other times checkworld is executed include when a frame is opened, closed, or navigated to. See checkworld and "Built-in Variables" in Chapter 2. When checkworld occurs, all frames whose reread descriptor evaluates to TRUE will be updated. (However, the form descriptor is not reread.) Execution of checkworld may cause the message line to clear.

Field Descriptors


The following descriptors can be defined once for each field in a form. In each set of field descriptors, name must be first. If a descriptor appears more than once in a set, the last one is used.

NOTE: There must be at least one active, visible (i.e., show=true) field in a form. If you open a form and none of the fields can be posted because rows or columns is negative or 0, or if frow or fcol is negative, fmli will display an empty frame with the cursor positioned in the title bar. If the form definition file contains properly defined field labels, they will be displayed.

autoadvance

The autoadvance descriptor defines whether a RETURN is automatically performed when a user fills in the last character of a field. It defaults to FALSE (an automatic RETURN is not performed).

If autoadvance is defined and evaluates to TRUE, when the user types in columns characters, the field will be automatically validated, and if valid, the cursor will be automatically advanced to the next field. This descriptor is ignored in scrollable fields (horizontally scrollable or multiline scrollable).

choicemsg

The choicemsg descriptor defines information to be displayed on the message line when the user presses CHOICES. The choicemsg descriptor displays a message with transient duration. That is, it remains on the message line only until the user presses another key or a checkworld occurs. Transient messages take precedence over frame duration messages and permanent duration messages (see the message(1F) manual page for more information). The default, if choicemsg is not defined, is There are no choices available.

fieldmsg

The fieldmsg descriptor defines information that will appear on the message line when this field is navigated to. The fieldmsg descriptor displays a message with transient duration. That is, it remains on the message line only until the user presses another key or a checkworld occurs. Transient messages take precedence over frame duration messages and permanent duration messages (see the message(1F) manual page for more information).

frow, fcol

The frow and fcol descriptors define the position of the field input area in the frame, The value can be an integer greater than or equal to 0 and less than DISPLAYW -2. (frow=0 and fcol=0 evaluate to the upper left corner of the frame.) If either value is negative or if either value is too large (the position is off the screen), then the field input area will not be displayed. If no field input areas are displayed on a page of a form, the cursor is positioned in the title bar.

inactive

The inactive descriptor defines a form field that is displayed in the form, but cannot be navigated to. If this descriptor is not defined, it defaults to FALSE (the field will be active). If this descriptor evaluates to TRUE, the field is displayed in the form, without an underline, and cannot be navigated to. The inactive descriptor is re-evaluated each time the cursor is moved from one field to another. There must be at least one active field for a form to be displayed.

invalidmsg

The invalidmsg descriptor defines a string that will be printed on the message line when the input for the field is invalid. The invalidmsg descriptor displays a message with transient duration. That is, it remains on the message line only until the user presses another key or a checkworld occurs. Transient messages take precedence over frame duration messages and permanent duration messages (see the message(1F) manual page for more information).

lininfo

The lininfo descriptor defines a string which will be assigned to the built-in variable LININFO when the user navigates to this field. If lininfo is not defined, LININFO evaluates to the null string.

menuonly

The menuonly descriptor defines the choices listed in the rmenu descriptor to be the only valid input for this field. If this descriptor evaluates to TRUE, then the user must input one of the choices in rmenu for this field. menuonly must only be used when the rmenu descriptor has been defined using the curly brace format, otherwise no input will be valid.

NOTE: In effect, menuonly causes the user's input to be checked against the rmenu list to determine validity. If you define menuonly for a field, do not define the valid descriptor.

name

The name descriptor defines the label for a field in the form. The value you define for name should tell the user what piece of information is wanted in the field. It can also be used to display information in a form, such as Page 2 of 4. (See "Example Form Definition Files" in this chapter for examples of using name, and inactive to display information in a form.)

noecho

The noecho descriptor defines whether what the user types in the field input area will be displayed, This descriptor defaults to FALSE (input will be displayed). If noecho does not evaluate to FALSE, then what the user types in this field will not be echoed on the input field (this descriptor is often used when the requested input is a password). noecho should not be defined for multi-line fields.

nrow, ncol

The nrow and ncol descriptors define the position of the first character of name in the form. These descriptors take integer arguments: the value of ncol can be greater than or equal to 0 and less than DISPLAYW-6; the value of nrow can be greater than or equal to 0 and less than DISPLAYH -2. (nrow=0 and ncol=0 evaluate to the upper left corner of the frame.) If either value is negative, name will not be displayed. If either integer is too large (the position is off the screen), the entire form will not be displayed.

page

The page descriptor allows you to define the page of a form on which this field will appear. (In effect, page creates multi-page forms.) This descriptor defaults to the integer 1 (all fields will appear on page 1). If page is defined for a field and evaluates to 2, for example, that field will appear on page 2 of the form.

The page descriptor accepts integer values greater than 0 (zero). A zero or negative value for this descriptor will cause the field to not appear in the form.

rmenu

The rmenu descriptor defines a list of choices for a field. Two formats are acceptable when defining this descriptor: The first format is a list of choices, separated by white space, enclosed in braces. The white space after the opening brace and before the closing one is mandatory:


NOTE: If your definition of rmenu degenerates to an empty list, (rmenu={}), the value of choicemsg will be displayed--your definition, if you have defined one, or the FMLI default message There are no choices available. If you define choicemsg, be sure it is appropriate to the "empty list" case.


The second format is an open command. When you use this format, the rmenu descriptor evaluates to opening a menu, and the user selects from that menu. For example:


NOTE: Do not use menuonly with this format. To validate the choices in a Choices menu, use the valid descriptor.


rows, columns

The rows and columns descriptors define the maximum size of the input area (the length and width of the region in which the users can type). These descriptors accept an integer value: the value or rows must be greater than 0 and less than DISPLAYH -2; the value of columns must be greater than 0 and less than DISPLAYW -4. If either is less than or equal to 0 (zero) the field will not be displayed. If either value is too large (the position is off the screen), the entire form will not be displayed.

In effect, a value greater than 1 for rows created a multi-line field.

scroll

The scroll descriptor defines whether a field input area can scroll. There are two types of scrolling: vertical, for multi-line fields; and horizontal, for single-line fields. If not defined, this descriptor defaults to FALSE (field input area cannot scroll).

If scroll evaluates to TRUE, then the field input area can be scrolled. This means that the field input area can be as long as the entry the user types, and the columns descriptor is not a limit for the length of user input. For single-line fields, the last space in columns is reserved for scroll symbols: > means the field can be scrolled to the right, < means the field can be scrolled to the left, and = means the field can be scrolled either left or right. For example, after the user types in columns -1 valid characters, the field will scroll, and the < symbol will appear in the lst space, indicating that the input in the field has scrolled to the left. For multi-line fields, scroll indicators for up (^) and down (v) appear in the bottom right border of the frame when the user has entered data up to the last character in the last displayed line of the field. For example, after the user types in rows lines of information, the scroll indicator for up (^) appears in the lower right border.

show

The show descriptor defines whether a field will be displayed in the form. If show evaluates to FALSE, then the label and the input field area will not be shown. There must be at least one field for which show evaluates to TRUE, or the form will not open. The show descriptor is re-evaluated each time the cursor moves from one field to another. Note that even if the field is not shown, it still counts as a field for the purpose of evaluating the built-in variable Fn. (See "Variables" in Chapter 2 for more information about the built-in variable Fn.)

valid

The valid descriptor defines whether what a user has entered in the input area of a form is valid. If valid evaluates to FALSE, the current input is considered invalid and FMLI will not process the field or evaluate the done descriptor. Checking the validity of the field is often done by evaluating a backquoted expression. The backquoted expression must be coded to evaluate to TRUE when the value is valid, FALSE otherwise.

NOTE: The built-in utility regex is often used in a valid descriptor for field validation. For example, it can be used to require that part of a field be non-numeric. The FMLI conditional statement has essentially the same functionality as the UNIX system shell conditional statement, and can be used to do more complicated validations.

Every field that defines the valid descriptor is validated when a user enters a value in that field. When the form is saved, those fields that have not been visited by the user (navigated to) are validated, including those which have a default value defined (see value descriptor).

For example, if a user opens a form frame with five fields that define the valid descriptor, but only visits the first two fields, the two visited fields are validated before the user can leave them. The remaining three fields will be validated when the user saves the form.

If any field (including fields on other pages in a multi-page form) does not pass its validation function, then FMLI will not process the field, the cursor will jump to the invalid field if not already on it, and the message defined in the descriptor invalidmsg (if defined, otherwise the default message) will be displayed on the message line, and the done descriptor will not be evaluated. In the case of more than one invalid field, this behavior will be repeated in field order.

NOTE: Be cautious using the valid descriptor on a field that could become inactive. Unexpected behavior can occur.

value

The value descriptor defines the default value for the input field. If this descriptor is defined, its value will be displayed in the field when the form is opened or updated. This default is not changed by the user entering data into the field. This default value will be restored when the FMLI command update is executed, or if the built-in utility reset is run when the field is current. The value descriptor may be re-evaluated each time the cursor moves from one field to another.

wrap

The wrap descriptor defines whether word wrap will occur if a word will not fit on the current line of a multi-line field. If this descriptor is not defined, it defaults to FALSE. If wrap evaluates to FALSE, then the cursor will not automatically wrap to the next input line when the user is typing an entry in this input field. If wrap evaluates to TRUE, when a user is typing word in a field and word won't fit on the current line, then if there is room on the next line (and word will fit there), then word will automatically be moved to the next line.

The wrap descriptor is ignored in a single-line field.

NOTE: Screen labels and actions for function keys can be defined in a form description file as well as at the initialization file level. Each set of screen-labeled function key descriptors must include the name and button descriptors, and the name descriptor must be first. If a descriptor appears more than once in a set, the last one is used.

See Chapter 4, "Application Level Files," for a discussion of how to use the screen-labeled function key descriptors.

Example Form Definition Files


The following examples show you how to write form definition files.

Saving User Input to a Form


May of the frame descriptors for forms and menus have the same names and do the same things. Since they were discussed in the examples of menu definition files, they won't be covered again here. Some frame descriptors in forms are different than in menus, however.

You can use the frame descriptor done to take information entered in a form by a user and save it in a file. The address entered by the user in the following form is to be written in a file named Addr.file. To accomplish this, the form definition file can be defined as follows:

Form.addr: An Example of a Form


This frame definition file creates the following form shown in the following figure.

Undisplayed Graphic

This form can be used in an application where addresses have to be entered into the system. If a user fills in this form shown in the following figure

Undisplayed Graphic

when the user presses SAVE (or CTRL-f 3), the done descriptor is evaluated and the following information is written into the Addr.file file:

Addr.file: Contents After User Saves the Form


If Addr.file does not exist it is created. If it already exists the information above is appended to it.

Note that the done descriptor in forms is of type command, and thus must evaluate to an FMLI command. In this example, done evaluates to the FMLI command update. After the user input is saved in the file Addr.file, the update command causes the form to be updated to its default values (a blank form), the cursor is positioned on the first field, and the user can begin to enter a new address record in the Address Entry Form form.

Validating a Form Field


Let us add some more functionality to the form. Assume that in this form it is valid to enter addresses of only three states; New York, New Jersey, and Connecticut. To do this three more field descriptors are added to the State field in the frame definition file

Form.3choices: An Example of Field Validation Using the Menuonly Descriptor


This form definition file will create the same form as above. However, the rmenu descriptor is used to create a Choices menu, and the menuonly descriptor defines only the choices in the Choices menu to be valid field values. If the user enters an invalid state code in the State field and presses RETURN or SAVE, the message defined by the invalidmsg descriptor appears on the message line and the done descriptor will not be evaluated.

When the user presses CHOICES the first valid state code, CT, will be displayed in the State field (see the description of toggle in Chapter 4, and "Forms" in Chapter 1 for discussions of Choices Menus and how to change their default behavior). Each press of CHOICES displays the next valid state code (wrapping to the first choice after the last one is displayed).

Now we will add some more state codes to the list of states in our rmenu descriptor and we will change the invalidmsg descriptor to reflect the changes. The following set of state field descriptors

Form.6choices: An Example of a Choices Menu


creates the same form as before. But now if the user enters a wrong state code the following message will be displayed at the bottom of the screen:


To find the valid state codes the user can again press CHOICES. This time, the valid choices are displayed in a pop-up choices menu shown in the following figure. This behavior occurs by default when there are more than three choices in the rmenu list.

Undisplayed Graphic

When the user selects a code from the Choices menu the code is placed in the state code field and the CHOICES menu is closed, as shown in the following figure.

Undisplayed Graphic

Example of Validating a Field Value with the valid Descriptor


Let us add two more descriptors, valid, and invalidmsg, to the Zip field definitions as follows:

Form.valid: An Example of Field Validation Using the valid Descriptor


The valid descriptor is defined to execute regex to validate the field. If a pattern is matched by regex, regex will write the corresponding template to stdout. The regex utility will also return the value TRUE which, for FMLI built-in utilities, is analogous to a UNIX system command that exits with status 0. If no pattern is matched, regex will not write to stdout and will return FALSE. For FMLI built-in utilities, FALSE is equivalent to a UNIX system command that exits with a non-zero exit status. For example, the field validation shown in the example above (i.e., the valid descriptor definition) uses the -v option to regex to specify that the argument that follows (rather than stdin) should be used as input. Note that this regex statement contains a single pattern without a template. In regex, a template is optional if only one pattern exists. The last pattern in a series of pattern/template pairs is also optional.

This use of regex will return TRUE if the current value of field 5 consists entirely of integers and will return FALSE otherwise. Since no template exists, regex will not write to stdout. If the field is not numeric and not all five digits are entered, the following message defined by the invalidmsg descriptor is displayed:

Text Frame Descriptors


A text-frame definition file begins with a single set of frame descriptors (ones that define attributes of the whole text frame), and it can end with one or more optional sets of SLK descriptors that define the screen-labeled function keys (one set per SLK) that will be displayed when the text frame is the current frame in the user's work area.

Some of the attributes of a text frame that you can define are the following:


The descriptors in a text frame definition file must follow this order:


CAUTION: Out-of-order descriptors will be ignored if this order--frame, then SLKs--is not followed.

Text Frame Descriptors


The set of frame descriptors can be any valid frame descriptors for text frames, in any order. (However, a text frame usually starts with the line title=title. The default value for title, if you do not define it, is Text.) If a descriptor is defined more than once in the set, the last one is used.

altslks

The altslks descriptor defines whether SLKs 9 through 16 are displayed when the frame is initially opened. If altslks evaluates to TRUE, SLKs 9 through 16 will be displayed. The default, if this descriptor is not defined, is FALSE, which causes SLKs 1 through 8 to be displayed.

begrow, begcol

The begrow and begcol descriptors define the original position of the top left corner of the text frame in the user's work area. (begrow=0 and begcol=0 evaluates to the upper left corner of the work area.) These descriptors accept values of type position:

center

the text frame will be centered in the work area

current

the text frame overlaps the current frame's position (valid for begrow only)

distinct

the text frame will not overlap the current frame (if possible) (valid for begrow only)

any

FMLI chooses a position with least amount of total overlap

integer

the text frame will be positioned in an absolute position, defined by integer. Defining begrow and begcol to be integer values causes the frame to appear in the given position.

If either begrow or begcol evaluates to center, then the other can only be an integer value or center. Any other value is ignored and the descriptor defaults to center.

If neither is center, then the value of begrow determines the legal values of begcol: if begrow is current, distinct, any, or an illegal value, then begcol defaults to any. IF begrow is a valid integer, begcol can be a valid integer: If begcol is an illegal integer in this case, it defaults to any.

close

The close descriptor is evaluated when the text frame is closed and when the user exits from the FMLI application. The close descriptor is of type null, which means its only purpose is to obtain the side-effects of a backquoted expression(s) coded in its defintion.

done

The Boolean descriptor done defines what will happen when the user executes the cancel command. If done evaluates to FALSE, the text frame stays open; otherwise it is closed, unless lifetime evaluates to immortal for that frame.

edit

If this descriptor evaluates to TRUE, then the user can modify the text. Otherwise, the text is read-only. The default for this descriptor is FALSE.

If the user modifies the text in the displayed text frame, this does not modify the frame definition file.

framemsg


header

The header descriptor defines information that will remain permanently displayed at the top of a text frame. For example, if a text frame contains a long table of information, header can be used to define column headings that will remain displayed below the title of the text frame while the user pages or scrolls through the rest of the table. The text defined in header can include embedded newline characters, and will be left justified in the frame. The header text cannot occupy all rows of the text frame: at least two lines must remain available for display of the text.

help

the help descriptor specifies what will happen when the user requests help while in this text frame. Since this descriptor is evaluated when the user requests help, the specification of what help is displayed can be determined through parameters that are set interactively.

init

If init evaluates to FALSE then the frame will not be displayed. If it evaluates to FALSE when the update command is executed, the frame closes.

interrupt

The Boolean descriptor interrupt defines whether an executable that is coded in action or done descriptors can be interrupted by users (FALSE means not interruptible, TRUE means interruptible). It is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value FALSE applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information.)

If defined among the frame descriptors in a text frame definition file, that value of interrupt is inherited by the action descriptor in all sets of SLK descriptors in the form, unless it is re-defined for a specific SLK.

lifetime

The lifetime descriptor defines when the text frame will be closed (that is, removed form the work area). It is evaluated whenever the text frame is opened, closed, made current, or made non-current. The acceptable values are:

shortterm

the text frame closes whenever the user navigates to another frame or when the command line is accessed (the user presses CTRL-j or CTRL-f c).

longterm

the text frame closes when the user issues a cleanup or close command

permanent

the text frame closes whenever the user issues a close command

immortal

the text frame closes only when the user exits from the application

The lifetime descriptor is ignored in text frame definition files that are given as arguments when fmli is invoked: such text frames have a lifetime of immortal. See "Example Form Definition Files" later in this chapter, for an example of using this descriptor to close a frame when another frame is opened or updated.

oninterrupt

The command descriptor oninterrupt define what will happen when an interrupt signal is received. If interrupt is not codes anywhere in your application, or if it evaluates to FALSE, oninterrupt is ignored.

oninterrupt is subject to an inheritance hierarchy: if not defined anywhere in your application, the default value `message Operation interrupted!' nop applies throughout. If explicitly defined at any inheritance level, then executables in action and done descriptors at or above that inheritance level will inherit that defined value. (See Chapter 2, "Interrupt Signal Handling" for complete information.)

If defined with the frame descriptors in a text frame definition file, the value of oninterrupt is inherited by the action descriptor in all sets of SLK descriptors, unless redefined for a specific SLK.

reread

If reread is not defined, it defaults to FALSE. If reread evaluates to TRUE, the text frame will be periodically updated by rereading it's description file when the checkworld command is executed. checkworld is executed when a SIGALRM alarm occurs (every $MAILCHECK seconds). Other times checkworld is executed when a frame is opened, closed, or navigated to. See checkworld and "Built-in Variables" in Chapter 2. When checkworld occurs, all frames whose reread descriptor evaluates to TRUE will be updated. (However, the title descriptor is not reread.) Execution of checkworld may cause the message line to clear.

rows, columns

The rows descriptor defines the desired number of rows long a text frame will be. It must evaluate to an integer value greater than 0 and less than DISPLAYH -2. The columns descriptor defines the width of a text frame. It must evaluate to an integer value greater than 0 and less than DISPLAYW -4.

text

The text descriptor defines the text you want to display.

title

The title descriptor defines the title of the text frame that will appear in the title bar. It will be truncated if it is longer than DISPLAYW -6. If not defined, it defaults to the string Text.

wrap

If this descriptor is set to anything except FALSE, the text will be wrapped to fit the available space when it is read in. If wrap evaluates to TRUE, word boundaries are respected at newlines. If not defined wrap defaults to TRUE. Newlines in your text are always preserved.

NOTE: Screen labels and actions for function keys can be defined in a text description file as well as in an initialization file. Each set of screen-labeled function-key descriptors must include the name and button descriptors, and the name descriptor must be first in each set. If a descriptor appears more than once in a set, the last one is used.

See Chapter 4, "Application Level File Descriptors", for a discussion of how to use SLK descriptors.

Example Text Frame Definition Files


The following examples will show you how to write a text frame definition file. We'll begin by looking at a simple use of the frame descriptors for text frames, and build from there.

Defining Attributes of Text Frames


The following example is a simple description file for a text frame.

Text.USA: An Example of a Text Frame


The lifetime descriptor defines this text frame to remain on display until the user issues a cleanup or close command. The wrap descriptor defines word-wrapping to occur: that is, a word that will not fit entirely on the current line will be displayed in full on the next line. The frame will look like the one shown in the following figure.

Undisplayed Graphic

Notice that even though the text is wrapped at 40 columns, the original newline characters are preserved.

Defining a Text Frame with readfile and longline


A more interesting way to define a text frame is to use the built-in utilities readfile and longline as shown in the following example.

Text.readfile: An Example of using readfile and longline in a Text Frame


Text.readfile illustrates the use of arguments that may be passed to menu, text, or form frames. You don't have to define a separate text frame definition file for each file that is to be displayed. Instead, pass $ARG1 to the text frame when you open it. For example, if Text.readfile were opened by a lines in a menu that looked like this:


$ARG1 would evaluate to help1, that file would be read by the built-in utility readfile, and all of the text in help1 would become the value of the text descriptor, which would then be displayed in a text frame as wide as the longest line of text in the file help1.

For more on how this happens, see the section "Variables" in Chapter 2, and the readfile(1F) manual page.

Using Text Frame Headers and Terminal Attributes


Text frame headers, defined by the header descriptor, are useful when you want to permanently display some information, perhaps a warning, or headings for columns of information, while the text of the text frame can be scrolled through by the user. This example also illustrates the use of the terminal display attribute for underlining.

Text.header: An Example of Text Frame Headers


This frame definition file results in the following screen shown in the following figure.

Undisplayed Graphic

The terminal attribute of underlining has been turned on for the text header to set it apart from the list of department members. Since the frame is defined to be 5 rows long, and the header uses one of those rows, the text is displayed in 4 rows, and the scroll bar indicates that there is more text that follows.

Other Useful Examples

Defining a Help Frame for Menu Items or Form Fields


In this example let us take a look how the item descriptor lininfo and the built-in variable LININFO can be used in conjunction with the frame descriptor help to define help that is specific to the current menu item.

This example defines a menu title TOP MENU that has three items. The first item does not have any help information. When help is requested while the cursor is on this item the help text frame for the menu is displayed. The seconds and third item have help text frames associated with each item. The menu definition file for this menu is:

Menu.lininfo: An Example of Defining Help with LININFO


The text frame definition file Text.gen_help displays information appropriate to the menu as a whole. (Presumably this information is also sufficient for a user to understand how to use the first menu item, Item 1.)

Text.gen_help: An Example of a Help Text Frame


The text frame definition files Text.item2 and Text.item3 display appropriate help information for the second and third items on the menu.

Text.item2: An Example of a Help Text Frame


Text.item3: An Example of a Help Text Frame


When this application is run, the user sees the following screen shown in the following figure.

Undisplayed Graphic

If the user asks for help, either by the appropriate function key, or by the help command (from the command line or the command menu), the appropriate text frame will be displayed as shown in the following figure. The lifetime descriptor, defined in each of the help text frames to be shortterm, ensures that whenever the user navigates away from the help text frame, it will be removed from the work area, thus reducing screen clutter.

Undisplayed Graphic

If the user navigates to the second menu item and again asks for help, the following text frame shown in the figure below will be displayed.

Undisplayed Graphic

The text defined in Text.item3 is displayed in the same manner when HELP is pressed while the cursor is positioned on menu item 3, exit. The display of these help frames is controlled by the lininfo descriptor and the LININFO variable.

Using Co-Processing Utilities


Co-processing allows an external process to communicate with the user via a frame (menu, text, form). A co-process does not have direct access to the terminal's screen. It communicates with the FMLI application, which can then post the messages in the frame that contains the co-processing descriptors or take other appropriate actions.

The co-processing feature in FMLI consists of five built-in utilities: cocreate, cosend, cocheck, coreceive, and codestroy, which support inter-process communication.

The cocreate utility is responsible for initializing the co-process and setting up pipes between it and FMLI. The codestroy utility is responsible for cleaning-up when the communication has been completed. The utility cosend is used to send information to the co-process via the pipe and block (wait) for some response by the co-process. The -n option to cosend performs a "no wait" write. This means that cosend will send information to the co-process but will not block for a response. The cocheck utility checks the incoming pipe for information. The coreceive utility performs a "no-wait" read on the pipe. The purpose of these built-in utilities is to provide a flexible means of interaction between FMLI and a co-process; to be responsive to asynchronous activity.

It is important to not that information passed to FMLI from a co-process is treated as text only. FMLI command s(for example, open, close, update) will not be recognized by FMLI unless they become the value of a descriptor of type command.

to illustrate the use of co-processing, consider a UNIX program that wishes to "talk" to the user as it executes (an interactive program). The following sample menu displays the item talk. When talk is selected, the backquoted expression creates the co-process and then opens an "interactive" form, Form.talk.

Menu.talk: An Example of Co-Processing


In the form frame definition file Form.talk shown in the next example, the following occurs:


A SLK, F8, is defined to abort the co-process at any time. This is done by forcing a close operation (as usual, the descriptor close is evaluated when a frame is closed).

Form.talk: An Example of Co-Processing


The following code segment illustrates how an interactive co-process (in this case talk) may be structured:

talk: An Example of a Co-Process


The executable vsig(1F) is used to send a signal telling the Interpreter that information is pending. This interrupt causes reread to be evaluated. The vsig executable is documented. For more information about co-processing, see the coproc(1F) manual page.

Previous Page Page Top TOC Next Page