Previous topic |
Next topic |
Contents |
Contact z/OS |
Library |
PDF
DISPLAY—display panels and messages z/OS ISPF Services Guide SC19-3626-00 |
|
The DISPLAY service retrieves a panel definition, performs any pre-display processing specified on the panel definition, initializes variable panel fields from the corresponding dialog variables, and displays the panel on the screen. A message can optionally be displayed with the panel. If the optional message is to be displayed in a message pop-up window, the position of the message pop-up window can be indicated by the MSGLOC parameter. Note: When running in GUI mode, the MSGLOC parameter is ignored.
After the panel has been displayed, you can enter information and press the Enter key. All input fields are automatically stored into dialog variables of the same name, and the )PROC section of the panel definition is then processed. If any condition occurs that causes a message to be displayed (verification failure, MSG=value condition in a TRANS, or explicit setting of .MSG), processing continues to the )HELP or )END section. The )REINIT section is then processed if it is present. The panel is then redisplayed with the first, or only, message that was encountered. When the user presses the Enter key again, all input fields are stored and the )PROC section is again processed. This sequence continues until the entire )PROC section has been processed without any message conditions being encountered. The panel display service finally returns, with a return code of 0, to the dialog function that invoked it. Alternatively, when a panel is displayed, the user can enter a CANCEL, END, EXIT, or RETURN command. If the input fields are not in a scrollable area, they are stored and the )PROC section is processed. In scrollable areas, only the input fields that have been displayed will be stored. No messages are displayed, even if a MSG condition is encountered. The panel display service then returns to the dialog function with a return code of 8. Command invocation format>>-ISPEXEC--DISPLAY--+-------------------+----------------------> '-PANEL(panel-name)-' >--+-----------------+--+---------------------------+-----------> '-MSG(message-id)-' '-CURSOR(cursor-field-name)-' >--+-------------------------+----------------------------------> '-CSRPOS(cursor-position)-' >--+----------------------------+-------------------------------> '-COMMAND(stack-buffer-name)-' >--+---------------------------+--------------------------------> '-RETBUFFR(ret-buffer-name)-' >--+--------------------------+---------------------------------> '-RETLGTH(ret-length-name)-' >--+----------------------------+------------------------------>< '-MSGLOC(message-field-name)-' Call invocation format>>-CALL--ISPEXEC--(buf-len,--buffer);-------------------------->< or >>-CALL--ISPLINK--('DISPLAYb'--,-+-panel-name-+-----------------> '-'b'--------' >--,-+-message-id-+--,-+-cursor-field-name-+--------------------> '-'b'--------' '-'b'---------------' >--,-+-cursor-position-+--,-+-stack-buffer-name-+---------------> '-'b'-------------' '-'b'---------------' >--,-+-ret-buffer-name-+--,-+-ret-length-name-+-----------------> '-'b'-------------' '-'b'-------------' >--,-+-message-field-name-+------------------------------------>< '-'b'----------------' Parameters
All of the parameters are optional. The panel-name and message-id
parameters are processed as follows:
In the first two situations, processing of the panel definition proceeds normally, through the )INIT section, before display of the panel. If .MSG, .CURSOR, or .CSRPOS is set in the )INIT section, that setting overrides an initial message or cursor placement passed by the calling sequence parameters. In the third and fourth situations, processing of the )INIT section
is bypassed, and there is no automatic initialization of variables
in the panel body, nor in the attribute section. However, the )REINIT
section is processed. The )REINIT section provides for specified variables
or attributes to be reset before a redisplay. Typically, the )REINIT
section contains:
Each time the DISPLAY service is invoked, the )PROC section of the panel is processed after the terminal user enters a response to the display. Therefore, it is recommended that all reinitialization logic be placed in the )REINIT section, rather than at the end of the )PROC section. Using the COMMAND OptionThe COMMAND option allows a dialog to pass a chain of commands in the variable specified by stack-buffer-name to ISPF for execution. The panel specified on the DISPLAY service request is processed in CONTROL NONDISPL ENTER mode. In addition, when ENTER is simulated by ISPF, the command chain is executed as though it were either entered on the command line of the panel by the user or entered through a function key. When the command chain is exhausted or one of the commands cannot be found in the active set of command tables, processing terminates and control returns directly to the dialog that issued the DISPLAY COMMAND call, except for those specific error conditions described further on. If the DISPLAY COMMAND service returns an error, the function pool variable specified by ret-buffer-name contains the unexecuted portion of the command chain, starting with the first command that cannot be found in the active set of command tables. If all commands have been processed, the variable will be blank. The ret-length-name variable contains the length of the string in the ret-buffer-name variable. If all commands have been processed, either by the DISPLAY COMMAND dialog or a dialog invoked to process a command in the stack, the length will be zero. One or more of the commands in the command chain can be processed by the dialogs initiated from previous valid commands in the chain. Processing those commands will be the same as if the command chain had been entered from the primary input field of the dialog's panel. Errors encountered because of these commands must be handled by the dialog. There are two cases in which the panel specified on the original
DISPLAY COMMAND service request is displayed:
Return codesThese return codes are possible:
ExamplesExample 1: Display variables and message, set cursor positionPanel definition XYZ specifies display of variables AAA and KLM
as input fields. Using this definition, invoke services to display
these variables at the terminal and superimpose, on line 1, the short
form text of message number ABCX013. Place the cursor, on the display,
at the beginning of input field KLM, ready for entry of data by the
person at the terminal.
or Set
the program variable BUFFER to contain:
Set
program variable BUFLEN to the length of the variable BUFFER. Enter
the command:
or alternately
Example 2: Unknown command handled by DISPLAYPass a command stack to ISPF to cause:
Issue:
or alternately
Because ISPF cannot find the command CHECK in a command table, processing of the command stack terminates at that point. ISPF places the unprocessed command, CHECK, in variable BUFFA, and sets variable LGTHA to 5. The DISPLAY service terminates with a return code of 4. Example 3: Unknown command handled by dialogPass a command stack to ISPF to cause the:
Issue:
or alternately
ISPF
cannot find the command CHECK in any active command table. Because
the unidentified command error is encountered by the KEYS dialog,
rather than the DISPLAY service, it is the responsibility of the dialog
to process the error. In this case, the KEYS dialog displays a message
indicating that CHECK was not found. Upon return from the KEYS dialog,
the DISPLAY service sets the return buffer, BUFFA, to blanks, sets
variable LGTHA to 0, and terminates with a return code of 0.Example 4: Command stack contains an invalid parameterPass a command stack to ISPF to cause:
Issue:
or alternately
COLOR
is not a valid parameter on the PFSHOW command. Therefore, PANA displays.
In this case, the user exits from PANA normally (ENTER, END, or RETURN).
The DISPLAY service returns control to the dialog with a return code
of 0.Example 5: Display message in a pop-up windowThis DISPLAY request displays message TSTA110 in a message pop-up
window that permits interaction with the underlying panel. The message
pop-up window is positioned relative to the field FLD1.
Using this message definition for TSTA110
Results in:
|
Copyright IBM Corporation 1990, 2014
|