Adding a date-time stamp field: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(46 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<p>You can add a date-time stamp field to your files to keep track of when records in the file were last modified. The date-time stamp feature lets you put a date-time stamp (DTS) on each record that was updated in a transaction. You can then use the data in the <var class="term">date-time stamp</var> field in an end-user written application to find and process all the rows of data that were changed.</p>
<p>
<p>An application that processes these records can track the <var class="term">date-time stamp</var> field values that have been processed to date, or it may take another action, including updating the date-time stamp field.</p>
You can add a <var class="term">date-time stamp</var> 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 <var>[[FOPT parameter|FOPT]]</var> for the files in which you want the timestamps, and by designating a date-time stamp fieldname, which can be done with the <var>[[DTSFN parameter|DTSFN]]</var> parameter.  When a file's <var>FOPT</var> 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.</p>
<p>To install and use this functionality, you must obtain the correct decrypt keys and install this release. After it is installed, the date-time stamp feature works only in files created in V6R1.0 or later.</p>
<p>
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.</p>
<p>
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.)</p>
<p class="note"><b>Note:</b> There is no support in PQO/204 for the date/time stamp feature.</p>
<p class="note"><b>Note:</b> There is no support in PQO/204 for the date/time stamp feature.</p>
==Overview of the date-time stamp feature==
==Overview of the date-time stamp feature==
<p>The date-time stamp (DTS) feature in <var class="product">Model&nbsp;204</var> can track when records are modified. The DTS feature is implemented on a file-by-file basis.</p>
<p>
<p>Except for DELETE RECORD(S) processing, all other updates are captured, including those made by BATCH204 and ONLINE jobs.</p>
The date-time stamp (DTS) feature in <var class="product">Model&nbsp;204</var> can track when records are modified. Except for <var>DELETE RECORD(S)</var> processing, all other updates are captured, including those made by BATCH204 and ONLINE jobs. From <var class="product">Model&nbsp;204</var> V7.4 onwards, updates performed by IFAM applications are also captured.</p>
<p>Precision and accuracy of the date-time stamp is to the millisecond when you use the date-time stamp as delivered. Rocket Software recommends that the date-time stamp field be defined as ORD CHARACTER to accommodate the length of this field: 17 bytes.</p>
<p>
<p>The date-time stamp field is updated at the beginning of commit time whenever a new record is stored or an existing record is updated-change, insert, or delete a field. </p>
The default date-time stamp string uses the operating system timestamp value, in this format: <code>CCYYMMDDHHMMSSMMM</code>. If your site prefers a different field value or a different data format, see [[DEFINE FIELD command#Date/time stamp field|Date/time stamp field]].</p>
<p>You can read and display the date-time stamp as you can any other field. User Language and IFAM may both be used to find and display date-time stamp field data.</p>
 
<p>Also of note:</p>
<ul>
<li>The DTS feature is implemented on a file-by-file basis.</li>
 
<li>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 <var>ORDERED CHARACTER</var>. (The length of this field value is 17 bytes.)</li>
 
<li>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.</li>  
 
<li>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.</li>
 
<li>You can exclude a user thread from date-time stamp field maintenance by resetting the <var>[[DTS parameter|DTS]]</var> parameter to 0.</li>
 
<li>You can specify a name for the date-time stamp field with the <var>[[DTSFN parameter|DTSFN]]</var> parameter.
</ul>
 
==Extracting date-time stamp field data==
==Extracting date-time stamp field data==
<p>Since the date-time stamp field is a normal <var class="product">Model&nbsp;204</var> field, all methods of extraction may be used.</p>
<p>
===Date-time stamp field in User Language===
Since the date-time stamp field is a normal <var class="product">Model&nbsp;204</var> field, all methods of extraction may be used.</p>
<p>The date-time stamp field may be:</p>
 
===Date-time stamp field in SOUL===
<p>
The date-time stamp field can be:</p>
<ul>
<ul>
<li>Read and printed either as a field name reference or through a $function.</li>
<li>Read and printed either as a field name reference or through a $function.</li>
<li>Searched in normal FIND statements.</li>
<li>Searched in normal <var>FIND</var> statements.</li>
<li>Assigned to %variables or other fields.</li>
<li>Assigned to %variables or other fields.</li>
<li>Printed as supported for all <var class="product">Model&nbsp;204</var> fields, including a PAI statement.</li>
<li>Printed as supported for all <var class="product">Model&nbsp;204</var> fields, including a <var>PAI</var> statement.</li>
</ul>
</ul>
===Date-time stamp field and OPEN processing===
===Date-time stamp field and OPEN processing===
<p>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:</p>
<p>
<p class="code">> OPEN DTSFILE
If the specified date-time stamp field name is not defined in a date-time stamp file, an <var>[[OPEN FILE command|OPEN]]</var> command is rejected. If the date-time stamp field name is <code>DATE.TIMESTAMP</code>, for example, the following messages are issued:</p>
<p class="code"><b>> OPEN DTSFILE</b>
<b></b>***  1  M204.1265: NO SUCH FIELD NAME. FIELD = DATE.TIMESTAMP
<b></b>***  1  M204.1265: NO SUCH FIELD NAME. FIELD = DATE.TIMESTAMP
<b></b>***  M204.2730: DATE/TIME STAMP FILE, BUT DTSFN NOT DEFINED IN FILE
<b></b>***  M204.2730: DATE/TIME STAMP FILE, BUT DTSFN NOT DEFINED IN FILE
Line 27: Line 52:
<b></b>***  2  M204.0630: FILE OPEN COMMAND REJECTED
<b></b>***  2  M204.0630: FILE OPEN COMMAND REJECTED
</p>
</p>
<p>If you do not set the DTSFN system parameter, files with FOPT=X'10' cannot be opened. An OPEN command will not be processed and the following message is issued:</p>
<p>
If you do not set the <var>DTSFN</var> system parameter, files with the <var>[[FOPT parameter|FOPT]]</var> X'10' bit cannot be opened. An <var>OPEN</var> command will not be processed, and the following message is issued:</p>
<p class="code">M204.2729: DATE/TIME STAMP FILE, BUT DTSFN UNSPECIFIED IN RUN
<p class="code">M204.2729: DATE/TIME STAMP FILE, BUT DTSFN UNSPECIFIED IN RUN
</p>
</p>
<p>If you have reset DTS to 0, you must open DTS enabled files with file manager privileges. Otherwise, the open is rejected.</p>
<p>
If you have reset <var>DTS</var> to 0, you must open <var>DTS</var> enabled files with file manager privileges. Otherwise, the open is rejected.</p>
 
==Date-time stamp considerations==
==Date-time stamp considerations==
===Backup and recovery===
===Backup and recovery===
<p>If any errors occur during processing, the transaction is backed out.</p>
<p>
<p>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 <var class="product">Model&nbsp;204</var> rules for BACKOUT, COMMIT, DUMP, RESTORE, ROLL BACK, and ROLL FORWARD.</p>
If any errors occur during processing, the transaction is backed out.</p>
<p>
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 <var class="product">Model&nbsp;204</var> rules for <var>BACKOUT</var>, <var>COMMIT</var>, <var>[[DUMP command|DUMP]]</var>, <var>[[RESTORE command|RESTORE]]</var>, <var>ROLL BACK</var>, and <var>ROLL FORWARD</var>.</p>
 
===File load utilities===
===File load utilities===
<p>FLOD and FASTLOAD 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.</p>
<p>
<var>[[FLOD command|FLOD]]</var> and <var>[[FILELOAD command|FILELOAD]]</var> 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.</p>
 
===Procedures with more than one request===
===Procedures with more than one request===
<p>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.</p>
<p>
<p>The following procedure has two requests. </p>
If there are two requests in one procedure, for example, and neither <var>COMMIT</var> nor <var>[[CLOSE command|CLOSE]]</var> is called between the two, then both requests are one transaction.</p>
<p>
The following procedure has two requests. </p>
<p class="code">BEGIN
<p class="code">BEGIN
   STORE a record in a DTS file
   STORE a record in a DTS file
Line 47: Line 83:
END
END
</p>
</p>
<p>DTS updates are not displayed by the PAI output, since the transaction does not complete until the end of the procedure.</p>
<p>
<p>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.</p>
DTS updates are not displayed by the <var>PAI</var> output, since the transaction does not complete until the end of the procedure.</p>
<p>If the same User Language requests are executed as separate procedures, the date-time stamp field is updated. </p>
<p>
If there is no <var>COMMIT</var> in the first request or if the file is not closed after the first request, then the date-time stamp field is not updated.</p>
<p>
If the same SOUL requests are executed as separate procedures, the date-time stamp field is updated. </p>
 
==Suspending date-time stamp updates==
==Suspending date-time stamp updates==
<p>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.</p>
<p>
<p>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.</p>
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.</p>
<p>To reset the DTS parameter, the user must have system manager privileges. The user must also have file manager privileges for any DTS-enabled files opened, either before or after DTS is reset to 0.</p>
 
<p class="note"><b>Note:</b> Automatic date-time stamp field updates are still performed for updates made to the files by other user threads with DTS set to 1.</p>
===Suspending updates for all files on one thread's updates ===
<p>To disable all date-time stamp processing for a specific file, turn off the FOPT parameter X'10' bit on the command line or using the File Management Subsystem facility. Turning off this bit disables date-time stamp updates made by all users of that file.</p>
<p>
<p>For more information on the DTS and FOPT parameters, see the Rocket <var class="product">Model&nbsp;204</var> Parameter and Command Reference.</p>
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.</p>
[[Category:File manager]]
<p>
[[Category:File Managment]]
To suspend DTS updates, reset the <var>[[DTS parameter|DTS]]</var> parameter to 0. When <code>DTS=0</code>, the user can update any field, including the date-time stamp field, without automatically updating the date-time stamp field.</p>
<p>
To reset the <var>DTS</var> parameter, you must have system manager privileges. You must also have file manager privileges for any DTS-enabled files opened, either before or after <var>DTS</var> is reset to 0.</p>
<p class="note"><b>Note:</b> Automatic date-time stamp field updates are still performed for updates made to the files by other user threads with <var>DTS</var> set to 1.</p>
 
===Suspending all updates for a file===
<p>
To disable all date-time stamp processing for a specific file, turn off the <var>FOPT</var> parameter X'10' bit on the command line, or use the [[Creating a file with FILEMGMT#Defining file organization|File Management Subsystem facility]]. Turning off this bit disables date-time stamp updates made by all users of that file.</p>
 
==See also==
<p>
For system management considerations of DTS fields, see [[Setting up the date-time stamp field]]. </p>
 
[[Category:Model 204 files]]

Latest revision as of 22:05, 1 February 2016

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.