RANDOM

Type

Dialog Language function

Format

RANDOM() (&seed [,&min,&max])  (&min,&max)

&min

The desired minimum numeric value of the random number in the range 0 - 2,147,483,647 (2³¹ - 1). If not specified, the default is 0.

&max

The desired maximum numeric value of the random number in the range 1 - 2,147,483,647 (2³¹ - 1). If not specified, the default is 999.

&seed

A 1- to 8-character seed used to generate the random number. Specifying a seed will generate repeatable results. If not specified, the dialog function will generate a unique random number. Refer to the usage notes for a description of &seed and &sysseed.

Return Codes

>=0

The random rumber output from the function.

-4

min is not a numeric between 0 and 2,147,483,647.

-8

max is not a numeric between 1 and 2,147,483,647.

-12

Invalid range magnitude. max - min is negative, 0, or > 1,073,741,822 (2³° - 2).

Usage Notes®

1. RANDOM requires )OPTION LEVEL(1).
2. While the RANDOM function returns numbers which by the definition of random follow "no discernible pattern" and are "evenly distributed," we are only simulating random numbers with pseudo-random numbers.
3. min must be lower than max or an error will result.
4. The range (i.e., max minus min) must be greater than 0 and less than 1,073,741,822 (2³° - 2) or an error will result.
5. If one operand is specified on the invocation, it is considered the seed. If two operands are specified they are considered the minimum and maximum, respectively. If three operands are specified they are considered the seed, minimum, and maximum respectively. Thus, to generate a random number between 1 and 10, code:

   set number (random(1 10))

   To generate a random number in the range of 0 - 999 based on a seed, code:

   set number (random('&seed'))

6. Specify a seed when repeatable results are desired.
7. The function generates a random number based on a seed. When the user does not specify a seed, the function first creates one. If the function must create a seed, it does so by first retrieving the contents of variable &sysseed which represents a seed generated from a previous RANDOM invocation. If the variable is null, the function will use a null seed. Otherwise, &sysseed will be used as the seed and updated on exit from the function with a new seed. The user, then, need only specify a seed once to generate a repeatable sequence of numbers, e.g.,

   set var0 (random('&seed'))
   set var1 (random())
   set var2 (random())
   set var3 (random())
   set var4 (random())
   set var5 (random())
   set var6 (random())
   set var7 (random())
   set var8 (random())
   set var9 (random())

   By declaring &sysseed appropriately, random number sequences can be repeatable within a particular dialog (scope local), a dialog thread (scope shared), an entire session (scope session), or for the entire address space (scope system).

8. Numerics passed as a seed are processed as string data; integers with leading zeros forwarded in quotes will yield different results than those without quotes.
9. The dialog function implements Lehmers linear congruential method to generate pseudo-random numbers.

Example

/* Generate a random number between 1 and 7 inclusive */
set seed1 (substr('&systime',4,4))
set seed2 (substr('&sysdate',4,4))
set decision (random('&seed1&seed2',1,7))

     if &decision = 1 set decision 'Perhaps'
else if &decision = 2 set decision 'Ask again'
else if &decision = 3 set decision 'I doubt it'
else if &decision = 4 set decision 'There is a good chance'
else if &decision = 5 set decision 'Now is not the right time'
else if &decision = 6 set decision 'Yes'
else if &decision = 7 set decision 'No'