ADDRESS AXC Commands › Commands for Automation Processing Data › READBUF Command

READBUF Command

The READBUF command reads the next message from an automated asynchronous session's internal message stream buffer (if one exists). Upon completion, the message is removed from the buffer. When the READBUF command returns a message with no lines, the buffer is either empty or the message has not yet arrived.

This command reads one message at a time from the session buffer. If a message exists in the session buffer when this command is issued, that message is placed into the Line.1 stem variable when using the default prefix of LINE.

This command has the following format:

"READBUF SESSION(sessname) [PREFIX(prefix|LINE|NO)] [WAIT(waittime)]"

SESSION

Specifies the session (sessname) that has a message buffer from which you want to read the host messages. The session must be an automated asynchronous session.

PREFIX

(Optional) Creates a stem variable to store the message read from the buffer. CA Automation Point stores each line of the message in a separate stem variable and numbers the variables consecutively (for example, LINE.1, LINE.2, and so on).

Note: The stem variable numbered 0 (for example, LINE.0) always contains the total number of message lines stored in the variable. (So if LINE.0=0, then the buffer was empty when your REXX program issued the READBUF command.)

Valid PREFIX values are:

prefix

Specifies the name that you want to assign to the stem variable. For example, specifying PREFIX(ROW) causes CA Automation Point to create a set of variables named ROW.0, ROW.1, ROW.2, and so on through ROW.n.

LINE

Tells CA Automation Point to create stem variables named LINE1 through LINEn to store lines of the buffer.

NO

Discards the message.

Default: LINE

WAIT

(Optional) Specifies the number of seconds (waittime)-from 0 to 100000-that the READBUF command waits if the buffer is empty.

If the waittime value expires before a message arrives in the buffer, the READBUF command generates a return code of 3.

Default: 0

Usage Notes:

Keep the following points in mind when using the READBUF command:

• Only the REXX program that opened the buffer can read from the buffer. (The OPENBUF command opens a buffer for an asynchronous session.)
• If your REXX program issues a CALL statement to call another REXX program, the called program can read from the buffer.
• If a buffer does not exist for the session that you specify, or if another REXX program currently owns the specified session's buffer, the READBUF command generates a return code of 3.
• You can direct messages that the REXX program reads from the buffer to CA Automation Point rules by issuing the MSG command.