Parameters

DISPLAY

Specifies that a display mode is to be set. The valid modes are LOCK, LINE, REFRESH, SAVE, RESTORE, SM, and ALLVALID. LINE mode is in effect until the next display of an ISPF panel. REFRESH occurs on the next display of an ISPF panel.

LOCK

Specifies that the next (and only the next) display output (such as output from the DISPLAY or TBDISPL service) is to leave the terminal user's keyboard locked. ISPF processes the next display output as though the user had pressed the Enter key. It is the dialog developer's responsibility to ensure that the keyboard is unlocked by the subsequent display of a message or panel.

While the keyboard is locked, the screen is not protected from being overlaid by line-mode messages. To ensure that the screen is fully rewritten you must follow the CONTROL DISPLAY LOCK request with a CONTROL DISPLAY LINE request.

CONTROL DISPLAY LOCK can be used to display an "in process" message during a long-running operation.

LINE

Specifies that terminal line-mode output is expected, for example from a TSO command or program dialog. The screen is completely rewritten on the next ISPF full-screen write operation, after the lines have been written.

Note: CONTROL DISPLAY LINE is automatically invoked by the SELECT service whenever a SELECT CMD request is encountered, unless the command begins with a percent (%) sign. For example:

SELECT CMD(ABC) – causes automatic entry into line mode
SELECT CMD(%ABC)– no automatic entry into line mode.

The MODE parameter of the SELECT service can be used to override this use of the percent sign.

line-number

This parameter specifies the line number on the screen where the line-mode output is to begin. (The first line on the screen is line number 1.) The screen is erased from this line to the bottom. If this parameter is omitted or coded as zero, the value defaults to the end of the body of the currently displayed panel.

The line-number parameter must have an integer value. For a call, it must be a fullword fixed binary integer. The parameter should specify a line value that is not within three lines of the bottom of the logical screen. If the value is within three lines of the bottom of the logical screen, a default line value is used. This value is equivalent to the number of the bottom line of the screen, minus 3.

This parameter is meaningful only when entering line mode. It can be specified with the SM keyword, since SM reverts to LINE if the Session Manager is not installed. Once line mode has been set, subsequent attempts to set line mode (without intervening full-screen output) are ignored. Accordingly, the line-number, once set, cannot be changed.

For DBCS terminals, CONTROL DISPLAY LINE always clears the screen and places the cursor on line 1, regardless of the line-number value.

SM

Specifies that the TSO Session Manager is to take control of the screen when the next line-mode output is issued. If the Session Manager is not installed, the SM keyword is treated as LINE.

Note: If you specify the SM keyword when graphics interface mode is active (for example, following a GRINIT service request but before a GRTERM service request has been issued), Session Manager does not get control of the screen. In this case, the SM keyword is treated as LINE.

REFRESH

Specifies that the entire screen image is to be rewritten when the next ISPF-generated full-screen write is issued to the terminal. This facility should be used before or after invoking any program that uses non-ISPF services for generating full-screen output. Be aware that REFRESH does not always result in a return to full-screen mode. To ensure a return to full-screen mode in ISPF, the dialog should issue CONTROL DISPLAY LINE.

SAVE

Used in conjunction with DISPLAY, TBDISPL, BROWSE, EDIT, or VIEW processing to indicate that information about the current logical screen, including control information, is to be saved.

Use of the CONTROL service SAVE and RESTORE parameters allows DISPLAY, TBDISPL, BROWSE, EDIT, or VIEW processing to be nested. The CONTROL service should be used to save and restore the environment at each level. SAVE and RESTORE must be issued in pairs. Issue SAVE following the screen display; issue RESTORE before the next request for the saved panel.

A command entered by the user in the command field of a displayed panel causes the dialog manager to issue a SELECT service request for the dialog to process the command. The current display environment is automatically saved before invoking the designated dialog. That environment is subsequently restored when the dialog ends.

The current DISPLAY environment that existed before the SAVE is not available to a nested processing level.

Table display service system variables, ZTD*, are not saved as part of the SAVE/RESTORE information. The values of these variables may be saved by the dialog developer before invoking another table display and restored before resuming processing of the initial table display. Also, the ZVERB variable is not saved.

RESTORE

Specifies the restoration of information previously saved by CONTROL DISPLAY SAVE. The logical screen image is restored exactly as it appeared when the SAVE was performed. Processing of the previous panel or table display can then be resumed.

ALLVALID

Specifies that ISPF is to consider all displayed code points from X'40' to X'FE' as valid. This specification applies to all subsequent DISPLAY and TBDISPL service requests within the current SELECT level only and remains in effect until the SELECT level ends. It is not propagated to lower SELECT levels.

It is the responsibility of the dialog to ensure that the code points are displayable without a hardware error before issuing this option.

NONDISPL

Specifies that no display output is to be issued to the terminal when processing the next panel definition. This option is in effect only for the next panel; after that, normal display mode is resumed. Initializing the ZCMD variable to a value may cause a panel to display after 'CONTROL NONDISPL' has been issued. This can be circumvented by using the COMMAND option of the DISPLAY service which will cause the panel specified on the DISPLAY service to be processed in CONTROL NONDISPL ENTER mode.

Note: NONDISPL mode stays active until the next panel definition is processed; that is, until the PROC section of a panel display has been completed. Error conditions, such as an error in the panels INIT section, or an action coded in an INIT section, such as .RESP=ENTER, causes panel processing to bypass the panels PROC section, leaving CONTROL NONDISPL active until the PROC section of the next panel is processed.

ENTER

Specifies that the Enter key is to be simulated as the user response to the NONDISPL processing for the next panel.

END

Specifies that the END command is to be simulated as the user response to the NONDISPL processing for the next panel.

NOSETMSG

Specifies that the SETMSG Service message is to be suppressed when the panel on which it was intended to be displayed is suppressed by the CONTROL NONDISPL ENTER Service, but an error when processing the panel causes the panel to be displayed. The NOSETMSG parameter is, in effect, only for the next panel. the NOSETMSG parameter is ignored on the CONTROL NONDISPL END Service.

ERRORS

Specifies that an error mode is to be set. The valid modes are CANCEL and RETURN. If the RETURN mode is set, it applies only to the function that set it using this, the CONTROL, service. The error mode that has been set is not propagated to any new function invoked by the SELECT service.

CANCEL

Specifies that the dialog is to be terminated on an error resulting from a return code of 12 or higher from any service. A message is written to the ISPF log file, and a panel is displayed to describe the particular error situation. In batch mode, messages are written to the SYSTSPRT data set.

RETURN

Specifies that control is to be returned to the dialog on an error. System variables ZERRxxxx, as described in Return codes from services, contain the information for the message that describes the error. The message is not written to the ISPF log file unless TRACE mode is in effect, and no error panel is displayed. If you want the dialog to abend with STAE you must specify CONTROL ERRORS RETURN, because specification of CONTROL ERRORS CANCEL nullifies the requested STAE.

SPLIT

Specifies the user's ability to enter split-screen mode, as defined by the ENABLE or DISABLE keyword.

ENABLE

Specifies that the user is to be allowed to enter split-screen mode. Split-screen mode is normally enabled. It is disabled only if explicitly requested by use of the CONTROL service. It remains disabled until explicitly re-enabled by the CONTROL service. Because SPLIT commands are not supported when ISPF is running in the batch environment, issuing CONTROL SPLIT ENABLE results in a severe error (return code 20).

DISABLE

Specifies that the user's ability to enter split-screen mode is to be disabled, until explicitly enabled by the CONTROL service. If the user is already in split screen mode, a return code of 8 is issued and split-screen mode remains enabled.

NOCMD

Specifies that for the next displayed panel only, any command entered on the command line or through use of a function key is not to be honored. NOCMD is in effect for any redisplay of the panel.

SUBTASK

This option pertains to multi-task program dialogs that are invoked as TSO commands by the CMD interface of the SELECT service.

PROTECT

Specifies that ISPF is to establish an ESTAE routine to trap and ignore the abend that occurs when ISPF tries to POST a subtask that no longer exists.

If an abend does occur on a POST when the ESTAE protection is in effect, ISPF will return to a wait state until another service request occurs or the application terminates.

The new ESTAE will be in effect only around the POST, but once it is requested, it will be established each time ISPF is to POST the application, until the application cancels the protection request or the current SELECT level is terminated.

The scope of the ESTAE protection on the POST is strictly within the current SELECT level. It will not be automatically propagated to another SELECT level but must be requested again if it is to be used.

Any tables or other files that are opened by ISPF on behalf of the detached subtask (for example, by LIBDEF, table services, or file tailoring) will remain open until the application is terminated or the appropriate DM component service is used to close them. Thus, if such a subtask is to be restarted after being detached, it must have the logic to handle the situation when a table, or other file, it tries to open is already opened on entry to that routine.

Although both the parent task and subtask of a dialog can make DM component service calls, ISPF does not support asynchronous service requests. In other words, DM component service calls cannot be made while a service is in process for another caller.

Because the ESTAE protection is provided only on the POST of the DM component service caller, this rule must be followed by the application:

A subtask that can be detached while a DM component service that it invoked is in process cannot use any storage acquired under its TCB in the parameter list of a service call. That is, all parameters used in service calls must reside in storage that will not be released when the DETACH for the subtask is issued. Furthermore, any other resource which can be used by ISPF on behalf of the subtask must not be released while a DM component service is in process.

The parent task should acquire all the storage to be used by the subtask and pass it as a parameter on the ATTACH. Thus, all local variables to be used by the subtask would be declared in a DSECT and be based on the storage acquired by the parent task. This will prevent the possibility of an abend caused by an attempt by ISPF to access storage that was released and will still allow the subtask to use all DM component services.

CLEAR

Specifies that ESTAE protection on the POST of a subtask is to be terminated.

buf-len

Specifies a fullword fixed binary integer containing the length of "buffer".

buffer

Specifies a buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC call for a command procedure.

TSOGUI

QUERY

Gives the current status of the ISPF/TSO window:

Return code = 0: Either the user is not running ISPF GUI with TSO line mode support or TSOGUI is OFF. All TSO input and output is directed to the 3270 session.
Return code = 1: All TSO line mode output is displayed in the ISPF/TSO window and line mode input must be entered into the ISPF/TSO window's input field.

OFF

Specifies that the ISPF/TSO window is suspended and all full screen and line mode data appear in the 3270 window until CONTROL TSOGUI ON is issued.

ON

Specifies that the ISPF/TSO window is to be resumed and all TSO line mode output and input is directed to the ISPF/TSO window.

Note:

CONTROL TSOGUI is ignored if you are not running ISPF GUI with TSO line mode support.
CONTROL TSOGUI defaults to ON during ISPF GUI session initialization.

REFLIST

UPDATE: Enable ISPF allocations to add entries to the data set and library reference lists.
NOUPDATE: Do not allow ISPF allocations to add entries to the data set and library reference lists.

Note:

The CONTROL REFLIST command is used to enable or disable automatic updates to the reference lists. It is intended to be used around calls to ISPF services that normally cause entries in the reference lists. These services include EDIT, BROWSE, VIEW, and LMINIT.
When NOUPDATE is specified, the reference list is not updated, even if the user settings request updates. This is so programs can ensure that they do not fill up the reference list with names that the user would never want to see, such as temporary or intermediate files.
The program invoking the CONTROL REFLIST NOUPDATE command to turn off reference list updates must specify CONTROL REFLIST UPDATE before it exits. It is recommended that you issue a CONTROL REFLIST NOUPDATE immediately before the service that would normally update the reference list (such as LMINIT, EDIT, or BROWSE) and issue a CONTROL REFLIST UPDATE immediately after the service returns.
There is only one CONTROL REFLIST setting for each logical screen (or split screen), and using this command can affect updates in the logical screen after the invoking program ends.

LE

ISPF initialisation for Language Environment® support.

ON: CONTROL LE ON is required before each BRIF or EDIF call where the application has provided Language Environment-enabled command, read, or write routines.
OFF: CONTROL LE OFF is required after each such call.

PASSTHRU

LRSCROLL

PASQUERY

Gives the current status of processing for the LEFT and RIGHT scroll commands:

Return code = 0: The LEFT and RIGHT scroll commands are not being passed to the dialog program.
Return code = 1: The LEFT and RIGHT scroll commands are being passed to the dialog program for processing.

PASOFF

Specifies that the LEFT and RIGHT scroll commands are not to be passed to the dialog program.

PASON

Specifies that the LEFT and RIGHT scroll commands are to be passed to the dialog program for processing.