SENDCMD—Send a VTAM operator command to VTAM

Purpose

It is possible for an application program to send VTAM® operator commands to VTAM and to reply to messages sent to the application program by VTAM. The SENDCMD macroinstruction permits an authorized application program to send the following commands: VARY, DISPLAY, MODIFY, and REPLY.

Note: The HALT and START commands cannot be issued using the SENDCMD macroinstruction. They can be issued only by the VTAM operator at the system console.

Usage

Before issuing the SENDCMD 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 SENDCMD 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


>>-+------+--SENDCMD--RPL--=--rpl_address----------------------->
   '-name-'                                 

>--+----------------------------+------------------------------->
   |                        (1) |   
   '-,--ACB--=--acb_address-----'   

>--+---------------------------------+-------------------------->
   |                             (1) |   
   '-,--AREA--=--command_address-----'   

>--+---------------------------+-------------------------------->
   |                       (1) |   
   '-,--BRANCH--=--+-NO--+-----'   
                   '-YES-'         

>--+--------------------------------------+--------------------->
   |                     (1)              |   
   +-,--ECB--=--INTERNAL------------------+   
   +-,--ECB--=--ecb_address---------------+   
   |                                  (1) |   
   '-,--EXIT--=--exit_routine_address-----'   

>--+--------------------------------+--------------------------->
   |                            (1) |   
   '-,--OPTCD--=--(--+-ASY-+--)-----'   
                     '-SYN-'            

>--+----------------------------------+------------------------><
   |                              (1) |   
   '-,--RECLEN--=--command_length-----'

Notes:

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.

Input parameters

RPL=rpl_address: Indicates the RPL that specifies which kind of processing SENDCMD is to perform.

The following RPL operands apply to the SENDCMD macroinstruction:

ACB=acb_address

Indicates the ACB that identifies the application program issuing SENDCMD.

AREA=command_address

Indicates the address of the header and command to be sent to VTAM.

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) SENDCMD 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) SENDCMD 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=SYN

OPTCD=ASY

If the SYN option code is set, control is returned to the application program when the SENDCMD operation has been completed. If the ASY option code is set, control is returned as soon as VTAM has accepted the request. After the SENDCMD 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 SENDCMD operation, the SYN option should not be used if suspending the SENDCMD-issuing task or SRB for this time is undesirable. Instead, the ASY option code should be used.

RECLEN=command_length

Indicates the number of bytes to be sent to VTAM. The number specified must be equal to the length of the header and command pointed to by the AREA field. If the RECLEN field is set to 0, the AREA field is not examined. The maximum length is 130.

Examples

SENDCMD1 SENDCMD RPL=RPL1,AREA=VARYCMD1,RECLEN=CMDLEN
         .
         .
         .
VARYCMD1 DC    00          HEADER
         DC    03          STATUS FIELD
         DC    0001        IDENTIFICATION NUMBER
         DC    C'VARY NET,ACT,ID=LU1' COMMAND
CMDEND   EQU   *
CMDLEN   EQU   CMDEND-VARYCMD1

SENDCMD1 sends a message to VTAM, consisting of the area between VARYCMD1 and CMDEND, instructing it to activate logical unit LU1. The status field indicates that a reply is returned to the application program. See Data exchanged between a program operator and VTAM for information pertaining to the header and status field settings.

Completion information

A SENDCMD operation is successfully completed when the command is passed to VTAM for subsequent processing.

After the SENDCMD operation is completed, the following RPL fields are set:

The value 39 (decimal) is set in the REQ field, indicating a SENDCMD request.
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.