TAA Tools
GENRANNBR       GENERATE RANDOM NUMBER                 TAANBRA

The  Generate  Random  Number  command  allows  you  to  create  random
numbers.     This   is  a   useful  function   for  several   types  of
applications:

   - Simulations
   - Creating test data
   - Creating a relative record number (synonyms will exist)
   - Performance testing
   - Playing games (Spin the wheel, roll the dice etc.)

See also the GENUNQNBR tool for generating unique numbers.

A typical command would be entered as:

      GENRANNBR    RANNBR(&RANNBR) LOVAL(1) HIVAL(1000)

This would return a random number between 1 and 1000.

There are two ways to use the command:

  **   The  default is  to use the  current time as  a beginning value.
       Each time  you use  the command,  you will  receive a  different
       random number.   If  you request multiple  uses of  the command,
       the  numbers will vary.   This is the technique  to use when you
       want random data.

  **   A starting  value may be  specified to  be used  instead of  the
       beginning time.   This allows you to receive the  same number or
       set of  numbers each time you make a  request.  A starting value
       would normally be  used when you  are doing performance  testing
       and want  the same test  values for repeated  tests or when  you
       are generating a relative record number based on a key.

A  command interface  is provided  or the  CPP  can be  called directly
with a parameter list.

The  command returns a value so  therefore it can only  be used in a CL
program.

Randomizing results
-------------------

The randomizing technique  is fairly good.   It will spread the  values
over the  range available.   If a wide  range exists and the  amount of
numbers  generated  is not  great,  there will  be  minimal duplicates.
With a small range of  possible values (e.g.  2-10), the  randomization
is still reasonably good.

A perfect  randomization is not  achieved (nor is  it achieved  in real
life).

If you  are interested in testing the  results of the randomization, be
sure to run the  same test multiple times  (assuming a 0 start  value).
The results will  vary each time you run  a test in the same  manner it
varies in real life.

Using relative record numbers
-----------------------------

Generating a  relative record number from a key  value is a typical use
of  the need for a  random number.  The  use of relative record numbers
can be a  performance advantage in  that it does  not require a  search
of an  index.  However, you  normally must provide a  larger space than
is  necessary and  handle  the synonyms  (a synonym  is where  two keys
would generate the same random number).

The algorithm  used by the  tool is  not very  efficient as  it uses  a
combination of  multiply and  divide.   This can  use considerable  CPU
resources.

Accessing randomly  by relative record number  may not be significantly
more efficient  than keyed  processing.   The major  potential gain  is
the  avoidance  of paging  in  the  index  pages.   In  a  system  with
sufficient  memory, the  index  pages will  more likely  be  in memory.
The  most likely  place for  a gain is  when you  are doing interactive
work.

Assume you have  1000 records and  speed of access  is essential.   You
could create  a data file  that was initialized  so there was  room for
10,000  records.  The larger the space  you create the less possibility
there will be of synonyms.   With a 10 to  1 ratio (10,000 slots to  be
filled by  1,000 records),  you would  typically get  about 95%  unique
requests  using the  GENRANNBR command  (assuming your  starting values
were unique).  This means that about  5% of the time you would have  to
handle a synonym.

A typical  means of handling  a synonym  would be to  look in the  next
relative record number slot to see if the key really matches.

You may  want to try some  different starting values with  your data to
determine  the best one  to use (the  one which normally  gives you the
most unique values as well as spreading the numbers).

Parameter list
--------------

You may call  the TAANBRAR command  processing program directly with  a
HLL program.  The parameter list is as follows:

     RANNBR    *DEC  LEN(9 0)        The number to be returned
     LOVAL     *DEC  LEN(9 0)        The lowest value to be returned
     HIVAL     *DEC  LEN(9 0)        The highest value to be returned
     PGMEND    *CHAR LEN(4)          *YES/*NO value for setting LR
     STRVAL    *DEC  LEN(9 0)        0 = Random start, n = fxd str

The following  code is in  the proper format  to be copied into  an RPG
program.   Use CPYTAA  TAAARCMBR(GENRANNBR) to  copy this documentation
source to the QATTINFO file in TAATOOL.

     C                     Z-ADD1         LOVAL            Low value
     C                     Z-ADD50000     HIVAL            High value
     C                     Z-ADD0         STRVAL           Start value
     C                     MOVE '*NO '    PGMEND           Program end
     C                     CALL 'TAANBRAR'                 Call pgm
     C                     PARM           RANNBR  90       Random nbr
     C                     PARM           LOVAL   90       Low value
     C                     PARM           HIVAL   90       High value
     C                     PARM           PGMEND  4        Program end
     C                     PARM           STRVAL  90       Start value

Sample program to simulate flipping a coin for heads or tails
-------------------------------------------------------------

The following program shows  how the GENRANNBR  command can be used  to
simulate flipping a coin.

             PGM        /* FLIP program for simulating coin toss */
             DCL        &RANNBR *DEC LEN(9 0)
             DCL        &FLIP *CHAR LEN(10)
             GENRANNBR  RANNBR(&RANNBR) LOVAL(1) HIVAL(2) PGMEND(*YES)
             IF         (&RANNBR *EQ 1) CHGVAR &FLIP 'HEADS'
             IF         (&RANNBR *EQ 2) CHGVAR &FLIP 'TAILS'
             SNDPGMMSG  MSG(&FLIP)
             ENDPGM

Sample program to simulate tossing two dice
-------------------------------------------

             PGM        /* ROLL program to simulate roll of 2 dice */
             DCL        &RANNBR *DEC LEN(9 0)
             DCL        &TOTAL *DEC LEN(9 0)
             DCL        &ROLLAMT *CHAR LEN(22)
             GENRANNBR  RANNBR(&RANNBR) LOVAL(1) HIVAL(6)
             CHGVAR     &TOTAL (&TOTAL + &RANNBR)
             GENRANNBR  RANNBR(&RANNBR) LOVAL(1) HIVAL(6) PGMEND(*YES)
             CHGVAR     &TOTAL (&TOTAL + &RANNBR)
             EDTVAR     CHROUT(&ROLLAMT) NUMINP(&TOTAL)
             SNDPGMMSG  MSG(&ROLLAMT)
             ENDPGM

Command parameters                                    *CMD
------------------

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

   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.

   PGMEND        A  *YES/*NO value that  determines whether the command
                 processing  program  should end  (set  LR  on).    The
                 default  is  *NO.   If  you  are  going to  request  a
                 series  of numbers, you  would say *NO  until the last
                 request.

   STRVAL        Starting value.   A *DEC LEN(9  0) value.   A 0  entry
                 means that  the function  should pick  a random  value
                 to begin  with.  The current time  in 9 digits is used
                 and is  added  to  the YYMMDD  value  in  a  scrambled
                 fashion.    With  a  0  value,  you  would  receive  a
                 different set  of values each  time you made  the same
                 request.

                 A  specific value requests  the same number  or set of
                 numbers each  time you  make  a request.   A  specific
                 value  would  normally  be  used when  you  are  doing
                 performance  testing or  generating a  relative record
                 number.  Any 9 digit value may be entered.

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

None.

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

None.

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

None, the tool is ready to use.

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

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

   GENRANNBR     *CMD                      TAANBRA        QATTCMD
   TAANBRAR      *PGM          RPG         TAANBRAR       QATTRPG
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top