The CMDAREA tag defines a command entry area on an application panel.

Parameters

HELP=NO | YES | help-panel-name | *help-message-id | %varname | *%varname

This attribute specifies the help action taken when the user requests help for the command area.

When HELP=YES, control is returned to the application. You can specify either a help panel or a message identifier. If a message identifier is used, it must be prefixed with an asterisk (*).

The help attribute value can be specified as a variable name. When %varname is coded, a panel variable name is created. When *%varname is coded, a message variable name is created.

If the user requests help on a choice and no help is defined, the extended help panel is displayed. If an extended help panel is not defined for the panel, the application or ISPF tutorial is invoked.

The help-panel-name must follow the standard naming convention described in Rules for variable names.

See HELP (Help Panel) for information about creating help panels. For information about creating messages, see MSG (Message).

PMTLOC=BEFORE

This attribute defines the location of the prompt text. The text defined by command-prompt-text appears on the same line as the command area entry field.

NOINIT

This attribute controls the initial display of the command line. When this attribute is specified, the ZCMD field is not initialized to blanks before the panel is displayed.

PAD=NULLS | USER | char | %varname

This attribute specifies the pad character for initializing the field. You can define this attribute as a variable name preceded by a “%”.

PADC= NULLS | USER | char | %varname

This attribute specifies the conditional padding character to be used for initializing the field. You can define this attribute as a variable name preceded by a “%”.

OUTLINE=NONE | L | R | O | U | BOX | %varname

This attribute provides for displaying lines around the field on a DBCS terminal. You can define this attribute as a variable name preceded by a “%”.

NAME=cmdarea-variable-name

This attribute specifies a command area name to replace the default name ZCMD.

The cmdarea-variable-name must follow the standard naming convention described in Rules for variable names.

ENTWIDTH=n

This attribute is used to specify the length of the command field. It is used in combination with WINDOW=NO on the PANEL tag to create a command line which is longer than a single panel line.

PMTTEXT=YES | NO

This attribute is used to control the formatting of the command-prompt-text. When PMTTEXT=NO, the command-prompt-text is not used, leaving only the “===>” indicator for the command field.

CMDLOC=DEFAULT | ASIS

This attribute is used to control the placement of the command line in the generated panel. When CMDLOC=DEFAULT (or when CMDLOC is not specified) the command area is placed at line 2 in the panel, and the display position is controlled by the option specified on the Settings panel. When CMDLOC=ASIS is specified, the command area is placed in the generated panel in the same relative position as the CMDAREA tag is found in the DTL source, and the Settings option is ignored when the panel is displayed.

CMDLEN=DEFAULT | MAX

This attribute is used to control the length of the command line in the generated panel. When CMDLEN=DEFAULT (or when CMDLEN is not specified) the command line length is taken from the specified (or defaulted) WIDTH attribute of the PANEL tag. When CMDLEN=MAX is specified, the command line length is taken from the record length of the output panel file.

This attribute is valid only when WINDOW=NO is specified on the PANEL tag.

AUTOTAB=NO | YES

When AUTOTAB=YES, the cursor moves to the next input field when you enter the last character in the command field. If there is no other input field on the panel, the cursor returns to the beginning of the command line. The ISPF SKIP keyword is not supported in GUI mode.

SCROLLVAR=scroll-variable

This attribute specifies the name of a variable that the application uses to obtain scrolling information. The scroll-variable must follow the standard naming convention described in Rules for variable names.

If the attribute is specified, the conversion utility creates a scroll entry on the command line, providing that the resulting command area allows at least 8 bytes for a command entry.

SCRVHELP=NO | YES | scroll-help-panel-name | *scroll-help-message-id | %varname | *%varname

This attribute specifies the help action taken when the user requests help for the field specified with the SCROLLVAR attribute.

When SCRVHELP=YES, control is returned to the application. You can specify either a help panel or a message identifier. If a message identifier is used, it must be prefixed with an asterisk (*).

The help attribute value can be specified as a variable name. When %varname is coded, a panel variable name is created. When *%varname is coded, a message variable name is created.

If the user requests help on a choice and no help is defined, the extended help panel is displayed. If an extended help panel is not defined for the panel, the application or ISPF tutorial is invoked.

The scroll-help-panel-name must follow the standard naming convention described in Rules for variable names.

See HELP (Help Panel) for information about creating help panels. For information about creating messages, see MSG (Message).

SCROLLTAB=NO | YES

When SCROLLTAB=YES, the cursor moves to the next input field when you enter the last character in the scroll amount field. If there is no other input field on the panel, the cursor returns to the beginning of the command line. The ISPF SKIP keyword is not supported in GUI mode.

SCRCAPS=OFF | ON

When SCRCAPS=ON, the data in the scroll field is displayed in uppercase characters.

PSBUTTON=cmd-pb-text

This attribute requires that the PSVAR and PSVAL attributes also be specified.

This attribute specifies that a command push button is to be placed at the end of the command line, provided that the resulting command area allows at least 8 bytes for a command entry. The push button text area is created as a point-and-shoot field.

PSVAR=point-and-shoot-variable | %varname

This attribute provides the name of a variable that is to be set when the cmd-pb-text is clicked on for point-and-shoot selection. You can define this attribute as a variable name preceded by a percent (%) sign.

The point-and-shoot-variable must follow the standard naming convention described in Rules for variable names.

PSVAL=point-and-shoot-value | %varname

This attribute provides the value to be placed in the field specified by the PSVAR attribute. You can define this attribute as a variable name preceded by a percent (%) sign. To specify a blank value, use the coding notation “' '” (quotation mark, apostrophe, blank space, apostrophe, quotation mark).

IMAPNAME=image-name | %varname

This attribute specifies the name of an image to be placed on the point-and-shoot push button when it is displayed in GUI mode. The image-name is not used when the panel is displayed in host mode. The image-name must follow the standard naming convention described in Rules for variable names.

IMAPNAMEP=image-namep | %varname

This attribute specifies the name of an image to be placed on the point-and-shoot push button after it has been pushed when it is displayed in GUI mode. The image-namep is not used when the panel is displayed in host mode. The image-namep must follow the standard naming convention described in Rules for variable names.

PLACE=ABOVE | BELOW | LEFT | RIGHT | %varname

This attribute specifies the position of the image relative to the text within the point-and-shoot push button.

CAPS=OFF | ON

When CAPS=ON, the data in the field is displayed in uppercase characters.

NOJUMP=OFF | ON

When NOJUMP=ON, the JUMP function is disabled for the field.

VARDCL=YES | NO

When VARDCL=NO the cmdarea-variable-name is not checked to the declared variable information provided with the VARCLASS and VARDCL tags.

command-prompt-text

The command-prompt-text specifies the prompt text for the command entry area. The maximum prompt text (not including the command area prefix ===>) is 59 bytes for a standard 76 byte-width panel. The conversion utility reserves 8 bytes for a minimum command entry field and 3 additional bytes are required for panel attributes. One blank is placed between the command-prompt-text and the command area prefix. One blank is placed between the end of the command line and the right panel boundary (unless the WINDOW=NO attribute has been specified) to prevent the cursor from skipping into the right panel window border. These formatting considerations mean that the maximum length of the command-prompt-text for a panel 76 bytes in width is 59. If the length of the command-prompt-text exceeds the available space, a message is issued and the command-prompt-text is truncated. If your panel requires that the Scroll field be added to the Command line, or the SCROLLVAR attribute is specified in the CMDAREA definition, the command-prompt-text must be further reduced to allow for the Scroll field. If your panel specifies the PSBUTTON attribute, the command-prompt-text must be further reduced to allow for the Command push button.

If you do not provide command-prompt-text, the word "Command" (or its translated equivalent) is the default, unless you are creating an ISPF selection panel, in which case the word "Option" (or its translated equivalent) is the default. The Common User Access command area prefix (===>) is always added automatically in front of the entry field.

Comments

Restrictions

• You must code the CMDAREA tag within a PANEL definition. You can code only one command area definition for each panel. See PANEL (Panel) for a complete description of this tag.
• The data entered on the command line is processed “as is”. To translate the data to uppercase, you must either provide a VARDCL definition for the field ZCMD with a reference to a VARCLASS containing an XLATL tag which specifies FORMAT=UPPER, or specify CAPS=ON.
• You cannot code the CMDAREA tag within an AREA definition. The Command area is generated at the top of the panel source to allow for floating of the command line. See the z/OS ISPF Dialog Developer's Guide and Reference for more information.
• If both PAD and PADC have been specified, PAD is ignored and PADC is used.
• When a "%varname" notation is found on any of the attributes that allow a variable name, the "%varname" entry must follow the standard naming convention described in Rules for “%variable” names.

Processing