ENVIRON command syntax and parameter descriptions

The general syntax for the ENVIRON command is:


>>-ENVIRON--+-------------------+--+---------------------+------>
            |           .-ON--. |  |           .-ON----. |   
            '-ENBLDUMP--+-OFF-+-'  '-TERMTRAC--+-ERROR-+-'   
                                               +-DUMP--+     
                                               '-OFF---'     

>--+---------------------+--+------------------+---------------><
   '-TERMSTAT--+-------+-'  |         .-OFF--. |   
               '-QUERY-'    '-REXCHK--+-ON---+-'   
                                      '-DUMP-'

The parameter descriptions for the ENVIRON command are as follows:

ENBLDUMP

Specifying the ENBLDUMP parameter enables ISPF to produce an abend dump if a subtask abnormally terminates when ISPF is not running in TEST mode. The ENBLDUMP parameter does not apply to attached commands. Before a dump is taken you must allocate either the SYSUDUMP, SYSMDUMP, or SYSABEND ddname. For more information about these data sets, refer to z/OS MVS Diagnosis: Tools and Service Aids.

The default value for the ENBLDUMP parameter is ON. ENVIRON ENBLDUMP ON specifies to ISPF that a dump is to be generated for the subtask that abended.

Issuing ENVIRON ENBLDUMP OFF cancels the effect of the ON status.

The ENBLDUMP parameter value is preserved across ISPF sessions in the ISPSPROF profile.

With ENBLDUMP active, even when ISPF is not running in TEST mode, abnormal termination of a subtask results in a dump being taken and control being returned to TSO. ISPF execution is not resumed.

When running in ISPF TEST mode, issuing ENVIRON ENBLDUMP has no effect on dump processing.

TERMTRAC

Specifying the TERMTRAC parameter allows you to trace all terminal input and output data (TPUT, TGET, PUTLINE) during an ISPF session. The TERMTRAC parameter also allows you to turn on in-core tracing and cause ISPF to produce a SNAP dump if the TPUT or TGET service results in an error. ISPF does not have to be running in TSO TEST mode.

Note: The ENVIRON TERMTRAC buffer does not include:

The TPUT/TGET instructions issued to query the terminal:
- At ISPF initialization
- By the ENVIRON TERMSTAT command
The TPUT instruction issued to clear the screen at ISPF termination
Under certain severe ISPF error conditions, the TPUT instruction issued to display a severe error line message

Before issuing the ENVIRON TERMTRAC DUMP command you must have first issued the ENVIRON TERMTRAC ON or ENVIRON TERMTRAC ERROR command.

Before using the TERMTRAC option, you must define to ISPF the ddname for the data set to be used for the SNAP macro, which ISPF invokes to provide data stream dumps. The ddname can be defined by specifying it on the panel displayed as a result of either issuing the ENVIRON command with no parameters, or selecting the "Environ settings" choice from the Environ pull-down on the ISPF Settings panel. You must follow the data set characteristics guidelines defined by MVS™ for the SNAP macro. See z/OS MVS Programming: Assembler Services Guide for DCB information that can be specified for the SNAP ddname.

The terminal data stream buffer used for ENVIRON TERMTRAC data collection is not reset to zeros.

Subparameters define terminal data tracing as follows:

ENVIRON TERMTRAC ON
Activates TPUT, TGET, and PUTLINE buffer tracing of the terminal data stream. All data is retained in a 24K buffer provided by ISPF. No buffer entry is fragmented. If an entry will not fit into the remaining buffer space, ISPF issues a SNAP to capture the buffer data. The next trace entry is stored at the top of the buffer, regardless of the status of the SNAP execution.

Messages are displayed to the user only for errors during SNAP execution. No messages are displayed during dumps taken as a result of the data buffer filling.

Because ENVIRON TERMTRAC ON causes a SNAP dump to be taken each time the buffer fills, the ddname that you allocate for the SNAP macro should have a disposition of MOD. This assures that no trace data is lost.
The layout of the terminal data buffer for all SNAP dumps is:
```
1 TPUT/TGET/PUTLINE BUFFER TRACE
  2 Header of 8 bytes initialized to
    TERMTRAC
  2 4-byte pointer to where the next entry
    is to be placed
  2 Reserved (20 bytes, for 32-byte boundary
    alignment)
  2 TPUT/TGET/PUTLINE DATA (*)
    3 8-byte TPUT/TGET/PUTLINE identifier
    3 4-byte pointer to previous entry
    3 Information specific to the terminal
      type identifier.
```
The TPUT/TGET identifiers and specific information for each is as follows. Each buffer entry is aligned on a 32-byte boundary.
TGET
Before issuing TGET SVC. 4-byte pointer to previous entry. General purpose registers 0, 1, and 15:
```
   R0  = input data area size
   R1  = input data area pointer
   R15 = TGET option byte
```
TGETR
Return from TGET SVC. 4-byte pointer to previous entry. General purpose registers 1 and 15:
```
   R1  = input data length
   R15 = TGET return code

4-byte length of data stream.
Data stream.
```
TPUT
Before issuing edit TPUT macro. 4-byte pointer to previous entry. General purpose registers 0, 1, and 15:
```
   R0  = output data area
   R1  = output data area pointer
   R15 = TPUT option byte

4-byte length of data stream.
Data stream.
```
TPUTR
Return from edit TPUT macro. 4-byte pointer to previous entry. General purpose register 15:
```
   R15 = TPUT return code
```
TPUTNE
before issuing the noedit TPUT macro. 4-byte pointer to previous entry. General purpose registers 0, 1, and 15:
```
   R1  = address of plist
   R15 = TPUT option byte

16-byte noedit plist:

   Reserved (2 bytes)
   2-byte length of data stream
   Code (1 byte)
   3-byte addr of data stream
   Reserved (8 bytes)

Data stream.
```
TPUTNER
Return from noedit TPUT macro. 4-byte pointer to previous entry. General purpose register 15:
```
   R15 = TPUT return code
```
PUTLINE
Before issuing the PUTLINE macro. 4-byte pointer to previous entry 12-byte PUTLINE parameter block:
```
   Control flags (2 bytes)
   2-byte TPUT options field
   4-byte address of message
   4-byte address of format-only line

125-byte message description:

   2-byte message length
   2-byte message offset
   121-byte message
```
Actions that occur as a result of issuing the ENVIRON TERMTRAC command when ENVIRON TERMTRAC ON is already in effect are listed by command subparameter below:
ON

ENVIRON TERMTRAC ON continues to function normally.

OFF

Tracing is turned off and ISPF issues a SNAP macro. If ENVIRON TERMTRAC tracing is requested again, the next entry is written at the top of the buffer, regardless of whether the prior SNAP was successful.

ERROR

Changes the setting of the command to ENVIRON TERMTRAC ERROR. Tracing continues, with the next buffer entry being written after the last entry written by the ENVIRON TERMTRAC ON setting.

DUMP

The ENVIRON TERMTRAC ON condition continues. In addition, ISPF issues a SNAP macro and, if the SNAP is successful, the next trace entry is written at the top of the buffer. If the SNAP fails, the next entry is written after the last entry before the SNAP.
ENVIRON TERMTRAC ERROR
Initiates tracing of the TPUT, TGET, and PUTLINE buffers. In addition, it causes ISPF to initiate a SNAP dump if a TPUT or TGET error occurs. The dump includes the storage trace buffer, the current TCB, all system control program information, and all problem program information. The SNAP macro definition provides more specific information about the areas dumped when all system control program and problem program information is requested.

ISPF issues the SNAP macro on the first occurrence of a TPUT failure. ISPF makes three consecutive attempts to correct a TPUT error.

Before using this option, you must have defined the ddname for the SNAP macro as described earlier in this topic under TERMTRAC.

Actions that occur as a result of issuing the ENVIRON TERMTRAC command when ENVIRON TERMTRAC ERROR is already in effect are listed by command subparameter below:

ON

Changes the setting of the command to ENVIRON TERMTRAC ON. Tracing continues, with the next buffer entry being written after the last entry written by the ENVIRON TERMTRAC ON setting.

ERROR

ENVIRON TERMTRAC ERROR continues to function normally, with the next trace entry written after the last ERROR trace entry.

OFF

The setting for ENVIRON TERMTRAC is set to OFF. If ENVIRON TERMTRAC tracing is requested again, the next entry is written at the top of the buffer, regardless of whether the prior SNAP was successful.

DUMP

The ENVIRON TERMTRAC ERROR condition continues. In addition, ISPF issues a SNAP macro and, if the SNAP is successful, the next trace entry is written at the top of the buffer. If the SNAP fails, the next entry is written after the last entry before the SNAP.
ENVIRON TERMTRAC DUMP
Causes ISPF to immediately issue a SNAP macro, but only if ENVIRON TERMTRAC ON or ENVIRON TERMTRAC ERROR is active. The resulting dump includes the storage trace buffer, the current TCB, all system control program information, and all problem program information. The SNAP macro definition provides more specific information about the areas dumped when all system control program and problem program information is requested.
Note:
1. This command execution does not turn off terminal data stream tracing if it is active at the time.
2. The next entry is written to the top of the terminal data buffer if the SNAP was successful; otherwise, tracing continues immediately after the last trace buffer entry.
ENVIRON TERMTRAC OFF
Resets active ENVIRON TERMTRAC ON and ENVIRON TERMTRAC ERROR commands. If ENVIRON TERMTRAC is active, ISPF issues a SNAP macro.

The TERMTRAC parameter value is preserved across ISPF sessions in the ISPSPROF profile. The ddname specified for TERMTRAC on the ENVIRON option panel is also saved across sessions.

TERMSTAT

Specifying the TERMSTAT option of the ENVIRON command allows you to collect information about the characteristics of the terminal you are using and the line to which it is attached. The information is returned to your terminal by using line mode, and is written to the ISPF log data set.

The description below of the information returned from an ENVIRON TERMSTAT request is divided into three parts:

A list of terminal characteristics as defined in ISPF variables. In other words, this list defines what ISPF thinks your terminal characteristics are.
A list of terminal characteristics as defined within TSO.
A list of structured fields that apply only to terminals with extended data stream (EDS) capability.

If you issue ENVIRON TERMSTAT (without the QUERY parameter) ISPF unconditionally returns information from lists A and B (below). In addition, if your terminal is connected to a port that supports extended data streams, ISPF returns information from list C (below).

If your terminal is one that supports extended data streams, such as an IBM® 3279, but is connected to a non-EDS port, you can issue ENVIRON TERMSTAT QUERY to force ISPF to return information from list C. Be aware that if you issue ENVIRON TERMSTAT QUERY, and your terminal is not a type that supports extended data streams, such as the IBM 3277, you will receive an ORDER STREAM CHECK error.

Information returned as a result of issuing the ENVIRON TERMSTAT command is as follows:

List A – Terminal Characteristics as Defined Within ISPF

   14-bit terminal addressing mode (ON or OFF)
   16-bit terminal addressing mode (ON or OFF)
   Color mode (ON or OFF)
   Highlighting mode (ON or OFF)
   DBCS mode (ON or OFF)
   Primary screen size (length, width, total bytes)
   Alternate screen size (length, width, total bytes)
   Partition screen size (length, width, total bytes)
   ISPF terminal buffer data (TSB ptr., TSB size,
    TPP addr.)

List B – Terminal Characteristics as Defined Within TSO

   Return code from GTTERM
   Primary screen information (rows, columns)
   Alternate screen information (rows, columns)
   Screen attribute value
   Character set (ASCII or EBCDIC)
   Extended data streams or non-EDS support
   Return code from GTSIZE
   GTSIZE information (rows, columns)
   Access method being used (VTAM*)

List C – Terminals Supporting EDS (structured fields)

   Usable areas
   Partitions
   Character sets
   Color
   Highlighting
   Reply modes
   PC 3270
   Implicit partition
   Input control
   Field rule

ENVIRON TERMSTAT QUERY
The QUERY parameter allows you to request terminal data related to extended data stream capability, even though your terminal is connected to a port that does not support extended data streams.

REXCHK

ENVIRON REXCHK should only be used at the request of IBM service personnel.