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
|
