TSO terminal interface
Overview
The TSO (Time Sharing Option) interface causes a TSO terminal to appear to be a Model 204 terminal. The TSO interface program is run as a program in the TSO user region, either as a command processor (CP) or as a called program.
This topic summarizes terminal operation particulars for the TSO interface end user.
Terminals supported
The TSO interface supports the use of:
- IBM 3270 and compatible terminals. MODEL 6 terminals are not currently supported by this interface.
- Teletypes and Teletype-compatible terminals
Each of these terminals provide slightly different capabilities, responses, and default output parameter settings. The information supplied for these terminals in Using SNA Communications Server terminals does not necessarily apply when the terminals are used through TSO.
Host language applications
Most host language application programs that communicate with Model 204 through the host language interface can be run under TSO as called programs. Refer to HLI: Job design factors and to the TSO documentation for information about using host language application programs.
Selection of terminal support mode
Two modes of TSO support are available to Model 204 users of IBM 3270 terminals: full-screen and line-at-a-time. Full-screen terminals allow the entire screen to be formatted and displayed as a single entity whereas line-at-a-time terminals print all screen inputs and outputs on a line-by-line basis.
To select the desired mode for an installation, the system manager must do the following:
- Assemble, link-edit, and install the appropriate TSO programs.
- Set the IODEV parameter on the user's parameter line for the terminal, specifying 11 for full-screen TSO usage and 29 for line-at-a-time TSO usage.
For more information about these system manager actions, see Defining the user environment (CCAIN).
Much of the information in this topic is presented according to terminal IODEV setting. IODEV 11 terminals are full-screen and IODEV 29 terminals are line-at-a-time. For the general features of full-screen and line-at-a-time terminal processing, see Terminal processing.
Using a CLIST
A CLIST can be established by the system manager when TSO line-at-a-time (IODEV 29) and full-screen (IODEV 11) SOUL connections are being used. This allows input to be passed to TSO from the CLIST, rather than from the terminal, as described in CLIST input.
Invoking and disconnecting from the TSO interface
The steps required for logging in to Model 204 through the TSO interface and for disconnecting from the TSO interface are described in this section.
Getting online
To connect to Model 204 by using the TSO system interface, you must first log in to TSO using the procedures defined at the installation. The installation supervisor has the necessary installation-specific information. TSO normally indicates that it is ready to accept input by displaying:
READY
Then, invoke Model 204 by one of the following methods:
- If the TSO interface is installed as a command processor (CP) with the name
M204:- You normally enter the following command for a full-screen connection:
M204FS
Where
M204FSidentifies a CLIST member that contains the single line:CALL 'your.M204.loadlib(M204FS)' 'subsystem:channel_name'
The
M204FSCLIST invokes the Model 204 load module also namedM204FS. - For a line-at-a-time connection, you enter:
M204TTY
Where
M204TTYidentifies a CLIST member that contains the single line:CALL 'your.M204.loadlib(M204TTY)' 'subsystem:channel_name'
Where:
subsystem Specifies an optional one-to-four character subsystem name, plus colon(:), to override the CRAM IGCLM244module's subsystem value. Available for z/OS with CRAM-XDM only.channel_name Specifies an optional 1- to 8-character channel name. In the M204FSCLIST, use the value of CRFSCHNL; in theM204TTYCLIST, use the value of CRIOCHNL.If the subsystem is not specified, the default is the
IGCLM244module's value.If the channel-name is not specified, the default name usually is assumed: for full-screen,
M204FULL; for line-at-a-time,M204PROD. Verify with the system manager whether the channel name is to be specified. - You normally enter the following command for a full-screen connection:
- If the TSO interface is not installed as a CP, invoke Model 204 with the
CALLcommand:- For full-screen connections:
CALL 'library_name(M204FS)' ['[subsystem:]channel_name']
- For line-at-a-time connections:
CALL 'library_name(M204TTY)' ['[subsystem:]channel_name']
Where:
library name Specifies the fully qualified data set name for the load library containing the TSO interface module, and M204FSandM204TTYare the module names or aliases.subsystem Optional, specifies a subsystem name to override the subsystem value in the IGCLM244 module. Available only for z/OS with CRAM-XDM. channel_name Optional, necessary only if the channel name is not the default name. The full-screen default channel name is M204FULL; the line-at-a-time default name isM204PROD. The supervisor can tell you whether the channel name is to be included in theCALL. - For full-screen connections:
The TSO interface establishes a connection to Model 204, locks the terminal to the command processor or called program, and replies:
CONNECTED TO MODEL 204
When the terminal is prepared to accept input, it issues a prompting character and/or unlocks the keyboard (see Input lines). The user can now enter any desired system control commands. If the interface responds with any other message, control returns automatically to TSO.
You can now log in to Model 204. In general, Model 204 regards LOGIN and LOGON as equivalent commands.
CLIST input
Input can be passed to the TSO line-at-a-time or full-screen SOUL interface from a CLIST that has been defined by the system manager. Input can also be passed from a TSO file (in full-screen mode only). This alternate means of input to Model 204 is valid only when the interface is executed as a TSO command processor.
The use of a CLIST or file allows a series of commands to be defined and executed. If the user invokes a CLIST, Model 204 executes all of the commands in the CLIST and then allows additional lines to be entered from the terminal.
To invoke a CLIST or TSO file, use the following command:
{M204FS | M204TTY} ['[subsystem:] channel_name'] [FILE(ddname) | CLIST] [DEBUG]
where:
| M204FS and M204TTY | Identify the Model 204 load modules for the full-screen and line-at-a-time interfaces, respectively. |
| subsystem and channel_name | Identify the CRAM subsystem and channel name, as described in the preceding section. |
| FILE | Specifies that user inputs obtained from a file containing 80-byte records. If a ddname is not specified, then COMMAND is assumed. This file must be allocated to the TSO user region before executing the command.
Note: The FILE option can be used only if the user's terminal is set to full-screen mode ( |
| CLIST | Specifies that user input is obtained from the current CLIST. |
| DEBUG | Specifies that all input and Model 204 output is sent to the terminal, regardless of origin.
Note: The DEBUG option can be used only in full-screen mode ( |
The commands described in the "CLIST commands" table, below, allow the terminal user to:
- Switch between a CLIST or file and the terminal (in full-screen mode only)
- Switch back and forth between a CLIST and the terminal (in line-at-a-time mode only)
- Suppress terminal output (in both full-screen and line-at-a-time modes).
These commands are processed immediately by the TSO interface. Each of the commands can be entered in one of the following ways:
- directly from a terminal, CLIST, or file
- produced as output from Model 204
If one of the commands is entered from a terminal, it is not passed to Model 204. If it is produced by Model 204, it is not sent to the terminal.
| Command | Function |
|---|---|
| /INPUTTERM | Suspends processing of input from a CLIST or file. Subsequent input is expected from the terminal. |
| /INPUTLIST | Resumes processing of the CLIST, reversing the effect of the /INPUTTERM command. If this command is sent as an output line from Model 204 and if TSO was not invoked as a CP (command processor), the TSO user receives the message shown below and the session is ended:
APPLICATION REQUESTED DISCONNECT Note: The |
| /OUTPUTSTOP | Causes output from Model 204 to be discarded, rather than sent to the terminal. |
| /OUTPUTTERM | This command causes output from Model 204 to be sent to the user's terminal, reversing the effect of the /OUTPUTSTOP command. |
| /DISCONNECT | This command causes the session with Model 204 to be terminated as if the Model 204 DISCONNECT command were entered. Control is returned to TSO at the point where the interface was executed, either in a CLIST or at command level. This command is processed by the interface only if the command is received from the following procedure:
BEGIN SCREEN DISCONNECT TITLE '/DISCONNECT' END SCREEN READ SCREEN DISCONNECT END |
Return codes
The interface sets a return code that can be tested by the CLIST. If the interface is invoked by a CLIST, the messages corresponding to error return codes are suppressed. The following return codes are supported:
| Register 15 code | Meaning |
|---|---|
| X'14' | Unable to open command file |
| X'11' | Unsupported terminal type |
| X'10' | Cross-Region Access Method not operative |
| X'0C' | Cross-Region Access Method is busy |
| X'04' | Model 204 has terminated |
Refer to the Rocket Model 204 messages documentation for explanations of these messages.
Input lines
Whenever the terminal is prepared to accept input, it displays a prompt character and/or unlocks the keyboard, depending on terminal type. The following table lists the terminal type and corresponding character/action.
| Terminal | Character | Action |
|---|---|---|
| 3270 | > | Keyboard unlocked |
| Teletype | Keyboard unlocked |
The user enters a line of characters and then signals the end of the line by pressing the Return or Enter key. No data is sent to Model 204 until the Return or Enter key is pressed. You can edit the input line (before it is entered) in one of the following ways:
- Use the TSO input edit conventions defined in the TSO profile.
- Reset the EDIT parameter to 1 or 5 and use the Model 204 input editing conventions.
Backpaging
TSO supports the Model 204 backpaging feature. (For more information about backpaging, see Backpaging). Backpaging is available through TSO only if the system manager sets the NBKPG parameter (number of backpages) parameter to a positive number on User 0's parameter line during system initialization. In addition, the user must have the OUTLPP parameter set to a positive number.
Occasionally a displayed backpage can contain more lines than the original display of the page contained. This can occur when the attention key is used to interrupt output from Model 204. Output lines can be generated by Model 204 during the delay between TSO's receiving the attention interrupt and Model 204's receiving this interrupt from TSO. These lines are ignored by TSO but are stored in the backpage buffer.
Disconnecting
To disconnect from the TSO interface, follow these steps:
- Log out of Model 204 in the normal way by entering:
LOGOUT
or:
LOGOFF
Model 204 acknowledges the command as shown in the preceding sections. - To close the TSO connection to Model 204, enter:
DISCONNECT
or:
DISC
The interface then releases the connection and returns control to TSO.
If the interface detects that Model 204 has terminated while a connection is active, the following message is issued, and control returns to TSO:
MODEL 204 HAS TERMINATED EXECUTION
IBM 3270 terminals (IODEV = 11)
This section summarizes the information needed to use IBM 3270s (and compatible terminals) operating under TSO in full-screen mode.
Input lines
TSO users can utilize the full-screen input features described in Full-screen formatting. These features allow the entire screen to be formatted and displayed as a single entity. The user usually responds to prompts that are displayed on the screen. When the entire screen has been filled in, the user presses the Enter key, and the data is transmitted from the terminal to Model 204 for processing.
Program Function (PF) keys are supported by Model 204 only when the user accesses a screen formatted through the SOUL full-screen formatting feature. Otherwise, PF keys are not supported and cannot be used to enter data. Any line entered by means of a PF key is considered null, and any data entered is lost.
Attention key
The PA1 key serves as the attention key on IBM 3270 terminals, unless the attention key has been reassigned by the user through the FSATTN parameter.
Screen-formatting parameters
The screen-formatting parameters listed in the following table apply to IBM 3270 terminals being used through TSO.
The PGSEP parameter is not listed because it is not used with IBM 3270 terminals.
| Parameter | Meaning |
|---|---|
| INMRL | Maximum input line length for terminal |
| INCCC | Input continuation column |
| LOUTPB | Length of output page buffer |
| OUTMRL | Maximum output line length for terminal |
| OUTCCC | Output continuation column |
| OUTLPP | Number of lines per page, including headers and trailers |
| MODEL | Array of screen size parameters for the particular 3270 model |
| HDRCTL | Page formatting options |
The values of the first five parameters, which determine the size of the screen, are actually established by the value of MODEL, which corresponds to the terminal model within the 3270 family. Model 204 automatically sets MODEL to the appropriate value for SNA Communications Server (formerly VTAM) 3270s used through TSO, but the user also can reset it.
Terminal model options
The following table shows the valid settings for MODEL, the corresponding terminal types, and the corresponding default values for the screen size parameters. You can reset INCCC and OUTCCC to override the default values established by the MODEL parameter.
| MODEL | INMRL | INCCC | OUTMRL | OUTCCC | 3270 terminal type |
|---|---|---|---|---|---|
| 1 | 78 | 78 | 80 | 80 | Model 1 |
| 2 | 78 | 78 | 80 | 80 | Model 2 |
| 3 | 78 | 78 | 80 | 80 | Model 3 |
| 4 | 78 | 78 | 80 | 80 | Model 4 |
| 5 | 130 | 130 | 132 | 132 | Model 5 |
Output page buffer settings
Note that MODEL is reset only if the size of the output page buffer (LOUTPB) is large enough to hold the new screen size.
The minimum LOUTPB settings are listed in the following table.
| MODEL | LOUTPB |
|---|---|
| 0 | 1170 |
| 1 | 1170 |
| 2 | 2130 |
| 3 | 2770 |
| 4 | 3650 |
| 5 | 3774 |
Page header formats
HDRCTL consists of a series of switches that control the formatting of pages transmitted to the terminal. Each switch can be set independently of the others.
HDRCTL is usually not reset, but it can be reset to the following values for 3270 terminals:
| 0 | Normal headers (system header showing date, time, and page number) |
|---|---|
| 1 | Suppress header 0 (system header showing date, time, and page number) |
| 2 | Suppress the blank line that normally follows header 0 for nonrequest output |
Pausing and canceling output
At the end of each page of output, Model 204 pauses to allow the user to read the contents of the screen and to cancel the current request if too much output is being received. A prompting greater than sign (>) is displayed, indented 25 spaces on the last line of the screen.
Valid user responses are:
- Press Enter. The terminal goes on to the next page.
- Press the attention key or enter *CANCEL, C (cancel), or K (kill), followed by Enter. Unless an ON ATTENTION statement is in effect (see Attention interrupt feature), the current output and request are cancelled.
- Enter a backpage request (see Backpaging).
- Enter the next input line, which cannot exceed 53 characters. As the user enters input, the cursor moves in order to indicate the number of spaces used.
As discussed in the section Pausing, enter only one line of anticipatory input at this time. If the terminal reaches the end-of-page pause for the next page of output, the saved input line is lost.
Canceling the current request
The user can cancel the evaluation of the current SOUL request in one of the following ways:
- If the terminal is waiting for input, press the attention key.
- If Model 204 is waiting for input from the terminal or is actively displaying output on the terminal, press the attention key.
Note: If Model 204 is compiling or executing a command, the user cannot cancel the operation by pressing the attention key.
IBM 3270 terminals (IODEV = 29)
This section summarizes the information needed to use IBM 3270s (and compatible terminals) operating under TSO in line-at-a-time mode.
PA1 key
The PA1 key can be used to cancel either a single line or multiple lines of output. It cannot be used to terminate the TSO interface and return to TSO.
Output parameters
As soon as the Model 204 connection is made, the TSO interface sets the parameters shown in the following table to the default values shown.
| Parameter | Meaning | Default |
|---|---|---|
| OUTMRL | Maximum output line length for terminal | 80 |
| OUTCCC | Output continuation column | 80 |
| OUTLPP | Number of lines per page, including headers and trailers | 60 |
Pausing and canceling output
On the 3270, the TSO interface does not ordinarily pause at the bottom of the screen to allow the user to interrupt Model 204 or to cancel the current request if too much output is being received.
The user can cause TSO to pause by specifying a page size in the OUTLPP parameter. If OUTLPP = 23, the interface pauses after 23 lines have been displayed and allows the final line (line 24) on the screen to be used for a backpage request. The TSO interface indicates that it is in pause mode by pausing and unlocking the keyboard.
Valid user responses are:
- Press the attention key. The current request or operation is canceled and Model 204 is then ready to accept terminal input from the user.
- Press Enter. The interface goes on to the next page.
- Specify a backpage to be displayed, as described in Backpaging.
If too much output is being received, press the PA1 key at any time. It cancels all output and aborts the currently running request.
Teletypes (IODEV = 29)
This section summarizes the information needed to use Teletypes and compatible terminals operating under TSO.
Output parameters
As soon as the Model 204 connection is made, certain output conventions are established for Teletypes and compatible terminals.
The TSO interface sets the parameters shown in the following table to the default values shown.
| Parameter | Meaning | Default |
|---|---|---|
| OUTMRL | Maximum output line length for terminal | 80 |
| OUTCCC | Output continuation column | 80 |
| OUTLPP | Number of lines per page, including headers and trailers | 60 |
Pausing and canceling output
At the end of each page of output, the TSO interface pauses to allow the user to interrupt Model 204 or to cancel the current request if too much output is being received. The TSO interface indicates that it is in pause mode by ringing the teletype bell twice.
Valid user responses are:
- Press the attention key. The current request or operation is canceled and Model 204 is ready to accept any terminal input from the user.
- Enter a carriage return or any other character. The interface goes on to the next page.
- Specify a backpage to be displayed, as described in Backpaging.
Because the pause and cancel capability is activated at the end of a page, be sure not to set the OUTLPP (number of lines per page) parameter to zero, unless you want suppressed pausing and production of a header on the new page. If OUTLPP = 0, there is no logical end-of-page, and the interface never executes the pause.
If you find that you are receiving too much output, you can press the attention (BREAK) key at any time. This is equivalent to entering C or K. It cancels all output and aborts the currently running request. BREAK can be used to cancel either a single line or multiple lines of output. It cannot be used to terminate the TSO interface and return to TSO.