UTBL


UTBL(utbl_name,{index_number})
               {'R'}
               {'Rn'}

Where

utbl_name is the name of a user table. This name may be specified in one of the following formats:

msgutbl_name is the name coded on an MSGUTBL statement in this or another STL program. This can also be the name coded on a message generation MSGUTBL statement.
utbl_number is the number coded as a label on a UTBL statement within a network definition. The number must be from 0 to 255.

index_number is an integer expression.

n is a number from 0 to 255 and specifies a UDIST network definition statement.

Results

String

Function

The UTBL function returns an entry from the user table specified by utbl_name.

The second argument determines which entry is to be returned.

If index_number is used, the integer expression is evaluated and its value is used to index into the user table. User table entries begin with an index of 0. If index_number is greater than the maximum index for the user table, a null string is returned.

If R is used, a randomly selected entry will be returned.

If Rn is used, an entry is chosen from the table randomly using the distribution defined by the UDIST statement referenced by n.

Examples

mynames: msgutbl
   "Mary"     /* This is entry number 0. */
   "Joe"      /* This is entry number 1. */
   "John"     /* This is entry number 2. */
   "Sue"      /* This is entry number 3. */
endutbl
&#38;#8942;
a = 1
b = 2
name = utbl(mynames,0)      /* "Mary" is returned.         */
name = utbl(mynames,a+b)    /* "Sue" is returned.          */
name = utbl(mynames,"R")    /* A random entry is returned. */
name = utbl(mynames,"R3")   /* A random entry with the     */
                            /* distribution defined by     */
                            /* UDIST number 3 is returned. */