Appendix A

UFORM Statements

The vocabulary used to describe forms in TUXEDO System/T is embodied in the UFORM statements. UFORM statements can be produced in three ways:

The vuform field parameter pop-ups are shown in Figures 6 through 9 at the end of this section. Within the section there is information about how each parameter is specified in vuform.

Elements of a Basic Descriptor Statement

row
The line on the page where the field begins. The top line on a page is row 1. In vuform, this information is picked up from the location of the field in Layout Mode. In a UFORM statement, the value for row may be expressed in the following ways:

- row is same as in previous descriptor line.
+n row is n below the row in previous descriptor.
-n row is n above the row in previous descriptor.
n place field on row n.

COL
The column on a row where the field begins. The left-most column on a row is column 1. In vuform, this information is picked up from the location of the field in Layout Mode. In a UFORM statement, the value of COL may be any of the following:

- field starts in same column as previous field.
+n field starts n columns to the right of previous start.
n+ field starts n columns to the right of end of previous field.
-n field starts n columns to the left of previous start.
n field starts in column n.
C field is centered.

MIN
The minimum acceptable length of input. This element has no meaning for literals or protected variable fields. It applies only to unprotected variable fields where it can be used to make the field required. A zero or dash indicates that no entry is required, so the field is optional. In vuform, this information is specified on Page 1 of the Variable Field Parameters pop-up via the field labelled, Minimum number of characters:

LINES
The number of lines the field occupies. A dash indicates a one line field. In vuform, this information is picked up in Layout Mode from the depth of the field. Multi-line fields are required to be rectangular; that is, all lines of the field must be of the same width.

WIDTH
The number of character positions for each line of the field. For literal fields, WIDTH may be a dash, which means the width of the field is established by the length of the literal. In vuform, this information is picked up in Layout Mode from the width of the field.

FLAGS
The same attributes can also be specified on a #FORM or #PAGE statement. The attributes are listed in Figure 4 and several important points are discussed in the section ``Notes on Attribute Flags'' that follows Figure 4. In vuform, display features for a literal field are entered through the field labelled Display Flags: on the Literal Field Parameters pop-up. The TYPE flag is an implied L from the way the field was specified in Layout Mode. The other flag attributes (CASE, INITIAL, HOME, RESTRICTED or VALIDATION) have no meaning for literal fields, and so do not appear on the pop-up. For variable fields, all flag values are specified through fields on Page 1 of the Variable Field Parameters pop-up.
VALUE

In UFORM statements, the VALUE for a literal field is a string of characters. The string must be enclosed in quotes. In vuform, VALUE is the character string that was entered in Layout Mode. For a protected or unprotected variable field, VALUE must be the name of an FML field defined in a field table accessible to the form handler, mio. In vuform, the FML name of the field is entered on Page 1 of the Variable Field Parameter pop-up. Protected or unprotected fields can be subscripted (indexed). See Subscripted or Indexed Fields below. In vuform, subscripting is specified via the field labelled FML Field Occurrence: on Page 1 of the Variable Field Parameter pop-up.

Fig. 4: UFORM Attribute Flag Values

ATTRIBUTE FLAG EXPLANATION
TYPE L literal field
U unprotected field
P protected field
CASE u all data converted to upper case
l all data converted to lower case
m* data not converted (mixed case)
DISPLAY FEATURES S secret field, never displayed
N* display field.
0* normal mode (A_NORMAL)
1 standout mode (A_STANDOUT)
2 inverse video (A_REVERSE)
3 bold (A_BOLD)
4 dim (A_DIM)
5 blink (A_BLINK)
6 --------- (A_INVIS)
7 underline (A_UNDERLINE)
8 --------- (A_PROTECT)
9 --------- (A_ALTCHARSET)
INITIAL I initial cursor position
HOME H the home field. The mio home field function key, CTRL-t, moves the cursor to this field.
RESTRICTED R The cursor can be moved to this field, but keyboard input is not accepted. The field may be modified only with the display default function key. This option has no effect on a protected field.
r or unspecified* If unprotected, the field is unrestricted. All keyboard input is accepted. This option has no effect on a protected field.
FIELD-BY-FIELD VALIDATION V If a validation function is specified, the field is validated as the cursor leaves the field. Applies only to an unprotected field.
v or unspecified* Validation, if specified, is performed at exit from the form. Applies only to an unprotected field.

NOTE: * The default if nothing is specified.

Notes on Attribute Flags

More than one attribute flag can be specified for a field, although some are obviously mutually exclusive. If global attribute values have been set on the #PAGE or #FORM statements, a dash can be entered in the FLAGS element in place of attributes. One TYPE flag is required for each field; flags of all other classes are optional and have default values if nothing is specified. In the vuform Variable Field Parameter pop-up, TYPE is specified via a field labelled Protected Field? (y/n):; the default is n (Unprotected). Attributes can appear in any order. For example: P3 and 3P are equivalent. If no INITIAL field is specified, the cursor is initially placed in the first unprotected area on a page. DISPLAY FEATURE attributes are based on those supplied in the terminfo(4) database. Those shown in Figure 4 with dashes in the EXPLANATION column, should not be used unless the terminfo database is altered. In parentheses, next to the explanation of DISPLAY attributes 0-9 is the curses(3) equivalent. You can redefine these curses attributes in the terminfo database to take advantage of special features of a terminal. Changing the terminfo database automatically redefines the UFORM attribute flags. For example, if the terminfo definition of A_INVIS is changed to be the color red, then flag 6 defines a red field. DISPLAY FEATURE flag S denotes a secret field. As data is entered into a secret field, character echo is suppressed. When the form is used to display data, a secret field is not displayed. This does not imply that the data is stored in encrypted form. Flag R denotes unprotected fields with restricted values. The user can move the cursor to a restricted field, but no data is accepted from the keyboard. The user can toggle through the range of permissible choices with the display default function key, CTRL-w, leaving the field when the desired choice is displayed. The range of choices is specified with an extended descriptor DFLT statement.

Flag V causes mio to look for a VAL specification as the cursor leaves the field. The alternative is to postpone validation until the user leaves the form. If no VAL specification accompanies the field, then the field is not validated regardless of what is specified here. In vuform, the equivalent is the field labelled Validate when leaving (y/n): on Page 1 of the Variable Field Parameter pop-up.

Subscripted or Indexed Fields

A field name can be subscripted (or indexed). The subscript ties the field to a previous appearance of the same field; that is, one having the same FML field name or fieldname[subscript]. Fields thus tied together have identical value on display. On data entry, putting a value in one instance of a subscripted field puts the same value in all instances having the same subscript. If the same field name appears in another basic descriptor statement without a subscript, it creates an additional occurrence of the field in the fielded buffer. For example:

Fig. 5: Specifying Subscripted Fields


*	ROW	COL	MIN	LINES	WIDTH	FLAGS	VALUE
*	---	---	---	-----	-----	-----	-----
	+2	 -	10	  4	  15	U3	MSGFLD
	+2	 -	10	  4	  15	U3	MSGFLD
#PAGE
	+2	 -	10	  4	  15	U3	MSGFLD[0]
	+2	 -	10	  4	  15	U3	MSGFLD[1]
	+2	 -	10	  4	  15	U3	MSGFLD
#PAGE
	+2	 -	10	  4	  15	U3	MSGFLD[0]
	+2	 -	10	  4	  15	U3	MSGFLD[1]
	+2	 -	10	  4	  15	U3	MSGFLD

In this example, there are 8 instances of a field named MSGFLD. The first, second, fifth and eighth instances of MSGFLD are not subscripted. Hence they represent occurrences 0, 1, 2 and 3 of MSGFLD in the FML buffer. The third and sixth instance of MSGFLD are subscripted with a zero, so they are tied to the first instance (occurrence 0) of MSGFLD. Any data entered in any one of these fields (No. 1, No. 3, or No. 6) is displayed in all three. Similarly, the fourth and seventh instance of MSGFLD are tied to the second instance of MSGFLD, (occurrence 1). Any data entered in any one of these fields (No. 2, No. 4, or No. 7) is displayed in all three. Fields should only be subscripted across pages of a form. That is, only one instance of a fieldname[subscript] combination should appear on a single page. In the example, the fifth instance of MSGFLD is not subscripted, hence it results in an additional occurrence of MSGFLD in the buffer (occurrence 2). Similarly, the eighth instance of msgfld is not subscripted, hence it results in another additional occurrence of MSGFLD in the buffer (occurrence 3).

In vuform subscripting is done through the field labelled FML Field Occurrence: on Page 1 of the Variable Field Parameters pop-up. Leaving FML Field Occurrence: blank, where FML Field Name: repeats a previously specified field name, creates a new and different occurrence of the field. When the form is used, the content of this occurrence can legitimately be different from the earlier occurrence.

Fig. 6: vuform Literal Field Parameters Pop-up

TUXEDO VUFORM/V2
Literal Field Parameters
           Display Flags:________  (Press ESC 0 for help)
              >>> Press CTRL-v to save, or CTRL-d to return. 

Fig. 7: vuform Variable Field Parameters, Page 1

			       TUXEDO VUFORM/V2
                        Variable Field Parameters                Page 1 of 3
FML Field Name: ______________________   FML Field Occurrence:_____
                  Display flags:________    (Press ESC 0 for detail)
   Minimum number of characters: __
	 Protected field? (y/n): __
              Home field? (y/n): __
           Initial field? (y/n): __
	Restricted field? (y/n): __
            Secret field? (y/n): __
                   Case (u/l/m): __
   Validate when leaving? (y/n): __
   Page 2:  Help and error messages, default specification
   Page 3:  Validation and menu specifications
    >>> Press CTRL-v to save, CTRL-f to continue, or CTRL-d to return. 

Fig. 8: vuform Variable Field Parameters, Pages 2 and 3

			       TUXEDO VUFORM/V2
                    Variable Field Parameters                Page 2 of 3
Help message:
___________________________________________________________________
Error message:
___________________________________________________________________
Default type:__________    (Detail on default type and argument: ESC 0)
Argument:
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
    >>> Press CTRL-v to save, CTRL-f to continue, or CTRL-d to return. 
			       TUXEDO VUFORM/V2
                   Variable Field Parameters                Page 3 of 3
Validation type:___________  (Detail on validation type and argument: ESC 0)
Argument:
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
Menu type:           	     (Detail on menu type and argument: ESC 0)
Argument:
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
___________________________________________________________________
              >>> Press CTRL-v to save, or CTRL-d to return. 

Extended Descriptor Statements

Extended descriptor statements are optional for protected or unprotected fields. They may not be used with literal fields. If used for a protected or unprotected field, they occur directly after the basic descriptor statement for the field to which they apply, and should be indented.

Extended descriptor statements that exceed a single line may be continued by escaping the RETURN with a backslash.

In vuform, extended descriptor information is specified through Pages 2 and 3 of the Variable Field Parameters pop-up.

Format of Extended Descriptor Statement

Extended descriptor statements have the format:

KEYWORD=specification
where KEYWORD is a reserved word from the group

KEYWORD STATEMENT TYPE
HELP Help message
ERR Error message
DFLT Default values
VAL Validation options
MENU Menu choice
FORMEXIT Exit options

and specification is data appropriate to that keyword.

Up to five extended descriptor statements can follow a basic descriptor statement. (No more than one statement of each kind; a field can not have both a MENU statement and a FORMEXIT statement.)

A statement can be continued to another line by ending the first line with a backslash. The maximum length of a single statement is 1024 characters.

Specifications for HELP Statements

Any unprotected field can have a help message associated with it. The help message for a field is specified by the HELP extended descriptor statement. The syntax is


HELP=helpmsg
where helpmsg is a quoted string. For example:

HELP="Integer number expected"
The help message for the current field is displayed on the status line whenever the help key (CTRL-a in mio) is depressed. If no help message is available, the message:

NO HELP FOR THIS FIELD
is displayed.

In vuform, the text of the help message is entered on Page 2 of the Variable Field Parameters pop-up. (See Figure 8.) The HELP keyword is not used.

Specifications for ERR Statements

This type of extended descriptor statement lets you specify an error message to be printed when a field fails validation. Error message specifications have the following syntax:


ERR=errmsg
where errmsg is a quoted string. At runtime a %s within the string is replaced by the data entered in the field by the user. If the validation for the field fails then errmsg is displayed on the status line of the user\'s terminal. If no error message is given for a field, the default message FIELD IN ERROR is displayed when the validation fails. For example if the error message specification is:

ERR="%s is invalid"
and if the invalid data is 33 then the error message displayed is:

33 is invalid

In vuform, the text of the error message is entered on Page 2 of the Variable Field Parameters pop-up. (See Figure 8.) The ERR keyword is not used.

Specifications for DFLT Statement

DFLT is used to assign a default value to a field. If a default value is specified for a field, each time a new blank form is requested by a user, the field is displayed with its default value. More than a single default value can be specified. If more than one value is specified, the first value in the set is displayed; other values in the set are displayed by using the display-default key (CTRL-w in mio).

In vuform, the type of default is entered in the field labelled Default type: on Page 2 of the Variable Field Parameters pop-up. (See Figure 8.) The argument is specified on the lines that follow. The DFLT keyword is not used.

DFLT Statement Syntax

Default value specifications have the following syntax:


I= type [ : argument ] [ argument ] [ argument ] "..."
type can be one of the following three values:
LIT
The initial value for the field is given in argument.

STRING
Similar to LIT, but with more capability. If STRING is specified with no arguments, the default value for the field is the current date.

FUNC
The function named by argument is called to provide the default value for the field.

DFLT=LIT Specifications

The LIT type of default value specifies a literal string as the default value of a field. Double quotes are required if there are embedded white-space characters in the string. Double quotes and backslashes may appear within a quoted string if preceded by a backslash (\\).

To illustrate a LIT type of DFLT statement: DFLT=LIT:3 causes 3 to appear in the associated field whenever the form is displayed.

DFLT=STRING Specifications

The STRING type of default value lets you specify a character string to be the default value for a protected or unprotected field. It differs from DFLT=LIT in that the argument string can contain field descriptors that are expanded by the operating system when the field is displayed.

argument is a string of ASCII characters that can contain field descriptors. A field descriptor is one or more characters preceded by either a % or a $. Descriptors preceded by a % are shown below in Figure 10. A descriptor preceded by a $ is assumed to be an environment variable whose value is to be displayed on output. If it has more than one character (for example, ${LOGNAME}) it must be enclosed in braces. If there are white-space characters in the argument string, the entire string must be enclosed in double quotes. If there are double quotes or backslashes in the argument string, they must be preceded by a backslash (\\). If argument is omitted, the default value for the field is the current date, displayed as mm/dd/yy.

Fig. 9: Field Descriptors for STRING Specifications


m	 month of year -01 to 12
d	 day of month - 01-31
y	 last two digits of year - 00-99
D	 date as mm/dd/yy
H	 hour - 00 to 23
M	 minute - 00 to 59
S	 second - 00 to 59
T	 time as HH:MM:SS
j	 day of year 1-366
a	 abbreviated weekday - Sun to Sat
h	 abbreviated month- Jan to DEC
r	 time in AM/PM notation
P	 number of pages on form
p	 current page number

DFLT=STRING Examples

The following are example of DFLT=STRING specifications, and the output they might produce:


DFLT=STRING: %r
produces a value of

04:44:33 PM
as the default for the associated field, at around a quarter to five in the afternoon.

DFLT=STRING: "Page %p of %P"
produces a default value like:

Page 1 of 2

DFLT=STRING: "This is my path: ${PATH}"
produces a default value like:

This is my path: :/usr/bin:/bin:/usr/lbin

DFLT=FUNC Specifications

The FUNC type of default value specification indicates that a C function of your creation is called (by mio) to provide a default value for the associated field. In this type of specification, argument is the name of the function to be called, and may include a single usrarg string (eleven characters maximum) to be passed to that function. The syntax is


DFLT=FUNC: funcname(usrarg)
For example,

DFLT=FUNC: credlim("123-45-6789")
might call your function credlim to provide the value for a credit limit field. The usrarg, 123-45-6789, is presumably an identifying number needed by credlim.

Specifying Multiple Default Values

More than one value may be specified with a single DFLT extended descriptor statement. The first value listed is the one that the field is set to when the form is displayed. The user can cycle through the other values with the display-default function key (CTRL-w in mio). An example of a DFLT specification with multiple values appears below.


DFLT=STRING: "TOM" "DICK" "HARRY"

Specifications for VAL Statements

Extended descriptor statements of the VAL type contain validation option specifications. Validation options describe how mio is to determine valid input for an unprotected field. If the user tries to enter input that does not pass the specified validation test, it is rejected with an error message.

In vuform, the type of validation is entered in the field labelled Validation type: on Page 3 of the Variable Field Parameters pop-up. (See Figure 9.) The argument is specified on the lines that follow. The VAL keyword is not used.

VAL Statement Syntax

Validation option specifications have the following syntax:


VAL=type[:argument]
type is one of the nine values shown below. The format for argument varies according to type. Four of the nine types do not require an argument.
ALPHA
only input with alphabetic characters is acceptable. No argument is used with this type of validation option.

ALNUM
only input with alphanumeric characters is acceptable. No argument is used with this type of validation option.

LIT
only input that matches one of the literal strings in argument is valid.

RE
only input matching the regular expression in argument is valid.

INTEGER
any integer is valid. No argument is used with this type of validation option.

IR
only integers in a range specified in argument are valid.

NUMERIC
any numeric value is valid. No argument is used with this type of validation option.

NR
only numbers in a range specified in argument are valid.

FUNC
a user-written function is called to validate the data entered in the associated field.

The five validation option types that require an argument are explained in the paragraphs below.

VAL=LIT Specifications

In this type of validation option, argument is a list of strings separated by white-space characters. Strings containing embedded white space characters must be surrounded by double quotes. Double quotes and backslashes may appear within quoted strings if preceded by a backslash (\\). Data matching any of the strings is considered valid. For example:


VAL=LIT: "THANK YOU" GRACIAS
will cause either THANK YOU or GRACIAS to be accepted as valid input to the field.

VAL=RE Specifications

The regular expression in argument can be any regular expression acceptable to recomp(3c). For example:


VAL=RE: (a*b*) | (cd)
is a valid regular expression. The alternation operator ( | ) is supported.

Note: In a series of regular expressions, if one is a superset of others, the superset must be stated first.

VAL=IR Specifications

This type of validation option constrains the field to have an integer value that falls within any range specified by argument. argument may be a white-space separated list of the following format:

n
an integer.

(n-m)
any integer between n and m, but not including either n or m.

[n-m)
any integer between n and m, including n, but not including m.

(n-m]
any integer between n and m, including m, but not including n.

[n-m]
any integer between n and m, including both n and m.

n-m
equivalent to [n-m].

For example:


VAL=IR: 1-10 12-15
indicates that any integer between 1 and 15, excluding 11, is valid.

VAL=NR Specifications

The argument of this type of validation option is a list of numeric ranges. The value entered into the field is considered valid if it is numeric and falls within any of the specified ranges. argument can be a white-space separated list of the following format:

n
a decimal number.

(n-m)
any number between n and m, but not including either n or m.

[n-m)
any number between n and m, including n, but not including m.

(n-m]
any number between n and m, including m, but not including n.

[n-m]
any number between n and m, including both n and m.

n-m
equivalent to [n-m].

Following are examples of valid numeric ranges:

VAL=NR: 9.01

VAL=NR: (1-2.01]

VAL=NR: -10--1

VAL=NR: 3-6 9-12

The last example matches numbers that are either in the 3-6 range or in the 9-12 range. The numeric range list is taken to be all characters on the line following the NR:.

VAL=FUNC Specifications

argument is a the name of a function of your creation, followed by a set of parentheses that enclose an argument (usrarg) to be passed to that function. The function is called by mio to validate the data entered by a user. No blanks should appear from the first character of the function name through the closing parenthesis, unless they are in a usrarg enclosed in quotes.

A sample extended descriptor statement with the FUNC validation option might be:


VAL=FUNC: ZIP_CODE("NINE DIGIT")
It indicates that the function ZIP_CODE should be called to validate the current field. The argument, "NINE DIGIT" is to be passed to it as usrarg. An argument for the FUNC type of validation option can specify a list of functions to be called to validate the field. An example might be:

VAL=FUNC: ZIP_CODE("NINE DIGIT") ADDRESS( )
With this validation option specification, ZIP_CODE() is first called to validate the field. If ZIP_CODE() returns a -1 (invalid field) then ADDRESS() is called to validate the field. If ADDRESS() returned a 1 (valid field) then the field would be considered valid. In other words, the input need only be accepted by one of the specified validation functions to be considered valid. If both validations fail, the error message returned by ADDRESS() is displayed.

Specifications for MENU Statements

The MENU statement identifies the associated field as one where the selection from a menu list is expected. The extended descriptor statement described the actions to be taken depending on the value entered by the user.

In vuform, a MENU statement is entered on Page 3 of the Variable Field Parameters pop-up. (See Figure 9.) In the field labelled Menu type: the keyword MENU is entered. The argument is entered on the lines that follow.

MENU Statement Format

The MENU statement has the following format:


MENU value = option : suboption [, value = option : suboption, ... ]
where:
value
is a valid value the user can enter in the menu field. A value of * matches any value the user might enter.

option
controls the operation that goes with that choice. Valid option values are: A - action C - shell command F - form S - service

suboption
is the information needed to carry out the operation specified by the option.

You can specify as many value=option:suboption entries as the menu requires. Entries are separated by commas. If more than one line is needed, use the backslash to escape the newline character.

Other general rules about the format of a MENU statement are:

  • A space, a tab or an equal sign determines the end of a value string. If a space, tab or equal sign is intended as part of the value, it must be preceded by a backslash for an escape.

  • Except as noted in Rule 1, spaces and tabs are ignored.

  • A single asterisk (*) as a value indicates a match for any input not already matched by a previous value. The asterisk is useful for specifying a default action. If an asterisk is to be treated literally, it must be escaped with a backslash.

  • The end of a suboption is determined by finding a comma or an unescaped newline. If a comma is intended as part of the suboption, it must be preceded by a backslash for an escape.

  • option characters (A, C, F, or S) can be entered in either upper or lower case.

    These same rules apply to the FORMEXIT statement. In vuform, the statements are entered in the same way except that the keyword MENU or FORMEXIT is entered in the field labelled Menu type:, and the remainder of the specification is entered on the lines following the label Argument:.

    MENU Statement: Suboption Specifications for Option A

    Option A indicates an action is to be taken that affects the terminal screen. Valid suboption values are:

    A
    Abort the current form. The next higher level form is displayed. If the current form is the initial form, A causes an exit from mio.

    C
    Clear the current form and buffer. Re-display default values. C clears the entire fielded buffer, including fields not included on the current form.

    E
    Exit from mio. If mio was invoked with the -n option (no exit permitted), E causes an exit to the highest level form.

    N
    Display the Next page of the form. If the current page is the last page of the form, N causes the first page to be displayed. The user is not permitted to leave the page if any fields on the page fail to pass any specified validation.

    P
    Display the Previous page of the form. If the current page is the first page of the form, P causes the last page to be displayed. The user is not permitted to leave the page if any fields on the page fail to pass any specified validation.

    PF
    Print the Form; send it to a server offering the FRMPRT service.

    R
    Repaint the current form.

    S
    Escape to the Shell. Only valid if mio was invoked with the -e option. S prints the ! and waits for a shell command to be entered.

    T
    Go directly to the Top level form.

    MENU Statement: Suboption Specifications for Option C

    Option C causes the command specified in suboption to be passed to the shell. suboption can be a program name with or without arguments, or several programs connected by pipes. All output is printed on the terminal unless redirected in suboption. When the command completes, or the user hits break, the prompt

    
    [Hit return to continue]
    
    is displayed and the form from which the command was executed is displayed. The F option has three variations; all three take formname as a value for suboption.
    F
    Changes forms at the same level of the hierarchy. Fields currently filled in are displayed on the new form. F is not valid on the initial mask; if entered from the initial mask, F is treated like FC.

    FC
    Displays the form specified in suboption as a child form in the menu hierarchy. When aborting from the newly displayed form, either by entering CTRL-d or requesting a menu option of type A action A, the original parent form is displayed. Thus, this action can be used to provide a hierarchical menu system. Fields that are currently filled in are displayed on the new form.

    FT
    Causes a jump to the formname specified in suboption. Treated like a jump to the top level, followed by an FC to the named form. Aborting the new screen leaves the user at the top level. FT allows jumping from any point in the menu hierarchy to an unrelated form, and does not keep the history or hierarchy information. Thus, the user does not have to back up through the hierarchy. Fields that are currently filled in are displayed on the new form.

    MENU Statement: Suboption Specifications for Option S

    The S option causes the current form to be sent to the service named in suboption. All fields in the current form are validated. If some validations fail, fields in error are highlighted and the cursor is positioned at the first one. If all fields are valid but lastval fails, the cursor is positioned at the field specified by lastval. The application service may request that the same form be redisplayed, or that another form replace the current one.

    The S option has three variations. All three take servicename as a suboption.

    S
    Sends the currently filled-in fields on the form to the service specified in suboption at the current level in the hierarchy. S is not valid from the initial mask; treated like an SC.

    SC
    Creates a new child level in the hierarchy and sends the fields on the form from the child level. The form displayed after handling the service is displayed at the child level. When aborting from this new level, mio again displays the form from which the original SC option was specified. Thus, the service is treated as a child of the current level in the hierarchy.

    ST
    Causes a jump to the servicename specified in suboption. It is treated like a jump to the top level followed by an SC on the named service. Fields that are currently filled in are sent to the service. Aborting the screen displayed after handling the service leaves the user at the top level. This allows jumping from any point in the menu hierarchy to an unrelated service and resulting form. It does not keep the history or hierarchy information. Thus, the user does not have to back up through the hierarchy.

    Notes on Menu Options

    For C, F and S options, any appearance of the at sign (@) in suboption is expanded to the value of the menu field. For example, if a MENU line has:

    
    *=C:mycmd@
    
    the shell command mycmd is executed for all values entered in the field and the entered value is passed to the shell as an argument to mycmd. General form switching can be established with a MENU statement such as:
    
    *=F:@
    
    which is interpreted as "switch to the form specified by the user."

    All options can be mixed on a single MENU statement. In addition, other unprotected fields can appear on the form so that values can be passed to a service or a subsequent form.

    As the user leaves a menu form, the value of the menu field is compared against the list specified in the MENU extended descriptor statement. The first time a match is found, the associated option is acted on. If no match is found, the cursor is positioned at the beginning of the menu field and an error message is displayed. A definition of * causes the associated operation to be done regardless of what is entered in the field.

    An example of the UFORM statements needed to define a menu are shown in the following Figure.

    Fig. 10: UFORM Statements for a Menu List

    
    +1	2	0	1	-	L	"1. Print Date/Time: "
    +1	2	0	1	-	L	"2. Go to myform Form: "
    +1	2	0	1	-	L	"3. Perform myservice: "
    +1	2	0	1	-	L	"4. Pop Up a Menu Level: "
    +1	2	0	1	-	L	"5. Exit: "
    +1	2	0	1	-	L	"MENU SELECTION: "
    -	1+	1	1	6	UIH	 MENUFLD
     MENU 1=C:date, 2=F:myform, 3=SC:myservice, 4=A:A, 5=A:E, \
     *=S:default_svc
    

    In the example, the first five lines define literal fields that list the menu choices. The choices in this example are worded to suggest the action that is specified by the MENU statement option, but this is by no means a requirement. The sixth line is a literal that prompts the user to enter a menu selection. The seventh line specifies the field in which the user is expected to enter a selection. This is an unprotected field, and in the example it is the home and initial field as well. The field name is MENUFLD. The first seven lines are all basic descriptor statements. The eighth line is a MENU extended descriptor statement that contains the MENU specifications.

    Specifications for FORMEXIT Statements

    FORMEXIT extended descriptor statements are used to implement ring menu systems, but can also be used with any other field from which the user can leave the form.

    In vuform, a FORMEXIT statement is entered on Page 3 of the Variable Field Parameters pop-up. (See Figure 9.) In the field labelled Menu type: the keyword FORMEXIT is entered. The remainder of the specification is entered on the lines that follow the label Argument:.

    FORMEXIT statements specify actions that depend on the mio leave key used to exit the form.

    FORMEXIT Statement Format

    The FORMEXIT statement has the following format:

    
    FORMEXIT value = option : suboption [, value = option : suboption, ... ]
    
    where:
    value
    can be F0 through F9, (ESC-0 through ESC-9) or F11 (CTRL-v) and indicates the leave key entered. A value of * matches any leave key.

    option
    controls the operation to be done. Valid options are the same as those described above for the MENU extended descriptor statement.

    suboption
    is information needed to perform the operation. If the at sign (@) is included in suboption, it is xpanded to the value entered in the field (not the leave key used to exit the form via this field).

    A FORMEXIT statement defines a list of all possible leave keys the user can enter when leaving the form from the associated field. They behave much the same as MENU fields, except that the value is a leave key rather than a menu selection.

    If no match is found in the FORMEXIT statement for what the user enters, mio treats it as a request for the service named in the #SERVICE statement.

    Leaving a form from a field that does not have a FORMEXIT statement is treated according to the mio default for the leave key entered.

    UFORM Comment Lines

    Blank lines, or lines beginning with an asterisk are considered comments. They are good for internal documentation but have no bearing on the way the form works.

    Users of vuform can insert comments into a form by disassembling the .M file produced by vuform. mcdis is used to disassemble the form. mcdis sends its output to stdout. If the output is redirected, the resulting file can be edited with any UNIX editor.