ISPF Dialog Manager Services: Programmatic Panel Invocation

The ISPF Dialog Manager is the core component that handles panel invocation, display, and navigation. Dialog Manager services enable programs to invoke panels programmatically, display interactive dialogs, collect user input, and control panel navigation. Understanding Dialog Manager services is essential for building interactive ISPF applications with REXX, CLIST, and other programming languages. This tutorial covers Dialog Manager architecture, panel invocation mechanisms, SELECT_PANEL and DISPLAY_PANEL services, panel navigation, and building interactive applications.

Dialog Manager services provide the interface between your programs and ISPF panels. When you call DISPLAY PANEL from REXX, the Dialog Manager locates the panel, displays it, processes user input, and returns control to your program. Learning to use Dialog Manager services enables you to create sophisticated interactive applications that leverage ISPF's panel-driven interface. This tutorial provides comprehensive guidance for using Dialog Manager services programmatically.

Understanding the Dialog Manager

The Dialog Manager is ISPF's component responsible for panel management and invocation.

What is the Dialog Manager?

The Dialog Manager:

• Handles panel invocation and display
• Manages panel library resolution
• Processes panel variables
• Controls panel navigation
• Provides services for programmatic access

Dialog Manager Architecture

The Dialog Manager architecture includes:

• Panel library management - locates panels in libraries
• Panel display engine - renders panels on screen
• Variable processing - handles panel variables
• Navigation control - manages panel flow
• Service interface - provides programmatic access

The Dialog Manager sits between your programs and ISPF panels, translating service calls into panel operations.

Panel Library Resolution

The Dialog Manager locates panels by searching the panel library concatenation:

• Searches libraries in concatenation order
• Finds panel member matching panel name
• Uses first match found
• Returns error if panel not found

Panel libraries are specified in ISPF settings or via LMINIT/LMOPEN services. The Dialog Manager automatically searches these libraries when you invoke a panel.

Panel Invocation Mechanisms

Panels can be invoked through several mechanisms.

Direct Panel Invocation

Direct invocation uses DISPLAY PANEL service:

1
2
3
4
5
6
7
8
9
10
11
12
/*REXX*/
address ispexec
'DISPLAY PANEL(MYPANEL)'
if rc = 0 then do
  /* User pressed Enter */
  say 'User entered data'
end
else do
  /* User pressed PF3 or other exit */
  say 'User cancelled'
end
exit 0

This example:

• Uses ADDRESS ISPEXEC to direct commands to ISPF
• Calls DISPLAY PANEL with panel name MYPANEL
• Checks return code to determine user action
• Processes based on how user exited panel

Panel with Variables

Panels can pass variables to and from your program:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/*REXX*/
address ispexec
/* Set input variables */
username = 'JOHN'
'VPUT (USERNAME) PROFILE'
/* Display panel */
'DISPLAY PANEL(USERINPUT)'
if rc = 0 then do
  /* Get output variables */
  'VGET (USERNAME RESULT) PROFILE'
  say 'Username:' username
  say 'Result:' result
end
exit 0

This example:

• Sets USERNAME variable using VPUT
• Displays panel that uses USERNAME
• Retrieves variables after panel returns
• Processes user input from panel

Conditional Panel Invocation

You can conditionally invoke panels based on logic:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/*REXX*/
parse arg action
address ispexec
select
  when action = 'ADD' then
    'DISPLAY PANEL(ADDRECORD)'
  when action = 'EDIT' then
    'DISPLAY PANEL(EDITRECORD)'
  when action = 'DELETE' then
    'DISPLAY PANEL(DELRECORD)'
  otherwise
    'DISPLAY PANEL(MAINMENU)'
end
exit 0

This example shows how to invoke different panels based on application logic, enabling dynamic panel navigation.

SELECT_PANEL Service

SELECT_PANEL selects or switches panel context without displaying.

What is SELECT_PANEL?

SELECT_PANEL:

• Selects a panel without displaying it
• Changes active panel context
• Prepares panel for later use
• Useful for panel navigation setup

Using SELECT_PANEL

SELECT_PANEL usage:

1
2
3
4
5
6
7
8
9
10
/*REXX*/
address ispexec
/* Select panel context */
'SELECT PGM(ISR@PRIM)'
if rc <> 0 then do
  say 'Error selecting panel'
  exit 8
end
/* Panel context is now set */
exit 0

SELECT_PANEL is less commonly used than DISPLAY_PANEL, but is useful when you need to change panel context programmatically without immediate display.

SELECT_PANEL vs DISPLAY_PANEL

Key differences:

• SELECT_PANEL - selects context, no display
• DISPLAY_PANEL - displays panel immediately
• SELECT_PANEL - prepares for later use
• DISPLAY_PANEL - interactive user session

Most applications use DISPLAY_PANEL for interactive panels, while SELECT_PANEL is used for special navigation scenarios.

DISPLAY_PANEL Service

DISPLAY_PANEL is the primary service for displaying panels programmatically.

DISPLAY_PANEL Function

DISPLAY_PANEL:

• Locates panel in panel library
• Displays panel on screen
• Collects user input
• Processes panel variables
• Returns when user exits
• Returns code indicating exit method

Basic DISPLAY_PANEL

Basic usage:

1
2
3
4
5
6
7
8
9
10
11
12
13
/*REXX*/
address ispexec
'DISPLAY PANEL(MYINPUT)'
if rc = 0 then do
  say 'User pressed Enter'
end
else if rc = 8 then do
  say 'User pressed PF3 (End)'
end
else do
  say 'User pressed other key, RC=' rc
end
exit 0

Return codes indicate how the user exited:

• RC = 0 - User pressed Enter
• RC = 8 - User pressed PF3 (End)
• RC = 12 - User pressed PF12 (Cancel)
• Other codes - Other function keys or errors

DISPLAY_PANEL with Options

DISPLAY_PANEL supports various options:

1
2
3
4
5
6
7
8
9
/*REXX*/
address ispexec
/* Display with cursor positioning */
'DISPLAY PANEL(MYINPUT) CURSOR(USERNAME)'
/* Display with message */
'DISPLAY PANEL(MYINPUT) MSG(ISRZ001)'
/* Display with shared variables */
'DISPLAY PANEL(MYINPUT) SHARED'
exit 0

Options include:

• CURSOR - positions cursor on specific field
• MSG - displays message on panel
• SHARED - uses shared variable pool
• Other options for panel control

Panel Variable Processing

DISPLAY_PANEL processes panel variables:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
/*REXX*/
address ispexec
/* Set variables before display */
username = 'JOHN'
password = ''
'VPUT (USERNAME PASSWORD) PROFILE'
/* Display panel */
'DISPLAY PANEL(LOGIN)'
if rc = 0 then do
  /* Get variables after display */
  'VGET (USERNAME PASSWORD) PROFILE'
  /* Process login */
  if password <> '' then do
    say 'Login successful for' username
  end
  else do
    say 'Password required'
  end
end
exit 0

Variables flow between your program and the panel, enabling data exchange.

Panel Navigation

Dialog Manager services enable sophisticated panel navigation.

Sequential Panel Flow

You can chain panels sequentially:

1
2
3
4
5
6
7
8
9
10
11
12
/*REXX*/
address ispexec
/* Step 1: Get user information */
'DISPLAY PANEL(STEP1)'
if rc <> 0 then exit 8
'VGET (NAME EMAIL) PROFILE'
/* Step 2: Confirm information */
'DISPLAY PANEL(STEP2)'
if rc <> 0 then exit 8
/* Step 3: Process */
'DISPLAY PANEL(STEP3)'
exit 0

This creates a multi-step wizard flow where each panel collects part of the information.

Conditional Navigation

Navigation can be conditional based on user input:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/*REXX*/
address ispexec
/* Main menu */
'DISPLAY PANEL(MAINMENU)'
if rc <> 0 then exit 8
'VGET (OPTION) PROFILE'
/* Navigate based on option */
select
  when option = '1' then do
    'DISPLAY PANEL(OPTION1)'
  end
  when option = '2' then do
    'DISPLAY PANEL(OPTION2)'
  end
  when option = '3' then do
    'DISPLAY PANEL(OPTION3)'
  end
  otherwise
    say 'Invalid option'
end
exit 0

This enables menu-driven navigation where user choices determine which panel displays next.

Error Handling and Retry

You can implement retry logic for error handling:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/*REXX*/
address ispexec
retry = 'YES'
do while retry = 'YES'
  'DISPLAY PANEL(USERINPUT)'
  if rc <> 0 then exit 8
  'VGET (INPUTDATA RETRY) PROFILE'
  /* Validate input */
  if inputdata = '' then do
    'SETMSG MSG(ISRZ002)'
    retry = 'YES'
  end
  else do
    retry = 'NO'
  end
end
exit 0

This allows panels to be redisplayed with error messages until valid input is provided.

Building Interactive Applications

Dialog Manager services enable building complete interactive applications.

Application Structure

A typical interactive application structure:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
/*REXX*/
address ispexec
/* Initialize */
'CONTROL ERRORS RETURN'
/* Main loop */
do forever
  'DISPLAY PANEL(MAINMENU)'
  if rc <> 0 then leave
  'VGET (OPTION) PROFILE'
  /* Process option */
  select
    when option = '1' then
      call process_option1
    when option = '2' then
      call process_option2
    when option = 'X' then
      leave
    otherwise
      'SETMSG MSG(ISRZ001)'
  end
end
exit 0
 
process_option1:
  'DISPLAY PANEL(OPT1PANEL)'
  return
 
process_option2:
  'DISPLAY PANEL(OPT2PANEL)'
  return

This structure provides a main menu loop with option processing and subroutines for different functions.

Data Validation

Validate user input before processing:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/*REXX*/
address ispexec
valid = 'NO'
do while valid = 'NO'
  'DISPLAY PANEL(DATAENTRY)'
  if rc <> 0 then exit 8
  'VGET (USERDATA) PROFILE'
  /* Validate */
  if userdata = '' then do
    'SETMSG MSG(ISRZ002)'
    valid = 'NO'
  end
  else if length(userdata) < 5 then do
    'SETMSG MSG(ISRZ003)'
    valid = 'NO'
  end
  else do
    valid = 'YES'
  end
end
/* Process valid data */
say 'Processing:' userdata
exit 0

This ensures data quality before processing, improving application reliability.

Error Messages

Display appropriate error messages:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/*REXX*/
address ispexec
'DISPLAY PANEL(MYINPUT)'
if rc = 0 then do
  'VGET (INPUTDATA) PROFILE'
  /* Validate and set messages */
  if inputdata = '' then
    'SETMSG MSG(ISRZ002)'  /* Required field */
  else if verify(inputdata, '0123456789') > 0 then
    'SETMSG MSG(ISRZ004)'  /* Numeric only */
  else
    say 'Valid input:' inputdata
end
exit 0

Error messages guide users to correct input, improving user experience.

Panel Library Management

Dialog Manager locates panels through panel library management.

Panel Library Concatenation

Panel libraries are searched in concatenation order:

• User panel libraries first
• Application panel libraries
• System panel libraries last
• First match is used

Specifying Panel Libraries

You can specify panel libraries programmatically:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/*REXX*/
address ispexec
/* Initialize library access */
'LMINIT DATASETID(id) DATASET(MY.PANEL.LIB)'
if rc <> 0 then do
  say 'Error initializing library'
  exit 8
end
/* Open library */
'LMOPEN DATASETID(id) OPTION(INPUT)'
/* Display panel from library */
'DISPLAY PANEL(MYPANEL)'
/* Cleanup */
'LMCLOSE DATASETID(id)'
'LMFREE DATASETID(id)'
exit 0

This allows your application to use custom panel libraries.

Return Codes and Error Handling

Understanding return codes is essential for proper error handling.

Common Return Codes

Common DISPLAY_PANEL return codes:

• RC = 0 - User pressed Enter (normal completion)
• RC = 4 - Warning condition
• RC = 8 - User pressed PF3 (End)
• RC = 12 - User pressed PF12 (Cancel)
• RC = 16 - Panel not found
• RC = 20 - Other error

Error Handling Pattern

Standard error handling pattern:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/*REXX*/
address ispexec
'CONTROL ERRORS RETURN'
'DISPLAY PANEL(MYPANEL)'
select
  when rc = 0 then do
    /* Normal completion */
    'VGET (USERDATA) PROFILE'
    /* Process data */
  end
  when rc = 8 then do
    /* User cancelled */
    say 'Operation cancelled'
    exit 0
  end
  when rc = 12 then do
    /* User cancelled with PF12 */
    say 'Operation cancelled'
    exit 0
  end
  when rc = 16 then do
    /* Panel not found */
    say 'Panel MYPANEL not found'
    exit 8
  end
  otherwise do
    /* Other error */
    say 'Error displaying panel, RC=' rc
    exit 8
  end
end
exit 0

This pattern handles all common scenarios appropriately.

Advanced Techniques

Advanced Dialog Manager techniques for sophisticated applications.

Dynamic Panel Selection

Select panels dynamically based on runtime conditions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/*REXX*/
address ispexec
parse arg panelname
/* Validate panel name */
if panelname = '' then do
  say 'Panel name required'
  exit 8
end
/* Display panel dynamically */
'DISPLAY PANEL('panelname')'
if rc <> 0 then do
  say 'Error displaying panel' panelname
  exit 8
end
exit 0

This enables flexible panel invocation based on runtime parameters.

Panel Chaining with State

Maintain state across multiple panels:

1
2
3
4
5
6
7
8
9
10
11
12
13
/*REXX*/
address ispexec
/* Initialize state */
step = 1
total_steps = 3
'VPUT (STEP TOTAL_STEPS) PROFILE'
/* Chain panels */
do step = 1 to total_steps
  'VPUT (STEP) PROFILE'
  'DISPLAY PANEL(STEP'step')'
  if rc <> 0 then leave
end
exit 0

This maintains application state across a series of panels.

Nested Panel Invocation

Invoke panels from within panel processing:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/*REXX*/
address ispexec
/* Main panel */
'DISPLAY PANEL(MAIN)'
if rc = 0 then do
  'VGET (ACTION) PROFILE'
  if action = 'HELP' then do
    /* Nested panel for help */
    'DISPLAY PANEL(HELP)'
  end
  else if action = 'OPTIONS' then do
    /* Nested panel for options */
    'DISPLAY PANEL(OPTIONS)'
  end
end
exit 0

This enables hierarchical panel structures with nested dialogs.

Explain It Like I'm Five

Imagine ISPF Dialog Manager services like a restaurant ordering system:

• Dialog Manager - The waiter who brings you menus and takes your order
• Panels - The menus you see with options to choose from
• DISPLAY_PANEL - Asking the waiter to bring you a specific menu
• Your Program - The kitchen that processes your order
• Variables - The order form that goes between you and the kitchen

When you call DISPLAY_PANEL, it's like asking the waiter (Dialog Manager) to bring you a menu (panel). You look at the menu, make choices, and give it back. The waiter takes your order (variables) to the kitchen (your program), which processes it. The Dialog Manager makes sure you get the right menu from the menu library and handles the whole ordering process!

Best Practices

Follow these best practices when using Dialog Manager services:

• Always check return codes - handle all exit scenarios
• Use VPUT/VGET for variables - proper variable management
• Validate user input - ensure data quality
• Provide clear error messages - guide users
• Use meaningful panel names - improve maintainability
• Handle errors gracefully - don't crash on errors
• Clean up resources - free libraries when done
• Document panel flows - explain navigation logic

Common Mistakes

Avoid these common mistakes:

• Not checking return codes - missing user cancellations
• Forgetting VGET after DISPLAY - not retrieving user input
• Not validating input - processing invalid data
• Infinite loops - not handling exit conditions
• Wrong panel names - typos cause panel not found errors
• Not freeing libraries - resource leaks
• Assuming RC=0 - not handling all return codes

Exercises

Practice using Dialog Manager services:

• Create a REXX script that displays a simple input panel and processes the input
• Build a multi-step wizard using sequential panel chaining
• Implement a menu-driven application with conditional panel navigation
• Add error handling and retry logic to a panel input form
• Create a dynamic panel selector that chooses panels based on runtime conditions