DISPLAY—display panels and messages

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);--------------------------><


>>-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

panel-name

Specifies the name of the panel to be displayed.

message-id

Specifies the identification of a message to be displayed on the panel.

cursor-field-name

Specifies the name of the field where the cursor is to be placed.

If cursor-position is specified both by this parameter and by setting the control variable .CURSOR in the )INIT or )REINIT section of the panel being displayed, the value in .CURSOR overrides this parameter.

cursor-position

Specifies the character position within the field where the cursor is to be placed. This position applies regardless of whether the initial cursor placement was specified in the CURSOR calling sequence parameter, the .CURSOR control variable in the )INIT or )REINIT section of a panel, or is the result of default cursor placement. If cursor-position is not specified or is not within the field, the default is 1.

If cursor-position is specified both by this parameter and by setting the control variable .CSRPOS in the )INIT or )REINIT section of the panel being displayed, the value in .CSRPOS overrides this parameter.

stack-buffer-name

Specifies the name of a variable containing the chain of commands passed by the dialog to ISPF for execution. The maximum length of the actual command chain within this variable is 255.

ret-buffer-name

Specifies the name of a variable in which the unprocessed portion of the command chain is stored should an error occur before the complete chain is processed. This includes the command being processed when the error is detected.

ret-length-name

Specifies the name of a variable in which the length of the unprocessed portion of the command chain is stored should an error occur before the complete chain is processed. This includes the command being processed when the error was detected.

message-field-name

Used to position the message pop-up window. If the application specifies this parameter, the dialog manager positions the message pop-up relative to the named field.

If this parameter is omitted and a message is displayed in a message pop-up window, the window is displayed at the bottom of the logical screen or below the active ADDPOP pop-up window if one exists.

For compatibility with later versions, this parameter should be specified only when the message will display in a pop-up window.

Note: When running in GUI mode, this parameter is ignored.

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.

All of the parameters are optional. The panel-name and message-id parameters are processed as follows:

If panel-name is not specified, an error occurs unless a previous panel was displayed at the same nesting level.
If panel-name is specified and message-id is not specified, the panel is retrieved, the )INIT section, if it exists, is processed, and the panel is displayed without a message.
If panel-name and message-id are both specified, the panel is retrieved, the )INIT section, if it exists, is processed, and the panel is displayed with the specified message, which is typically a prompt or confirmation message.
If panel-name is not specified and message-id is specified, the )REINIT section, if it exists, is processed and the current panel is overlaid with a message, which is typically an error message.
If neither panel-name nor message-ID is specified, the )REINIT section, if it exists, is processed and the current panel is redisplayed without a message. Use the CONTROL service to save and restore the environment when a display series, in which the panel-name is not specified, is to be interrupted by another DISPLAY, TBDISPL, BROWSE, or EDIT operation.
When a panel is displayed before invoking EDIT/VIEW, invoking the DISPLAY service without a panel name from within the EDIT/VIEW service can produce unpredictable results. The DISPLAY environment might be altered by the EDIT/VIEW service. Do not expect the DISPLAY environment that existed before invoking the EDIT/VIEW service to remain unchanged.

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:

Field attribute overrides, specified with the .ATTR control variable.
Changes to displayed panel fields, specified in assignment statements and the REFRESH statement.

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 Option

The 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:

First, when a command error, which results in a message such as "command NOT ACTIVE" or "INVALID command PARM" occurs, the current panel is presented, along with the corresponding message, in normal DISPLAY mode. This occurs even if the current panel is the panel specified on the original DISPLAY COMMAND call. To return to the dialog, the user has to enter the END command or an equivalent.
The second case is when a SPLIT or SPLITV command is executed from the stack as input from the original panel. That panel is displayed on part of the physical screen. Control is not immediately returned to the dialog if execution of the command chain results in SPLIT, SPLITV, or SWAP. In this case the user must re-activate the original screen, such as enter SWAP, to give the dialog control once again.
Note:
1. If the panel displayed with the COMMAND option has its primary input field initialized to a nonblank value, that string will not be concatenated to the end of the command chain.
2. A CONTROL NOCMD pending at the time the DISPLAY COMMAND service is issued will be canceled.
3. ISPF does not support the jump function when the COMMAND option is being executed. ISPF deletes any equal signs (=) preceding a command, but the command remains in the stack.

Return codes

These return codes are possible:

0: Normal completion.
For the COMMAND option, the ret-buffer-name is set to blanks and the ret-length-name is set to zero. Passing an empty command chain buffer also results in a normal completion.
4: One or more commands in the stack could not be found in the active set of command tables.
8: User requested termination using the END or RETURN command. If CANCEL and EXIT are requested from a panel displayed using the DISPLAY service call and the panel was defined with the dialog tag language (DTL), the dialog manager returns the command in ZVERB and sets a return code of 8 from the display screen.
12: The specified panel, message, message location field, or cursor field could not be found.
16: Truncation or translation error in storing defined variables.
20: Severe error.

Examples

Example 1: Display variables and message, set cursor position

Panel 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.

ISPEXEC DISPLAY PANEL(XYZ) MSG(ABCX013) CURSOR(KLM)

or Set the program variable BUFFER to contain:

DISPLAY PANEL(XYZ) MSG(ABCX013) CURSOR(KLM)

Set program variable BUFLEN to the length of the variable BUFFER. Enter the command:

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('DISPLAY ','XYZ ','ABCX013 ','KLM ');

Example 2: Unknown command handled by DISPLAY

Pass a command stack to ISPF to cause:

The display screen to split horizontally at the line on which the cursor was positioned when the DISPLAY COMMAND was issued
Control to return to the top screen (SWAP)
A command, CHECK, to be issued on the top screen (assume CHECK does not exist in the active set of command tables).

Function pool variable STACKA contains the command string:

SPLIT;SWAP;CHECK

Issue:

ISPEXEC DISPLAY PANEL(PANA) COMMAND(STACKA) RETBUFFR(BUFFA) RETLGTH(LGTHA)

or alternately

CALL ISPLINK ('DISPLAY ','PANA ',' ',' ',' ','STACKA ','BUFFA ','LGTHA ');

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 dialog

Pass a command stack to ISPF to cause the:

Function key definition panel, containing the INVALID COMMAND message, to display
Primary input field (PIF) of the panel to be set to CHECK
Alarm to sound.

Function pool variable STACKA contains the command string:

KEYS;CHECK

Issue:

ISPEXEC DISPLAY PANEL(PANA) COMMAND(STACKA) RETBUFFR(BUFFA) RETLGTH(LGTHA)

or alternately

CALL ISPLINK ('DISPLAY ','PANA ',' ',' ',' ','STACKA ','BUFFA ','LGTHA ');

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 parameter

Pass a command stack to ISPF to cause:

PANA, containing the INVALID PFSHOW PARM message, to display
The alarm to sound.

Function pool variable STACKA contains the command:

PFSHOW COLOR

Issue:

ISPEXEC DISPLAY PANEL(PANA) COMMAND(STACKA) RETBUFFR(BUFFA) RETLGTH(LGTHA)

or alternately

CALL ISPLINK ('DISPLAY ','PANA ',' ',' ',' ','STACKA ','BUFFA ','LGTHA ');

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 window

This 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.

PROC 0
ISPEXEC DISPLAY PANEL(A) MSG(TSTA110) MSGLOC(FLD1)

Using this message definition for TSTA110

TSTA110 .WINDOW=NORESP
'ENTER NUMERIC DATA'

Results in:

                 PANEL A



FIELD===> FLD1
         ┌────────────────────┐
         │                    │
         │ ENTER NUMERIC DATA │
         │                    │
         └────────────────────┘