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 chapter 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 chapter 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 M204FS identifies a CLIST member that contains the single line:

    CALL 'your.M204.loadlib(M204FS)' 'subsystem:channel_name'

  • For a line-at-a-time connection, you enter:

    M204TTY

    Where M204TTY identifies 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 IGCLM244 subsystem value. Available for z/OS with CRAM-XDM only.
  channel_name	Specifies an optional 1- to 8-character channel name. In the M204FS CLIST, use the value of CRFSCHNL; in the M204TTY CLIST, use the value of CRIOCHNL.

  If the subsystem is not specified, the default is the IGCLM244 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.

• If the TSO interface is not installed as a CP, invoke Model 204 with the CALL command:
  • 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 M204 is the module name or alias.
  subsystem	Optional, specifies a subsystem name to override the subsystem value in IGCLM244. 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 is M204PROD. The supervisor can tell you whether the channel name is to be included in the CALL.

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. See the Rocket Model 204 messages documentation for a detailed description of TSO: messages.

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:

Syntax

{M204FS | M204TTY} ['[subsystem:]channel_name'] [FILE(ddname) | CLIST] [DEBUG]

where:

CLIST	Specifies that user input is obtained from the current CLIST.
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 (IODEV = 11). It cannot be used in line-at-a-time mode (IODEV = 29).
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 (IODEV = 11).

The commands described in the CLIST commands table 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.

CLIST commands

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 /INPUTLIST command can be used only if the user's terminal is set to line-at-a-time mode (IODEV = 29). It cannot be used in full-screen mode (IODEV = 11).
/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 input prompts and 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:

1. 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.
2. 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.

Screen-formatting parameters for TSO interface

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.

Valid MODEL settings for TSO interface

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.

Minimum LOUTPB settings

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.

TSO interface output parameters for 3270s

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.

TSO interface output parameters for teletypes

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.