&PAUSE

Suspends processing of an NCL process until the operator requests that processing continue or be terminated.

&PAUSE [ { VARS=prefix* [ RANGE=(start, end) ] |
           VARS={ name | (name, name, ..., name) } |
           STRING=( name, name, ..., name) |
           ARGS [ RANGE=( start, end ) ] [ user supplied text ] } ]

The &PAUSE statement allows an NCL process to suspend processing pending input from an OCS window. When using a non-full screen procedure, interaction with the OCS operator may be required. An example of this is a procedure that contains documentation for the operator describing some manual action that must be taken, such as calling a number for service. Once the specified action has been taken, the operator can enter a command to resume or to terminate processing:

Use a GO command to resume processing. Optionally, the GO command can pass information to the procedure.
Use a FLUSH command to terminate the NCL process.

Enter an &PAUSE statement in the procedure at the point where processing is to be suspended. The &PAUSE is specified either with or without user text. If no text is entered, the system will supply appropriate highlighted text defining the action the operator must take to continue or terminate processing of the procedure:

N04107 PROCEDURE xxxxxxxx NCLID=nnnnnn PAUSED.

The highlighted text (default or as supplied on the &PAUSE statement) is displayed as a non-roll delete message on the OCS window and will remain displayed until the procedure leaves its paused state.

On completing the &PAUSE, the system variable &ZVARCNT is set to the number of variables created or modified by the operation.

Operands:

VARS=

Specifies the variables that will contain the operator's response. The operator response is entered using a GO command followed by text. The response text (excluding the GO command keyword) will be tokenized into the nominated variables from left to right before control is returned to the procedure. If insufficient variables are provided, some data will not be available to the procedure. Excess variables will be set to a null value. The formats of the operands that may be coded with VARS are described below.

prefix*: Denotes that variables are generated automatically during the tokenization process, and that variable names will be prefix1 … prefix2, and so on. (The RANGE= operand may be specified to indicate a starting and ending suffix number). prefix* cannot be used with other variable names.
name: The name of a variable, excluding the ampersand (&).
name(n): As name, but n denotes the length of the data to be placed in the variable. If necessary, the data is truncated.
*(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'. The asterisk (*) by itself is the same as *(1).

STRING=

Specifies that no tokenization is to be performed. The entire text of the command line is treated as a single string and returned to the procedure in the nominated variables. The formats of the operands associated with STRING are:

name: User-specified variables, excluding the leading &, into which the string text is put. Text is placed into each variable up to the maximum length of that variable.
name(n): User-specified variables, excluding the leading &, into which the string text is put. Text is placed into each variable for the length specified n.
*(n): Denotes a skip operation, where n denotes 'skip this number of characters'. An asterisk (*) by itself is the same as *(1).

ARGS

Denotes that the line of text retrieved will be 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 text. The RANGE= operand may be coded to designate a start number and optionally an end number, which delimits the number of variables that will be generated.

user supplied text

Optional upper and lower case text describing the action the user must take. When specifying this form of the &PAUSE statement, the VARS or STRING operand cannot be specified. Entry of text on the GO command will be assigned as if ARGS was coded.

Note: When user-supplied text is not specified, system default message N04107 is written. When information concerning the reason the procedure paused, or operator action is required, it is the user's responsibility to ensure that an appropriate prompt is displayed, such as using &WRITE, before issuing the &PAUSE.

Examples:

&CMDLINE GO ID=&ZNCLID _YES  -* Preformat OCS reply for user
&WRITE DATA=ENTER “GO YES” TO CONTINUE, “GO NO” TO END.  
&PAUSE ARGS
&IF .&1 EQ .NO &THEN +
 &END
-*
-* Processing
-*

&PAUSE STRING=(CMD)
ROUTE NMT &CMD

&PAUSE ARGS RANGE=(20,80)

Waits for the operator response, specifying that it is tokenized into variables &20 to a maximum of &80. &ZVARCNT is set to indicate how many variables were created.

&PAUSE VARS=(*(3),A(2),B(3),C,D,E,F)

Reads the operator response text and tokenizes the message into individual words; *(3) indicates that the first 3 words are ignored, 2 characters of the next word are placed in the variable &A, three characters of the next word are placed in the variable &B and the next 4 words are placed in variables &C, &D, &E and &F respectively.

&PAUSE VARS=ABC* RANGE=(1,50)

Reads the operator response text, tokenizes it and places the text word by word into a series of automatically generated variables of the form ABC1 ABC2 ... ABC50. As many variables as required are generated, to the limit specified by the RANGE operand.

&PAUSE STRING=(A,B(2),*(5),C(3))

Reads the operator response as a single string of text. The first 256 bytes are placed in &A, the next 2 characters are placed in &B, the next 5 characters are ignored and the next 3 characters are placed in &C.

Notes:

The status of all paused procedures in a user's NCL processing region is interrogated using the SHOW PAUSE command.

Multiple NCL processes may be executing in the same NCL processing environment and all may issue &PAUSE to await operator input. The operator must use the ID operand of the GO command to identify the process being referenced.

If an OCS operator exits while a procedure is in a paused state, the procedure will be flushed. The PROFILE EXIT command is used to prevent termination of OCS while NCL processes are active.

Procedures executing in a dependent processing environment can issue &PAUSE. In association with the GO command this provides a useful mechanism for process communication between hierarchically dependent NCL processes.

While a procedure remains paused in an OCS environment, the P mode indicator will be displayed to the left of the command line to warn the operator. This indicator will be cleared when all pause conditions are satisfied.

More information:

&INTCMD

&INTREAD