&AOMREAD

&AOMREAD is used within an AOMPROC to request delivery of the next AOM message. If no message is immediately available, processing of the procedure is suspended and then resumes when the next message arrives.

Any messages and associated attributes routed to PROC, PROCONLY, or BOTH from the screening table are delivered to &AOMREAD.

Multiple &AOMREAD statements are present within an AOMPROC but we recommend that only one is used within a closed loop environment.

On completion of &AOMREAD, the system variable &ZVARCNT are set to the number of variables created, unless the SET operand is specified.

The profile of the message received by &AOMREAD is set in a suite of reserved system variables. The message profile provides a complete description of all the message attributes in addition to the message text. (The attributes reflect the processing attributes such as color, highlighting, source, and delivery information that the screening table sets.)

This verb has the following format:

&AOMREAD [ WAIT={ YES | NO | 0 | nn } ]
         [ MINOR={ YES | NO } ] 
       { [ VARS=prefix* [ RANGE=(start,end) ] ] |
         [ VARS={ name | var-name-list } ] |
         [ STRING { &name | string-name-list } ] |
         [ ARGS [ RANGE=(start,end) ] ] |
         [ SET ] }

Operands:

WAIT={ YES | NO | 0 | nn.nn }

Specifies what to do if no message is immediately available to satisfy the &AOMREAD.

WAIT=YES causes the procedure to be suspended indefinitely, pending receipt of a message.
WAIT=NO or WAIT=0 causes the procedure to continue if no message is pending. If no message was pending, the system variable &RETCODE is set to 4. The procedure is never suspended in this case.
WAIT=nn.nn causes the procedure to wait for up to nn.nn seconds for a message. If none have arrived in this time, &RETCODE is set to 4 and the procedure resumes execution. The range of nn.nn is 0.01 to 9999.99.

If a message satisfies &AOMREAD, &RETCODE is set to 0.

Default: YES

MINOR={ YES | NO }

Specifies whether &AOMREAD is to return minor lines of a multiline WTO message.

MINOR=YES presents the individual lines of a multiline WTO message in order, following the &AOMREAD of the major line. This setting is useful if you want to examine attributes of each line.
MINOR=NO causes the next &AOMREAD after reading a major line to skip all the minor lines, and read the next message.

Default: YES

Note: Regardless of this setting, the &AOMMINLN and &AOMMINLT built-in functions allow access to the text and line type of any minor line of the current message. The &AOMNMIN system variable indicates how many minor lines there are. The operand has no effect except in the case where the previous line read was a multiline WTO major line. Thus, you can use &AOMREAD MINOR=NO in a main processing loop, and enter an inner processing loop, to read &AOMNMIN minor lines.

VARS=

Tokenizes the message into the nominated variables before control is returned to the procedure. Each word of the message is tokenized into the nominated variables from left to right. If insufficient variables are provided, some data is lost. Excess variables are set to a null value. The format of the operands that can be coded with VARS= are as follows:

prefix*: Denotes that variables are generated automatically during the tokenization process, and that the variable names are prefix1, prefix2, and so on. The RANGE= operand is specified to indicate a starting and ending suffix number. prefix* cannot be used with other variable names.
name: Specifies the name of a variable, excluding the ampersand (&).
name(n): Is the same as name, but n denotes the length of the data that is placed in the variable.
*(n): Denotes a skip operation, where n represents the number of units to skip during the tokenization process. On VARS= statements, n denotes 'skip this number of words'. An asterisk (*) by itself is the same as *(1).

STRING

Specifies no tokenization. The entire text of the message is returned as a single string to the procedure in the nominated variables. The format of the operands associated with STRING are:

&name: Specifies the variables, including the leading &, into which to place the string text. Text is placed into each variable for the maximum length of a variable.

ARGS

Denotes that the message received is tokenized and placed word by word into automatically generated variables of the form &1 through &n, depending on how many are required to hold the message. The RANGE= operand is coded to designate a start number and optionally, an end number, which delimits the number of variables that are generated.

SET

Specifies that no tokenization of the incoming AOM message is performed, but that the &AOMREAD statement is to return only the AOMPROC system variables that relate to the message.

If SET is not coded, instructions must be coded on the &AOMREAD statement specifying the tokenization requirements for the message by using other &AOMREAD operands.

Examples: &AOMREAD

&AOMREAD VARS=(A,B,C,D,E,F,G,H,I,J) MINOR=NO

&AOMREAD VARS=A*

&AOMREAD ARGS RANGE=(2,60)

&AOMREAD STRING &DATA

&AOMREAD SET

Notes:

Following an &AOMREAD, you can use an &GOTO statement, using the ID of the message, to go to the routine that processes the message. (The ID is set in &AOMID by a screening table GLOBAL, MSGGROUP, or SET statement ID=id.)

When a message is delivered to &AOMREAD, a suite of system variables is set, including one for the message prefix (&AOMMSGID). No request for further tokenization is necessary unless specific processing is required on the message text. On this basis, using &AOMREAD SET is sufficient.

The following example illustrates the use of both &AOMMSGID and &AOMID:

&CONTROL NOLABEL
.READ
&AOMREAD MINOR=NO SET
&GOTO .&AOMMSGID
&GOTO .&AOMID
&AOMCONT
&GOTO .READ
 :
-* Special msg processing
.IOS000I
 : &GOTO .READ
-* Special msg processing for screening table set ID.
.HASPMSGS

 :
&GOTO .READ

While testing and developing the primary AOMPROC, you can terminate the current version and invoke a new updated copy. The SYSPARMS AOMPROC= command with FLUSH specified terminates the primary AOMPROC. To start the primary AOMPROC, the same command is used, specifying the member name from the relevant NCL library.

More information:

&AOMCONT

&AOMDEL

&AOMREPL