Pre-Load Fields

This feature is not available under the S/390 product

If a calling program passes data into a screen function, the caller may not want a user to be able to change the value of that data. This can be achieved by setting the field attribute to some combination of ‘No Change’, ‘Auto Repeat’ and a new attribute, ‘Pre-Load’.

The primary purpose of the pre-load flag on a screen field is to allow data to be fed into the field from outside the screen, either from a parent screen (standard mode) or from third-party program using component mode. A pre-load field behaves as a no-change, auto-repeat field if there is data in the field when the field is first visited. The data can be placed in the field prior to file reads in any way that a field is loaded in PROIV—via P4API, via a logic command, etc.

If there is data in the pre-load field, the field cannot be changed, no matter what the screen mode. If there is no data in the field when it is first visited during a screen iteration, the field will behave as a normal field and data can be entered until the current record is saved and the iteration begins again. This is different from the behaviour of a ‘no-change’ field, where data cannot be entered into the field when the screen is in ‘change’ mode, whether or not data is present in the field.

The PROIV Timing Cycle initialises the file data to null before each iteration of a logical screen, report or update. It also clears the scratch data associated with the screen fields. Key fields and data associated with auto-repeat fields are not initialised, neither are data fields used by pre-load screen fields. The latter will be treated as auto-repeat fields as long as the field remains pre-loaded.

The following use cases describe the functionality of pre-load fields more fully.

The pre-load screen field is a field prior to the Last Key Field. In any screen mode, data will not be cleared from the field. Data passed into the function, or set up in earlier screens, will still be present when the logical screen is executed.
A screen in ‘Add’ or ‘Insert’ mode has a pre-load field following the Last Key Field. Any data passed in from outside the function, or set up in function logic for a pre-loaded field will be preserved. The pre-loaded field will be treated like an auto-repeat field with the additional feature that it cannot be changed.
A screen in ’Change’, ‘Look’, or ‘Delete’ mode has a pre-load field following the Last Key Field. The fields are not cleared, but they will be overwritten by the file reads unless the associated data element is a scratch field. The values cannot be changed.

If a pre-loaded field is visited, and the data element has no data in it, the pre-load restraint is removed for that iteration. The user is allowed to enter and change the data. Since the pre-load constraint has been turned off, this data will not be preserved for the next screen iteration. If the screen is not a one-time screen (set by the writable CURRENTLS.ONETIME property), then the next time the screen is executed, the field is treated as a pre-load field again but the pre-load data protection is never turned on again.

It is possible to create a pre-load field that is not pre-load on one iteration and is then pre-load on the next. In this case, the field would have been loaded from within the screen, but not by the user. If this is done, the pre-load state of the field will no longer protect the data from the initialisation at the start of screen execution. If the programmer does not want the data re-initialised, the auto-repeat flag on the field will protect the data from initialisation unconditionally.

There are two caveats to the use of pre-load fields:

Same data, multiple fields. If the same data element is attached to multiple screen fields, marking some or all of the fields as pre-load can have unpredictable (and undefined) results. If one screen field is pre-loaded and the other is not, then the auto-repeat characteristic will hold for both. Similarly, if a pre-loaded screen field reverts to user input, the pre-loaded mark on the data element will go away. It can then be initialised, which may not be expected by another pre-load field in the same screen that uses the same data.
Key fields and auto-repeat fields. These fields are already protected from initialisation before the screen iteration. If such a field is also pre-loaded but there is no data, the protection is not removed.

Based on the rules above, if a pre-loaded field is specified for execution, a file read error occurs, and there is data in the field, the field cannot be visited. If every field between the file read field and the new field to be executed is a field that cannot be changed by the user, an infinite loop occurs. This is treated as a fatal error and rollback is invoked. The rollback occurs whether or not it is enabled for the function in general.

There are no validation checks for pre-load fields. The application developer must make sure data is correct in the third party application or in the Task start function.

Comment on this topic

Topic ID: 540111