>>-ISPEXEC--SELECT---------------------------------------------->

>--+-PANEL(panel-name)--+--------+--+-------------+----------------------------------+-->
   |                    '-ADDPOP-'  '-OPT(option)-'                                  |   
   +-CMD(command)--+------------------+--+------------------+--+---------+--+------+-+   
   |               '-LANG(-+-APL--+-)-'  '-MODE(-+-LINE-+-)-'  '-BARRIER-'  '-NEST-' |   
   |                       '-CREX-'              '-FSCR-'                            |   
   +-PGM(program-name)--+------------------+--+------------------+-------------------+   
   |                    '-PARM(parameters)-'  '-MODE(-+-LINE-+-)-'                   |   
   |                                                  '-FSCR-'                       |   
   |                             .-MODELESS-.                  .-MAX-.  .-VIS---.    |   
   +-WSCMD(workstation-command)--+----------+--+------------+--+-----+--+-------+----+   
   |                             '-MODAL----'  '-WSDIR(dir)-'  '-MIN-'  '-INVIS-'    |   
   |                   .-MODELESS-.                  .-MAX-.  .-VIS---.              |   
   '-WSCMDV(var_name)--+----------+--+------------+--+-----+--+-------+--------------'   
                       '-MODAL----'  '-WSDIR(dir)-'  '-MIN-'  '-INVIS-'                  

>--+--------------------------------------------+--------------->
   '-NEWAPPL--+------------------+--+---------+-'   
              '-(application-id)-'  '-PASSLIB-'     

>--+---------+--+---------+--+----------+--+----------------------+-><
   '-NEWPOOL-'  '-SUSPEND-'  '-EXCLPROF-'  '-SCRNAME(screen_name)-'   

>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><

or

>>-CALL--ISPLINK--('SELECTbb'--,--length,----------------------->

>--+-PANEL(panel-name)--+--------+--+-------------+----------------------------------+-->
   |                    '-ADDPOP-'  '-OPT(option)-'                                  |   
   +-CMD(command)--+------------------+--+------------------+--+---------+--+------+-+   
   |               '-LANG(-+-APL--+-)-'  '-MODE(-+-LINE-+-)-'  '-BARRIER-'  '-NEST-' |   
   |                       '-CREX-'              '-FSCR-'                            |   
   +-PGM(program-name)--+------------------+--+------------------+-------------------+   
   |                    '-PARM(parameters)-'  '-MODE(-+-LINE-+-)-'                   |   
   |                                                  '-FSCR-'                       |   
   |                             .-MODELESS-.                  .-MAX-.  .-VIS---.    |   
   +-WSCMD(workstation-command)--+----------+--+------------+--+-----+--+-------+----+   
   |                             '-MODAL----'  '-WSDIR(dir)-'  '-MIN-'  '-INVIS-'    |   
   |                   .-MODELESS-.                  .-MAX-.  .-VIS---.              |   
   '-WSCMDV(var_name)--+----------+--+------------+--+-----+--+-------+--------------'   
                       '-MODAL----'  '-WSDIR(dir)-'  '-MIN-'  '-INVIS-'                  

>--+--------------------------------------------+--------------->
   '-NEWAPPL--+------------------+--+---------+-'   
              '-(application-id)-'  '-PASSLIB-'     

>--+---------+--+---------+--+----------+--+----------------------+-><
   '-NEWPOOL-'  '-SUSPEND-'  '-EXCLPROF-'  '-SCRNAME(screen_name)-'   

panel-name

Specifies the name of a selection panel to be displayed.

option

Specifies an initial option, which must be a valid option on the menu specified by panel-name. Specifying an option causes direct entry to that option without displaying the menu. The menu is processed in non-display mode, as though the user had entered the option.

ADDPOP

Specifies that the panel displayed from a SELECT service appears in a pop-up window. An explicit REMPOP is performed when the SELECT PANEL has ended.

command

Specifies a CLIST command procedure, any TSO command that is to be invoked as a dialog function, or an APL2 command with appropriate keyword values. If the APL2 workspace is already started, command specifies a string to be passed to the APL2 workspace for execution.

CLIST command parameters can be included within the parentheses. You can prefix the CLIST procedure name with a percent sign (%) to:

• Improve performance.
• Prevent ISPF from entering line display mode if you do not specify MODE(FSCR).
• Ensure that the CLIST command procedure is invoked if ISPF has access to a program function that has the same name as the CLIST. If you use the percent sign prefix, ISPF searches only for a CLIST with the specified name. However, without the percent sign prefix, ISPF searches first for a program, then for a CLIST procedure.

  TSO commands specified by this parameter are invoked by the ATTACH macro.

LANG(APL)

If this is the first LANG(APL) request, this parameter specifies that the command specified by the CMD keyword is to be invoked and an APL2 environment is to be started. If this is not the first request, this parameter specifies that the string specified by the CMD keyword is to be passed to the APL2 workspace and executed. If this is the first LANG(APL) request and a command other than APL2, or equivalent, is specified by the CMD keyword, the result is not predictable.

LANG(CREX)

Specify that the command specified in the CMD keyword is a REXX EXEC that has been compiled and link-edited into a load module, and that a CLIST/REXX function pool is to be used rather than an ISPF module function pool. LANG(CREX) is optional if the compiled REXX has been link-edited to include any of the stubs EAGSTCE, EAGSTCPP, or EAGSTMP.

See z/OS ISPF Dialog Developer's Guide and Reference for more information about Compiled REXX processing.

MODE(LINE)

Specifies that line mode is to be entered when selecting a command procedure or program function. If you do not specify mode when selecting a command procedure, line mode is entered unless you prefix the command with a percent sign (%).

MODE(FSCR)

Specifies that line mode is not to be entered when selecting a command, CLIST, or program function.

BARRIER

Specifies that no commands from the REXX data stack will be pulled upon completion of a command invoked with the SELECT service.

NEST

Specifies that commands invoked with the SELECT service will be nested. This will allow command output trapping and communication through global variables.

program-name

Specifies the name of a program that is to be invoked as a dialog function. If the program is coded in PL/I, it must be a MAIN procedure. Dialog developers should avoid the ISP and ISR prefixes (the DM and PDF component codes) in naming dialog functions. Special linkage conventions, intended only for internal ISPF use, are used to invoke programs named "ISPxxxxx" and "ISRxxxxx".

This parameter must specify a name of a load module, load module alias, or an entry point that is accessible by use of the LINK macro.

See the z/OS ISPF Dialog Developer's Guide and Reference for restrictions that apply to dialogs in various languages.

parameters

Specifies input parameters to be passed to the program. The program should not attempt to modify these parameters.

The parameters within the parentheses are passed as a single character string, preceded by a halfword containing the length of the character string, in binary. The length value does not include itself.

Parameters passed from the SELECT service to a PL/I program can be declared on the procedure statement in the standard way:

XXX:  PROC (PARM) OPTIONS(MAIN);
      DCL PARM CHAR (nnn) VAR;

If the value of the PARM field is to be used as an ISPF dialog variable, it must be assigned to a fixed-length character string, because the VDEFINE service cannot handle variable-length PL/I strings.

Note: If you want to use special characters in your character string you must use a single quotation mark at the beginning and at the end of the string.

Some high-level languages, such as PL/I, have parameter syntax requirements specific to the language. For example, the first character of the PARM field must be a slash ('/'), because PL/I assumes that any value before the slash is a runtime option. See the publications supporting the language for specific requirements.

workstation-command

Specifies a fully qualified workstation program including any parameters. To issue a command that is not a program (.exe, .com, .bat) DOS allows it to be prefaced with COMMAND. For example:

SELECT WSCMD(COMMAND /C DIR C:)

MODAL

The MODAL parameter invokes the workstation command modally. It waits until the workstation command has completed and then returns to ISPF.

MODELESS

The MODELESS parameter invokes the command modelessly and is only valid when running in GUI mode. It is the default. It does not wait until the workstation command has completed. It always returns a return code of zero if the command was started, even if the command does not exist at the workstation.

WSDIR(dir)

The WSDIR parameter specifies the variable name containing the workstation current working directory. This directory is the directory from which the workstation command should be invoked.

MAX

The MAX parameter attempts to start the workstation command in a maximized window. The workstation command may override this request. MAX and MIN are mutually exclusive.

MIN

The MIN parameter attempts to start the workstation command in a minimized window. The workstation command may override this request. MAX and MIN are mutually exclusive.

VIS

The VIS parameter attempts to start the workstation command as a visible window. The workstation command may override this request. This is the default. VIS and INVIS are mutually exclusive.

INVIS

The INVIS parameter attempts to start the workstation command in an invisible (hidden) window. The workstation command may override this request. VIS and INVIS are mutually exclusive.

var

Specifies a variable name that contains the text string of a command and its parameters. Use this when the command path or parameters, or both, contain any embedded blanks, quotation marks, or special characters that might not parse properly with the WSCMD service.

NEWAPPL

Specifies that a new application is being invoked.

application-id

Specifies a 1- to 4-character code for the new application named in this SELECT service request. The code is to be prefixed to the user's profile, the edit profile, and the command table associated with the application, as follows, where xxxx is the application-id:

Application Profile   -  xxxxPROF
Edit Profile          -  xxxxEDIT
Command Table         -  xxxxCMDS

The names xxxxPROF, xxxxEDIT, and xxxxCMDS represent table (member) names in the profile or table input library.

If the NEWAPPL keyword is specified but the application-id is not specified, the default application-id is ISP, as follows:

User Profile     -  ISPPROF
Edit Profile     -  ISPEDIT
Command Table    -  ISPCMDS

If the NEWAPPL keyword is not specified, the application-id defaults to the current application-id.

If an application is invoked using SELECT with NEWAPPL and the invoked application has its own command table that is defined to ISPTLIB using LIBDEF, the LIBDEF of ISPTLIB must be done before issuing the SELECT CMD(..) NEWAPPL(..) for the application's command table to be available for use. This is necessary because the command table associated with the APPLID is opened at the time that the SELECT is processed. Failing to do the LIBDEF for ISPTLIB before the SELECT with NEWAPPL will result in the command table which was defined using LIBDEF not being opened and commands not being found. If the application's unique command table is not found, then the ISPF default command table, ISPCMDS, is loaded for that dialog.

This example shows how to code a LIBDEF for ddname ISPTLIB with the data set that contains the command table, APPCCMDS, for application APPC.

The application invoking CLIST CCC:

      .
      ISPEXEC SELECT CMD(CCC) NEWAPPL(TEMP)
      .

CLIST CCC:
      PROC 0
      ISPEXEC LIBDEF ISPTLIB DATASET ID(....)
      ISPEXEC SELECT CMD(CMDC) NEWAPPL(APPC) PASSLIB
      ISPEXEC LIBDEF ISPTLIB
      EXIT CODE(0)

PASSLIB

Indicates that the current set of application-level ISPF libraries, if any exist, are to be used by the application being selected. PASSLIB is valid only if NEWAPPL is specified.

The PASSLIB keyword can also be specified when setting the & ZSEL variable in a selection panel or in command table entries containing the SELECT action.

When both NEWAPPL and PASSLIB are specified, the current set of application-level libraries is made available to the selected application. Any changes made to this set of libraries while this application is running are in effect only while this application has control. Once the selected application terminates, the original set of application-level libraries is reactivated.

If LIBDEF has been issued for a user link library when a SELECT specifying NEWAPPL and PASSLIB is issued, the selected program makes available the LIBDEF user link library definition. Any SELECTs subsequently issued by the program employ member search orders dependent upon the LIBDEF user link library definition.

If a SELECT of a program is issued, and a LIBDEF of a user link library has not been made or PASSLIB is not specified, any SELECTs issued by the program rely on this convention for member search order:

   JOB PACK AREA
   ISPLLIB
   STEP LIBRARY
   LINK PACK AREA
   LINK LIBRARY

If NEWAPPL is specified and PASSLIB is not specified, the current set of application-level libraries, if any exist, are not to be used by the application being selected. The deactivation of these libraries takes place before the application is selected. The current application-level library definitions are saved, however, so they can be replaced in the library search sequence when the application being selected terminates.

When NEWAPPL and PASSLIB are not specified, the current set of application-level libraries remains in effect because the selected function does not represent a new application. If the selected function changes any of these library definitions, the changes apply through all select levels of the application of which the selected function is a part.

NEWPOOL

Specifies that a new shared variable pool is to be created without specifying a new application. Upon return from the SELECT service, the current shared variable pool is reinstated.

SUSPEND

Specifies that all pop-up windows in the logical screen should be temporarily removed from the terminal screen. Panels displayed by the selected dialog will appear in the full logical screen.

The selected dialog can issue ADDPOP and REMPOP services to create its own pop-up windows. A dialog that is invoked with the SUSPEND option cannot display panels in the windows created by the previous dialog.

When the selected dialog ends, any pop-up windows that were removed will be restored.

The terminal screen is not changed at the time of the SELECT service. The pop-up windows are removed or restored at the next panel display.

EXCLPROF

Specifies that ISPF is to disable the multi-logon profile sharing support for this service call. The parameter is ignored if the ISPF multi-logon support is not enabled, either by means of the ISPF Configuration options, or by specifying SHRPROF on the ISPSTART command. The parameter is optional.

screen-name

Specifies that the logical screen in which the SELECT command is issued will be given the specified "screen name". This logical screen will keep the screen name until that select level is exited, then it returns to its previous value. The user may override the screen name assigned with the SCRNAME command.

length

Specifies the length of a buffer containing the selection keywords. This parameter must be a fullword fixed binary integer.

keywords

Specifies the name of a buffer containing the selection keywords. This is a character string parameter. The selection keywords in the buffer are specified in the same form as they would be coded for the ISPEXEC command. For example:

BUFNAME = 'PANEL(ABC) OPT(9) NEWPOOL';

In the example shown, it is assumed that BUFNAME is the name of the buffer. The single quotes are part of the syntax of the PL/I assignment statement. They are not stored in the buffer itself.

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.

These return codes are possible if a panel is specified:

 0

Normal completion. The END command was entered from the selected menu.

 4

Normal completion. The RETURN command was entered or the EXIT option was specified from the selected menu or from some lower-level menu.

12

The specified panel could not be found.

16

Truncation error in storing the ZCMD or ZSEL variable.

20

Severe error.

These return codes are possible from a MODAL workstation command:

20

Parameter or syntax on SELECT service (all SELECTs) is not valid.

41

A null command was passed to the workstation.

42

ISPF was not able to start the command at the workstation.

43

Remote execution of commands was not allowed by the user.

OTHER

The return code from the workstation command + 100 if the return code from the workstation command was greater than 0.