Free-Form Syntax | DSPLY{(E)} {message {message-queue {response}}} |
Code | Factor 1 | Factor 2 | Result Field | Indicators | ||
---|---|---|---|---|---|---|
DSPLY (E) | message | message-queue | response | _ | ER | _ |
The DSPLY operation allows the program to communicate with the display work station that requested the program. Either message, response, or both operands must be specified. The operation can display a message and accept a response.
The value in the message operand and possibly the response operand are used to create the message to be displayed. message can be a field name, a literal, a named constant, a table name, or an array element whose value is used to create the message to be displayed. Within free-form calculations, the message operand can be an expression, provided the expression is enclosed by parentheses. The message operand can also be *M, followed by a message identifier that identifies the message to be retrieved from the message file, QUSERMSG. Use the OVRMSGF CL command to use a different message file. QUSERMSG must be in a library in the library list of the job receiving the message.
The message identifier must be 7 characters in length consisting 3 alphabetic characters and four numeric characters (for example, *MUSR0001, this means message USR0001 is used).
If specified, the message-queue operand can be a character field, a literal, a named constant, a table name, or an array element whose value is the symbolic name of the object meant to receive the message and from which the optional response can be sent. Any queue name, except a program message queue name, can be the value contained in the message-queue operand. The queue must be declared to the operating system before it can be used during program execution. (For information on how to create a queue, see the CL Programming). There are two predefined queues:
The response operand is optional. If it is specified, the response is placed in it. response can be a field name, a table name, or an array element in which the response is placed. If no data is entered, response is unchanged. To specify a response but no message queue in a free-form specification, specify ' ' for message-queue.
Fully qualified names may be specified as the Result-Field operand, and expressions are allowed as Factor 1 and Factor 2 operands, when coded in free-form calculation specifications. However, if the operand is more complex than a fully qualified name, the expression must be enclosed in parentheses.
To handle DSPLY exceptions (program status code 333), either the operation code extender 'E' or an error indicator ER can be specified, but not both. The exception is handled by the specified method if an error occurs on the operation. For more information on error handling, see Program Exception/Errors.
The maximum length of information that can be displayed is 52 bytes.
The format of the record written by the DSPLY operation with no message identifier specified by the message operand follows:
When you specify the DSPLY operation with a message identifier in the message operand, the operation functions as follows: the message identified in the message operand is retrieved from QUSERMSG, the message is displayed, and the program waits for the user to respond by entering data if the response operand is specified. The response is placed in the result field.
For more information, see Message Operation.
/free
// Display prompt and wait for response:
dsply prompt '' result;
// Display string constructed in an expression:
dsply ('Length of name is ' + %char(%len(str)) + ' bytes.');
/end-free