Generating messages with the $UTBL$ data field option

After you have defined a user table and coded the table's entries, you can generate messages by selecting table entries with the $UTBL$ data field option.

MSG1  TEXT  ($UTBL,id,sel$)   Coding to insert a user table entry into
*                             a message sent to the system under test.

When you code the $UTBL$ option, id specifies the name of a MSGUTBL statement or the number of a UTBL statement. sel specifies how WSim selects the entry from the user table. As discussed in the WSim Script Guide and Reference, WSim provides several values for sel that enable you to determine how WSim selects a table entry:

Fn

Specifies fixed selection, that is, WSim selects the same entry each time it processes the $UTBL$ option. n is an integer that specifies the index of the entry WSim selects from the user table. If n exceeds the number of entries in the table, WSim does not select an entry or include any data in the message being generated.

R

Specifies random selection of an entry. WSim generates a random number and then selects the entry with the corresponding index.

Rn

Specifies random selection based on a probability distribution defined by UDIST network definition statement n. n is an integer from 0 to 4095.

cntr

Specifies selection of an entry based on the value of an index counter. For more information about selecting user table entries with index counters, see Index counters.

To specify fixed selection of table entries, code the $UTBL$ option as shown in the following example:

MSG1  TEXT  ($UTBL,id,Fn$)   Coding for fixed selection of table entries.

WSim uses zero indexing for user tables. That is, it indexes entries sequentially beginning with 0. For example, you can specify fixed selection of the fourth entry as shown in the following example:

PARTNUMS MSGUTBL   (NUM1),(NUM2),(NUM3),   Defines entries for a user table
                   (NUM4),(NUM5),(NUM6)    named PARTNUMS.
          .
          .                                Message generation statements.
          .
MSG1     TEXT      ($UTBL,PARTNUMS,F3$)    WSim selects the entry indexed as
*                                          number 3 in table PARTNUMS, which
*                                          is NUM4, the fourth table entry.

In MSG1, F3 specifies that WSim selects the entry from PARTNUMS with a corresponding index of three, which is the fourth entry, NUM4. Because selection is fixed, WSim selects NUM4 each time it processes MSG1.

To specify random selection of table entries, code the $UTBL$ option as shown in the following example.

MSG8  TEXT  ($UTBL,id,R$)  Coding for random selection of table entries.

In this example, R indicates random selection. When WSim processes MSG8, it generates a random integer and then selects the table entry with an index number that corresponds to the random integer. In this way, WSim can select a different entry each time it processes the message generation statement.

You can also select table entries randomly based on a probability distribution defined on the UDIST network definition statement.

1     UDIST  80,20       Assigns weights for selecting entries.

As shown in the preceding example, WSim requires an integer in the UDIST statement's name field. The numbers you code in the UDIST statement's operand field assign weights to corresponding table entries. Each weight represents a fraction that determines the probability that WSim selects a particular entry during message generation. For example, 80 indicates that if WSim processes the statement 100 times on the average, it selects the first entry in a table 80 times or 80% of the time. The 20 indicates that WSim selects the second table entry 20 times or 20% of the time. If there are more than two entries in the user table, WSim selects only the first two entries.

To specify random selection based on a probability distribution, code the $UTBL$ option as shown in the following example.

MSG3  TEXT  ($UTBL,id,Rn$)  Coding to select an entry based on a
*                           probability distribution.

In this example, id specifies the number of a UTBL statement or the name of a MSGUTBL statement that defines the user table which WSim selects an entry; R specifies random selection. n is the number of the UDIST statement that defines the probability distribution.

The sample script shown below illustrates a network definition and message generation deck with the coding required to select an entry based on a probability distribution.

NET1   NTWRK
*                           Sample WSim Script
*   This script illustrates the coding required to define a table and its
*   entries and then select an entry based on a probability distribution.
*
*                               Beginning of NET1.
*
          .
          .                     Network definition statements.
          .
2      UDIST   50,30,20         Defines a probability distribution.
          .
          .                     Network definition statements.
          .
TBL1   MSGUTBL (1487),(7911),   Entries for user table TBL1.
               (1098)
          .
          .                     Other MSGUTBLs and MSGTXTs.
          .

DECK3  MSGTXT
*                               Beginning of DECK3.
MSG5   TEXT    ($UTBL,TBL1,R2$) Defines random selection of entries from
*                               TBL1 with distribution defined by UDIST 2.
        .
        .                       Message generation statements.
        .
       ENDTXT                   End of DECK3.

Every time WSim processes the TEXT statement named MSG5, it selects a table entry from the table defined by MSGUTBL statement TBL1 based on the distribution defined by UDIST statement 2. WSim selects the first table entry 50% of the time, the second table entry 30% of the time, and the third table entry 20% of the time. Since the selection is specified as random, entries will be selected randomly in this proportion.