RCVCMD—Receive a message from VTAM

Purpose

After an application program issues a VTAM® operator command (VARY, DISPLAY, MODIFY, or REPLY) using a SENDCMD macroinstruction, a RCVCMD macroinstruction is used to receive the requested information. In addition, unsolicited VTAM messages, such as those indicating an unexpected failure in the network, can be received with this macroinstruction.

Usage

Before issuing the RCVCMD macroinstruction, the application program must set register 13 to the address of an 18-word save area. Refer to Summary of register usage, for information pertaining to the register contents upon return of control.

For information on writing an application program that can issue VTAM operator commands and receive VTAM messages, see Program operator coding requirements.

VTAM receives control from the RCVCMD macroinstruction in the addressing mode of the application program that issued the macroinstruction and returns control to the application program in that same mode.

Syntax

Read syntax diagramSkip visual syntax diagram name RCVCMDRPL=rpl_address ,ACB=acb_address1,AREA=input_message_address1,AREALEN=input_message_area_length1,BRANCH=NOYES1,ECB=INTERNAL1,ECB=ecb_address,EXIT=exit_routine_address1
Read syntax diagramSkip visual syntax diagram,OPTCD1=(2ASYSYNQNQTRUNC)
Notes:
  • 1 Operand value can be placed in its RPL field either by specification on an RPL macroinstruction operand or by explicitly setting the field using the IFGRPL DSECT.
  • 2 You can code more than one suboperand on OPTCD, but code no more than one from each group.

Input parameters

RPL=rpl_address
Indicates the RPL that specifies which kind of processing RCVCMD is to perform.
The following RPL operands apply to the RCVCMD macroinstruction:
ACB=acb_address
Indicates the ACB that identifies the application program issuing RCVCMD.
AREA=input_message_address
Must contain the address of the area in the application program where the incoming message header, optional message identification, and the message text are to be placed. After the message has been moved to this area, the RPL's RECLEN field is set by VTAM with the total number of bytes of received data that have been moved into the AREA field. The AREA field is ignored if AREALEN=0.
AREALEN=input_message_area_length
Contains the length (in bytes) of the message area pointed to by AREA. The length specified should be 8 bytes longer than the longest message text anticipated to provide enough space for the message header and optional reply ID. The AREA field must be at least 4 bytes and no longer than 130 bytes.
BRANCH
For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.
BRANCH=YES
When the macroinstruction is issued, VTAM processes the macroinstruction using authorized path. For programs running under an SRB rather than under a TCB, the macroinstruction is processed in this manner automatically, regardless of the actual setting of the BRANCH field.
BRANCH=NO
When the macroinstruction is issued, VTAM does not process the macroinstruction using authorized path.
ECB
Indicates that an ECB is posted when an asynchronous (OPTCD=ASY) RCVCMD operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction.
ECB=event_control_block_address
Specifies that VTAM is to post an event control block (ECB). Event_control_block_address is the location of the ECB to be posted. The ECB can be any fullword of storage aligned on a fullword boundary.
ECB=INTERNAL
Specifies that VTAM is to post an internal ECB.
EXIT=exit_routine_address
Indicates the address of an RPL exit routine that is scheduled when an asynchronous (OPTCD=ASY) RCVCMD operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction. For details about the EXIT operand, refer to the RPL macroinstruction description in this chapter.
OPTCD=Q
OPTCD=NQ
Indicates the action to be taken if no input is available when the RCVCMD macroinstruction is executed. OPTCD=Q means that the macroinstruction is completed when the requested input eventually arrives. OPTCD=NQ means that the macroinstruction is completed immediately with (RTNCD,FDB2)=(X'00',X'06') if the input is not available.
Note: After a CLOSE macroinstruction fails because operator messages are still queued for the application program, RCVCMD macroinstructions can still be issued, but they are not queued. After the last message is received, RCVCMD is posted with (RTNCD,FDB2)=(X'14',X'70') if OPTCD=Q is specified, or (RTNCD,FDB2)=(0,6) if OPTCD=NQ is specified. This indicates that no more messages are queued. CLOSE can be reissued.
OPTCD=SYN
OPTCD=ASY
If SYN option code is set, control is returned to the application program when the RCVCMD operation has completed. If ASY option code is set, control is returned as soon as VTAM has accepted the request. Once the RCVCMD operation has completed, the ECB is posted or the RPL exit routine is scheduled, depending on the setting of the ECB-EXIT field. Refer to the RPL macroinstruction description in this chapter for details about OPTCD=SYN or OPTCD=ASY.

Because it might take VTAM a relatively long time to complete the RCVCMD operation, you should not use the SYN option if suspending the RCVCMD-issuing task or SRB for this time is undesirable. Use the ASY option code, instead.

OPTCD=TRUNC
Indicates that input data that is too lengthy is truncated whenever the RCVCMD macroinstruction is issued.

Examples

RCVCMD1   RCVCMD RPL=RPL1,AREA=MSGBUF,AREALEN=126,                     C
               OPTCD=(TRUNC,Q)

RCVCMD1 is completed when an incoming message is received from VTAM. After RCVCMD1 is completed, the application program can examine the contents of MSGBUF to determine the message received. Any messages that exceed 126 bytes are truncated to 126 bytes.

Completion information

The RCVCMD operation is successfully completed when the message or reply is received, the data (if any) is placed in the input area, and the appropriate information is set in the RPL. If NQ is specified and no input is available, RCVCMD is completed immediately.

After the RCVCMD operation is completed, the following RPL fields can be set by VTAM:
  • The value 40 (decimal) is set in the REQ field, indicating an RCVCMD request.
  • The RECLEN field indicates the length of the message placed in the input area pointed to by the AREA field. The length specified includes 4 bytes for the header and 4 additional bytes (if required) for the reply identifier. The reply-requested bits in the status field of the header can be tested to determine if this field is present.

    If a reply is requested for this message, the AAREALN field indicates the maximum length the reply can be. This reply length includes header, message ID, and text.

  • The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions.

Registers 0 and 15 are also set as indicated in Handling errors and special conditions.