GETSCRN Command

ADDRESS AXC Commands › Commands for Automation Processing Data › GETSCRN Command

GETSCRN Command

The GETSCRN command captures the screen image associated with a session and places information about that session in variables.

This command has the following format:

"GETSCRN SESSION(sessname) [SCREEN(YES|NO)] [PREFIX(prefix|LINE|NO)]"

SESSION

Specifies the name of the session (sessname) from which you want to capture the screen image.

SCREEN

(Optional) Specifies whether to create the REXX variable SCREEN to store the character portion of the screen image. This operand has two options:

YES: Creates the SCREEN variable.
NO: Does not create the SCREEN variable. Specifying SCREEN(NO) saves memory if you do not intend to use the SCREEN variable.

Default: YES

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: The name that you want to assign to the variables set by the PREFIX operand. For example, specifying PREFIX(ROW) causes CA Automation Point to create stem variables named ROW.0, ROW.1, ROW.2, and so on through ROW.n.
LINE: Tells CA Automation Point to create REXX variables named LINE1 through LINEn to store lines of a screen image.
NO: Does not create the screen variable. Specifying PREFIX(NO) saves memory if you do not intend to use the variables.

Default: LINE

Usage Notes:

Some asynchronous console sessions have a scrolling display and sometimes generate multiple screens of output. For these sessions, it is better to open an internal message stream buffer and redirect the incoming messages to the buffer; your REXX program can then read the messages in the buffer and act upon each one as necessary. For more information about message stream buffering, see the description of the OPENBUF command.
For compatibility with earlier versions of CA Automation Point, the GETSCRN 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, GETSCRN also creates the non-stem 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.
When you issue the GETSCRN command from a REXX program, CA Automation Point captures the screen image and places information about the screen into the following REXX variables:

CSRCOL

Specifies the column in which the cursor is positioned.

CSRPOS

Specifies the number of positions the cursor is away from the upper-left corner of the screen.

CSRROW

Specifies the row containing the cursor.

OIA

Specifies the operator information area (OIA) (also called the status line).

SCREEN

Creates a copy of the text of the screen image, with each row laid end to end. This copy does not include attributes such as colors or field positions.

SCRLEN.

Specifies the number of lines on the screen.

SCRSIZE

Specifies the number of characters the screen can contain.

SCRSTAT

Specifies the status of the screen:

LOCKED-The terminal emulator for the session is currently in an X-state and will not accept any input from the keyboard.

UNLOCKED-The terminal emulator for the session is not currently in an X-state.

SCRWIDTH

Specifies the number of columns on the screen.
Each time you issue the GETSCRN command, CA Automation Point creates SCREEN and LINE.n variables automatically unless you specify otherwise.

Examples--capture screen image:

Suppose that you want to use a REXX program to capture a screen image from an MCS console session and place information about that screen in REXX variables. You can place a statement like the following in the REXX program:
```
"GETSCRN SESSION(S008)"
```
In the sample statement, S008 is the name of an MCS console session. Because this statement does not specify the PREFIX operand, CA Automation Point automatically stores lines of the returned screen image in REXX variables named LINE1 through LINEn.

The sample REXX program described next uses the CA Automation Point GETSCRN and WTO commands to capture the contents of a screen and place them in a file called SCREEN.cap. To invoke the REXX program, issue the command shown below either manually or using a CA Automation Point rule:
```
SC sessname filename [DEBUG]
```
The command has these components:
- SC specifies the name (SC.cmd) of the REXX program.
- The sessname value is the name of the session supplying the screen to be captured.
- The filename specifies the file name to hold the captured screen image. (The default file name is SCREEN.cap.)
- DEBUG is an optional operand that activates the REXX trace facility for debugging purposes.

CA Automation Point provides a sample REXX program, SC.cmd, for capturing a screen image. The following example shows the text of the SC.cmd program. Besides the GETSCRN command, the program also uses the SESSCMD and WTO commands.

/* This REXX program captures a screen image. */
PARSE UPPER ARG . "'" TEXT "'" .   /* Get the message text.  */
IF DEBUG \= '' THEN TRACE R         /* Activate REXX trace.   */

PARSE UPPER ARG P1 P2 .            /* Parse off positional arguments */
IF P1="" | P1='DEBUG'               /* If first arg not there,        */
THEN SESSNAME ='SESSION'            /* Then set default session name  */
ELSE SESSNAME = P1                  /* Else, use 1st argument         */

IF P2="" | P2="DEBUG"               /* If second argument not there   */
THEN FILENAME = 'SCREEN.CAP'        /* Then set default filename      */
ELSE FILENAME = P2                  /* Else, use 2nd arg as filename  */

1  "WTO 'SC.CMD active, session= &SESSNAME filename= &FILENAME'"
"GETSCRN SESSION(&SESSNAME) PREFIX(LINE) SCREEN(NO)"
IF RC \= 0
THEN SAY 'GETSCRN FAILED, RC='RC
ELSE DO
   TITLE = "SCREEN FROM SESSION " SESSNAME
   CALL LINEOUT FILENAME, TITLE
     DO I = 1 TO SCRLEN               /* Loop through each row */
     CALL LINEOUT FILENAME, LINE.I    /* Write line to disk    */
     END
   CALL LINEOUT FILENAME              /* Close the file        */
   END

2  "WTO 'SC.CMD COMPLETE' "
EXIT

The WTO commands in SC.CMD issue write-to-operator messages as the GETSCRN command captures the screen image. The WTO command statement indicated by 1 in the example above alerts the operator when screen processing begins, and the statement indicated by 2 notifies the operator when SC.CMD finishes executing.