Functions

Six

functions are provided:

AXRWTO
AXRWTOR
AXRMLWTO
AXRCMD
AXRWAIT
AXRINFO

AXRWTO is a function that issues the WTO macro containing the specified text, using the CONSNAME and CART provided on the AXREXX invocation. If CONSDATA is not specified, the message text is sent to the system log. There is one required argument for AXRWTO:

Message text - Containing the message text to be issued via the WTO macro. The text must be from 1 - 126 characters in length.

The return codes from AXRWTO are displayed as follows:

0 - AXRWTO was successful.
4 - Input message text was too long. WTO is truncated.
8 - Input message text was a 0 length string. WTO is not issued.
12 - Too many arguments were passed. WTO is not issued.
16 - The WTO macro returned a bad code. The REXX variable AXRDIAG contains the return code from WTO (in hexadecimal).
20 - Required argument was omitted. WTO is not issued.

The following are examples for AXRWTO:

WTOResult=AXRWTO('Hello from a REXX Exec');
CALL AXRWTO ‘Hello from  a REXX Exec’;     /* The return code from 
                      AXRWTO is set in the variable “Result”   */

AXRWTOR is a function that issues the WTOR macro containing the specified text, using the CONSNAME and CART provided on the AXREXX invocation. If CONSDATA is not specified, the message text is issued without any routing attributes. There is one required argument for AXRWTOR: Start of change

Message text - Containing the message text to be issued via the WTOR macro. The text must be from 1 - 126 characters in length.

Start of change The reply to the WTOR will be set to the AXRREPLY variable. End of change

An example follows:

Retcode = AXRWTOR('A message')
IF AxrReply = 'YES' THEN 
   SAY 'The operator reply was YES'
ELSE 
   Say 'Some other response'

Start of change The WTOR will be issued with descriptor code 7 so that the message is associated with the issuing task. If the exec were to time out or be cancelled, prior to the operator reply, the WTOR will be automatically DOM'd since the task running the exec will terminate under such conditions. Note, however, that if the WTOR is DOM'd prior to the operator replying to the WTOR, the exec will remain waiting for the reply indefinitely; the console DOM processor does not notify the WTOR issuer in this case. End of change

The following shows the return codes from AXRWTOR:

0 - WTOR was issued and a reply in AXRREPLY is returned.
4 - WTOR message text is too long. Message text is truncated.
16 - WTOR returned a non-zero return code. The REXX variable AXRDIAG contains the return code from the WTOR invocation.
20 - Internal error.

The following REXX syntax error messages are returned from AXRWTOR:

AXRWTOR – Missing required argument: The message text was missing.
AXRWTOR – Too many arguments specified: Too many arguments were specified.

AXRMLWTO is similar to AXRWTO, except instead of issuing a single line WTO, a multi-line WTO is issued. There are three required arguments for AXRMLWTO:

Message Text - containing the text of the message and the length of which depends on the line type.
Name of connect id variable - for the first invocation of the multi-line WTO, the variable should be set to FIRSTLINE. After the first call, the variable will contain the connect id and should not be altered by the application until the multiline WTO is completed. This argument must appear in quotation marks.
Line type - there are 5 different line types. For details, see the WTO - Write to Operator macro in z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO.
- C - Control Line. The message text must be from 1-35 characters. If used, this must be the first line of the multi-line.
- L - Label line. The message text must be from 1-71 characters.
- D - Data line. The message text must be from 1-71 characters.
- DE - Data end line. The message text must be from 1-71 characters.
- E - End line. The message text must be omitted.

AXRMLWTO has the following return codes:

0 - AXRMLWTO was successful.
4 - Message text was too long. Message is truncated.
8 - Text length was 0. WTO not issued.
12 - too many arguments were passed. WTO not issued.
16 WTO macro returned a bad code. The REXX variable AXRDIAG contains the return code from WTO in hexadecimal.
20 - A required argument was omitted. WTO is not issued.
24 - Invalid line type. WTO is not issued.
28 - Invalid connect id. WTO is not issued.
32 - Unable to set connect id variable. The variable name is bad. WTO is issued.

The following are examples of the invocation of AXRMLWTO:

ConnectId = 'firstline';                                       
MyResult=AXRMLWTO('Line 1 from a REXX Exec', 'Connectid','c');  /* Issue  
                             the 1st line of the multiline */
                       
IF MyResult^=0 THEN                                            
  EXIT 1;                                                      
MyResult=AXRMLWTO('Line 2 from a REXX Exec', 'Connectid','d'); /* Issue
                             the 2nd line of the multiline    */                
IF MyResult ^=0 THEN   
  EXIT 2; 
CALL AXRMLWTO ,'ConnectId','e';  /* End the multiline.  In this case,    
                              return code from AXRMLWTO is set in the 
                              variable “result”  */

AXRCMD is used to issue a system command from within the exec and obtain one or more command responses. The arguments that can be specified are as follows:

Command text - The system command to be invoked. This is an optional argument. If it is omitted, no command will be issued, but a response from the last command issuance will be returned if one exists.
Msgstem - The stem of a list of variables into which AXRCMD places the command response message text. This is an optional argument. If it is omitted, command text must be specified. To place the message text into compound variables which allows for indexing, msgstem should end with a period (for example, "messg."). AXRCMD places each line of the retrieved message into successive variables. For example, if the command response is a 3 line message, then messg.1 contains line 1, messg.2 contains line 2 and mssg.3 contains line 3. messg.0 will contain the number of lines. If msgtem does not end with a period, the variable names are appended with consecutive numbers. For example, suppose you specify msgstem as "conmsg" (without a period). If AXRCMD retrieves a message that has two lines of message text, AXRCMD places the text in the variables consmsg1 and consmsg2. The variable consmsg0 contains the number of lines in the message text, which is 2.
Time - The amount of time in seconds that AXRCMD should wait for a command response. This is an optional argument. If it is omitted, AXRCMD will not wait before attempting to determine whether a command response was returned. A value of 0 - 21474535 seconds may be specified.

Return codes are as follows:

0 - The system command was issued and the command response received if requested. The REXX variable AXRDIAG contains the return code and ASID (separated by a blank) from MGCRE which are only valid for the START command.
4 - Command was issued but no command response was received in the specified time limit.
8 - The input wait time contained an invalid value. AXRCMD is not processed.
12 - Too many arguments were passed. AXRCMD is not processed.
16 - The variable name to contain the output of the system command was not acceptable to REXX. If a command was specified, it is issued, but no command response is returned.
20 - A required argument was omitted. Either the Command text or Msgstem (or both) must be specified. This return code will also occur if both of these arguments are 0 in length. AXRCMD is not processed.
24 - STIMERM could not be issued to time the request, possibly because there were too many STIMERM requests already in existence. The command was issued if the command argument was specified, but the command response is not returned.
32 - The command text is too long, exceeding 126 characters. AXMCMD not processed.

When command text is specified, AXRCMD invokes the MGCRE macro to issue the command. Once the command is successfully issued, AXRCMD will retrieve the command response. Most commands will issue the command response as a multi-line WTO. However, there are some commands that return the response in a number of distinct WTOs. In order to obtain all the command responses returned in distinct WTOs, the AXRCMD command can be reissued without any specified command until there are no more responses to obtain. For example, CmdResult=AXRCMD(,OutputVar.,Time). A return code of 4 in CmdResult indicates that there are currently no more responses to be obtained, although the command may still be providing responses.

When the START command is invoked, the AXRDIAG variable will contain the return code from MGCRE in hexadecimal, followed by the ASID of the new address space (also in hexadecimal), separated by a blank.

Users of AXRCMD can initiate another REXX exec by either specifying the MODIFY AXR command or by using the System REXX command prefix, but should be careful not to recursively invoke the same exec using AXRCMD.

The following are some examples of the invocation of AXRCMD.

This example will issue a command which returns its response as a multi-line WTO and will display the output from it:

CmdResult=AXRCMD ('D U,,,480','OUTPUTVAR.',40); /*Issue the D U command */

DO I = 1 TO OUTPUTVAR.0                      /* Iterate for the number  
                                        of lines returned */ 
  SAY OutputVar.I                           /* Say the line   */
END;

This example will issue a command that returns its response in separate WTOs and will display the output from them. This can also be used to issue and display output for commands that return their responses in a multi-line WTO.

Note: Variable OutputVar.0 will only contain the number of lines within a single WTO issuance.

      CmdResult =  AXRCMD('$DI',OutputVar.,40)  
      IF CmdResult = 0 THEN                     
         DO WHILE CmdResult = 0                 
            IF OutputVar.0 > 1 THEN             
               DO LineNum = 1 TO OutputVar.0    
                  CALL AXRWTO OutputVar.LineNum 
               END                              
            ELSE                                
               CALL AXRWTO OutputVar.1          
            CmdResult=AXRCMD(,OutputVar.,40) /* Wait up to 40 sec for
                             a cmd response */  
         END                                    
      ELSE                                      
         CALL AXRWTO 'command failed. RC=' CmdResult

Below is an example of the use of AXRCMD, but not waiting for the command response. Instead, retrieving the command response at a later time:

MyResult=AXRCMD('D  T');     /* Issue the D T command but don't wait for
                             a command response   */
     /* Do some other work */
MyResult=AXRCMD(, OUTPUTVAR.,10);    /* Obtain the command response from
                            the last command issued and wait 10 seconds
                            if it hasn't already arrived */

AXRWAIT is a function that provides the capability for a REXX exec to wait for a specified amount of time in seconds. A single parameter with a numeric value between 0 and 21474536 is required. If the input is not syntactically correct, AXRWAIT ends the exec with a syntax error; otherwise, it returns error codes. The following statement would be coded to pause an exec for 15 seconds:

X = AXRWAIT(15)

Possible syntax error messages are:

AXRWAIT: Missing argument
AXRWAIT: Extraneous argument
AXRWAIT: Non-numeric time value

Possible return codes are:

14 - Wait time was too large.
18 - STIMERM returned a bad code. The variable AXRDIAG contains the code that STIMERM returned.

AXRINFO method returns information about the environment under which the exec is running. The following are valid options:

SUBSYSTEM

Returns the name of the Subsystem associated with the home address space the exec is running in.

AXREXXINVOKERSHOMESTOKEN

Returns the STOKEN associated with the home address space in which AXREXX was invoked to initiate the currently running exec.

REXXENVTYPE

Returns information about the environment that the exec is running under. The possibilities are:

TSO=YES,TMP=NO
TSO=YES,TMP=YES
TSP=NO

The following is an example for the parameter option SUBSYSTEM:

X = AXRINFO('SUBSYSTEM')

Possible syntax error messages are:

AXRINFO: Missing argument
AXRINFO: Extraneous argument
AXRINFO: Unrecognized argument