 |
The CHOFLD tag defines an input field,
an output field, or an input/output field within the text of a CHOICE
tag.
Syntax 
>>-<CHOFLD--DATAVAR=field-data---------------------------------->
>--+------------------------------+----------------------------->
'-VARCLASS=variable-class-name-'
>--+----------------------------+--+-----------------+---------->
| .-NO---------------. | | .-BOTH-. |
'-HELP=-+-YES--------------+-' '-USAGE=-+-IN---+-'
+-help-panel-name--+ '-OUT--'
+-*help-message-id-+
+-%varname---------+
'-*%varname--------'
>--+-------------------------------------------+---------------->
| .-NO--------------------------. |
'-REQUIRED=-+-YES-------------------------+-'
'-YES--MSG=message-identifier-'
>--+------------------+--+------------+--+------------+--------->
| .-NO--. | '-ENTWIDTH=n-' '-FLDSPACE=n-'
'-AUTOTAB=-+-YES-+-'
>--+-------------------+--+------------------+--+-----------+--->
| .-START--. | | .-YES-. | '-NOENDATTR-'
'-ALIGN=-+-CENTER-+-' '-DISPLAY=-+-NO--+-'
'-END----'
>--+-------------------+--+--------------------+---------------->
'-PAD=-+-NULLS----+-' '-PADC=-+-NULLS----+-'
+-USER-----+ +-USER-----+
+-char-----+ +-char-----+
'-%varname-' '-%varname-'
>--+-----------------------+------------------------------------>
| .-NONE-----. |
'-OUTLINE=-+-L--------+-'
+-R--------+
+-O--------+
+-U--------+
+-BOX------+
'-%varname-'
>--+-------------------------------------+---------------------->
'-PSVAR=-+-point-and-shoot-variable-+-'
'-%varname-----------------'
>--+----------------------------------+--+--------------+------->
'-PSVAL=-+-point-and-shoot-value-+-' '-PAS=%varname-'
'-%varname--------------'
>--+--------+--+---------------------+-------------------------->
'-EXPAND-' | .-NO--. |
'-ATTRCHANGE=-+-YES-+-'
'-NEW-'
>--+--------------------+--+------------------+----------------->
'-INIT=initial-value-' '-| IMAP options |-'
>--+---------------+--+---------------+-->---------------------->
'-ATTRCHAR=code-' | .-OFF-. |
'-CAPS=-+-ON--+-'
>--+-------------------------+--+-----------+------------------><
'-choice-description-text-' '-</CHOFLD>-'
IMAP options
|--IMAPNAME=-+-image-name-+--+----------------------------+----->
'-%varname---' '-IMAPNAMEP=-+-image-namep-+-'
'-%varname----'
>--+---------------------+--------------------------------------|
| .-ABOVE----. |
'-PLACE=-+-BELOW----+-'
+-LEFT-----+
+-RIGHT----+
'-%varname-'
Parameters - DATAVAR=field-data
- This
attribute specifies the variable name for the data in the field. The
value coded must be a variable-name without the leading % notation.
- VARCLASS=variable-class-name
- This
attribute specifies the name of the variable class, defined using
a VARCLASS tag, that overrides the default variable class referred
to by the VARDCL that declared the data variable for this field.
- HELP=NO | YES |
help-panel-name | *help-message-id | %varname | *%varname
- This
attribute specifies the help action taken when the user requests help
for this choice data field. This is field-level help.
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 for the choice data field 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).
- USAGE=BOTH | IN
| OUT
- This
attribute indicates whether the field is for input only, output only,
or both.
- REQUIRED=NO | YES
- This
attribute indicates if the field requires input. This attribute is
valid only when USAGE=IN or BOTH.
If REQUIRED=YES is coded, a
VER(variable,NONBLANK) statement is built by the conversion utility
and placed in the )PROC section of the ISPF panel generated.
- MSG=message-identifier
- This attribute specifies the message that is displayed when the
user does not complete a required entry (defined with the REQUIRED
attribute). If you do not specify a message-identifier, ISPF
displays a default message.
If you specify the MSG attribute and
REQUIRED=YES, a VER(variable,NONBLANK,MSG=message-identifier) statement
is built by the conversion utility and placed in the )PROC section
of the ISPF panel generated. If you specify the MSG attribute and
REQUIRED=NO (the default), the conversion utility issues a warning
message.
See MSG (Message) for information
about creating messages.
Note: You can specify messages pertaining
to other validations using XLATL and CHECKL tags within a VARCLASS
definition. See the descriptions of these tags for additional information.
- AUTOTAB=NO | YES
- When
AUTOTAB=YES, the cursor moves to the next field capable of input when
the user enters the last character in this field. If no other field
capable of user input exists on the panel, the cursor returns to the
beginning of this field. The ISPF SKIP keyword is not supported when
running in GUI mode.
AUTOTAB=YES is valid only when the value
for USAGE is either BOTH or IN. If specified, this attribute overrides
the AUTOTAB value of the DTACOL tag.
- ENTWIDTH=n
- This
attribute specifies the number of bytes used for the choice data field.
The minimum width is 1 and the maximum is the remaining available
panel width, less the required amount of space for field attributes.
If ENTWIDTH is not provided on either the CHOFLD tag or the enclosing
DTACOL tag, the conversion utility uses the width determined by the
TYPE value of the associated VARCLASS.
If specified, this attribute
overrides the ENTWIDTH value of the DTACOL tag.
- FLDSPACE=n
- This
attribute specifies the number of bytes reserved for the choice data
field. The minimum width is 2 and the maximum is the remaining available
panel (or region) width. The FLDSPACE value should include the actual
entry width plus the number of entry field attributes. If the value
specified by ENTWIDTH is less than the specified FLDSPACE value, the
entry field is padded with blanks to the FLDSPACE value. This creates
blank space between the entry field and following choice-description-text and
allows you to align description text from successive CHOFLD definitions.
If specified, this attribute overrides the FLDSPACE value of the
DTACOL tag.
- ALIGN=START | CENTER
| END
- This
attribute specifies the alignment of data within the display field
after all translations have been performed. Use this attribute to
align the data with the start, the end, or the center of the display
field.
This is accomplished in the conversion utility by using
an attribute character for the field that specifies JUST(LEFT) if
ALIGN=START or JUST(RIGHT) if ALIGN=END. ALIGN=CENTER uses an attribute
character for the field that specifies JUST(ASIS).
Alignment
occurs if the transformed value of the dialog variable is shorter
than the display width of the field. When ALIGN=END, no underscore
is padding performed. Instead, blanks are used.
- DISPLAY=YES | NO
- This
attribute specifies whether data displays on the screen as the user
types it in. If you specify NO, the data is not displayed. This attribute
is useful when creating fields for passwords or other information
which you do not want to appear on the screen.
- NOENDATTR
- This
attribute, which is valid only when WINDOW=NO is specified on the
PANEL tag or DIR=HORIZ is specified on the REGION tag, specifies that
no ending attribute is placed after the choice data field. NOENDATTR
is ignored for the last field on each panel line unless WINDOW=NO
has been specified on the PANEL tag. NOENDATTR is valid only when
the CHOFLD tag is followed by a CHOFLD, CHOICE, or CHDIV tag.
- 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 “%”.
If specified, this attribute overrides the PAD value of the DTACOL
tag.
- 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 “%”.
If specified, this attribute overrides
the PADC value of the DTACOL tag.
- 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 “%”.
If specified, this attribute overrides the OUTLINE value
of the DTACOL tag.
- PSVAR=point-and-shoot-variable | %varname
- This
attribute provides the name of a variable that is to be set when a
CHOFLD is clicked on for point-and-shoot selection. You can define
this attribute as a variable name preceded by a “%”.
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 “%”. To specify a blank value, the "' '" (quotation
mark, apostrophe, blank, apostrophe, quotation mark) coding notation
should be used.
- PAS=%varname
- This
attribute can be used to provide a variable name to specify ON or
OFF for point-and-shoot. When PSVAR and PSVAL have been specified
without the PAS attribute, the point-and-shoot field is automatically
enabled.
- EXPAND
- The
EXPAND attribute, used in combination with EXPAND=xy on the PANEL
definition, causes the expand characters to be added to the CHOFLD
definition, effectively allowing ENTWIDTH to expand. The ENTWIDTH
value must be specified as 4 or greater for the EXPAND function to
operate.
Note: If the PANEL tag attribute EXPAND is defined with
no value specified, the CHOFLD tag EXPAND attribute is not used.
- ATTRCHANGE=NO |
YES | NEW
- When
ATTRCHANGE=YES or ATTRCHANGE=NEW, the conversion utility formats an
additional entry in the panel )ATTR section (that can apply to multiple
data fields) instead of creating a unique .ATTR(field-name) entry
in the )INIT section for this field. With this option, multiple CHOFLD
tags with the same characteristics require fewer panel logic statements.
ATTRCHANGE=NEW creates a new entry. ATTRCHANGE=YES uses an existing
entry, if possible.
- INIT=initial-value
- When
the INIT attribute is specified, the conversion utility adds a statement
to the panel )INIT section to initialize the field to the initial-value.
- 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
- This attribute specifies the position of the image relative to
the text within the point-and-shoot push button.
- ATTRCHAR=code
- This attribute can be a single character or a two-position entry
of valid hex digits. If you enter an incorrect value, a warning message
is issued and the value is set to null. Hex entries are converted
to character. Hex values '00'-'2F' are reserved for use by the conversion
utility.
- CAPS=OFF | ON
- When CAPS=ON, the data in the field is displayed in uppercase
characters.
- choice-description-text
- This is the text for the choice data field. The choice-description-text appears
following the field.
Comments The
CHOFLD tag is similar to the DTAFLD tag. When the enclosing SELFLD
tag is defined within a DTACOL tag, the CHOFLD tag uses default values
defined by the DTACOL tag in the same way as the DTAFLD tag.
The
CHOFLD tag defines an input field, an output field, or an input/output
field within CHOICE tag description text on an application panel.
The
formatted width of the field is 2 positions more than the ENTWIDTH
value to provide for an attribute byte both before and after the field.
Restrictions - You must code the CHOFLD tag within a CHOICE tag definition. The
CHOFLD tag can be placed anywhere within the choice-description-text.
See CHOICE (Selection Choice) for a description of
this tag.
- The variable name specified in the DATAVAR attribute should have
an associated VARDCL definition. See VARDCL (Variable Declaration) for
a complete description of this tag.
- 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.
Examples Here
is source file markup that contains an application panel that is similar
to the example for the CHOICE tag. In this example, the first selection
field is modified to illustrate the CHOFLD tag. The first choice includes
a panel input/output field named cardtype which must be completed
when the new choice is selected.
Notice that the reference
CHOICE source file has been modified to:
- Add a VARCLASS for the cardtype field before the
include file which has both VARCLASS and VARDCL tags.
- Add a VARDCL for the cardtype field after the
include file which has both VARCLASS and VARDCL tags.
- Add the CHOFLD tag to define the choice data field.
- Add a DTACOL tag definition to allow for a SOURCE tag that provides
an audit of cardtype only when new is
selected.
Figure 1 shows
the formatted result. <!DOCTYPE DM SYSTEM(
<!entity sampvar1 system>
<!entity sampabc system>)>
<VARCLASS NAME=char9cls TYPE='char 9'>
<XLATL FORMAT=upper>
</XLATL>
&sampvar1;
<VARLIST>
<VARDCL NAME=cardtype VARCLASS=char9cls>
</VARLIST
<PANEL NAME=chofld KEYLIST=keylxmp>Library Card Registration
<AB>
&sampabc;
</AB>
<TOPINST>Type in patron's name and card number (if applicable).
<TOPINST>Then select an action bar choice.
<AREA>
<DTAFLD DATAVAR=curdate PMTWIDTH=12 ENTWIDTH=8 USAGE=out>Date
<DTAFLD DATAVAR=cardno PMTWIDTH=12 ENTWIDTH=7 DESWIDTH=25>Card No
<DTAFLDD>(A 7-digit number)
<DTAFLD DATAVAR=name PMTWIDTH=12 ENTWIDTH=25 DESWIDTH=25>Name
<DTAFLDD>(Last, First, M.I.)
<DTAFLD DATAVAR=address PMTWIDTH=12 ENTWIDTH=25>Address
<DIVIDER>
<REGION DIR=horiz>
<SELFLD NAME=cardsel PMTWIDTH=30 SELWIDTH=38>Choose
one of the following
<CHOICE CHECKVAR=card MATCH=new>
New Type:
<CHOFLD datavar=cardtype autotab=yes entwidth=9>
(Permanent or Temporary)
<CHOICE CHECKVAR=card MATCH=renew>Renewal
<CHOICE CHECKVAR=card MATCH=replace>Replacement
</SELFLD>
<DTACOL>
<SOURCE>
IF (&CARDSEL = 1)
VER(&CARDTYPE,NB,LIST,TEMPORARY,PERMANENT)
</SOURCE>
</DTACOL>
<SELFLD TYPE=multi PMTWIDTH=30 SELWIDTH=25>Check valid branches
<CHOICE NAME=north HELP=nthhlp CHECKVAR=nth>North Branch
<CHOICE NAME=south HELP=sthhlp CHECKVAR=sth>South Branch
<CHOICE NAME=east HELP=esthlp CHECKVAR=est>East Branch
<CHOICE NAME=west HELP=wsthlp CHECKVAR=wst>West Branch
</SELFLD>
</REGION>
</AREA>
<CMDAREA>Enter a command
</PANEL>
Figure 1. Choice
data fields File Search Help
--------------------------------------------------------------------------
Library Card Registration
Type in patron's name and card number (if applicable).
Then select an action bar choice.
Date . . . :
Card No. . . _______ (A 7-digit number)
Name . . . . _________________________ (Last, First, M.I.)
Address . . _________________________
Choose one of the following Check valid branches
__ 1. New Type: Z _ North Branch
(Permanent or Temporary) _ South Branch
2. Renewal _ East Branch
3. Replacement _ West Branch
Enter a command ===> ______________________________________________________
F1=Help F2=Split F3=Exit F6=KEYSHELP F9=Swap
F12=Cancel
|
z/OS ISPF Dialog Tag Language Guide and Reference
Copyright IBM Corporation 1990, 2014