Parameters

All the parameters described here apply to the PDF and ISPF commands as well as ISPSTART. For more information about the GUI parameters, see Graphical User Interface (GUI) guidelines. For more information about running in GUI mode, refer to the topic on the ISPF user interface in the z/OS ISPF User's Guide Vol I.


>>-ISPSTART----------------------------------------------------->

>--+-PANEL(panel_name)--+-------------+--+--------+-------------------------------+-->
   |                    '-OPT(panopt)-'  '-ADDPOP-'                               |   
   +-CMD(command-parm1-parm2)--+------------------+-------------------------------+   
   |                           '-LANG(-+-APL--+-)-'                               |   
   |                                   '-CREX-'                                   |   
   +-PGM(program_name)--+------------------+--------------------------------------+   
   |                    '-PARM(parameters)-'                                      |   
   |                             .-MODELESS-.                  .-MAX-.  .-VIS---. |   
   +-WSCMD(workstation_command)--+----------+--+------------+--+-----+--+-------+-+   
   |                             '-MODAL----'  '-WSDIR(dir)-'  '-MIN-'  '-INVIS-' |   
   |                   .-MODELESS-.                  .-MAX-.  .-VIS---.           |   
   +-WSCMDV(var_name)--+----------+--+------------+--+-----+--+-------+-----------+   
   |                   '-MODAL----'  '-WSDIR(dir)-'  '-MIN-'  '-INVIS-'           |   
   '-+-option-------------+-------------------------------------------------------'   
     +-BASIC--------------+                                                           
     '-cmd_stack_var_name-'                                                           

>--+-------------------------------------------------------------------+-->
   '-GUI--(--+-LU:address:tpname-+--+-----------+--)--+--------------+-'   
             +-IP:address:port---+  '-,NOGUIDSP-'     '-TITLE(title)-'     
             '-FI:---------------'                                         

>--+-----------------------+--+-----------------------+--------->
   '-GUISCRW(screen_width)-'  '-GUISCRD(screen_depth)-'   

>--+------------------+--+--------------------+----------------->
   |        .-STD-.   |  '-CODEPAGE(codepage)-'   
   '-FRAME(-+-FIX-+-)-'                           
            '-DLG-'                               

>--+------------------------+--+-------------------+------------>
   '-CHARSET(character_set)-'  |         .-DLG-.   |   
                               '-BKGRND(-+-STD-+-)-'   

>--+------------------------------+--+----------+--------------->
   '-NEWAPPL-+------------------+-'  +-SHRPROF--+   
             '-(application_id)-'    '-EXCLPROF-'   

>--+----------------------+--+--------+------------------------->
   '-SCRNAME(screen_name)-'  +-TEST---+   
                             +-TESTX--+   
                             +-TRACE--+   
                             '-TRACEX-'   

>--+-----------------------+--+-----------------------+--------->
   +-NOLOGO----------------+  '-BATSCRW(screen_width)-'   
   '-LOGO(logo_panel_name)-'                              

>--+-----------------------+------------------------------------>
   '-BATSCRD(screen_depth)-'   

>--+----------------------------------+------------------------->
   '-BDISPMAX(max_number_of_displays)-'   

>--+------------------------------------+--+-------+------------>
   '-BREDIMAX(max_number_of_redisplays)-'  '-BDBCS-'   

>--+----------+--+----------+----------------------------------><
   +-DANISH---+  '-NESTMACS-'   
   +-ENGLISH--+                 
   +-GERMAN---+                 
   +-JAPANESE-+                 
   +-PORTUGUE-+                 
   +-SPANISH--+                 
   +-KOREAN---+                 
   +-FRENCH---+                 
   +-ITALIAN--+                 
   +-CHINESET-+                 
   +-CHINESES-+                 
   +-SGERMAN--+                 
   '-UPPERENG-'

where:

panel_name

Specifies the name of the first menu (that is, the primary option menu) to be displayed.

panopt

Specifies an initial option, which should be a valid option on the first menu panel specified using the PANEL parameter. This causes direct entry to that option without displaying the specified menu panel. (The menu panel is processed in nondisplay 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 command procedure (CLIST or REXX), an APL2® command, or a TSO command processor that is to be invoked as the first dialog function. For more information about invoking APL2 dialogs, refer to the z/OS ISPF Services Guide.

CLIST or REXX command parameters can be included within the parentheses. For example, the call format would be:

   ISPSTART CMD(MYCLIST parm1 parm2 …)

These parameters are passed to the command procedure. For information about specifying CLIST parameters, see z/OS TSO/E CLISTs. For information about specifying REXX parameters, see z/OS TSO/E REXX User's Guide.

You can type a percent sign (%) preceding the CLIST or REXX procedure name to:

Improve performance
Prevent ISPF from entering line-display mode when the procedure is started.
Note: When starting a CLIST or REXX procedure or a program through the SELECT service, a MODE(LINE|FSCR) parameter is available for specifying either line mode or full-screen mode. If you do not specify the mode parameter or do not use the % prefix, ISPF enters line-display mode.
Ensure that the command procedure is invoked if ISPF has access to a program function that has the same name as the procedure. If you use the percent sign prefix, ISPF searches only for a procedure with the specified name. However, without the percent sign prefix, ISPF searches first for a program, then for a CLIST or REXX procedure.

On extended data stream terminals, using the percent sign causes the keyboard to remain in a locked condition. To avoid this condition, the CLIST or REXX procedure can issue output line I/O before issuing a READ.

LANG(APL|CREX)

Specifies special language invocations. LANG(APL) specifies to start the command specified by the CMD keyword, and to start an APL2 environment. LANG(CREX) specifies that the command specified by 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. LANG(CREX) is optional if the compiled REXX has been link-edited to include any of the stubs EAGSTCE, EAGSTCPP, or EAGSTMP.

program_name

Specifies the name of a program that is to be invoked as the first dialog function. In PL/I, it must be a MAIN procedure. This parameter must specify the name of a load module that is accessible by use of the LINK macro.

However, if the program dialog consists of multiple tasks and if any of the subtasks use ISPF services, the CMD keyword, not the PGM keyword, must be used. Dialog developers should avoid using prefixes ISP and ISR, the ISPF component codes, in naming dialog functions. Special linkage conventions, intended only for internal ISPF use, are used to invoke programs named ISPxxxxx and ISRxxxxx.

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 half-word containing the length of the character string, in binary. (The length value does not include itself.) This convention is the same as that for passing parameters by use of the PARM= keyword on a JCL EXEC statement.

Parameters on the ISPSTART command to be passed to a PL/I program are coded 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 character string because the VDEFINE service cannot handle varying length PL/I strings. In PL/I the first character of the PARM field must be a slash (/), as PL/I assumes that any value before the slash is a runtime option.

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

option

Specifies an initial option, which should be a valid option on the default primary options menu. This causes direct entry to that option without displaying the default primary options menu. (The primary option menu is processed in nondisplay mode, as though the user had entered the option.) If you specify an option that is not valid, the primary option menu displays an appropriate error message.

BASIC

ISPF displays the default primary options menu and bypasses processing of the default initial command stack variable ZSTART.

cmd_stack_var_name

The name of an ISPF profile variable that contains an initial command stack to be processed by ISPF. The specified command stack is processed by ISPF as though it had been entered on the initial display of the primary options menu. The first four characters of the variable value must be "ISPF" followed by the command delimiter character followed by the initial command stack.

The following example specifies a command stack to have three logical screens created when ISPF starts:

Screen 1 - Data Set List Utility (ISPF option 3.4)
Screen 2 - z/OS® UNIX Directory List Utility (ISPF option 3.17)
Screen 3 - SCLM (ISPF option 10)

The Data Set List Utility is the initial logical screen displayed:

ISPF;3.4;START 3.17;START 10;SWAP 1

var_name

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 embedded blanks, quotation marks, or special characters that might not parse properly with the WSCMD service.

LU:address:tpname

Specifies the workstation's Advanced Program-to-Program Communication (APPC) network name.

Note: The variable ZGUI will be set to the workstation address (in character format) if ISPSTART is issued with the GUI parameter; ZGUI will be set to blank if ISPSTART is issued without the GUI parameter.

IP:address:port

Specifies the workstation's TCP/IP hardware-level IP address: a fully qualified machine name.

Note:

The variable ZGUI will be set to the workstation address (in character format) if ISPSTART is issued with the GUI parameter; ZGUI will be set to blank if ISPSTART is issued without the GUI parameter.
If address is set to an asterisk (*) the value of the system variable ZIPADDR is used. ZIPADDR contains the TCP/IP address of the currently connected TN3270 workstation.

FI:

Specifies that you want to search a file allocated to DD ISPDTPRF for the user's network protocol and workstation address to be used when initiating a workstation connection or GUI display. For more information, refer to the information about workstation connections in the Settings topic of the z/OS ISPF User's Guide Vol II.

NOGUIDSP

Specifies that you want to make a connection to the workstation, but DO NOT want ISPF to display in GUI mode.

Note: This parameter is only valid if you have specified an LU, IP, or FI parameter. In other words, you can have any of these situations:

you specify LU:address:tpname, IP:address:port, or FI: without the NOGUIDSP parameter
or you specify LU:address:tpname, NOGUIDSP
or you specify IP:address:port, NOGUIDSP
or you specify FI:, NOGUIDSP

TITLE(title)

Specifies the text displayed in the title bar unless a dialog has assigned a nonblank value to ZWINTTL or ZAPPTTL. The default value for the title bar is the user ID. This value has a maximum length of 255 characters and will be truncated without notice to the user at display time if it does not fit on the panel.

GUISCRW(screen_width)

Allows you to specify a screen width different than that of the emulator or real device from which you enter the ISPSTART command. If you do not specify GUISCRD, the depth will be that of the emulator or real device.

If GUISCRW is different than the emulator or real device, and GUI initialization fails, ISPF will not initialize. Dialogs started with dimensions other than those of the emulator or real device that use the GRINIT service will not display GDDM® screens.

Note: This parameter is usually only used with the GUI parameter. If you do specify a value for this parameter without using the GUI parameter, ISPF ignores it. If you specify a value that is not valid for this parameter, ISPF might return an error condition.

GUISCRD(screen_depth)

Allows you to specify a screen depth different than that of the emulator or real device from which you enter the ISPSTART command. If you do not specify GUISCRW, the width will be that of the emulator or real device.

If GUISCRD is different than the emulator or real device and GUI initialization fails, ISPF will not initialize. Dialogs started with dimensions other than those of the emulator or real device that use the GRINIT service will not display GDDM screens.

CODEPAGE(codepage) CHARSET(character_set)

When running in GUI mode or connecting to the workstation, these values are used as the host code page and character set in translating data from the host to the workstation, regardless of the values returned from the terminal query response.

When running in 3270 mode, if your terminal or emulator does not support code pages, these values are used as the host code page and character set. Otherwise, these values are ignored.

FRAME(STD|FIX|DLG)

Specifies that the first window frame displayed will be a standard (STD), fixed (FIX), or dialog (DLG) window frame, where:

Standard: A GUI window frame that can be resized and has max/min buttons. This is the default value.
Fixed: A GUI window frame that has max/min buttons but cannot be resized.
Dialog: A GUI window frame that cannot be resized and does not have max/min buttons.

Note:

Pop-up panels are displayed in dialog frames by default.
This parameter is usually only used with the GUI parameter. If you do specify a value for this parameter without using the GUI parameter, ISPF ignores it. If you specify a value that is not valid for this parameter, ISPF might return an error condition.

BKGRND(STD|DLG)

Specifies that the first window frame displayed will be a standard (STD) or dialog (DLG) background color. These colors are defined by the workstation. The default is DLG.

NEWAPPL(application_id)

Specifies a 1- to 4-character code that identifies the application that is being invoked. The code is to be prefixed to the user and edit profile names or to the command table associated with the application, as follows:

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

where xxxx is the application_id. If the application_id is omitted, or if the NEWAPPL keyword is omitted, the application_id defaults to ISP.

SHRPROF

Specifies that ISPF is to enable the multi-logon profile sharing support. The parameter is optional.

EXCLPROF

Specifies that ISPF is to disable the multi-logon profile sharing support. The parameter is optional

SCRNAME(screen_name)

Specifies a screen name to be used with the SWAP command and the ISPF task list. The name can be from 2 to 8 characters in length, must satisfy the rules for a member name, but cannot be LIST, PREV, or NEXT.

TEST

Specifies that ISPF is to be operated in TEST mode, described under ISPF test and trace modes.

TESTX

Specifies that ISPF is to be operated in extended TEST mode, described under ISPF test and trace modes.

TRACE

Specifies that ISPF is to be operated in TRACE mode, described under ISPF trace modes.

TRACEX

Specifies that ISPF is to be operated in extended TRACE mode, described under ISPF trace modes.

LOGO(logo_panel_name)

Specifies that ISPF displays the named panel before invoking the specified dialog object. Subsequent SELECT service requests that identify a LOGO panel will not result in the indicated panel being displayed. This includes a repeat of the first SELECT as a result of a split-screen request or a logical screen restart following a severe dialog error.

Applications can choose to display their own LOGO panel directly. These applications can determine whether the user specified the NOLOGO keyword on ISPSTART by retrieving the ISPF system variable ZLOGO. Applications that choose to display their own LOGO panel are responsible for controlling that display operation during split-screen operations and logical-screen restart situations.

NOLOGO

Specifies that ISPF is to bypass the display of the message pop-up window containing the product title and copyright statement.

screen_width

For batch mode, specifies screen width in character positions. The default value is 80. This parameter is ignored when not running in batch mode.

All screen sizes from 24 x 80 to 62 x 160 are valid.

screen_depth

For batch mode, specifies screen depth in lines. The default value is 32. This parameter is ignored when not running in batch mode.

max_number_of_displays

For batch mode, specifies the maximum number of displays that can occur during a session. This number includes the total of all SELECT PANEL calls, plus all DISPLAY and TBDISPL calls (with or without panel name). This number does not include redisplays related to the .MSG control variable. The largest number that can be specified is 999999999. The batch default value is 100. This parameter is ignored when not running in batch mode.

max_number_of_redisplays

For batch mode, specifies the maximum number of redisplays allowed for a .MSG-redisplay loop. The largest number that can be specified is 255. The batch default value is 2. This parameter is ignored when not running in batch mode.

BDBCS

For batch mode, specifies that Double-Byte Character Set (DBCS) terminal support is required. This parameter is ignored when not running in batch mode.

DANISH, ENGLISH, GERMAN, JAPANESE, PORTUGUE, SPANISH, KOREAN, FRENCH, ITALIAN, CHINESET, CHINESES, SGERMAN, UPPERENG

Specifies the national language that is to override the default language for this session. The JAPANESE keyword specifies that the KANJI character set is to be used. The CHINESET keyword stands for Traditional Chinese, CHINESES stands for Simplified Chinese, and SGERMAN stands for Swiss-German. The UPPERENG keyword specifies that the uppercase English character set is to be used. For information about establishing the default session language, refer to z/OS ISPF Planning and Customizing.

Note:

Attempting to run a dialog under a session language other than that for which it was intended may produce unexpected results.
When the Korean, French, Italian, Traditional Chinese, Simplified Chinese, Spanish, Brazilian-Portuguese, or Danish session language is specified, its respective literal module is used. However, the ISPF product panels and messages are displayed in English.

NESTMACS

Specifies that all REXX and CLIST edit macros invoked during the ISPF session are to run as nested commands, allowing output from these macros to be trapped using either the REXX OUTTRAP function or the CLIST &SYSOUTTRAP control variable.