PUTRETAIN (Put-Retain) keyword for display files

Use this record- or field-level keyword with the OVERLAY keyword so that the i5/OS™ operating system does not delete data already on the display when displaying a record again. The PUTOVR keyword has a function similar to, but more effective than, PUTRETAIN.

This keyword has no parameters.

To understand what effect this keyword has on output operations, consider the following sequence of steps:

  1. Your program sends an output operation to RECORD1, displaying RECORD1. PUTRETAIN, if in effect, is ignored. Any data in the record area for RECORD1 is deleted before RECORD1 is displayed.
  2. At some later time, with RECORD1 still on the display, your program sends a second output operation to RECORD1. Two conditions can occur:
    • If the PUTRETAIN keyword is not in effect, the i5/OS operating system first deletes the record area for RECORD1, then displays RECORD1. Fields selected for display at this time are displayed with new data contents and new display attributes, which can be the same as before. The record area includes every line on which a field or part of a field for RECORD1 appears.
    • If PUTRETAIN is in effect, the i5/OS operating system does not delete the record area for RECORD1. The data contents of selected fields are not changed. However, the display attributes for selected fields are sent to the display and can be changed (by selecting which DSPATR keyword is in effect for this output operation). Fields not selected for display are written over character-by-character by fields selected for display. (For more information, see the When fields are selected by option indicators section in this topic.)
Note: When using the field-level PUTRETAIN keyword, the entire record area is deleted if none of the fields in the record has PUTRETAIN optioned on. If you specify at least one field with unoptioned field-level PUTRETAIN keyword, this ensures that the record area is not deleted.

If you specify the PUTRETAIN 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.

Option indicators are valid for this keyword.

Conditions affecting the PUTRETAIN keyword

PUTRETAIN applies only to the record format for which it is specified, and then only if the record is already displayed. If the record on which PUTRETAIN is specified is not on the display, PUTRETAIN is ignored.

If you specify this keyword at the record level, the keyword applies to all fields in the record format that are selected for display.

This keyword can be specified for more than one field of a record format, but only once per field. This keyword can be specified at the record level and at the field level within the same record format.

PUTRETAIN cannot be specified with the PUTOVR keyword.

A warning message appears at file creation time if the PUTRETAIN keyword is specified on a record with the DSPMOD keyword. At run time, the PUTRETAIN keyword is ignored when the display mode changes.

The OVERLAY keyword must be specified whenever PUTRETAIN is specified.

If the OVERLAY keyword is not in effect, PUTRETAIN is ignored and the entire display deleted before the record is displayed.

When fields are selected by option indicators

When PUTRETAIN is in effect on an output operation involving field selection, fields in the record format that are not selected for redisplay are not deleted; they can be partially or completely rewritten by newly selected fields.

If PUTRETAIN is in effect only for a newly selected field (specified at the field level), only the beginning attribute character of the field is sent to the display; the ending attribute character is not sent. For fields without PUTRETAIN in the same record format, the i5/OS operating system sends the display attribute and the data. If PUTRETAIN is in effect for the whole record (specified at the record level), only the beginning and ending attribute characters are sent to the display. Thus, the display attribute of a field can be reset to normal if the field immediately preceding this field is selected and this field is not selected.

For example, assume that the DSPATR(UL) keyword is in effect for two consecutive fields with overlapping attribute characters. If on an output operation with PUTRETAIN in effect, the first of these fields is selected and the second field is not selected, the display attribute of the second field is reset to the normal display attribute. This is because the i5/OS operating system sends the first field to the display with beginning and ending attribute characters, and its ending attribute character overrides the beginning attribute character of the second field.

Example

The following example shows how to specify the PUTRETAIN keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
00101A          R CUST
00102A                                      PUTRETAIN OVERLAY
     A
Parent topic: DDS keyword entries for display files (positions 45 through 80)