Formatting attribute section statements

EXTEND

Specifies whether the depth of an area can be automatically increased.

ON

Specifies that the depth (number of lines) of an area can be automatically increased, if required, so that the depth of the entire body of the panel matches the depth of the physical screen on which it is being displayed. Accordingly, an extendable area can be designated in the panel definition by a single line unless text or other fields are to appear along the graphic area. Only one extendable area can be specified in a panel definition.

Note: Using EXTEND(ON) is not recommended if your dynamic area is displayed in a pop-up. When EXTEND(ON) is used, the panel is extended to the size of the logical screen. If the panel is then displayed in a pop-up, the panel may be truncated at the pop-up border.

The value for the EXTEND keyword cannot be specified as a dialog variable.

OFF

The default. Specifies that the depth (number of lines) of an area cannot be automatically increased.

SCROLL

Specifies whether the area can be treated as a scrollable area.

ON

Specifies that the area can be treated as a scrollable area. When a panel containing a scrollable area is displayed, the scrolling commands are automatically enabled. Only one scrollable area can be specified in a panel definition.

The value for the SCROLL keyword cannot be specified as a dialog variable.

A panel cannot have more than one scrollable area or more than one extended area.

A panel displayed using TBDISPL cannot have a dynamic area defined by SCROLL ON.

Although the panel display service does not perform the scrolling, it does provide an interpretation of the user's scroll request.

OFF

The default. Specifies that the area cannot be treated as a scrollable area.

USERMOD(usermod-code) and DATAMOD(datamod-code)

Specifies a character or two-position hexadecimal value to be substituted for attribute characters in a dynamic area variable following a user interaction. The attribute characters used within the dynamic area are intermixed with the data. These attribute characters designate the beginning of a new data field within the area. When the dynamic area variable is returned to the dialog, usermod-code and datamod-code are used to replace the attribute character of each field that has been modified, according to these rules:

• USERMOD specified but DATAMOD not specified

  If there has been any user entry into the field, even if the field was overtyped with identical characters, the attribute byte for that field is replaced with usermod-code.

• DATAMOD specified but USERMOD not specified

  If there has been any user entry into the field, and if the value in the field has changed, either by the user entry or by ISPF capitalization or justification, the attribute byte for that field is replaced with datamod-code.

• Both USERMOD and DATAMOD specified If there has been any user entry into the field but the value in the field has not changed, the attribute byte for that field is replaced with usermod-code.

  If there has been any user entry into the field and the value in the field has changed, either by the user entry or by ISPF capitalization or justification, then the attribute byte for that field is replaced with datamod-code.

• Neither DATAMOD nor USERMOD specified

  The attribute byte for the field is unchanged.

You can specify more than one dynamic area on a panel. The number of dynamic areas in a panel definition is limited only by physical space limitations of the particular terminal being used for the display.

)ATTR
  # AREA(DYNAMIC) EXTEND(ON) USERMOD(!)

)ATTR
  # AREA(DYNAMIC) EXTEND(ON) DATAMOD(01)

)ATTR
  # AREA(DYNAMIC) EXTEND(ON) USERMOD(0C) DATAMOD(03)

blank < ( + | ) ; ¬ - , > : =

EXTEND

Specifies whether the depth of an area can be automatically increased.

ON

Specifies that the depth (number of lines) of an area can be automatically increased, if required, so that the depth of the entire body of the panel matches the depth of the physical screen on which it is being displayed. Accordingly, an extendable area can be designated in the panel definition by a single line unless text or other fields are to appear along the graphic area. Only one extendable area can be specified in a panel definition.

Note: Using EXTEND(ON) is not recommended if your graphic area is displayed in a pop-up. When EXTEND(ON) is used, the panel is extended to the size of the logical screen. If the panel is then displayed in a pop-up, the panel may be truncated at the pop-up border.

The value for the EXTEND keyword cannot be specified as a dialog variable.

OFF

The default. Specifies that the depth (number of lines) of an area cannot be automatically increased.

A graphic attribute character cannot have any other attribute properties. For example, it cannot be mixed with attributes such as INTENS, CAPS, JUST, or PAD.

These rules are applied in Figure 1.

)ATTR
 *  AREA(GRAPHIC)
)BODY
%------------------- TITLE -------------------
%COMMAND ===>_ZCMD                           %
%
+  (Text or other fields that are part of the
+   normal panel body ... )
+ 
+   +*PICT1 ----------------------------*
     *                                  *
     *                                  *
     *                                  *
     *                                  *
     *                                  *
     *                                  *
     * ---------------------------------*
)END

In this example, a graphic area is defined. PICT1 is specified as the name of the area. An asterisk (*) is the delimiter character for the vertical sides of the area, and hyphens (-) are the delimiter character for the top and bottom. Note that a blank follows the area name and follows all asterisks (*) other than the asterisk adjacent to PICT1.

Figure 2 and Figure 3 are examples of panel definitions with a graphic area. In Figure 3, note that the alphanumeric field INPUT1 starts at '_' and ends at '|'.

)ATTR
 * AREA(GRAPHIC)

)BODY
%             MY COMPANY OPTION PANEL
% Your selection ==>_ZCMD                          + 
+ 
+  1 Our application 1      +*LOGO ----------------*
+  2 Our application 2      +*                     *
+  3 Our application 3      +*                     *
+  4 Our application 4      +*                     *
+  5 Our application 5      +*                     *
+                           +*                     *
+  X Exit                   +* --------------------*
+  T Tutorial                   <--- Graphic  Area --->
)END

)ATTR
 | AREA(GRAPHIC)

)BODY
%       Panel with Overlapping text field
%
% Here is the data as a graph and with editorial text:
+ 
     +|PIC1 ------------|
      |                 |
      |                 |
      |                 |
      |                 |
  _INPUT1    |          |
      |                 |
      | ----------------|

%        <- graphic area  ->
)END

EXTEND

Specifies whether the depth of an area can be automatically increased.

ON

Specifies that the depth (number of lines) of an area can be automatically increased, if required, so that the depth of the entire body of the panel matches the depth of the physical screen on which it is being displayed. Accordingly, an extendable area can be designated in the panel definition by a single line unless text or other fields are to appear along the graphic area. Only one extendable area can be specified in a panel definition.

Note: Using EXTEND(ON) is not recommended if your scrollable area is displayed in a pop-up. When EXTEND(ON) is used, the panel is extended to the size of the logical screen. If the panel is then displayed in a pop-up, the panel may be truncated at the pop-up border.

The value for the EXTEND keyword cannot be specified as a dialog variable.

OFF

The default. Specifies that the depth (number of lines) of an area cannot be automatically increased.

ON

Specifies that the field can be selected by using the cursor select key.

OFF

The default. Specifies that the field cannot be selected in this manner.

ON

Data is translated to uppercase before being displayed and all input fields are translated to uppercase before being stored.

OFF

Data is displayed as it appears in the variable pool and all input fields are stored as they appear on the screen.

IN

Data is displayed as it appears in the variable pool, but all input fields on the screen are translated to uppercase before being stored.

OUT

Data is translated to uppercase before being displayed. All input fields are stored as they appear on the screen.

Unless you specify a CONTROL ASIS command procedure (CLIST) statement, the use of CAPS(OFF), CAPS(IN), and CAPS(OUT) is negated if the dialog variable is referred to in the command procedure.

If the check box input field is not blank, the check box is initialized as selected (checked). If the check box is selected, a slash character (/) is placed in the check box input field when the panel is processed.

The CKBOX keyword is ignored if the input field is greater than one character, or if the field following the check box field is not a protected field. An error message is issued if the CKBOX keyword is used on any fields other than input fields, or the selected choice (SC) output field.

)ATTR
@ TYPE(CEF) CKBOX(ON)
$ TYPE(SAC)
)BODY
% -------- CHECK BOX PANEL ---------- +

+  Select options:
   &INSTR+
   @Z$Check box #1 description+
   @Z$Check box #2 description+
   @Z$Check box #3 description+
   @Z$Check box #4 description+

)INIT
 .ZVARS = '(BOX1 BOX2 BOX3 BOX4)'
 IF (&ZGUI = ' ')
   &INSTR = 'Enter '/'' to select option.'
 ELSE
   &INSTR = 'Check box to select option.'
)END

If a color has been specified and the panel is displayed on a terminal other than one with features such as those on the 3279-B, then:

• If an explicit intensity has also been specified for the field, the color specification is ignored. For example:

  )ATTR
    @ TYPE(INPUT) INTENS(HIGH) COLOR(YELLOW)

  In this example, COLOR(YELLOW) is ignored except on terminals like the 3279-B. On a 3279-A terminal, for example, the resulting color is red.

• If an explicit intensity has not been specified for the field, the color is used to generate a default intensity. Specification of blue, green, or turquoise defaults to low intensity. Specification of red, yellow, pink, or white defaults to high intensity. For example:

  )ATTR
    $ TYPE(OUTPUT) COLOR(GREEN)

  In this example, a low-intensity output field results.

• If neither color nor intensity has been specified for a field, the default intensity is HIGH.

The COMBO attribute keyword is valid on input type fields only. The combination box combines the functions of an entry field and a drop-down list (see DDLIST Keyword). It has an entry field and contains a list of choices that you can scroll through to select from to complete the entry field. The list of choices is hidden until you take an action to make the list visible. As an alternative, you can type text directly into the entry field. The typed text does not need to match one of the choices in the list.

The width of the input field determines the width of the combination box. If a COMBOBOX field is immediately followed by three or more consecutive attributes, the COMBOBOX will be displayed for the entire length of the field, since the three attributes allow space for the COMBOBOX button without overlaying data in the next field. If a COMBOBOX field is not followed by three or more consecutive attributes, the COMBOBOX will be displayed for the length of the field, to avoid overlaying data in the next field, but the COMBOBOX field will scroll to the right so that the user will be able to type in more than enough data to fill the field.

On the host, the application must be made to implement this function. One method to do this is to code the input field with a field-level help panel containing a scrollable list of choices.

The COMBO keyword must be used in conjunction with the CSRGRP(x) keyword. The CSRGRP(x) keyword must appear on the CEF field that is used to enter the selection on the host, and on the SAC field that identifies the choices in the list. The x value is a number that ties the choices to the correct input field, which has the same COMBO keyword and CSRGRP(x) number.

attribute-char TYPE(input) COMBO(ON|OFF|name) CSRGRP(x) DEPTH(d)

The TYPE value must be an input type field. The DEPTH(d) sets the number of rows for the combination box. Values can be from 0 to 99. For example, if you specify DEPTH(8), the combination box contains eight rows of data. If the depth specified is 0, or if the depth is not specified, the default depth is 4.

attribute-char TYPE(PS) CSRGRP(x)
attribute-char TYPE(OUTPUT) PAS(ON) CSRGRP(x)
attribute-char TYPE(CEF) CKBOX(ON) CSRGRP(x)

All pushbuttons and checkbox fields that do not have a CSRGRP defined do not have a cursor group set in GUI mode, which has the same effect as having them all in the same cursor group.

The DDLIST keyword must be used in conjunction with the CSRGRP(x) keyword (see "CSRGRP(x)"). The CSRGRP(x) keyword must appear on the CEF field that is used to enter the selection on the host, and on the SAC field that identifies the choices in the list. The x value is a number that ties the choices to the correct input field, which has the same DDLIST keyword and CSRGRP(x) number.

You can define a DDLIST with or without a (LIST section. For more information see:

• Defining a DDLIST without a )LIST section
• Defining a DDLIST with a )LIST section

EBCDIC

EBCDIC characters only

DBCS

DBCS characters only

MIX

EBCDIC and DBCS characters

In a FORMAT(MIX) field, any DBCS character string must be enclosed by a shift-out (hexadecimal 0E) and a shift-in (hexadecimal 0F).

The default value for a TYPE(INPUT) and a TYPE(DATAIN) field is FORMAT(EBCDIC). These two default values can be changed by using the )ATTR statement or the )BODY statement. These values, in turn, can be overridden if explicitly specified on a subsequent statement. For example, the net result of these two statements is FORMAT(DBCS):

)ATTR FORMAT(MIX) $ TYPE(INPUT) FORMAT(DBCS)

The default value for a TYPE(TEXT) and a TYPE(OUTPUT) field is FORMAT(MIX). The format of a TYPE(TEXT) field cannot be overridden by the execution of an .ATTR or .ATTRCHAR statement. Attempting to do so results in a dialog error.

The pad character for a DBCS field is converted to the corresponding 16-bit character and is then used for padding. Other format fields are padded normally.

The CAPS attribute is meaningful only for EBCDIC and MIX fields. In addition, within a MIX field, the CAPS attribute applies only to the EBCDIC subfields.

If GE(ON) is specified on TYPE(ABSL), TYPE(WASL), or TYPE(CH), and if the characters following these TYPE's in the panel definition are dashes (-) or vertical bars (|), then the appropriate APL character will be used. This results in these panel elements displaying as solid horizontal or vertical lines, instead of broken lines.

For more information about the GE keyword support on TYPE(CHAR) within a dynamic area, see Specifying character attributes in a dynamic area.

USCORE

Underscore

BLINK

Blinking

REVERSE

Reverse video

No default is assumed if highlighting is not specified. When you are running in GUI mode, the HILITE keyword is ignored.

HIGH

High-intensity field

LOW

Low-intensity (normal) field

NON

Nondisplay field

You can specify these operands for the basic attribute types (TEXT|INPUT|OUTPUT). NEF is the only CUA panel-element type that supports the INTENS(NON) operand. The remaining CUA panel-element types do not allow the COLOR, INTENS, and HILITE keyword default values to be changed. The NON operand allows you to optionally display comments or directive lines.

For a panel displayed on a color terminal, you can also use the INTENS keyword to generate a default color for the field, as described for the COLOR keyword. INTENS(HIGH) and INTENS(LOW) are ignored for a 3290 terminal and in GUI mode.

LEFT

Left justification

RIGHT

Right justification

ASIS

No justification

Justification occurs if the initial value of a field is shorter than the length of the field as described in the panel body. Normally, right justification should be used only with output fields, since a right-justified input field would be difficult to type over.

For LEFT or RIGHT, the justification applies only to how the field appears on the screen. Leading blanks are automatically deleted when the field is processed. For ASIS, leading blanks are not deleted when the field is processed, nor when it is initialized. Trailing blanks are automatically deleted when a field is processed, regardless of its justification.

The LISTBOX keyword can have one of these values:

ON

Specifies a single selection list to display as a list box when running in GUI mode.

OFF

Specifies a single selection list is NOT to display as a list box when running in GUI mode. This is the default setting.

name

Specifies a name that is matched with the )LIST section name parameter (see Defining the LIST section). This name is valid only on a CEF or other input type field. The name can be 1 to 8 characters long. Alphanumeric characters A-Z, a-z, 0-9, #, $, or @ can be used in the name, but the first character cannot be numeric. Lowercase characters are converted into uppercase equivalents.

The LISTBOX keyword must be used with the CSRGRP(x) keyword (see CSRGRP(x)). The CSRGRP(x) keyword must appear on the CEF field that is used to enter the selection on the host, and on the SAC field that identifies the choices in the list. The x value is a number that ties the choices to the correct input field, which has the same LISTBOX keyword and CSRGRP(x) number.

You can define a LISTBOX with or without a (LIST section. For more information see:

• Defining a LISTBOX without a )LIST section
• Defining a LISTBOX with a )LIST section

ON

Specifies that the jump function is disabled and the data entered is passed to the dialog as it was entered.

OFF

Specifies that the jump function is enabled for fields with field prompts of ==> and for fields with field prompts of leader dots (. . or ...) provided that "jump from leader dots" is set to YES in the Configuration table or selected in the Settings panel. This is the default.

ON

Specifies that the Numeric Lock feature is to be activated. The terminal keyboard locks if the operator presses any key other than 0 through 9, minus(-), period (.), or duplicate (DUP). ON is valid only for unprotected fields.

OFF

Specifies that the Numeric Lock feature is not to be activated. The user can type in any characters. NUMERIC(OFF) is the default value.

On a data-entry keyboard with the Numeric Lock feature, when the user moves the cursor into a field defined by the NUMERIC(ON) attribute keyword, the display shifts to numeric mode. If the user presses any key other than those allowed by the Numeric Lock feature, the DO NOT ENTER message displays in the operator information area and the terminal is disabled. The user can continue by pressing the reset key.

NUMERIC(ON) and SKIP(ON) attributes cannot be specified for the same field. If attempted, ISPF issues an error message.

The NUMERIC(ON) attribute is not supported when GDDM is active.

When running in GUI mode, any panel field defined as NUMERIC(ON) is verified at the workstation. That is, only numeric characters 0 through 9 and special characters comma (,), dash (-), and period (.) are accepted in a numeric only defined field.

L

Line to the left side of the field

R

Line to the right side of the field

O

Line over the field

U

Line under the field

BOX

Line surrounding the field (equivalent to LROU)

NONE

No lines

You can specify any combination of the L, R, O, or U parameters in any order, without intervening blanks.

)ATTR OUTLINE(U)
  @ TYPE(INPUT) OUTLINE(BOX)

char

Any character, including blank (' '), can be specified as the padding character. If the character is any of these, it must be enclosed in single quotes:

blank < ( + ) ; ¬ , > : =

If the desired pad character is a single quote, use four single quotes: PAD('''').

NULLS

Nulls are used for padding.

USER

Padding character is specified by a user through the ISPF Settings panel.

If the field is initialized to blanks or the corresponding dialog variable is blank, the entire field contains the pad character when the panel is first displayed. If the field is initialized with a value, the remaining field positions, if any, contain the pad character.

Padding and justification work together as follows. At initialization, unless you have specified ASIS, the field is justified and then padded. For left-justified and ASIS fields, the padding extends to the right. For right-justified fields, the padding extends to the left.

In no case does ISPF delete embedded pad characters. It deletes only leading or trailing pad characters.

char

Any character, including blank (' '), can be specified as the padding character. If the character is any of these, it must be enclosed in single quotes:

blank < ( + ) ; ¬ , > : =

If the desired pad character is a single quote, use four single quotes: PADC('''').

NULLS

Nulls are used for padding.

USER

Specifies that a user-defined character be used for padding. You define the character by using the ISPF Settings panel. PAD and PADC are incompatible. It is not valid to specify both PAD and PADC for the same attribute character.

If PADC is omitted, the default is PADC(USER) for input fields.

ISPF initially sets the radio button in the group that corresponds to the value in the CEF field. If the CEF field is blank or the value in the field does not correspond with any of the radio button selections, then no radio button is set by default. ISPF then uses the characters following the SAC attribute to set the value into the CEF field with the same CSRGRP(x) number.

The CEF field must be no more than 3 characters, because only 3 characters are checked and set for the CEF fields processed as radio buttons. If the text following the SAC attribute is longer than 3 characters, or longer than the value in the CEF field, then the text is truncated to the size of the CEF field or 3 characters, whichever is smaller when the radio button corresponding to that choice is selected. Periods at the end of the string are ignored.

attribute-char TYPE(CEF) RADIO(ON/OFF) CSRGRP(x)
attribute-char TYPE(SAC) RADIO(ON/OFF) CSRGRP(x)

)ATTR
@ TYPE(CEF) RADIO(ON) CSRGRP(1)
$ TYPE(SAC) RADIO(ON) CSRGRP(1)
! TYPE(CEF) RADIO(ON) CSRGRP(2)
^ TYPE(SAC) RADIO(ON) CSRGRP(2)
#TYPE(SAC)
)BODY
% -------- Radio Button PANEL ---------- +

+Terminal Characteristics:
  +Screen format  @Z $1.#Data+  $2.#Std+   $3.#Max+   $4.#Part+

  +Terminal Type  !Z ^1.#3277+  ^3.#3278+  ^5.#3290A+ ^7.#3278CF+
                     ^2.#3277A+ ^4.#3278A+ ^6.#3278T+ ^8.#3277KN+
)END
 

You can specify any replacement character, but those that must be enclosed in single quotes are as follows: < > ( ) + ; : , = blank.

Replacement characters are defined in the attribute section. Then, in the body section of the panel definition, a record containing only the defined attribute replacement characters is inserted immediately below any field defined by a corresponding statement in the attribute section. Each replacement character must be in the same column position as the attribute character position in the field above.

When the panel definition, for example, is viewed for editing, the data field and the characters that replace the attribute positions are both displayed. However, when the panel is displayed, the record containing the replacement characters is not displayed.

Any character immediately above an attribute replacement character in the panel definition is overlaid by the attribute character's hexadecimal code, not by the displayable replacement character.

In the example shown, hexadecimal codes 38, 31, 32, and 34 are in the field attribute positions when the panel is displayed. Because these codes are not visible on a display, replacement characters *, !, $, and # are specified for viewing the panel definition.

When the panel is displayed, the attribute position above the asterisk (*) contains hexadecimal 38; the one above the exclamation marks (!) contain hexadecimal 31; the one above the dollar sign ($) contains hexadecimal 32, and the one above the number sign (#) contains hexadecimal 34. None of these attribute characters is visible on the display, and the panel definition record containing the replacement characters is not displayed.

The field attribute positions on the panel definition can contain any character, illustrated as x in the example shown, because they are overlaid by the replacement characters when the panel is displayed.

)ATTR
  38 TYPE(INPUT) FORMAT(DBCS) REP(*)
  31 TYPE(INPUT) FORMAT(EBCDIC) REP(!)
  32 TYPE(TEXT) FORMAT(EBCDIC) REP($)
  34 TYPE(TEXT) FORMAT(MIX) REP(#)

)BODY
  + DBCS input field %===>x VARDBCS +
                          *

  [DBDBDBDBDBDBDBDBDB]===>x VAREBC  +
  #                  $    !

Any characters used to replace shift-out or shift-in characters must be less than hexadecimal 40 and must not be hexadecimal 00, 0E, or 0F.

The EXPAND keyword cannot be used for records containing only those characters defined by the REP keyword.

ON

Specifies that the cursor automatically skips the field. When a character is entered into the last character location of the preceding unprotected data field, ISPF positions the cursor at the first character location of the next unprotected field.

OFF

Specifies that the cursor does not automatically skip the field when the condition described for SKIP(ON) occurs.

The UNAVAIL attribute keyword can also be used with the LISTBOX, DDLIST, and COMBO attribute keywords on choices specified in the )LIST section to show the availability of a choice.

In GUI mode, if a LISTBOX, DDLIST, or COMBO choice is set as unavailable, that choice does not appear in the LISTBOX, DDLIST, or COMBO list of choices.

ON

Specifies that the choice is not available. In GUI mode this means that the choice cannot be selected in the current context. In host mode, you can still select the choice. It is up to the application you are running to display an error message or ignore the choice. You can use the VER statement keywords LISTX or LISTVX to handle an unavailable choice selection.

OFF

Specifies the choice is available and can be selected. This is the default setting.