Creating a prompt rules table

A prompt rules table file (.tbl) is created from a prompt rules source file (.ptx) using mkprompt. mkprompt expects a text source file that contains prompt table commands.

A prompt rules table is composed of a list of commands, keywords, and labels that:

Perform operations on an input string
Output message numbers to a list
Affect flow of control

The following table lists the commands:

Command	Description
CONVERT	Converts a string to a message number or label. Appends a computed message number to an output list or jumps to a computed label.
FIND	Parses an input string. Performs conditional jumps.
OUTPUT	Appends message numbers to an output list. Can also be used to terminate processing.
TEST	Performs conditional jumps based upon the result of a string or integer comparison.

In addition to the commands, the following elements are used:

Element	Description
;	Identifies the comment field. All remaining text on the line is ignored.
label=num	Assigns a value to a label. This element is primarily used to assign a name to each message in the prompt message file.
label:	Marks the command as a target for a jump from a CONVERT, TEST, or FIND command.

The syntax of the commands is:

command [option1|option2] value

where:

command	Name of the command.
[option1\|option2]	Optional keywords. The available choices are within the brackets. Select only one. That is, specify either option1 or option2, but not both. Both choices can be omitted, and the default option is used.
value	A number, string, or label. This value is dependent on the command syntax.

CONVERT

The CONVERT command converts a substring to a value used as either a message number to append to the output list of messages or as a label to which to jump.

Usage

CONVERT [CASE|NOCASE] subval [MESSAGE|CALL|GOTO] baseval [EXIT|CONT]

CASE	Do a case sensitive character subtract.
NOCASE	Do a case insensitive character subtract. This is the default.
subval	Subtract the specified integer or character from the string.
MESSAGE	Generate and append a message number to the output list.
CALL	Generate a label to call as a subroutine.
GOTO	Generate a label to which to jump. This is the default.
baseval	Use the specified base label or message number.
EXIT	Return after MESSAGE.
CONT	Continue when done (MESSAGE). This is the default.

Note: EXIT and CONT apply only if MESSAGE is used.

Description

The message number or label is constructed by first subtracting subval from the input string and then adding baseval to the result. If the input string is to be treated as an integer, as many as five digits are used. If the input string is to be treated as a character string, the first character is used, as is the first character of subval. By default, the input string and subval are treated as integers. If the keyword CASE or NOCASE is used, they are treated as characters.

If a message number is generated, it is appended to the end of the output list. If the EXIT keyword is specified, processing returns to the line following the command that called EXIT. If the EXIT keyword is not specified, processing resumes at the next line in the prompt rules table.

If a GOTO label is generated, processing continues with the command at the computed label.

If a CALL label is generated, processing continues with the command at the computed label. When control is returned, processing resumes at the next line in the prompt rules table.

Examples

TEN = 30                  ;message number to say TEN.
CONVERT 1 MESSAGE TEN     ;subtract 1 from passed digit
                          ;and add to label value TEN,
                          ;output resulting message
                          ;number then goto next cmd.
                          ;Note that case 0 is ruled out
                          ;beforehand.
LETTERA = 60              ;message number for letters
                          ;'a' - 'z'
CONVERT NOCASE "A" MESSAGE LETTERA
                          ;convert letters to appropriate
                          ;message number
CONVERT 0 GOTO PLACE
                          ;say first, second etc.

FIND

The FIND command searches for a character in the input string and uses its position as a beginning or end pointer of a substring to be passed to the next command. The command performs a conditional jump or error return.

Usage

FORWARD	Search forward from the beginning of the input string. This is the default.
BACKWARD	Search backward from the end of the input string.
CASE	Do a case-sensitive search.
NOCASE	Do a case-insensitive search. This is the default.
occur	Occurrence number to find, such as find the second occurrence of a colon (:). An absolute position can also be specified if "letter" is not specified.
"letter"	The letter to find. If not specified, the search is absolute positioning based on occur.
INCLUDE	Include the found character when passing the string. This is the default.
EXCLUDE	Exclude the found character when passing the string.
FULL	Pass the full string. This is the default.
LEFT	Pass count characters to the left of the found character.
RIGHT	Pass count characters to the right of the found character.
count	Pass a number of characters to the specified command. The maximum is 127.
FOUND	Perform a CALL or GOTO if the string is found. This is the default.
NOTFOUND	Perform a CALL or GOTO if the string is not found.
CALL	Call a FOUND or NOTFOUND label as a subroutine.
GOTO	Go to a FOUND or NOTFOUND label. This is the default.
ERROR	Return VCEERR_PROMPT_BUILD_FAIL immediately to the application. This keyword enables the rules to notify the application that an invalid input string was specified.
label	Command to CALL or GOTO if found or not found. The computed substring is passed to the command. If label is omitted, the substring is passed to the next command.
ELSE	Allow optional NO-OP keyword before EXIT to enhance readability.
EXIT	Return if FOUND or NOTFOUND condition is not met.

Description

The character search can be performed forward from the beginning of the input string, or backward from the end of the input string, as specified by the keywords FORWARD or BACKWARD. The nth occurrence of the character, as specified by occur, is sought. If no character is specified by letter, then occur is used as an offset from the beginning or end of the string. Once this position is established, the substring to the right or to the left of this position can be passed to the next command. By default, the entire string is passed.

The substring to be passed is specified by the RIGHT, LEFT, or FULL keyword. For RIGHT or LEFT, the number of characters in the substring is specified by count. Use a large count to pass all characters to the right or left. The found letter is passed as part of the substring unless the keyword EXCLUDE is used.

If a GOTO jump is performed, the substring is passed to the command at the specified label, where processing continues.

If a CALL jump is performed, the substring is passed to the command at the specified label, where processing continues. When control is returned, the input string originally presented to the FIND command is restored and passed to the command on the next line in the prompt rules table.

If the search condition is not met and EXIT is not specified, the unmodified input string is passed to the next command.

The FIND command can be used as an unconditional GOTO. (Refer to the examples.)

Examples

FIND 2 ":" RIGHT 2 EXCLUDE FOUND SAYSECONDS

If a second colon is found, pass 2 characters to the right to a routine that says the seconds count.

FIND 1 "$" FULL FOUND SAYDOLLAR

Find the first occurrence of a $ (dollar sign). If found, pass the full string to the dollar routine, otherwise fall through to the next record.

FIND GOTO SAYMORE

Unconditional GOTO.

FIND FORWARD 1 "$" RIGHT EXCLUDE 127

Extract the substring to the right of a $ (dollar sign) but continue to the next command.

OUTPUT

The OUTPUT command appends the specified message numbers to the output list. From zero to three messages can be specified in the OUTPUT command. If more than three messages are needed, use additional OUTPUT commands.

Usage

OUTPUT [msg [,msg [,msg]]] [EXIT|CONT|QUIT]

msg	A message number. As many as three messages can be specified.
EXIT	Return to the previous command when done.
CONT	Continue to the next line. This is the default.
QUIT	Stop processing commands.

Description

If this keyword is specified...	Then processing....
CONT	Resumes at the next line in the prompt rules table.
EXIT	Returns to the line following the command that called this one.
QUIT	Terminates and SUCCESS is returned to the application.

Examples

OUTPUT OCLOCK,LETTERA,LETTERM

Output the following messages: o'clock, a, m.

OUTPUT MSGSUNDAY

Output the following message: Sunday.

OUTPUT DEGREES,FAHR EXIT

Output the following messages: degrees, fahrenheit. Then return.

OUTPUT HELLO QUIT

Output the following message: hello. Then stop processing commands.

OUTPUT QUIT

Stop processing commands.

TEST

The TEST command compares the input string with a specified value and jumps if the test evaluation is true.

Usage

GREATER	True if substring is greater than cmpval.
LESS	True if substring is less than cmpval.
EQUAL	True if substring is equal to cmpval.
NOT	True if substring is not equal to cmpval. This is the default.
CASE	Do a case-sensitive compare.
NOCASE	Do a case-insensitive compare. This is the default.
cmpval	Value with which to compare substring.
CALL	Call the command at label, if true.
GOTO	Go to the command at label, if true. This is the default.
ERROR	Return VCEERR_PROMPT_BUILD_FAIL immediately.
label	Execute specified command if the evaluation is true.
ELSE	Allow specified optional NO-OP keyword before EXIT to enhance readability.
EXIT	Return if a label was specified and the evaluation is false, or no label was specified and the evaluation is true.
CONT	Continue if the evaluation is false. This is the default.

Description

If the keyword CASE or NOCASE is specified, a character comparison is performed. Otherwise an integer comparison of up to five digits is performed.

If the test evaluation is true, processing continues with the command at the specified label. If a CALL jump is specified, processing resumes at the next line in the prompt rules table once control is returned.

If the test evaluation is false or no label is specified, processing continues directly at the next line unless the EXIT keyword is used. In this case, processing resumes at the line following the command that called this one.

Examples

TEST GREATER 99 CALL DO100 ;if >100 process hundreds

If the input string contains a number greater than 100, call the subroutine that handles them.

TEST EQUAL NOCASE "SUN" GOTO SAYSUNDAY

If the input string starts with SUN, go to the routine to output the message for SUNDAY.

TEST NOT 0 EXIT

Return if the input string is not equal to 0 (zero).