Host Environment Commands › ADDRESS EPI Commands › EPI SESSCMD—Issue Command to VTAM Session

EPI SESSCMD—Issue Command to VTAM Session

Use the SESSCMD command to issue a command to a VTAM application session. For SESSCMD to function, CA OPS/MVS must be monitoring the VTAM session.

This command has the following format:

ADDRESS EPI "SESSCMD keywords"
  {'cmdtext'}
  {SESSION(sessid)}
  [CMDRESP(dest)]
  [CMDWAIT(maxwait)]
  [ID(screenid)]
  [MAXCMDOUT(maxlines)]
  [PREFIX(prefix)]
  [STOPMSG(text,text)]
  [SUBSYS(ssid)]
  [TRUNCATE(YES|NO)]

cmdtext

Specifies the text of the command to be issued to the VTAM session. It can be up to 1,000 bytes long. If the cmdtext contains quotes, you can specify the command in one of the following ways:

• Use two consecutive single quotes for each quote that will be passed to the application. For example, SESSCMD '''DSIRB11.ASM''' causes the text 'DSIRB11.ASM' to be set.
• Use a pair of characters other than question marks to enclose the text. For example, SESSCMD /'DSIRB11.ASM'/ causes the text 'DSIRB11.ASM' to be set.

As part of the command text you enter, include an abbreviation for an AID key, that is, one of the function keys on the 3270 keyboard. When CA OPS/MVS executes SESSCMD, it issues the command and sends the function keystroke you specified. If you do not enter a key abbreviation, CA OPS/MVS issues the specified command, and then sends an Enter keystroke.

To simulate an Enter keystroke, use this text:

SESSCMD ''

Otherwise, the Enter keystroke is implied. A key abbreviation consists of the at-sign (@) followed by a lowercase letter, a digit, or uppercase C. The abbreviations correspond as much as possible to the actual name of the key. For example, the abbreviation for the CLEAR key is @C, the abbreviation for PF3 is @3, and so on. For a list of possible abbreviations, see Keyboard Mnemonics for Special Function Keys in this chapter.

When specifying an abbreviation for an AID key, enter the abbreviation exactly as shown in Keyboard Mnemonics for Special Function Keys in this chapter. Otherwise, SESSCMD cannot interpret the abbreviation you entered as a valid keystroke. The abbreviation must be the final item in your text, or else CA OPS/MVS issues this message:

OPS4386W EXTRANEOUS CHARACTERS IGNORED AFTER PF, PA OR CLEAR KEY

After this message appears, CA OPS/MVS continues to process the SESSCMD command processor. However, CA OPS/MVS sends only the command text that preceded the key abbreviation, plus the key abbreviation itself, to the VTAM session.

SESSION

Specifies the session ID of the VTAM application session.

CMDRESP

(Optional) Specifies the kind of variables to store the fetched screen image.

The dest value can be either CLIST or REXX.

Default: CLIST

CMDWAIT

(Optional) Specifies the maximum amount of time that SESSCMD waits before it times out. SESSCMD normally waits for the terminal keyboard unlock condition before it returns to the current screen image (unless it is used with the STOPMSG keyword).

When used with the STOPMSG keyword, SESSCMD tries to satisfy the STOPMSG request until the CMDWAIT value expires.

Default: 1 second, and the maximum value is 900 seconds.

ID

(Optional) Assigns a one- to eight-character ID to the screen image generated by the command. In screen rules, this ID identifies the command that produced the screen.

CA OPS/MVS assigns this ID to all responses from the application while the SESSCMD command processor is executing, regardless of whether those responses are responses to the command or to some other application action.

Default: No screen ID.

MAXCMDOUT

(Optional) Specifies the maximum number of lines that SESSCMD returns.

PREFIX

(Optional) Specifies the one- to six-character prefix to be used when creating the CLIST or REXX variables. For more details on these variables, see Using SESSCMD in a CLIST or REXX EXEC in this chapter.

STOPMSG

(Optional) Specifies a text string that CA OPS/MVS searches for as it receives the response from a command issued to a VTAM application session (through SESSCMD). If text matches any text in the response screen returned by the VTAM session, CA OPS/MVS terminates the SESSCMD. If no text in the response screen matches text, SESSCMD times out, producing an error message and return code.

You can specify up to ten text elements with the STOPMSG keyword. Each text element can use as many as 32 characters. If you specify more than one text element, you must separate those elements with commas as shown in the following example:

STOPMSG(text,text,text, . . .)

Also, text can contain non-alphabetic characters. For example, many application screens terminate with three asterisks (***). So if you want SESSCMD to terminate when CA OPS/MVS detects the end of the response screen from the VTAM session, specify STOPMSG(***).

Notes:

• Exercise caution when using the STOPMSG keyword to search for a text string when a high value is specified for the CMDWAIT keyword-doing so may encumber your system resources.
• SESSCMD polls the terminal four times a second for updates to the screen until the CMDWAIT value expires or a STOPMSG string is found.

SUBSYS

(Optional) Addresses the command to a copy of CA OPS/MVS with a subsystem ID other than the default subsystem ID, which is OPSS.

TRUNCATE

(Optional) Specifies whether CA OPS/MVS truncates the screen image display when you enter SESSCMD from a TSO terminal. Possible TRUNCATE values are YES, which tells CA OPS/MVS to truncate this display to make it more readable; and NO, which tells CA OPS/MVS not to truncate this display. The default is YES.

Examples: SESSCMD Command

• This command gets TSO session TSOAA11 out of ISPF and back to the READY prompt:

  SESSCMD '=X' SESSION(TSOAA11)
  

• The following shows the use of the SESSCMD command in a REXX program:

  sess = 'A44IEPC1'
  /* GET THE CURRENT SCREEN IMAGE INTO STEM VARIABLES PREFIXED WITH LINE*/
  ADDRESS EPI
  "GETSCRN SESSION("sess") CMDRESP(REXX) PREFIX(LINE)"
  IF RC > 0 THEN
    DO
      SAY "GETSCRN RETURN CODE =" RC
      EXIT
    END
  DO FOREVER
    DO Z=1 TO LINE.0
      LINE.Z = SUBSTR(LINE.Z,1,60)
    END
    ADDRESS WTO
    "TEXTVAR(LINE.) MSGID('')"
    "TEXT('CURSOR AT ROW" csrrow ", COLUMN" csrcol "ENTER COMMAND",
      "OR EXIT') REPLY"
    IF RC > 0 THEN EXIT
    IF QUEUED() > 1 THEN EXIT
    PARSE PULL . RPLY
    "TEXT('OPERATOR REPLY IS:" rply "')"
    IF POS('EXIT',RPLY) > 0 THEN EXIT
    ADDRESS EPI
    "SESSCMD /"rply"/ SESSION("sess") CMDRESP(REXX) PREFIX(LINE)",
      "CMDWAIT(5)"
    IF RC > 0 THEN
      DO
        DO WHILE QUEUED() > 0
          PARSE PULL X; SAY X
        END
        EXIT
      END
  END
  RETURN