The Retrieve Time Stamp 2 command retrieves a 26 byte time stamp that
is intended to be written to a data base Z type (Timestamp) field.
The Timestamp data type has a required format of
yyyy-mm-dd-hh.mm.ss.nnnnnn. The value returned will be unique across
the system and will be 'greater than' the previous returned value.
The RTVTIMSTM2 command is provided, but the normal use would be to
call the CPP (TAANBRCR) directly from a HLL program.
While the function is intended to be used for Z type (Timestamp) data
base fields, you may format the returned result for your own
requirements.
The last 3 digits of the returned time stamp are not a true time.
See the later discussion.
To use the RTVTIMSTM command, you would specify:
DCL &TIMSTM *CHAR LEN(26)
.
RTVTIMSTM2 RTNTIMSTM(&TIMSTM)
For proper use of RTVTIMSTM2, be sure you understand the ACTION
parameter (the default is used in the example).
To call the program TAANBRCR from a HLL program, two parameters must
be passed.
ACTION *CHAR LEN(4) Pass *GET or *END
TIMSTM *CHAR LEN(26) Return timestamp
The ACTION parameter should be passed as *GET when the next timestamp
is needed. This causes the TAANBRCR program to remain active waiting
for the next call (the program ends with LR off). *END should be
passed when no timestamp should be returned and the program should be
ended (the program ends with LR on).
The following is an example of RPG III code:
C MOVE '*GET' ACTION
.
C CALL 'TAANBRCR'
C PARM ACTION 4
C PARM TIMSTM 26
Details of returned value
-------------------------
The system clock provides a 9 digit time value (thousandths of a
second) in the format hhmmssnnn whereas the Z type timestamp field
uses a 12 digit time in millionths of a second (hhmmssnnnnnn). To
provide for a unique value for the last 3 digits, the same function
as described for the NBRCTR tool is used with the COMPSWAP MI
instruction. This provides the fastest possible method of generating
a consecutive number.
The last 3 digits will not be a true time value, but rather a
consecutive number ranging from 1 to 999. After 999, the value is
reset to 1. No message occurs on the reset.
If the value is to be reset, a comparison is made of the first 23
bytes of the new timestamp versus the same bytes assigned from the
last assigned timestamp. If they are the same, the program delays
for one second before generating a new timestamp. This ensures a
unique value is returned that is 'greater than' the previously
returned value.
Note that a time stamp is never returned with the last 3 digits of
000. Note also that the last 3 digits are not reset when the time in
thousandths of a second changes, but rather when the counter reaches
999. Thus, consecutive retrievals might produce values such as:
2009-05-15-11.15.10602997
2009-05-15-11.15.10602998
2009-05-15-11.15.10604999
2009-05-15-11.15.10606001
There are no considerations for a job failure or system abnormal
termination. As long as the system clock is not set backwards, the
RTVTIMSTM2 function will return unique values that are 'greater than'
the previous value returned.
Note that if Standard Time is reset from Daylight Savings Time by
moving the clock backwards, the guarantee will not exist for a period
of time.
The TAANBRCT *USRSPC object in TAATOOL is used for all jobs using the
RTVTIMSTM2 function. It provides the function as described in the
NBRCTR tool.
RTVTIMSTM2 Commands
-------------------
Several commands are provided:
RTVTIMSTM2 Retrieve time stamp 2
May call directly with TAANBRCR
DMOTIMSTM Demo timestamp - Builds a file
DMOTIMSTM2 Demo timestamp 2 - Analyzes file
Demo Function
-------------
To assist you in understanding the RTVTIMSTM2 function and in testing
it, two DMO commands are provided.
Use the DMOTIMSTM command to submit multiple batch jobs. The concept
is that the batch jobs run simultaneously (default is to submit to
QINTER), to demonstrate how multiple jobs can use the RTVTIMSTM2
function at the same time.
DMOTIMSTM NBRACCS(nnn) NBRJOBS(nnn)
With DMOTIMSTM, you describe the number of accesses you want each
batch job to use (the number of RTVTIMSTM2 functions) and how many
batch jobs should run.
The output of these batch jobs is to write a record in the DMOTIMSTMP
file in TAAWORK. Each job will output records until the number
specified for NBRACCS is reached.
The DMOTIMSTM2 command analyzes the file to ensure that all
timestamps are unique. The command has no parameters and is entered
as:
DMOTIMSTM2
Completion messages from the command describe how to view the file
for your own satisfaction.
If your system has a single CPU, each job shares the CPU for a given
amount of time (based on the Job's Class Timeslice). Consequently,
you will see bursts of consecutive numbers retrieved from each job
that is running.
Because the output file is written in blocks of records (not one
record at a time), you will see blocks of consecutive records from
each batch job written to the DMOTIMSTMP file. If the data is
displayed in physical sequence, the timestamp field will not be in
sequence.
When you are completed testing, delete the file:
DLTF FILE(TAAWORK/DMOTIMSTMP)
Each use of DMOTIMSTM clears the TAAWORK/DMOTIMSTMP file.
RTVTIMSTM2 escape messages you can monitor for
----------------------------------------------
None. Escape messages from based on functions will be re-sent.
RTVTIMSTM2 Command parameters *CMD
-----------------------------
RTVTIMSTM2 retrieves a unique timestamp in the format of a Z data
type field.
ACTION Whether to return a timestamp and keep the program
active or to end the program. The default is *GET
which causes the program to return a timestamp and
remain active. Allowing the program to remain
active provides better performance the next time the
function is needed in the same job.
*END may be specified when the program is no longer
needed in the job. Note that when *END is used, the
RTNTIMSTM parameter is not updated. The program
does an immediate end (LR is set on).
If the job ends without using ACTION(*END), the
system cleans up the program.
There are no considerations for a job failure or an
abnormal system termination. As long as the system
clock is functioning correctly and is not reset
backwards, a unique value will be returned that is
'greater than' the previous value. Note that there
is an exception if you move from Daylight Savings
Time to Standard Time by moving the clock backwards.
RTNTIMSTM The 26 byte time stamp that will be returned is in
the format 'yyyy-mm-dd-hh.mm.ss.nnnnnn' which is
ready to be written to a data base Z type field.
You may use the value for your function (a Z type
field is not required).
The last 3 digits are not a true time value, but
rather a consecutive number between 1 and 999. See
the detail documentation for how the number is
generated.
DMOTIMSTM Command parameters *CMD
----------------------------
DMOTIMSTM provides a demonstration of the RTVTIMSTM2 function. The
demonstration occurs by submitting a user specified number of batch
jobs. Each batch job uses the RTVTIMSTM2 function a specified number
of times. Each time a number is retrieved, a record is added to the
DMOTIMSTM file in the TAAWORK library. This file is created by
DMOTIMSTM before the batch jobs are submitted. If the file already
exists, the data is cleared.
After the batch jobs complete, analyze the output with the the
DMOTIMSTM2 command.
NBRACCS The number of RTVTIMSTM2 accesses that will be made
from each job that is submitted. The default is
10,000. Each access causes a record to be written
to the DMOTIMSTP file in the TAAWORK library.
NBRJOBS The number of batch jobs to be submitted. The
default is 5. Providing multiple jobs provides a
reasonable test of the function of different jobs
retrieving the next number from the number counter.
Each job will have a name of TIMSTMnn where nn is a
consecutive number.
JOBQ The qualified name of the job queue to be used.
QINTER is the default.
The intent of using QINTER is to allow multiple jobs
to be active at the same time that are making
requests for the next number from the number counter
used by RTVTIMSTM2.
The library name defaults to *LIBL.
DMOTIMSTM2 Command parameters *CMD
-----------------------------
DMOTIMSTM2 provides an analysis of the DMOTIMSTM file in TAAWORK.
The file is sequenced by the number that was retrieved from the
RTVTIMSTM2 function. The data is checked to ensure there are no
duplicates and no gaps (consecutive numbers must exist). A summary
of the file is output to a spooled file.
The command has no parameters.
Restrictions
------------
** Because the command returns a variable, it may only be used in
a CL program.
** The last 3 digits of the timestamp are not a true time, but
rather a consecutive number.
** The value returned will be unique and 'greater than' the
previous returned value as long as the system clock is not set
backwards.
Prerequisites
-------------
CHKOBJ3 Check object 3
DUPFILFMT Duplicate file format
EDTVAR Edit variable
SNDCOMPMSG Send completion message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVTIMSTM2 *CMD TAANBRC QATTCMD
DMOTIMSTM *CMD TAANBRC2 QATTCMD
DMOTIMSTM2 *CMD TAANBRC3 QATTCMD
TAANBRCC2 *PGM CLP TAANBRCC2 QATTCL
TAANBRCC3 *PGM CLP TAANBRCC3 QATTCL
TAANBRCC12 *PGM CLP TAANBRCC12 QATTCL
TAANBRCR *PGM RPGLE TAANBRCR QATTRPG
TAANBRCR12 *PGM RPG TAANBRCR12 QATTRPG
TAANBRCP *FILE PF TAANBRCP QATTDDS
TAANBRCT *USRSPC
The TAANBRCT *USRSPC is where the next consecutive number is held to
provide uniqueness in the last 3 digits of the timestamp.
Structure
---------
RTVTIMSTM2 Cmd
TAANBRCR RPG ILE Pgm (the RPG program is the CPP)
Uses TAANBRCT user space
DMOTIMSTM Cmd
TAANBRCC2 CL pgm
Submits TAANBRCC12 CL pgm
TAANBRCR12 RPG pgm writes to DMOTIMSTMP file
DMOTIMSTM2 Cmd
TAANBRBC3 CL pgm
TAANBRCR3 RPG pgm
|
