# 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

FIND [FORWARD|BACKWARD] [CASE|NOCASE] [occur] ["letter"] [INCLUDE|EXCLUDE] [FULL|LEFT count|RIGHT count] [[FOUND|NOTFOUND] [CALL|GOTO|ERROR] [label] [[ELSE]EXIT]

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

TEST [GREATER|LESS|EQUAL|NOT] [CASE|NOCASE] cmpval [CALL|GOTO|ERROR] [label] [[ELSE] EXIT|CONT]

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).