Objects in this document may appear out of sequence if not viewed with Internet Explorer

ORMSware NMOD Primer: Chapter 9


Creation, assignment and disposal of tokens and surrogates

Most of the creation, assignment and disposal of tokens and surrogates in a model occur automatically based on the properties of network objects in the model. However, there are potential occasions when analysts directly create, manipulate, track and dispose off tokens and surrogates based on the nature of the problem being modeled.

Creation and disposal of tokens

While tokens are automatically created when surrogates reach Arrival nodes, and are automatically disposed off when surrogates complete Departure node events, analysts can also specify creation and disposal of tokens by using exposed NMOD procedures CreateTkn and DisposeTkn as follows:

CALL CreateTkn ( bigTokenID, bigCustID )
CALL DisposeTkn ( bigTokenID, bigCustID )

bigCustID is optional in either call.

If bigCustID is present, analyst must provide its value in CreateTkn call. bigCustID  can be a constant, variable, function or expression that evaluates to a scalar integer value of the big KIND. If it is not present, the customer is assumed to be default Customer (ID = 0).

Note: KIND is explained in detail in Chapter 11 (Notations of properties). For now, let us just mention that defining numerical data in terms of the KIND attribute makes the model portable to any platform (PCs to supercomputers) hosting a Fortran 95 compiler. big KIND ensures that integers stored in a variable of that KIND on any platform can hold a value at least as large as 10 ** 18.

bigCustID is an optional output argument in DisposeTkn call.

When the analyst makes a CreatTkn call, NMOD does the following:

  • If the optional argument bigCustID is present in the call, creates a new Customer ID as explained in Chapter 8 (Arrival and Departure nodes). If bigCustID is not present, assumes that the customer is the default Customer.

  • Creates a token and relates/assigns it to the Customer ID as determined in the step above, and returns the token's ID value in bigTokenID.

When the analyst makes DisposeTkn call, NMOD does the following:

  • Determines to which customer the token bigTokenID was assigned.

  • Disposes off token bigTokenID and, if the optional argument bigCustID is present in the call, returns bigTokenID's Customer ID value in bigCustID.

A network object subroutine is a procedure created by NMOD's NETrans, the ORMSware translator/preprocessor program that converts ORMSware NMOD models into compilable code, to execute content provided by the analyst for any given network object (node/arc).

Caution: By default, the active token in a network object subroutine is bigTkn. It is an automatic argument in every network object subroutine and is automatically declared in every network object subroutine by NETrans. The user should consider the consequences of using the symbol bigTkn as argument in the above CALLs. 
Notes

1. The analyst can use any symbol they choose in place of bigTokenID and/or bigCustID. Whatever the analyst chooses to use (even if they are bigTokenID and bigCustID), they should be declared at the appropriate level in the model. Chapter 17 (User-defined scalars, arrays, derived types and procedures) contains explanations of the levels (model level and network object level) at which the user-defined variables can be declared.

2. NMOD automatically executes DisposeTkn when an entity comes out of Events queue upon completing a Departure node, but before executing SignalTarget property of that node. Events queue is explained in Chapter 13 (Events, execution feedback, and model debugging) and SignalTarget property is expalined in Chapter 14 (SignalTargets/temporal arcs property of network objects).

3. There are other node Types (Cloning and Decloning) that cause creation and disposal of tokens, but they are not available in the current version of NMOD.

Creation and disposal of surrogates

In Chapter 7 (ORMSware entities) we explained that NMOD creates two surrogates at the very beginning of a model run; the first one for certain housekeeping purposes, and the second one for triggering the Start node in the top network (first page) of the model. Additional surrogates are automatically created and disposed by NMOD based on the networks formulated by the analyst.

In our example problem (see diagram in Figure 10 window -- click here if it is not already open), when the Start node n[6]Initializations is finished, NMOD creates three surrogates (assuming all three arc conditions are satisfied) to send along arcs a[11], a[12] and a[13]. When NMOD creates these surrogates, it also sets values of their user-defined properties equal to those of the surrogate that finished execution of [6].

Note: To be more precise, when n[6] is finished, NMOD actually stores property values of the surrogate that triggered (and completed) the execution of n[5] before it "disposes" that surrogate; when it determines that n[6] has three successor arcs, it creates three surrogates to send along those arcs. Since NMOD reuses the most recently disposed surrogate (viz. the surrogate that completed n[6] and was disposed off when n[6] was finished), that will be the first surrogate used for traversing n[6]'s first successor arc. Before traversing successor arcs, all surrogates inherit stored property values of the trigger surrogate. We are giving you that bit of detail at this point to prepare you for looking at execution feedback files later on.

Surrogates automatically get disposed off when a node does not have any arcs originating from it (i.e. there are no successor arcs). When a node is finished, NMOD disposes the surrogate as mentioned in the note above. If a node has no successor arcs, that surrogate becomes inactive until it is called into action again in another context. 

While surrogates are automatically created and disposed by the structure of network(s) in a model, analysts can actively specify additional creation and disposal of surrogates by using exposed NMOD procedures CreateSur and DisposeSur as follows:

CALL CreateSur ( bigSurrID, bigTokenID )
CALL DisposeSur ( bigSurrID, bigTokenID )

bigTokenID is optional in either call. If present, analyst must provide its value in CreateSur call. bigTokenID can be a constant, variable, function or expression that evaluates to a scalar integer value of the big KIND.

bigTokenID is an optional output argument in DisposeSur call.

When the analyst makes CreateSur call as above, NMOD does the following:

  • If the optional argument bigTokenID is not present in the call, assumes that the token is the default Token.

  • Creates a surrogate and relates/assigns it to the Token ID as determined in the step above, and returns the surrogate's ID value in bigSurrID.

When the analyst makes DisposeSur call, NMOD does the following:

  • Determines to which token the surrogate bigSurrID was assigned.

  • Disposes off surrogate bigSurrID and, if the optional argument bigTokenID is present in the call, returns bigSurrID's Token ID value in bigTokenID.

The analyst must declare bigSurrID and bigTokenID at the appropriate level.

Caution: By default, the active surrogate in a network object subroutine is bigSur. It is an automatic argument in every network object subroutine and is automatically declared in every network object subroutine by NETrans. The user should consider the consequences of using the symbol bigSur as argument in the above CALLs. 
Note: As explained earlier, when a node event is complete, NMOD automatically executes DisposeSur. Then, it executes CreateSur for every successor arc of that node.

 

Click to go to Chapter 8: Arrival and Departure nodes

Click to go to Chapter 10: System, Global, Customer and Surrogate properties

Click to go to Introduction: NMOD Primer