&WTOR

Issues an MVS WTOR and waits for a reply.

&WTOR[ CONSOLE={ nn | name } ] 
     [ RLEN={ 119 | nn } ] 
     [ MCSFLAG=([ RESP ][ ,REPLY ][ ,BRDCST ][ ,HRDCPY ] )] 
     [ ROUTCDE={ NONE | list } ] 
     [ WAIT={ YES | nn.nn } ] 
     { [ VARS=prefix* [ RANGE=(start,end) ] ] |
       [ VARS={ name | (var-name-list ) } ] |
       [ STRING ] | STRING=(var-name-list)
       [ ARGS [ RANGE=(start,end) ] ] }
      DATA=message text

The &WTOR verb lets an NCL procedure issue an MVS WTOR. Optional parameters allow specification of routing and descriptor codes, special MCS flags, and system console ID. By default, the procedure waits indefinitely for a reply. However, a maximum wait time is specified.

The &WTOR verb is not supported on z/VM.

Operands:

CONSOLE={ nn | name }

Indicates a system console ID that the WTOR is to be queued to. It uses the REG0 MCSFLAG to conditionally queue the WTOR to the nominated console. If this parameter is used with the ROUTCDE parameter, the WTOR will be queued to consoles based on routing code as well as the specified console ID.

RLEN={ 119 | nn }

Indicates the maximum reply length permitted. The default, and maximum (MVS-imposed) is 119 characters. Otherwise, specify a value of 1 to 119.

MCSFLAG=( [ RESP ] [ ,REPLY ] [ ,BRDCST ] [ ,HRDCPY ] )

Allows specification of some MCSFLAG values. If only a single value is required, MCSFLAG=flag is used. If more than one is required, MCSFLAG=(flag,flag...) is used.

Note: Some MCSFLAG values are not meaningful for &WTOR for example, HRDCPY.

The allowable MCSFLAG options are:

RESP: Indicates that this WTOR is a command response.
REPLY: Indicates that this WTOR is an echo of a reply to a WTOR.
BRDCST: Indicates that this WTOR is to be broadcast to all consoles, irrespective of routing codes, and so on.
HRDCPY: Indicates that this WTOR is to be a hardcopy-only WTOR that is, is to be logged to SYSLOG, but not sent to any console.

The only other MCSFLAG values that &WTOR uses are the ROUTCDE/DESC present flag, and the REG0 flag, set if CONSOLE= is specified.

ROUTCDE={ NONE | list }

Allows specification of a list of MVS routing codes.

A single value is specified as ROUTCDE=n. Multiple values, and ranges is specified as:

ROUTCDE=(4,13,27)ROUTCDE=(1-5,16,40-55)

Values: 1 to 128

WAIT={ YES | nn.nn }

Specifies how long the NCL procedure is to wait for a reply to the WTOR.

WAIT=YES, (the default) will cause the procedure to be suspended indefinitely, pending a reply.

WAIT=nn.nn will cause the procedure to wait for up to nn seconds for a reply. If no reply is provided by this time, the outstanding WTOR is canceled (DOM issued) and &RETCODE will be set to 4 and the procedure resumes execution. The valid range is 0.01 to 9999.99.

If a reply is provided, &RETCODE is set to 0.

WAIT=0 or WAIT=NO is not supported on &WTOR, as it would be senseless to issue and immediately cancel the WTOR.

Regardless of the WAIT value used, if the procedure is flushed for any reason, the WTOR is canceled.

VARS=

Specifies that the reply is to be tokenized into the nominated variables before control is returned to the procedure. Each word of the reply will be tokenized into the nominated variables from left to right. If insufficient variables are provided, some data will be lost. Excess variables will be set to a null value. The format of the operands that is coded with VARS= are described below.

prefix*: Denotes that variables will be generated automatically during the tokenization process, and that the variable names will be prefix1 .. prefix2 and so on. The RANGE= operand is specified to indicate a starting and ending suffix number. Prefix* cannot be used in conjunction with other variable names.
name: The name of a variable, excluding the ampersand (&).
name(n): As above, but n denotes the length of the data that is to be placed in the variable.

*(n)

Denotes a skip operation, where n represents the number of units to be skipped 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 that no tokenization is to be performed. The entire text of the reply is to be treated as a single string and returned to the procedure in &1. No variables is nominated if STRING is specified.

STRING=(var-name-list)

Specifies that the reply is to be segmented into substrings and placed in the nominated receiving variables. For example STRING=(A(5),B(10)) indicates that the first 5 characters are placed in &A and the next 10 characters in &B.

ARGS

Denotes that the message received will be tokenized and placed word by word into automatically generated variables of the from &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 will be generated.

DATA=message text

The text of the message to WTOR. Maximum length of the message is 122 characters.

Examples: &WTOR

&WTOR ARGS DATA=Reply with configuration parameters
&WTOR WAIT=10 CONSOLE=1 ARGS DATA=Reply with config. parameters
&IF &RETCODE=4 &THEN &WTO CONSOLE=1 +
   DATA=No parameters received within time limit

Notes:

When using &WTOR, consider these recommendations:

Always provide a message identifier at the start of the message. This identifier should establish some connection with the issuer of the &WTOR.
WTOR messages are always treated as Non-Roll-Delete. For this reason, keep to a minimum the number of WTOR messages outstanding at any one time.

No DOMID is returned after &WTOR, as the NCL procedure is always suspended until it is replied to, or until the WAIT interval is exceeded, in which case the WTOR is automatically deleted.

Careless use of &WTOR can tie up many system console buffers. WTOR messages are always Non-Roll-Delete (NRD).

The &WTOR verb generates an MVS WTOR. Thus, the message is seen and processed like any other WTOR message.

More information:

&WTO