REXX Variables

This chapter documents special variables defined by CA Verify for CICS to provide information to a REXX exec.

CA Verify for CICS REXX Variables

CA Verify for CICS commands return specific information to execs in CA Verify for CICS defined REXX variables.

All CA Verify for CICS defined REXX variable names begin with the characters PTE. Execs that use CA Verify for CICS commands for REXX should not create REXX variables that begin with PTE. Observing this convention ensures that there will be no conflict between user defined variables and current or future CA Verify for CICS defined variables.
PTEPORT, PTEAPORT, PTEPORTS, PTEINFO and PTEMESS are used to return unique information and are always returned using the defined simple variable names.
All other CA Verify for CICS defined variables are session variables, used by session commands to return information about a session on a CA Verify for CICS port accessed by an exec. If an exec accesses sessions on more than one port, session information is not unique. Session information is returned to an exec using either simple or compound session variable names that are unique for each session accessed by an exec.
All variable names defined below are simple variable names. Session commands return information using simple session variable names by default or when an exec accesses the session on the exec's port by issuing an ACCESS command that instructs session commands to return information using simple session variable names.
Compound session variable names have a REXX stem that is a defined simple session variable name and a tail that is a session's port number. For example, PTEBUFF.2 is a compound session variable name that may be used by session commands to return the session information defined for PTEBUFF when an exec accesses the session on port 2. Session commands return information using compound session variable names when an exec accesses a session on any port, including the session on the exec's port, by issuing an ACCESS command that instructs session commands to return information using compound session variable names.
Session commands return session variables if a session is active on the accessed port at the completion of the session command. Session commands drop all session variables except PTERSENS if a session is not active on the accessed port at the completion of the command. The value of a dropped variable symbol is the value of the symbol itself.

PTEALARM

When a message is received from an online system, PTEALARM is set to YES if the message sounded the terminal alarm, or is set to NO if the message did not sound the terminal alarm.

PTEAPORT

Every ACCESS command sets PTEAPORT to the number of the port being accessed by the exec. ACCESS EXECPORT or ACCESS * accesses the port on which an exec is executing. ACCESS NEWPORT or an ACCESS command that specifies no operands assigns and accesses a previously unused port. ACCESS FREEPORT accesses a port that may have been previously used, but is not currently being used, or accesses a previously unused port. An ACCESS command may specify the number of the port to be accessed.

PTEASIZ

When a session is started, PTEASIZ is set to one of the values 24X80, 32X80, 43X80or 27X132, and indicates the alternate screen size established for the session.

PTEBUFF

PTEBUFF is a copy of the virtual terminal display buffer used for a CA Verify for CICS session. The size of the buffer, in rows and columns, is indicated by the session variables PTEROWS and PTECOLS. Screen rows are arranged serially in PTEBUFF, so that when PTECOLS is 80, screen row 2 begins at position 81 in PTEBUFF.

The format of the data and attributes stored in PTEBUFF may be specified by a QUERY SESSION command. In any other case, the format of PTEBUFF is determined by the BASICDATA, EXTDSDATA, PANELDATA, IMAGEDATA or ATTRIBUTES options specified by the LOGON command that started the session.

PTECC

A chain is a complete message sent from or to a terminal. PTECC is a count of the outbound chains received at a virtual terminal during the execution of the previous CA Verify for CICS session command. PTECC is set to 0 (zero) if no message is received during the execution of an INVITE or DELAY command.

PTECOL

A virtual terminal cursor works like a real terminal cursor. An online system may send orders that move the cursor to any display position. The TYPE command moves the cursor while keying data into a virtual terminal display, when tab or other keys are used, and moves the cursor to any specified display position. At the completion of any CA Verify for CICS session command, PTEROW and PTECOL identify the current cursor row and column in the virtual terminal display buffer.

PTECOLS

PTECOLS contains the current number of virtual terminal screen columns. The possible values of PTECOLS are fixed when default and alternate screen sizes are established during session initiation. The current value of PTECOLS at any point in time is controlled by the online system using 3270 ERASE-WRITE or ERASE-WRITE-ALTERNATE commands.

PTECSRP

During the execution of a TYPE command, the cursor is advanced as data is keyed into a virtual terminal screen. When an online system sends a terminal message, the message may reposition the cursor. Whenever the cursor is repositioned, PTECSRP is set to the position of the cursor within PTEBUFF. When the cursor is at row 1, column 1, PTECSRP is 1. When the cursor is at row 2, column 1 of an 80-column screen, PTECSRP is 81.

PTEDSIZ

When a session is started, PTEDSIZ is set to one of the values 24X80, 32X80, 43X80or 27X132, and indicates the default screen size established for the session.

PTEEAB

PTEEAB is an image of a virtual terminal Extended Attribute Buffer used to store 3270 extended attribute data that correspond to the field attributes and data stored in PTEBUFF. Refer to 3270 Attribute Values for a description of the data contained in an extended attribute buffer.

When session variables are returned by a QUERY SESSION command, PTEEAB is returned if EXTDSDATA is specified, and is not returned if BASICDATA, PANELDATA or IMAGEDATA are specified. In any other case, when session variables are returned by a session command, PTEEAB is returned if the LOGON command that started the session specified EXTDSDATA or if the LOGON command started an EXTDS session and did not specify BASICDATA, PANELDATA or IMAGEDATA.

PTEINFO

If the QUERY command determines that a named CA Verify for CICS resource is active, the resource name is returned in PTEINFO. If the QUERY command determines that a named CA Verify for CICS resource is not active, the concatenation of NO and the resource name is returned in PTEINFO. For example, if the command QUERY SESSIONS finds a session active on any CA Verify for CICS port, SESSIONS is returned in PTEINFO, otherwise, NOSESSIONS is returned in PTEINFO.

PTEKB

PTEKB is the state of a virtual terminal keyboard and is one of the following values:

BUSY means that data has been typed but not entered and that additional data may be typed.
FREE means that data may be typed, but no data has been typed since the keyboard was freed.
INHIBITED means that a session is timed out, outbound or in another state that does not permit data to be typed, but a TYPE ATTN command is permitted.
LOCKED means that a session has timed out in a state that does not permit the use of the TYPE statement.
Note: Keyboard state names that have lower alphabetic values are "more free" and names with higher values are locked tighter. Data may be typed when PTEKB is LE "FREE", but may not be typed when PTEKB is GE "INHIBITED".

PTELUDS

When a session is started, PTELUDS is set to one of the values BASICDS or EXTDS, and indicates the 3270 data stream level supported by the virtual terminal used for the session.

PTEMESS

An error or information message may be stored in PTEMESS during the execution of any CA Verify for CICS command. Selected messages are sent to the terminal or to another message destination automatically, if a MONITOR command has been issued that specified SIGNALS, CONDITIONS or the PTEMESS variable name.

PTEPLU

When a session is started with any Primary Logical Unit (PLU), the network name of the online system is stored in PTEPLU. While most sessions are started by the LOGON command, sessions may also be started while executing any session command, if an online system passes the PLU end of a session to another PLU. All session commands store the name of the current PLU in PTEPLU if a session is passed to another PLU.

PTEPORT

All ACCESS commands store the number of the port on which an exec is executing in PTEPORT.

PTEPORTS

A QUERY command may specify one of the keywords, SESSIONS, TRACES, TASKS or QUEUES, to obtain a list of the ports on which the named CA Verify for CICS resource exists. For example, an exec may issue a QUERY SESSIONS command to set PTEPORTS to a list of port numbers on which CA Verify for CICS sessions are active. If sessions are active on ports 3, 4, and 7, the value 3 4 7 is stored in PTEPORTS.

PTEROW

PTEROWS

PTEROWS is the current number of virtual terminal screen rows. The possible values of PTEROWS are fixed when default and alternate screen sizes are established during session initiation. The current value of PTEROWS at any point in time is controlled by the online system using 3270 ERASE-WRITE and ERASE-WRITE-ALTERNATE commands.

PTERSENS

If VTAM is unable to start a session requested by a LOGON command, or if an active session fails, or if data sent to an online system is rejected during the execution of a CA Verify for CICS session command, the eight character sense code received from VTAM or the online system is stored in PTERSENS. Sense codes are defined by SNA and indicate the cause of a session failure or other negative response. If a LOGON fails, or a session fails unexpectedly, an exec may analyze the contents of PTERSENS to determine the cause. For example, 08570002 means the PLU is not active and 087D0001 indicates a session services path error, possibly resulting from an attempt to start a session with an undefined PLU. Unlike other session variables, PTERSENS is not dropped at the end of a session. General information on sense codes can be found in SNA Sense Codes.

PTERTIME

When a message is received from an online system, response time is calculated by subtracting the time of the previous terminal input from the time the message is received, and the calculated response time, expressed in hundredths of a second, is stored in PTERTIME.

PTESENSE

When CA Verify for CICS sends a negative response to a message received from an online system, the four-character SNA sense code sent with the negative response is stored in PTESENSE. The sense code indicates the reason that the online system request was rejected. If a negative response is not sent during the execution of a CA Verify for CICS session command, the value '0000' is stored in PTESENSE. General information on sense codes can be found in SNA Sense Codes.

PTESIZE

When a CA Verify for CICS session is started or when a 3270 ERASE-WRITE command is received from an online system, the default screen size, calculated as the default screen size rows times the default screen size columns, is stored in PTESIZE. When a 3270 ERASE-WRITE-ALTERNATE command is received, the alternate screen size is calculated as the alternate screen size rows times the alternate screen size columns, is stored in PTESIZE.

PTESLU

When a session is started by a LOGON command, the name of the VTAM APPL used as a CA Verify for CICS virtual terminal is stored in PTESLU. SLU is an acronym for Secondary Logical Unit. The name is either a name supplied by the exec, or is an assigned name, if a name was not supplied by the exec.

PTESTATE

PTESTATE is a name that describes the state of a CA Verify for CICS session. PTESTATE may be any state name described in CA Verify for CICS Logical Unit States, except OFFLINE. When a session ends, instead of storing the value OFFLINE, PTESTATE is dropped.

PTETTIME

When a TYPE command is used to send terminal input to an online system, think time is calculated by subtracting the time at which the previous message was received from the online system from the time of the terminal input, and the calculated think time, expressed in hundredths of a second, is stored in PTETTIME.