DSPSIZ (Display Size) keyword for display files

You use this file-level keyword to specify the display size to which your program can open the display file.

The formats of the keyword are:

DSPSIZ(*DSw [*DSx])
DSPSIZ(lines positions[condition-name-1][lines positions[condition-name-2]])

The DSPSIZ keyword is optional. If you do not specify it for a display file, the display file can be opened only to display devices with a 24 x 80 display size. You can specify this keyword in one of two ways:

  • Using IBM-supplied display size condition names. Specify up to two parameter values as *DS3 or *DS4 in any order. At least one parameter value is required. You cannot specify a parameter value twice.
  • Specifying lines and positions to permit user-defined display size condition names. Instead of the IBM-supplied display size condition names, specify the display size in lines and positions (only 24 x 80, and 27 x 132 are valid). (See examples 1, 2, and 3, in this topic.)

    Optionally, you can also define a display size condition name other than *DS3 or *DS4. The display size condition name you define must be from 2 to 8 characters long, and the first character must be an asterisk (*). You can specify these user-defined condition names in positions 7 through 16 (conditioning) on subsequent DDS statements at the field level. (See example 2, in this topic.) If you do not specify user-defined display size condition names, you must use IBM-supplied display size condition names to condition the location of fields.

    If you specify more than one parameter value, see Primary and secondary display sizes.

Option indicators are not valid for this keyword.

Primary and secondary display sizes

Whether you use IBM-supplied display-size condition names or specify lines and positions directly, the first display size you specify is the primary display size. The second display size, if specified, is the secondary display size. Figure 1 shows an example of primary and secondary display size specification. This figure shows the keyword specified as DSPSIZ(24 80 27 132). The primary display size is 24 by 80; the secondary display size is 27 by 132.

Figure 1. Using DSPSIZ to specify primary and secondary display sizes
A figure showing the DSPSIZ keyword specified as DSPSIZ(24 80 27 132).

When you specify more than one display size for DSPSIZ, you can specify display size condition names in positions 7 through 16 on subsequent DDS statements at the record and field levels. These display size condition names are then used to condition keywords and the locations of fields. When both a primary and secondary display are specified, the display file will be validated for both sizes.

Note: If you specify user-defined display size condition names for DSPSIZ, you cannot use IBM-supplied display size condition names for conditioning.

The capability to display in the 27 x 132 mode is allowed only on a 3180-2, or a 3197 Model D1, D2, W1, or W2 device attached locally to a 6040 or 6041 controller or remotely to a 5294 or 5394 controller. The display size for the 27 x 132 mode will be ignored for DSPSIZ unless these controllers are used.

The following table shows the valid display sizes.

Display sizes Display device Meaning
*DS3 or 24 x 80 3179 3180 3196 3197 3476 3486 3487 (Models HA, HC, HG, and HW) 3488 5251 (Models 11 and 12) 5291 5292 24 lines x 80 positions 1920 positions total
*DS4 or 27 x 132 3180 3197 (Models D1, D2, W1, and W2) 3477 (Models FA, FC, FD, and FG) 3487 (Models HA, HC, HG, and HW) 3488 (Use 6040 or 6041 controller locally, or 5294 or 5394 controller remotely for 27 x 132 display capability.) 27 lines x 132 positions 3564 positions total

The display size designated as the primary display size should be the one with which the display file will most often be used. Additional processing is performed when the actual display size is the secondary display size.

The display size condition names let you improve the use of a single display file for any size display. For example, when you are using subfiles, you can specify 24 records per page for a 27 x 132 display and 22 records per page for a 24 x 80 display.

Special cases you might encounter when specifying DSPSIZ

You might encounter the following special cases when specifying DSPSIZ:

  • DSPSIZ(*DS3 *DS4). All field locations for display size *DS4 are the same as for display size *DS3.
  • All fields of a record can be defined such that none fit on the display size to which the file is opened. In this case, no fields are displayed. The record is handled as it does for a larger display where the fields fit. The record remains active until it is deleted or overlaid. Active records can be read by your program. The input request is sent to the display device, and the workstation user must respond to satisfy the request.
  • All fields of a subfile record must fit within the specified subfile page, and the complete page must always fit (vertically) on the display size on which it is displayed at processing time. Specify valid display sizes by conditioning the SFLPAG (Subfile Page) keyword with display size condition names.
  • The following records occupy no display space:
    • Records with no fields defined (this is different from none selected)
    • Records with only hidden, message, or program-to-system fields
    • Records that have the CLRL keyword specified and that have no input-capable fields. (These records can remain on the display, but are not recognized by the IBM® i operating system for input operations, or they can be cleared through the use of the ERASE keyword.)

    For implementation and programming purposes, these records are assumed to be located at 00 (from line 0 to line 0). On an output operation, any record located at 00 overlays a record at that location. When an overlap occurs, the previous record is disregarded and no longer considered active. The new record at location 00 is active and can be read by your program.

  • If two fields in a record format have the same display location (line/position), they are treated as overlapping fields. Overlapping fields are not displayed at operation time. The IBM i operating system checks each field as it is processed to ensure that it does not overlap a previously processed field.

    If a field does overlap, it is treated as an optioned field and not selected. To allow this processing-time checking, data description specifications must ensure all fields within a record are in primary location sequence, even when condition names are specified. For example, assume only one input field is specified for a record format and, according to the field location specification, this field overlaps a preceding output field. The workstation user cannot enter any data because the input field is never displayed.

Note: The primary location sequence as it is seen in the display file must not be changed by specifying a different location sequence for the secondary display size. (A severe error occurs and the file is not created.)

Example 1

The following example shows how to specify primary and secondary display sizes using the DSPSIZ keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A*
00020A*                                           1  2
00030A                                      DSPSIZ(27 132 24 80)
00040A          R RECORDA
00050A            FIELDA        10  0   1  2
00060A            FIELDB        10  0   1 81
00070A            FIELDC        10  0  25  1
     A

In this example, the primary display size 1 is 27 x 132 and the secondary display size 2 is 24 x 80. FIELDB is beyond position 80 and FIELDC is beyond line 24, so the data description processor gives them a location of *NOLOC in the expanded source printout for secondary display size 24 x 80.

If the data description processor assigns *NOLOC to an input-capable field, that field is processed at run time to the point of setting up the input buffer data to be returned in the user's input buffer. The field itself is not displayed. The workstation user cannot enter into or change these fields. No processing of any kind is done for output-only fields.

Figure 2 shows a compiler listing for the above example.

Figure 2. Compiler listing
A figure of the compiler listing produced for example 1.

Example 2

The following example is another example of specifying the primary and secondary display sizes using the DSPSIZ keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A                                      DSPSIZ(27 132 *WIDE 24 80 *NORMAL)
00020A          R RECORDA
00030A            FIELDA        10  0   1  2
00040A            FIELDB        10  0   1 81
00050A  *NORMAL                         1 50
00060A            FIELDC        10  0  25  1
00070A  *NORMAL                        23  1
     A

This example is similar to example 1 in that it specifies for FIELDB (line 1, position 50) and for FIELDC (line 23, position 1) on the secondary display size (user-defined as *NORMAL).

Example 3

The following example shows how to reposition a field when the file is opened to different display sizes.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A                                      DSPSIZ(24 80 27 132)
00020A          R RECORDA
00030A            FIELD1        10  0  23  2
00040A
00050A
00060A  *DS4                           26  2
     A

In this example, FIELD1 has valid locations on both display sizes. It appears on the next to the last line on each display size.

Example 4

The following example shows that if you do not specify a display size condition name, the display location of a field can still be display size dependent as the result of the plus feature of DDS.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00010A                                      DSPSIZ(*DS4 *DS3)
00020A          R RECORD1
00030A            FIELD1        21      2 70
00040A            FIELD2        10       +10
     A

In this example, a line and a position for each field is calculated for each display size specified on the DSPSIZ keyword. If the plus value extends the field location beyond position 80, the field location is dependent on the display size. Figure 3 is a compiler listing for the above example.

Figure 3. Compiler list
A figure of the compiler listing produced for example 4.