ADDRESS AXC Commands › Commands for REXX-related Operations › SESSCMD Command

SESSCMD Command

The SESSCMD command sends a text string (such as a command) to a specified session, and then retrieves a screen image from that session after the text string has been processed. (To fetch the screen image, an executing SESSCMD command invokes the GETSCRN command automatically.)

This command has the following format:

"SESSCMD 'keystring' SESSION(sessname) 
  [CMDWAIT(nn)]
  [PREFIX(prefix|LINE|NO)]
  [SCREEN(YES|NO)]"

keystring

Specifies the text of the command to be issued to the session. The string can contain up to 234 characters. If you execute the SESSCMD command from within a REXX program and the keystring contains quotation marks, specify the command by using different delimiter characters of your choice to enclose the text.

As part of the command text, you can include one of the following:

• A key abbreviation
• An operation instruction

Besides text, the string can also contain key abbreviations and keyboard operation instructions. A key abbreviation consists of the @ character followed by a letter (uppercase or lowercase), a digit, or the @ character itself. When specifying a key abbreviation, enter it exactly as shown in the key abbreviation table found in the appendix on customizing special CA Automation Point files in the Administrator Guide.

Note: The SESSCMD command automatically appends an ENTER keystroke (@E) to your keystring value.

SESSION

Specifies the name of the target session (sessname) to receive the command text.

CMDWAIT

(Optional) Specifies the number of seconds (up to 60) that CA Automation Point waits for the keyboard to unlock after the SESSCMD executes. After the specified waiting period, CA Automation Point then captures the current screen image of the current session.

If the time period you specified with the CMDWAIT operand expires before CA Automation Point issues the command, the SESSCMD command produces a return code of 32, meaning that the keyboard is locked. If CA Automation Point issues the command but the session does not respond to that command, the SESSCMD command generates a return code of 36.

Default: 15

PREFIX

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

Note: The variable numbered 0-for example, LINE.0-always contains the total number of elements in the stem variable.

Valid PREFIX values are:

prefix

Specifies he name that you want to assign to the line variables. 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 a screen image.

NO

Creates no variables. Specifying PREFIX(NO) saves memory if you do not intend to use the variables.

Default: LINE

Note: For compatibility with earlier versions of CA Automation Point, the SESSCMD command also creates the old-style, non-stem variables. For example, suppose that the PREFIX variable is LINE. In addition to the stem variables described above, SESSCMD also creates the nonstem variables LINE1, LINE2, and so on through LINEn. In this case, the variable LINE (equivalent to the stem variable LINE.0) contains the total number of elements in the variable.

Each time you issue the SESSCMD command, CA Automation Point creates SCREEN and LINE.n variables automatically unless you specify otherwise.

SCREEN

(Optional) Specifies whether CA Automation Point creates the variable SCREEN to store the character portion of the screen image. Valid SCREEN values are:

YES

Creates the SCREEN variable and other variables. For more information on those other variables, see the description of the GETSCRN command.

NO

Creates no variables. This option saves memory if you do not intend to use the variables.

Default: YES

Usage Notes:

A keyboard operation instruction consists of the @ character followed by a keyboard operation name enclosed in quotation marks. For example, the instruction for the MODE SELECT key is @"MODE_SEL". The Administrator Guide lists valid operation names

• CA Automation Point appends an ENTER keystroke (@E) before it sends the string.
• You can use key abbreviations and operations only where appropriate. For example, you cannot send the abbreviation for the PA1 key (@x) to a VT100 session because PA1 operates only in 3270 sessions.
• When you want to send a text string to a session without appending an ENTER keystroke to it (such as sending strings to 3270 sessions that contain 3270 AID keys: Enter, Clear, PA1 through PA3, PF1 through PF24), you can invoke the CA Automation Point @"SEND" operation from the same SESSCMD command.
• When the text string contains single or double quotes, use a different delimiter (such as /) to delimit the text string. For a complete description of alternate delimiters, see the section ADDRESS AXC Command Syntax.
• The SESSCMD and GETSCRN commands allow CA Automation Point to interact with 3270, 5250, and asynchronous consoles and screens generated by applications. CA Automation Point rules can also control some of those screens.
• For master console sessions, do not issue instructions that either change the state of the console or clear messages from the screen while automation is active.
• If you want to invoke the SESSCMD command from within a REXX program, use the following methods to prevent the SESSCMD command from interfering with message processing by rules:
  • Use a rule to capture the response of a SESSCMD command.

    When you issue a host command to an automated console session using the SESSCMD command in a REXX program, use CA Automation Point rules to capture data from the z/OS command response. In such a scenario, the rule stores the captured data in status variables; the REXX program retrieves the values from the status variables using the GETVAR command.

    Note: Rules process only the first line of a multi-line command response. To retrieve data from a multi-line response, invoke a REXX program or CLIST on the host to issue the host command, capture the command response data, and return the data to CA Automation Point as a set of single-line messages.

  • Use REXX programs instead of rules to control the console.

    TSO sessions are good candidates for REXX programs to control because you can use those sessions to communicate with your mainframe automation product.

    Note: If you use REXX programs to control a console, do not automate the session when you define it in the session definition set.

• If you issue an instruction to a session in one of the following ways, CA Automation Point sends the instruction as one complete unit:
  • Using a SESSCMD command
  • Using the KEY keyword for scripts
  • From the command line of the Command window, the Merged Messages window, or the AP Messages window
  • From rules clauses containing any of these keywords: OSCMD, REPLY, or SESSCMD

  However, a series of commands from any of those sources executes uninterrupted only if no other CA Automation Point facilities are using the session.

• Special considerations for VT52, VT100 and VT320 sessions: The CTRL+H key maps to an operation named DEL (represented by the ASCII character (ý) which has a decimal value of 127), a nondestructive backspace. The syntax for sending the nondestructive backspace from a REXX program is @"ý". (In most text editors, you can obtain the (ý) character by typing ALT+127. Press and hold the ALT key, type 127 on the numeric keypad, then release the ALT key.)

  The BACKSPACE key maps to the BACK_SPACE operation, a destructive backspace. When specifying a destructive backspace from a REXX program, you need to suppress the ENTER key. The syntax is:

  'SESSCMD /@"BACK_SPACE"@"SEND"/ SESSION(sessname)'
  

Examples:

• Suppose that you want a REXX program to issue the ISPF command =X (to take a TSO session out of ISPF) to a TSO session named S028. Insert the following statement into your REXX program:

  "SESSCMD /=X/ SESSION(S028)"
  

• Suppose that you want to send a NEWLINE keystroke to a non-automated, full-screen session named SESS_A, and you do not want the SESSCMD command to automatically append an ENTER keystroke. Insert the following statement into your REXX program:

  'SESSCMD /@N@"SEND"/ SESSION(SESS_A)'
  

• Suppose that you want to send a "power on reset" command to an asynchronous session called ASYNCH. Insert the following statement into your REXX program:

  'SESSCMD /@"POWER_RESET"/ SESSION(ASYNCH)'