CLRL (Clear Line) keyword for display files

See the Application Display Programming book for information about how to use CLRL in files that are used in the System/36 environment.

The format of the keyword is:

CLRL(nn|*END|*NO|*ALL)

You can specify the CLRL keyword in one of the following ways:

• Specify nn, where nn is an integer between 1 and 27. The number specified is the number of lines cleared, starting with and including the first line on which the record is to be displayed. If the SLNO (Starting Line Number) keyword is also specified for this record format, the clearing of lines begins with the starting line number in effect for the record format at the time it is displayed.
  Note: When you specify nn, the record must have at least one field defined.
• Specify *END to indicate that all lines starting with and including the first line on which the record is to be displayed are to be cleared. For a 24 x 80 display, lines up to and including line 24 are cleared. For a 27 x 132 display, lines up to and including line 27 are cleared.
• Specify *NO so that no lines on the display are cleared before displaying the record whose format you are defining. The displayed record overlays any data already on the display.
• Specify *ALL so that all of the lines on the display are cleared before displaying the record whose format you are defining. At least one field must be defined in the record format.

When a record format begins with a field in position 1, the beginning attribute byte of the format is in the last position of the previous line. The previous line number is the starting line number in the format. This also applies to a SLNO format with a field defined in the DDS in line 1, position 1.

If the record format for which the CLRL keyword is specified has one or more input-capable fields, any records that are overlaid are no longer recognized by the IBM i operating system. That is, any input-capable fields can no longer be typed into, any input operation written to one of those records results in an error, and they cannot be cleared by selecting the ERASE keyword.

If you specify the CLRL(nn) keyword in a record format without input-capable fields, the input-capable fields in the overlapped records remain input-capable. That is, input-capable fields in the overlaid records remain input-capable, and input operations written to those record formats are still valid. If the ROLLUP or ROLLDOWN keywords are specified on the record containing the CLRL keyword, they are ignored. Records with the CLRL keyword and no input-capable fields are not cleared properly when they are overlaid by other records that have the OVERLAY keyword specified. The lines needed for the overlapping record are cleared and the lines not needed for the overlapping record remain on the display.

You can use the CLRL(*NO) keyword to prevent an overlapped record from being cleared when the overlapping record is written to the display. If you use this keyword, any records being displayed that are to be overlapped are not cleared from the display. The new record overlays them entirely or partially. There is a performance advantage to using CLRL(*NO) if you have a display containing constants and data that is repeatedly sent to the display. Sending constants as a separate format and using the CLRL(*NO) keyword for the format containing the data reduces the time required to send the record format to the display.

If the CLRL keyword is not specified and neither OVERLAY nor PUTOVR (Put with Explicit Override) is specified, the entire display is cleared.

If the CLRL keyword is used and the PUTOVR or PUTRETAIN keyword is in effect, the clearing of any lines might conflict with the PUTOVR or PUTRETAIN function. The PUTOVR or PUTRETAIN keyword requires that the fields being overridden be on the display, while the CLRL(nn) or CLRL(*END) keyword clears those fields first. If a record becomes unavailable for input because of the CLRL(nn) or CLRL(*END) keyword, the input-capable fields remain input-capable if the PUTOVR keyword is in effect. However, the IBM i operating system sends a message if the program attempts to read such a record.

If you specify the CLRL keyword, you should also specify RSTDSP(*YES) on the Create Display File (CRTDSPF) or Change Display File (CHGDSPF) command. Otherwise, data on the display can be lost if the file is suspended.