TAA Tools
GENUNQNBR       GENERATE UNIQUE NUMBER                 TAANBRD

The  Generate Unique  Number  tool generates  unique  numbers within  a
specified  range.   The GENUNQNBR  command is  intended for  CL program
use  and  generates a  single unique  number each  time the  command is
used.   The GENUNQNBR2 command  creates an  outfile of unique  numbers.
The outfile name  is always UNQNBRP which uses  the model file TAANBRDP
with a format name of UNQNBRR.

A typical GENUNQNBR approach in a CL program would be:

             DCL        &UNQNBR *DEC LEN(9 0)
             DCL        &COUNT *DEC LEN(9 0)
              .
 LOOP:       CHGVAR     &COUNT (&COUNT + 1)
             IF         (&COUNT *LT 5000) DO /* LT max */
             GENUNQNBR  RANNBR(&UNQNBR) TOTNBRS(5000) LOVAL(1) +
                          HIVAL(100000) OUTPUT(*NONE) PGMEND(*NO)
                        /**************************************/
                        /*                                    */
                        /*    Your processing of &UNQNBR      */
                        /*                                    */
                        /**************************************/
             GOTO       LOOP
             ENDDO      /* LT max */
                        /* Change PGMEND and run cmd to close */
             GENUNQNBR  RANNBR(&UNQNBR) TOTNBRS(5000) LOVAL(1) +
                          HIVAL(100000) OUTPUT(*NONE) PGMEND(*YES)

The  TOTNBRS  parameter  describes  the  total  numbers  you intend  to
retrieve in  the loop.    This number  must  be 35%  or less  than  the
number specified  in the range  of LOVAL and  HIVAL.  In  this example,
5000  unique numbers would be  generated in the range  of 1 to 100,000.

The 35% maximum allows  the program to provide  a good range of  values
and avoids  the  function from  excessive processing  in attempting  to
generate a unique number.

The function  will run faster  if a small  number of total  records are
requested  in a wide range.  For  example, the request for 5,000 unique
numbers out of  a range of  1 to 100,000  is a 5%  penetration request.
As the  total number of requests and  percentage penetration increases,
the program must spend more time determining unique values.

The  program generating the numbers stays  open until you are finished.
At that  point, set  PGMEND to  *YES and  invoke the  command again  to
close the program properly.

If GENUNQNBR  is used in a  loop with PGMEND(*NO), unique  numbers will
be  generated  as   requested.    You  cannot  end  the  function  with
PGMEND(*YES), use GENUNQNBR  again for  another set  of unique  numbers
and expect uniqueness between the two sets of numbers.

A typical GENUNQNBR2 command would be:

             GENUNQNBR2  TOTNBRS(5000) LOVAL(1) +
                           HIVAL(100000) OUTLIB(QTEMP)

5,000 unique numbers would be written to the UNQNBRP file in QTEMP.

To ensure the numbers are unique, use the DSPDUPFLD command.

             DSPDUPFLD  FILE(QTEMP/UNQNBRP) FIELD(UNQNBR)


Internal approach
-----------------

The GENRANNBR  tool  is used  to generate  a random  number within  the
specified range.

A work file  is used in QTEMP with a key  value of the unique generated
number.   An  RPG WRITE  operation is  used and  the code checks  for a
duplicate key error.   If an error occurs,  the number is bumped  using
an internal algorithm attempting to find a unique value.

As  the penetration  percentage approaches  35%  or a  large number  of
total  unique numbers is  requested, duplicate keys are  more likely to
be generated.  Each time a  write of a duplicate key occurs, a  message
is sent to the  job log and cannot be cleaned up by  the tool.  You may
need  to  use  CHGJOB  JOBMSGQFL(*WRAP)  to  avoid  exceeding  the  job
message queue limit.

GENUNQNBR escape messages you can monitor for
---------------------------------------------

None.  Escape messages from based on functions will be re-sent.

GENUNQNBR command parameters                          *CMD
----------------------------

   UNQNBR        The  unique  number  to  be  returned.    It  must  be
                 defined as a 9 digit field with 0 decimals.

   TOTNBRS       The number  of unique numbers  that may  be generated.
                 The  number cannot  be higher  than  35% of  the range
                 provided   by  the  LOVAL  and   HIVAL  number.    For
                 example, if LOVAL(1)  and HIVAL(10000) are  specified,
                 TOTNBRS   cannot  be   greater   than   3500.     This
                 restriction  provides better  randomization and avoids
                 the  internal   program  from   performing   excessive
                 attempts to generate a unique number.

                 It is  not required that you  use the command  as many
                 times  as  specified.   The  number acts  as  an upper
                 bound for  the  number of  times  you can  invoke  the
                 command before using PGMEND(*YES).

                 The  processing  time  is best  if  the  total  number
                 requested to  be generated is  small and a  wide range
                 in  terms of the  LOVAL and HIVAL  parameters is used.

   LOVAL         The lowest  number  you want  returned.   It  must  be
                 defined as *DEC  LEN(9 0).  It cannot  be less than 0.

   HIVAL         The  highest number  you  want returned.   It  must be
                 defined as *DEC LEN(9 0).   It cannot be less than  or
                 equal   to   LOVAL.     The   number   cannot   exceed
                 999,999,999.

   PGMEND        A  *YES/*NO value that determines  whether the command
                 processing program  should  end  (set  LR  on).    The
                 default is  *NO  which causes  the command  processing
                 program  to remain  open.   After  you  have retrieved
                 the  number of  unique values  requested, specify *YES
                 and  use  GENUNQNBR  again  to  close  the  processing
                 program.

   OUTPUT        A *NONE/*PRINT  value for whether  to print a  list of
                 the generated unique numbers.

                 *NONE is the default to prevent printing.

                 *PRINT may be specified to create a printer file.

GENUNQNBR2 command parameters                          *CMD
-----------------------------

   TOTNBRS       The  number of unique numbers  that will be generated.
                 The number  cannot be  higher than  35%  of the  range
                 provided  by  the   LOVAL  and  HIVAL  number.     For
                 example,  if LOVAL(1) and  HIVAL(10000) are specified,
                 TOTNBRS  cannot   be   greater  than   3500.      This
                 restriction provides  better randomization and  avoids
                 the   internal  program   from   performing  excessive
                 attempts to generate a unique number.

                 The  processing time  is best  if the  total number of
                 numbers to be generated  is small and a wide  range in
                 terms of the LOVAL and HIVAL parameters is used.

   LOVAL         The  lowest number  you  want returned.    It must  be
                 defined  as *DEC LEN(9 0).  It  cannot be less than 0.

   HIVAL         The highest  number you  want returned.    It must  be
                 defined as *DEC  LEN(9 0).  It cannot be  less than or
                 equal to LOVAL nor greater than 999,999,999.

   OUTLIB        The  library   in  which  the  file  UNQNBRP  will  be
                 placed.  The default  is *LIBL.   If the UNQNBRP  file
                 does  not already  exist,  a  library must  be  named.
                 The  outfile name  is  always UNQNBRP  which  uses the
                 model file TAANBRDP with a format name of UNQNBRR.

   OUTMBR        The  member  of  the UNQNBRP  file  to be  used.   The
                 default is UNQNBRP.   If the member does not  exist it
                 is added.

   REPLACE       A  *YES/*NO value  for  whether the  member should  be
                 cleared  before writing records into  it.  The default
                 is *YES.

                 *NO may be  specified to add  records to any  existing
                 data.

Restrictions
------------

Because GENUNQNBR returns  a variable, the command may only  be used in
a CL program.

When  using  GENUNQNBR,  you  cannot  change  the values  for  TOTNBRS,
LOVAL, and HIVAL while  the internal program is  still open.  You  must
first end the program with PGMEND(*YES).

Each use  of GENUNQNBR produces  a set of  unique numbers.   You cannot
end  the function with  PGMEND(*YES), use  GENUNQNBR again  for another
set  of unique  numbers and expect  uniqueness between the  two sets of
numbers.

Each time a write of a  duplicate key occurs, a message is sent  to the
job log  and cannot be  cleaned up by  the tool.   You may need  to use
CHGJOB  JOBMSGQFL(*WRAP)  to  avoid  exceeding  the  job  message queue
limit.

Prerequisites
-------------

The following TAA Tools must be on your system:

     DUPTAADBF       Duplicate TAA Data Base file
     EDTVAR          Edit variable
     GENRANNBR       Generate random number
     RTVSYSVAL3      Retrieve system value 3
     SNDCOMPMSG      Send completion message
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message
     SNDSTSCNT       Send status message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   GENUNQNBR     *CMD                   TAANBRD       QATTCMD
   GENUNQNBR2    *CMD                   TAANBRD2      QATTCMD
   TAANBRDC2     *PGM       CLP         TAANBRDC2     QATTCL
   TAANBRDC10    *PGM       CLP         TAANBRDC10    QATTCL
   TAANBRDR      *PGM       RPG         TAANBRDR      QATTRPG
   TAANBRDR2     *PGM       RPG         TAANBRDR2     QATTRPG
   TAANBRDP      *FILE      PF          TAANBRDP      QATTDDS
   TAANBRDQ      *FILE      PF          TAANBRDQ      QATTDDS

Note that TAANBRDR is the CPP for GENUNQNBR.


Structure
---------

GENUNQNBR   Cmd
   TAANBRDR   RPG pgm
     TAANBRDQ   Work file in QTEMP
     TAANBRDC10  CL pgm

GENUNQNBR2  Cmd
   TAANBRDC2   CL pgm
     TAANBRDR2   RPG Pgm
       TAANBRDP    Outfile
					

Added to TAA Productivity tools September 15, 2007


Home Page Up to Top