Adding a date-time stamp field

You can add a date-time stamp field to some of your files to keep track of when records in the file were last modified. This is done by setting the X'10' bit FOPT for the files in which you want the timestamps, and by designating a date-time stamp fieldname, which can be done with the DTSFN parameter. When a file's FOPT X'10' bit is set, the date-time stamp field is updated for each record that was updated in a transaction. Applications can then use the data in the date-time stamp field to find and process all the records that were changed.

An application that processes these records can track the date-time stamp field values that have been processed to date, or it may take another action, including updating the date-time stamp field.

The date-time stamp feature works only in files created in V7R1.0 or later. (Under V6R1.0, DTS enabled files can be opened, and DTS fields read like any other, but no automatic updates to DTS fields will take place.)

Note: There is no support in PQO/204 for the date/time stamp feature.

Overview of the date-time stamp feature

The date-time stamp (DTS) feature in Model 204 can track when records are modified. Except for DELETE RECORD(S) processing, all other updates are captured, including those made by BATCH204 and ONLINE jobs. From Model 204 V7.4 onwards, updates performed by IFAM applications are also captured.

The default date-time stamp string uses the operating system timestamp value, in this format: CCYYMMDDHHMMSSMMM. If your site prefers a different field value or a different data format, see Date/time stamp field.

Also of note:

• The DTS feature is implemented on a file-by-file basis.
• Precision and accuracy of the date-time stamp is to the millisecond when you use the date-time stamp feature as delivered. To ensure optimal searching using the date-time stamp field, define it as ORDERED CHARACTER. (The length of this field value is 17 bytes.)
• While it should not be updated directly, you can read and display the date-time stamp as you can any other field. SOUL and IFAM can both be used to find and display date-time stamp field data.
• The date-time stamp field is updated at the beginning of commit processing when a new record is stored or an existing record is updated: changes, inserts, or deletes to fields or fieldgroups.
• You can exclude a user thread from date-time stamp field maintenance by resetting the DTS parameter to 0.
• You can specify a name for the date-time stamp field with the DTSFN parameter.

Extracting date-time stamp field data

Since the date-time stamp field is a normal Model 204 field, all methods of extraction may be used.

Date-time stamp field in SOUL

The date-time stamp field can be:

• Read and printed either as a field name reference or through a $function.
• Searched in normal FIND statements.
• Assigned to %variables or other fields.
• Printed as supported for all Model 204 fields, including a PAI statement.

Date-time stamp field and OPEN processing

If the specified date-time stamp field name is not defined in a date-time stamp file, an OPEN command is rejected. If the date-time stamp field name is DATE.TIMESTAMP, for example, the following messages are issued:

> OPEN DTSFILE *** 1 M204.1265: NO SUCH FIELD NAME. FIELD = DATE.TIMESTAMP *** M204.2730: DATE/TIME STAMP FILE, BUT DTSFN NOT DEFINED IN FILE *** M204.0608: FILE CLOSED: DTSFILE *** 2 M204.0630: FILE OPEN COMMAND REJECTED

If you do not set the DTSFN system parameter, files with the FOPT X'10' bit cannot be opened. An OPEN command will not be processed, and the following message is issued:

M204.2729: DATE/TIME STAMP FILE, BUT DTSFN UNSPECIFIED IN RUN

If you have reset DTS to 0, you must open DTS enabled files with file manager privileges. Otherwise, the open is rejected.

Date-time stamp considerations

Backup and recovery

If any errors occur during processing, the transaction is backed out.

Backup and recovery activity synchronize the date-time stamp with the data changes made. Date-time stamp field updates are part of your updating transaction and follow the normal Model 204 rules for BACKOUT, COMMIT, DUMP, RESTORE, ROLL BACK, and ROLL FORWARD.

File load utilities

FLOD and FILELOAD do not update the date-time stamp values. However, you can manually update date-time stamp values as you might update another field name value pair.

Procedures with more than one request

If there are two requests in one procedure, for example, and neither COMMIT nor CLOSE is called between the two, then both requests are one transaction.

The following procedure has two requests.

BEGIN STORE a record in a DTS file END BEGIN PAI the record END

DTS updates are not displayed by the PAI output, since the transaction does not complete until the end of the procedure.

If there is no COMMIT in the first request or if the file is not closed after the first request, then the date-time stamp field is not updated.

If the same SOUL requests are executed as separate procedures, the date-time stamp field is updated.

Suspending date-time stamp updates

There are two ways to suspend date-time stamp updates: suspending updates for all files on one thread's updates, or suspending all updates for a file.

Suspending updates for all files on one thread's updates

A user with system manager privileges can exclude date-time stamp files from DTS processing, suspending DTS updates for that user's thread. The user's thread does no date-time stamp processing on any file.

To suspend DTS updates, reset the DTS parameter to 0. When DTS=0, the user can update any field, including the date-time stamp field, without automatically updating the date-time stamp field.

To reset the DTS parameter, you must have system manager privileges. You must also have file manager privileges for any DTS-enabled files opened, either before or after DTS is reset to 0.

Note: Automatic date-time stamp field updates are still performed for updates made to the files by other user threads with DTS set to 1.

Suspending all updates for a file

To disable all date-time stamp processing for a specific file, turn off the FOPT parameter X'10' bit on the command line, or use the File Management Subsystem facility. Turning off this bit disables date-time stamp updates made by all users of that file.

See also

For system management considerations of DTS fields, see Setting up the date-time stamp field.