TAA Tools

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

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)

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:


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.


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


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

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

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.


  **   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


     CHKOBJ3         Check object 3
     DUPFILFMT       Duplicate file format
     EDTVAR          Edit variable
     SNDCOMPMSG      Send completion message


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
   TAANBRCR12    *PGM       RPG         TAANBRCR12    QATTRPG
   TAANBRCP      *FILE      PF          TAANBRCP      QATTDDS

The TAANBRCT *USRSPC is  where the next  consecutive number is held  to
provide uniqueness in the last 3 digits of the timestamp.


  TAANBRCR   RPG ILE Pgm  (the RPG program is the CPP)
     Uses TAANBRCT user space

   TAANBRCC2   CL pgm
     Submits  TAANBRCC12   CL pgm
                TAANBRCR12   RPG pgm writes to DMOTIMSTMP file

   TAANBRBC3   CL pgm
     TAANBRCR3   RPG pgm

Added to TAA Productivity tools May 1, 2000

Home Page Up to Top