DSPATR (Display Attribute) keyword for display files

You use this field-level keyword to specify one or more display attributes for the field that you are defining.

You can specify the DSPATR keyword more than once for the same field, and you can specify more than one attribute for the same keyword. However, each attribute (for example, UL), can be specified only once per field.

Note: The effects of attributes might not appear on the display, depending on the hardware or software emulator that you are using.

The format for the keyword is

DSPATR(attribute-1 [attribute-2 [attribute-3 [...]]])
or
DSPATR(&program-to-system-field);

If you specify more than one attribute for the same field, whether in one keyword or in separate keywords, each attribute that is specified (and in effect when the field is displayed) affects the field. For example, if you want a field to be displayed with its image reversed and with high intensity, specify either DSPATR (RI HI), or DSPATR(RI), and DSPATR(HI).

The program-to-system-field parameter is required and specifies that the named field must be defined in the record format, alphanumeric (A in position 35), length of one, and usage P (P in position 38). The program uses this P-field to set the display attribute for the field this DSPATR keyword applies to.

The name P-field is used for multiple fields with the record being defined. One DSPATR P-field is allowed per field. The P-field contains the display attribute and identifies whether the field should be protected. See Valid P-field values.

Valid attributes for the first format of the DSPATR keyword

The following list shows valid attributes for the first format of the DSPATR keyword:

  • For all fields
    Display attribute
    Meaning
    BL
    Blinking field
    CS
    Column separator
    HI
    High intensity
    ND
    Nondisplay
    PC
    Position cursor
    RI
    Reverse image
    UL
    Underline
  • For Input-Capable fields only
    Display attribute
    Meaning
    MDT
    Set changed data tag when displayed
    OID
    Operator identification
    PR
    Protect contents of field from input typing
    SP
    Select by light pen
Notes:
  1. If you specify the UL, HI, and RI attributes on the 5250 display station for the same field, the result is the same as if you had specified ND.
  2. If OID is specified, then SP should not be specified. Neither OID nor SP can be optioned unless specified with another display attribute.
  3. Display attributes BL, CS, HI, RI, and UL can also be specified at the file, record, or field level as parameter values on the CHGINPDFT keyword.
  4. Display attributes CS, HI, and BL can cause fields on the 5292, 3477 Model FC, 3487 Model HC, 3179, 3197 Model C1 and C2, and 34881 color display stations to appear as color fields.
  5. If you are using an IBM® Personal System/2 (PS/2) computer that is emulating a 5250 display station and you are directly changing the EBCDIC screen buffer, you need to set the MDT attribute. See the IBM Personal Computer Enhanced 5250 Emulation Program Technical Reference manual for additional information.
  6. If you are using a PS/2 computer and VGA monitor, the UL attribute does not work due to hardware specific limitations in the way buffers are used.

Option indicators are valid for this keyword, except when the attributes OID or SP are the only display attributes specified.

Detailed descriptions of each of the attributes follow the coding example and sample display are provided in the following figure.

Figure 1. A 5-byte field displayed with various display attributes
A 5-byte field displayed with various display attributes, described in the following text.

Display attributes for all fields

The following list shows attributes for all fields:

BL (Blink)
Use this attribute to specify that the field is to blink when it is displayed.
CS (Column separator)
Use this attribute to specify that each position of the field is to be displayed with a vertical bar at its left and right edge. When specified for a nondisplay field, the separators are displayed even though there are no characters between them. You can use column separators to precisely indicate cursor positioning within a field and to indicate the length of an otherwise blank field.
HI (High intensity)
Use this attribute to specify that the field is to be intensified (highlighted) when it is displayed on the display.
ND (Nondisplay)
Use this attribute to specify that the field is not to be displayed; the display positions for this field appear blank. The attribute can be used for passwords or other security-sensitive data. If the print function (permitted by specifying the PRINT keyword) is performed, nondisplay fields are not printed.
PC (Position cursor)
Use this attribute to position the cursor to the first character position of the field you are defining. You can specify this attribute for several fields, and the cursor will be positioned at the first selected field with this attribute. Note that the fields within a record are ordered in line/position sequence as they appear on the display and not necessarily in the order you specify them.
RI (Reverse image)
Use this attribute to specify that the image of the field is to be reversed from the other portion of the screen when it is displayed. Whether the screen is light-on-dark or dark-on-light depends on the status of the display before the field is displayed. This setting is controlled by the workstation user.
UL (Underline)
Use this attribute to specify that the field is to be underlined when it is displayed. All input-capable fields are underlined by default. Use the CHGINPDFT keyword to prevent the default underlining. (If CHGINPDFT is specified, DSPATR(UL) must be specified to underline an input-capable field.) If DSPATR(UL) is specified with option indicators and the option indicators are not satisfied (DSPATR(UL) is not selected), the field appears without underline.

Display attributes for input-capable fields

The following list shows attributes for input-capable fields:

MDT (Set changed data tag)
Use this attribute to specify that the IBM i operating system is to set on the changed data tag (MDT) for the field you are defining when the field is written to the display. The attribute ensures that the field is sent from the device when the record is read from the display.
Note: The IBM i program saves output data for input/output fields or initialized data for fields with the DFT keyword specified. This causes the saved data to be returned on an input operation if no new (changed) data is entered into the field.
OID (Operator Identification)

Use this attribute to specify that the IBM i operating system is to allow magnetic stripe reader OID data to be entered into this field. If it is to be a nondisplay field also, the DSPATR(ND) attribute must be specified.

A field with the DSPATR(OID) keyword functions like any other input-capable field; data can be entered from either the keyboard or the magnetic stripe reader. The DSPATR(OID) keyword can be specified (but is not required) to indicate that data can be entered using a magnetic stripe reader. You can type into the field unless the keyboard shift Inhibit Keyboard Entry (I) is specified. If both DSPATR(OID) and DSPATR(SP) are specified on the same field, DSPATR(SP) is ignored.

PR (Protect)
Use this attribute to specify that the workstation user cannot type into the input-capable field that you are defining. This attribute is valid for input-capable fields only. Output-only fields and constant fields are protected by definition.
SP (Select by light pen)

Use this attribute to specify that this input-capable field can be selected by a light pen. The workstation user can type in a light pen field unless an I (Inhibit Keyboard Entry) has been specified in position 35 (Data Type/Keyboard Shift) for the field.

When the field is first displayed, the contents of the field are set by your program (input/output field) or in the DDS (input-only field with DFT keyword or character string). If no new data is typed in by the workstation user, this output data is returned to your program on an input operation.

A field that can be selected by a light pen should be at least 3 bytes long. The recommended contents of this field are:
  • A switch character, either hex 6F (?) or, if the workstation user selects the field by a light pen, hex 6E (>)
  • A blank (hex 40)
  • A target character, which can be any character, such as an asterisk (*)
  • Another blank
  • Additional data to identify the field to the workstation user (1 or more characters)

This attribute is useful only for workstations with a light pen feature for selecting.

Valid P-field values

The DSPATR P-field does not support the following display attributes:

Display attribute
Meaning
MDT
Set changed data tag when displayed
OID
Operator identification
PC
Position cursor
SP
Select by light pen

Valid P-field values (nonprotect)

Hex Limited color Full color
20 Normal Green
21 Reverse image Green, reverse image
22 High intensity White
23 High intensity, reverse image White, reverse image
24 Underscore Green, underscore
25 Underscore, reverse image Green, underscore, reverse image
26 Underscore, high intensity White, underscore
27 Nondisplay Nondisplay
28 Blink Red
29 Blink, reverse image Red, reverse image
2A Blink, high intensity Red, high intensity
2B Blink, high intensity, reverse image Red, high intensity, reverse image
2C Blink, underscore Red, underscore
2D Blink, underscore, reverse image Red, underscore, reverse image
2E Blink, underscore, high intensity Red, underscore, blink
2F Nondisplay Nondisplay
30 Column separator Turquoise, column separator
31 Reverse image, column separator Turquoise, column separator, reverse image
32 High intensity, column separator Yellow, column separator
33 High intensity, reverse image, column separator White, reverse image, column separator
34 Underscore, column separator Turquoise, underscore, column separator
35 Underscore, reverse image, column separator Turquoise, underscore, reverse image, column separator
36 Underscore, high intensity, column separator Yellow, underscore, column separator
37 Nondisplay Nondisplay
38 Blink, column separator Pink
39 Blink, reverse image, column separator Pink, reverse image
3A Blink, high intensity, column separator Blue
3B Blink, high intensity, reverse image, column separator Blue, reverse image
3C Blink, underscore, column separator Pink, underscore
3D Blink, underscore, reverse image, column separator Pink, underscore, reverse image
3E Blink, underscore, high intensity, column separator Blue, underscore
3F Nondisplay Nondisplay

Valid P-field values (protect)

Table 1. P-field values (protect)
Hex Limited color Full color
A0 Normal Green
A1 Reverse image Green, reverse image
A2 High intensity White
A3 High intensity, reverse image White, reverse image
A4 Underscore Green, underscore
A5 Underscore, reverse image Green, underscore, reverse image
A6 Underscore, high intensity White, underscore
A7 Nondisplay Nondisplay
A8 Blink Red
A9 Blink, reverse image Red, reverse image
AA Blink, high intensity Red, high intensity
AB Blink, high intensity, reverse image Red, high intensity, reverse image
AC Blink, underscore Red, underscore
AD Blink, underscore, reverse image Red, underscore, reverse image
AE Blink, underscore, high intensity Red, underscore, blink
AF Nondisplay Nondisplay
B0 Column separator Turquoise, column separator
B1 Reverse image, column separator Turquoise, column separator, reverse image
B2 High intensity, column separator Yellow, column separator
B3 High intensity, reverse image, column separator White, reverse image, column separator
B4 Underscore, column separator Turquoise, underscore, column separator
B5 Underscore, reverse image, column separator Turquoise, underscore, reverse image, column separator
B6 Underscore, high intensity, column separator Yellow, underscore, column separator
B7 Nondisplay Nondisplay
B8 Blink, column separator Pink
B9 Blink, reverse image, column separator Pink, reverse image
BA Blink, high intensity, column separator Blue
BB Blink, high intensity, reverse image, column separator Blue, reverse image
BC Blink, underscore, column separator Pink, underscore
BD Blink, underscore, reverse image, column separator Pink, underscore, reverse image
BE Blink, underscore, high intensity, column separator Blue, underscore
BF Nondisplay Nondisplay

Example 1

The following example shows how to specify the DSPATR(SP) keyword with an input-only field (showing the recommended data contents as a character string).

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00110A            SPFLD         50I  I  5  4'? * OPTION 1'
00120A                                      DSPATR(SP)
     A

No data can be typed into field SPFLD. When the field is selected with the light pen, the data returned in field SPFLD will be: >_*_OPTION_1, where _ represents a blank.

Example 2

The following example shows that when the workstation user selects a field with the light pen, both the MDT bit and the first character of that field are changed. When the field is selected, the MDT bit is set on, changing the first character of the field to >. If the same field is selected again, the MDT bit is set off and the first character becomes ?.

By specifying a switch character, your program prevents the first character of data from being changed to > or ? when the field is selected by the light pen. If the MDT bit is on when your program sends an input operation to the record format, the contents of the field are returned to your program as a user-changed field.

If you use DSPATR(MDT) to set on the MDT of a field that can be selected by the light pen, then you should either omit the MDTOFF keyword from other record formats, or read that field before displaying any record format with MDTOFF in effect.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A          R LIGHTPEN
00020A            FLD1          10   I  5  2'> * $12.50'
00030A                                      DSPATR(SP MDT)
00040A*
00050A          R RCD2                      OVERLAY MDTOFF
00060A            FLD1          10   B 11  2
     A

If the program displays LIGHTPEN, then displays RCD2, then reads LIGHTPEN, and the workstation user does not select FLD1 with the light pen, the MDT of FLD1 is turned off by the display of RCD2.

Also, the switch character of FLD1 is returned as ?, even though the field was not selected, and the switch character appears as >. The MDT and the switch character are in opposing states.

Example 3

The following example shows how to specify the DSPATR keyword with P-field usage:

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A          R RECORD                   
     A            FLD1           5A     2  6DSPATR(&PFLD1)
     A            FLD2           5A     2  6DSPATR(&PFLD2)
     A            PFLD1          1A  P
     A            PFLD2          1A  P
     A
1 Dependent on the monitor attached to the display device.