Request composition rules

From m204wiki
Revision as of 21:02, 30 April 2014 by JAL (talk | contribs)
Jump to navigation Jump to search

Statement labels

This page summarizes the rules for composing compilable User Language requests. The rules for specifying statement labels in User Language statements are summarized below.

  • A statement label must begin with a letter (A-Z, a-z) which can be followed by one or more occurrences of a letter (A-Z, a-z), digit (0-9), period (.), or underscore (_). The label can be a maximum of 254 characters in length.
  • A statement label should not be a User Language keyword. Model 204 interprets a statement label which is a keyword as the keyword itself, not as a statement label, if that keyword makes syntactic sense where the statement label is referenced.
  • The label must be the first word on a line, must end with a colon, and must be followed by a space.
  • A label can start in any column up to but not including column INCCC.
  • Within a request, statement labels should be unique. If not, Model 204 displays the message:

M204.0223: STATEMENT LABEL MULTIPLY DEFINED

This is a warning message only; the request can still be run.

Statements that must be labeled

Any statement can be labeled, but some statements must be labeled.

In particular, a statement must be labeled if:

  • It immediately follows a STORE RECORD or a FIND statement and an END STORE or END FIND statement is not being used to end the statement. In this case, the statement label indicates the end of the preceding statement.
  • It is referred to by later statements. In most requests, COUNT, FIND, FOR EACH OCCURRENCE, FOR EACH VALUE, NOTE, and SUBROUTINE, are referred to later and should therefore be labeled.

Unlabeled statements

The retrieval conditions of a FIND statement, the conditions of an IF statement and ELSEIF clause, and the fields of a STORE RECORD statement must not be labeled, even if they begin new lines.

If a statement is not labeled, it is assigned a default level of nesting. The default level is the same as the level of the previous statement. If there is no previous statement, the default is the first level. If the previous statement starts a loop or a THEN clause, or is a SUBROUTINE statement, the default level is one greater than the level of the previous statement.

Label references

Labels allow statements to refer to other User Language statements. The label reference must be coded exactly as the label, including upper- and lowercase lettering. However, the label reference must omit the colon.

Statement block ends

Beginning a block

The FIND (except for FIND ALL VALUES), FOR, IF, ON, REPEAT, STORE, and SUBROUTINE statements begin blocks in User Language and therefore must be explicitly ended.

Ending a block statement

You can end a block statement in the following ways:

  • The appropriate block end statement (END {statement type} [label]) can be used to end any block.
  • A label can be used to end blocks of multiline conditions (blocks begun by the FIND and STORE statements). A label cannot be used to end blocks of nested statements (blocks begun by the FOR, IF, ON, REPEAT, or SUBROUTINE statements).
  • The END BLOCK statement can be used to end any block except for blocks of multiline conditions (blocks begun by the FIND and STORE statements).
  • END, END MORE, END NORUN, and END USE can be used to end any block, because these forms the END statement terminate the request, thereby ending all statements within the request.

Statement format

The rules for constructing User Language statements are summarized below:

Begin statements on a new line

Each statement must begin on a new line unless it follows a THEN, ELSE, or ELSEIF clause.

Statement continuation

Use of hyphens

You can continue statements onto another line by using a hyphen after the last character on the line to be continued, or by using any nonblank character in the column specified by the INCCC parameter (discussed in the Rocket Model 204 Terminal User's Guide).

Use of parentheses

You can continue statements using parentheses, although Rocket Software recommends that you use parentheses only to change the order of precedence in retrieval statements or with FR WHERE statements. See:

Avoid blank lines between continued lines

You should not use blank lines between continued lines. The following example illustrates two problems that occur if you use blank lines between continued lines (for example, if you wanted to double space your code).

B %A = 'AAA- BBB' PRINT %A IF $SETG('A','B') OR - $SETG('B','C') THEN PRINT 'ERROR' END

First, when you print %A, you will get "AAA;BBB"; Model 204 inserts a semicolon to represent the blank line. The second problem is that the second $SETG statement will be rejected with an "INVALID STATEMENT" message. To correct both problems, simply add a hyphen to each blank line following the continued line.

The following example illustrates proper coding:

B %A = 'AAA- - BBB' PRINT %A IF $SETG('A','B') OR - - $SETG('B','C') THEN PRINT 'ERROR' END

Compatibility issues

In Model 204 releases prior to Version 2.1, the compiler accepted certain types of invalid expressions, but returned unpredictable results. The following is an example of an invalid expression:

IF %X = %Y * %Z THEN

Note that the first line (IF %X . . .) needs a continuation hyphen.

Invalid expressions are recognized as syntax errors and produce the following message:

M204.0298: INVALID OPTION: cccc

where cccc is the program text that was in error.

Also, the following example code lacks continuation hyphen following an "AND" or an "OR" within a conditional IF statement.

IF FIELD1 = A AND FIELD2 = B AND FIELD3 = C THEN DO X

The above example results in a compiler error. The proper syntax for the above statement is:

IF FIELD1 = A AND - FIELD2 = B AND - FIELD3 = C THEN DO X

Line length

An input line, together with its continuation lines, constitute one logical line. Lines continued with a nonblank character in column INCCC cannot exceed LIBUFF characters. Lines continued with a hyphen before the end of a terminal line have no length limit.

Blanks between words

At least one blank must separate words in a statement. Extra blanks are optional.

Where lines can begin

Typing can begin anywhere on the terminal line.

Logical lines

Most statements are entered as one logical line.

The following statements might require the use of multiple logical lines:

  • FIND

    The first retrieval condition for a FIND statement can appear on the same line as the FIND clause. Other retrieval conditions which start a new line are preceded implicitly by a logical AND.

  • IF and ELSEIF

    The conditional expression in an IF statement or ELSEIF clause can begin on the same line as IF or ELSEIF on the next line. Each new line in the expression is preceded implicitly by a logical AND. THEN can appear on the same line as the expression or on the next line.

  • STORE RECORD

    Each fieldname = value pair of a record to be stored must be entered on a new line.

The number of input lines used by FIND, IF, ELSEIF or STORE RECORD is unlimited.

Use of semicolon to perform a carriage return

Description

The semicolon (;) normally performs a carriage return within a request. For example:

BEGIN;PRINT.INFO: FIND AND PRINT COUNT;END

Do not use a semicolon after the INCLUDE statement

A semicolon should not be used after the INCLUDE statement because INCLUDE takes the next physical line from the specified procedure. For example, the procedure GREET consists of a single line:

PRINT 'HELLO'

Therefore, the following request:

BEGIN INCLUDE GREET END

causes Model 204 to read the PRINT statement from procedure GREET immediately after the INCLUDE. If the same request is entered with semicolons:

BEGIN;INCLUDE GREET;END

Model 204 reads the INCLUDE statement and does what is necessary to read the next physical line from the GREET procedure. Model 204 then looks for the next logical line, which comes from the current physical line, and sees the END statement. This terminates a request which does nothing. The command handler reads the next physical line from the GREET procedure, getting PRINT 'HELLO'. PRINT is flagged as an invalid command.

The LINEND parameter

The LINEND parameter sets the logical line-end character to something other than a semicolon. If the LINEND parameter is set to a non-printable character, you cannot stack multiple logical lines on a single physical line. LINEND should never be set to X'00'. The Rocket Model 204 Editing Guide discusses the effects of the LINEND parameter on the editing and including of a procedure.

Field names and values

Rules for field names

The rules for specifying field names in the User Language statements are summarized below.

  1. Any word or character, including space, can be used as part of a field name except the correction characters @ and #. The choice of symbols to signify correction characters is parameter controlled and can be changed. If you chooses different symbols, the restriction regarding the use of @ and # in field names then applies to the new symbols instead. (See the List of Model 204 parameters.)
  2. If any reserved word or character is embedded in a field name, the word or character must be part of a quoted string (see the discussion on field attributes in Field attributes).
  3. Field names that contain a colon followed by a space (for example, COLOR: CAR) cannot be distinguished from labels when used as the first word on a line. Any field name containing this combination either should be renamed or must be enclosed in single quotes at the beginning of a line.
  4. When more than one consecutive space appears in a field name, the extra spaces are ignored.
  5. A field name can be subscripted by including a parenthesized expression after the name. This facilitates references to multiply occurring fields (see Operations on multiply occurring fields).
  6. To refer to a fieldname indirectly, specify it with the format %%name (see the discussion in Field name variables). Field name variables also can be subscripted.

Examples

Some examples of legal field names are:

AGENT ANNUAL_INTEREST 'TOTAL USE'

Some examples of illegal field names are:

Unacceptable How to correct...
YEAR TO DATE Year-to-date
USE COUNT 'Use count'
STRING@ Use another character, not @, or change the correction character
AND "AND"

Rules for field values

The rules governing the formation of field values are the same as rules 1, 2, and 4 for field names (see the preceding discussion).

In addition, values cannot contain more than 255 characters.

Use of quotes with field values

Although single quotes are required to enclose a text field value when the value contains reserved words or characters or when used in expressions, it is good practice to enclose the text in quotes, even if it contains no reserved words or characters. To store the field:

PARENTS = MARY AND JOHN SMITH

the value portion of the pair must be quoted because AND is a reserved word. Used with a STORE RECORD statement, the field should look like this:

PARENTS = 'MARY AND JOHN SMITH'

For more information about the use of quotation marks, refer to Quotation marks.

Quotation marks

You can direct Model 204 to display arbitrary text information by means of the single quote symbol.

Uses for quotation marks

User Language statement employ quotation marks as follows:

  • Following a PRINT statement, any characters enclosed in single quotes are printed literally when the statement is executed.
  • Within a request, quotation marks can be used to provide titles for output or display messages to the end user.
  • Quoted material can be included in a list with other things to be printed (see PRINT statement).
  • Quoted material can be used in expressions.
  • Quoted material can be saved by the NOTE statement for later use in a request.
  • Single quotes also are used when a reserved word or symbol is to be interpreted in other than its standard system sense. Thus when reserved words or symbols are used in the formation of field names or values, the entire string must be enclosed in quotation marks.

Rules for using quotation marks

Model 204 handles quotation marks as follows:

  1. A pair of single quotation marks, for example 'TEXT', delineates a quoted string.
  2. Quoted strings are stored and utilized with quote marks dropped. Thus PARENTS = 'MARY AND JOHN SMITH' is stored as PARENTS = MARY AND JOHN SMITH, and the statement PRINT PARENTS results in the output MARY AND JOHN SMITH.
  3. A pair of consecutive quotation marks inside of a quoted string is replaced by a single quotation mark when the string is stored or printed. For example, PRINT 'FATHER"S NAME' results in the output FATHER'S NAME and PRINT "AND" yields 'AND'.
  4. A pair of consecutive quotation marks that is not included in a quoted string converts to a character string of zero length, called a null string.
  5. Only pairs of quotation marks are used.

Example

The following examples illustrate different ways of referring to a TITLE field with the value, WHY JOHNNY CAN'T READ:

TITLE = 'WHY JOHNNY CAN"T READ' TITLE = WHY JOHNNY 'CAN"T' READ TITLE = WHY JOHNNY CANT""T READ

Quotation marks designating a null string

In a FIND statement, the pair:

BIRTHPLACE =

is the same as:

BIRTHPLACE =

The retrieved records will contain the field BIRTHPLACE and its value will be null. If the field is printed, it will result in a blank line of output.

Quoting a reserved word

To store the field, A OR B = VALUE, one of the following must be used because OR and VALUE are reserved words:

A 'OR B' = 'VALUE' A 'OR' B = 'VALUE'

A field name beginning with a quotation mark looks like quoted text to a PRINT statement. Thus the forms 'A OR B' and 'A OR' B should not be used.

After Model 204 encounters a closing quote, it does not recognize a reserved word again until a delimiter such as a space or an operator is encountered. In the following string:

'TESTDATA'AND

Model 204 regards the AND not as a reserved word but as part of the string (TESTDATAAND). The quotes do not actually have to surround the string.