article

ne Reference

This topic describes, in detail, the available functionality provided by the zone.

The following is the table of contents for this topic:

• zone Basics

• Default Statistics
• Subset Basics
• Example Subsets
• Subset Statistics
• Subset Calculation Basics
• Subset Calculation Statistics
• Example Subset Calculations

• Restricting Access
  • Max Content
  • Constraints
  • Constraint Examples
• Advanced Topics
  • Custom Constraint Check
  • Queue Strategy
  • Enforcing Queue Order
  • Evaluate Calculations On Exit
  • Proxy Entry and Exit
  • Non-Member Exit

• zone Basics

  The zone represents any kind of area in a Process Flow. Tokens enter and exit the zone through Enter zone and Exit zone activities. A token that has entered a zone is said to be a member of that zone until it exits. The zone keeps a list of all its members and collects statistics about them.

  The following image shows an example zone. The blue curves indicate that the Enter zone and Exit zone activities reference the zone. The green lines indicate that the tokens belong in the zone. This zone has 12 members in 4 activities. Notice that two tokens have not yet passed over an Enter zone activity, so they are not yet members of the zone.

  

  The zone can optionally categorize its members. It does this through Subsets that you define. Each token might belong in one, many, all, or none of the zone's Subsets, depending on the token's label values. The zone keeps track of the tokens that belong in each Subset, and collects statistics about each Subset.

  You can limit the number of tokens that are allowed in the zone. If the zone is full, tokens wait on the Enter zone activity until another token exits the zone.

  You can also limit the total of a given label value that is allowed in the zone. For example, if each token has a weight label, you can limit the total weight allowed in the zone. Each token waits on the Enter zone activity until there is enough room in the zone.

  In summary, the zone can collect statistics and restrict access to a set of activities.

  Back to top

  Default Statistics

  As a shared asset, the zone keeps the statistics described in Shared Assets Statistics. These statistics are updated in four steps:

  1. A token arrives on an Enter zone activity.
     The RequestInput is incremented. If the token cannot immediately enter the zone, the RequestContent is incremented.
  
  
• A token leaves an Enter zone activity.
  The RequestOutput is incremented, and the RequestStaytime is updated. If the token has waited to enter the zone, the RequestContent is decremented.
• 
  
• A token enters the zone.
  The Input and Content are incremented.
• 
  
• A token exits the zone.
  The Output is incremented, the Content is decremented, and the Staytime is updated.

• It is possible for a token to leave the Enter zone activity without actually entering the zone. This occurs if you call releasetoken() on the waiting token (perhaps when a Max Wait Timer fires). In this case, the third and fourth steps do not occur.

  Back to top

  Subset Basics

  By default, a zone does not have any Subsets. In order to add a subset, click the More Properties button in the zone's Quick Properties panel. This opens the zone Properties window. On the Subsets tab, click the Add button.

  When you add a Subset, you can specify a name and define the Token Selection Criteria.

  The name is arbitrary. However, the name will appear in other places like the Constraints tab, so make sure that it is unique and helpful.

  Token Selection Criteria

  The Token Selection Criteria is an expression. Only tokens that match that expression are included in the Subset. It is this expression that truly defines the Subset.

  The expression should be a boolean expression consisting of label names, literal value, and arithmetic operators. If there is a space in a label name, surround it with square brackets: [Label Name].

  By default, or if the Token Selection Criteria is removed, then all tokens will be included in the Subset. The expression will be replaced with the text "Include all tokens".

  When a token arrives on an Enter zone activity, the zone will determine which Subsets it belongs to. The zone assumes that the label values used to categorize the token will not change while it is on the Enter zone activity, or while the token is in the zone.

  Calculations

  You can also define Calculations for each Subset, which will be discussed later. They are not required.

  Back to top

  Example Subsets

  The following are some screenshots of subsets you could add to a zone. Each image is followed by an explanation about that Subset.

  ---

  

  This Subset only contains tokens that have an itemtype label value of 1.

  ---

  

  This Subset only contains tokens that have a weight label value greater than 300.

  ---

  

  This Subset only contains tokens that have a destination label with text equal to "England" or "Germany".

  Back to top

  Subset Statistics

  Each Subset records the same statistics as the zone (Input, Output, Content, Staytime, and their Request counterparts), but they are calculated only for the tokens that match the Token Selection Criteria. They are updated at the same time as the zone statistics.

  These statistics are very powerful. You can analyze any area of a Process Flow and answer very complex questions. Using the three examples previous shown, you could answer the following questions:

  • How many Itemtype 1 Items are in the zone?
  • How long do Heavy Items stay in the zone on average?
  • How many European Orders are waiting to enter the zone?

  Back to top

  Subset Calculation Basics

  By default, a Subset does not have any Calculations. In order to add a Calculation, click the Add () button in the Subset Calculations panel. This panel found on each Subset panel in the zone Properties window.

  A Subset Calculation is a value that is calculated per token and then totalled for the Subset. It is also composed of a name and an expression.

  The name is arbitrary, but should be unique in the Subset, and should reflect the meaning of the expression.

  The expression can be as simple as a label name, but it can include number values and arithmetic operators. Examples of valid expressions could include:

  • weight
  • length * width * height
  • age / 24

  Each Subset can have many Calculations, so there is no reason to have two Subsets with the same Token Selection Criteria.

  Back to top

  Subset Calculation Statistics

  When a token arrives on an Enter zone activity, the value of the calculation expression is evaluated for that token, and the result is saved. The following statistics are then calculated based on the result:

  • Input increases by the result when the token enters the zone.
  • Total increases by the result when the token enter the zone and decreases by the result when the token exits the zone.
  • Output increases by the result when the token exits the zone.
  • PerToken is set to the result for each token that enters the zone.
  • RequestInput increases by the result when a token arrives on an Enter zone activity.
  • RequestTotal increases by the result when a token arrives on and Enter zone activity, and decreases by the result when the token leaves the Enter zone activity.
  • RequestOutput increases by the result when a token leaves an Enter zone activity.

  Back to top

  Example Subset Calculations

  The following screenshots show Subsets with Subset Calculations. Each example followed by a list questions that could be answered by that subset.

  ---

  

  • What is the total weight of all the tokens in the zone?
  • What is the average weight per token in the zone?
  • What is the total weight of all tokens waiting to enter the zone?

  ---

  

  • What is the total weight of all the Heavy Items?
  • What is the average staytime of the Heavy Items?
  • What is the minimum volume of all the Heavy Items?

  Back to top

  Restricting Access

  You can use the zone to restrict access to a group of activities. If you think of the zone as an area, then you can limit the size or capacity of that area. If the area is full, tokens wait on the Enter zone activity until enough tokens exit the zone.

  Back to top

  Max Content

  The easiest way to restrict access to a zone is by using the Max Content option on the Quick Properties panel for the zone. When you check this box, it enables the accompanying field. This field is evaluated when a token arrives, or when a token exits the zone.

  The behavior defined by this option is very simple. The zone guarantees that its content will never exceed the value specified by the Max Content option.

  Back to top

  Constraints

  You can also use a Constraint to restrict access to the zone. By default, zones do not have any Constraints. In order to add a Constraint, click the More Properties button to open the zone Properties window. On the Constraints tab, click the Add () button. Select a constraint from the menu that appears. If the Add button is disabled, it is because there are no subsets available.

  Constraints are always applied to a Subset. You cannot change which Subset the Constraint applies to. You must remove the Constraint, and then add a new Constraint for the correct Subset.

  Next, you can specify the value that will be constrained using the Calculation dropdown menu. You can always constrain the number of tokens allowed in a subset, or you can constrain any Calculation value.

  Finally, specify the value for the right hand side of the comparison. This value becomes an upper limit for the Subset.

  Constraints can be read in this way:

  The [Calculation] must be less than or equal to [value].

  If allowing a token into the zone would violate any of the constraints (i.e. make the statement untrue), the token is not allowed into the zone.

  For example, if you are calculating the total weight of a Subset, you could restrict the total weight allowed in the Subset. You would create a Constraint for that Subset, set the Calculation to the total weight, and set the Valueto something like 1000. Then, if allowing a token into the zone would push the total weight over 1000, the token will not be allowed into the zone.

  The Value of all Constraints are evaluated if one or more tokens are about to be tested for entry into the zone. This can occur when a token arrives at a zone, or when a token exits a zone. However, it is not evaluated per token. Therefore, the Value cannot depend on a token.

  Back to top

  Constraint Examples

  The following screenshots show some example subsets, and constraints that could apply to that subset. Each example also contains a description of the expected behavior for the zone.

  ---

  

  

  This constraint requires that only 10 tokens with an itemtype label of 1 will be in the zone at any given time.

  ---

  

  

  

  Since this Subset includes all tokens, the first Constraint implies that the total weight in the zone will be no more than 300. The second constraint will ensure that there will be no more than 20 tokens in the zone. This is the same as applying a Max Content, unless a Custom Constraint Check is being used. Normally, you would only constrain the number of tokens of a Subset that has a Token Selection Criteria.

  Back to top

  Advanced Topics

  The zone provides some additional control over its behavior. Most of these options are found on the Advancedtab of the zone Properties window. Proxy Entry and Exit covers options found on the Quick Properties panel for Enter zone and Exit zone activities. Non-Member Exit describes the option with the same name on the Quick Properties panel for the Exit zone activity.

  Back to top

  Custom Constraint Check

  When the zone checks if a token can be allowed in, it evaluates all the constraints in order. As soon as a single constraint is violated, however, the zone will not check any additional constraints, and the token will be forced to wait on the Enter zone activity.

  More complex constraint logic may require a Custom Constraint Check. If a Custom Constraint Check is defined, then all constraints will be evaluated and the results of those constraints will be passed to this FlexScript function. The return value must be 1 or 0. If it returns 1, the token is allowed in the zone. Otherwise, the token will not be allowed in the zone.

  The code header for this option follows:

  /**Custom Code*/  treenode current = param(1);  treenode activity = param(2);  treenode token = param(3);  treenodearray enterFor = param(4);  intarray passFailValues = param(5);  intarray matchesValues = param(6);  doublearray currentValues = param(7);  doublearray limitValues = param(8);  doublearray spaceAvailableValues = param(9);  doublearray spaceRequiredValues = param(10);  treenode processflow = ownerobject(activity);    // If this function returns 1, all enterFor tokens will enter the zone.  // If it returns zero, none of the enterFor tokens will enter the zone,  // and 'token' waits on the Enterzone activity.    // enterFor is an array of all the tokens represented by 'token'  // passFailValues[i] specifices whether constraint i would be satisfied  // matchesValues[i] specifies how many of the enterFor tokens match the subset of constraint i  // currentValues[i] specifies the current LHS of constraint i  // limitValues[i] specifies the current RHS of constraint i  // spaceAvailableValues[i] specifies how much space is left in the constraint  // spaceRequiredValues[i] specifies the space required for all enterFor tokens for constraint i  

  As the comments indicate, many useful values are passed in. Except for the enterFor array, all array values correspond to a value dealing with a Constraint. They are explained in more detail in the following list:

  • enterFor This array contains all the tokens that are represented by the token on the Enter zone activity, namely token.
  • passFailValues The values in this array are either 1 or 0. If it is a 1, then allowing all enterFortokens will not violate the corresponding constraint.
  • matchesValue The values in this array tell you how many of the tokens in the enterFor array belong in the Subset corresponding to the given constraint.
  • currentValues The value in this array contain the current level of each constraint, telling you how much of the constraint is used.
  • limitValues The values in this array contain the maximum value for each constraint.
  • spaceAvailableValues The values in this array contain the amount left in the constraint before it will be broken. spaceAvailableValues[i] = limitValues[i] - currentValues[i]
  • spaceRequiredValues The values in this array contain the amount of each constraint that would be used if all enterFor tokens are allowed in the zone.

  Because the Custom Constraint Check is evaluated per token, you could use it to make exceptions for certain tokens. For example, you might use the Custom Constraint Check to always allow high priority tokens into the zone. You could also use it to make some constraints conditional.

  Another use of the Custom Constraint Check might be to simply log when the zone is in a violated state, but allow all tokens in.

  Max Content
  

  When the zone is using the Max Content option, it checks the Max Content first. If the Max Content would be violated by allowing a token in, it won't check any of the Constraints. If you want to use the Max Content in a Custom Constraint Check, make a Subset without a Token Selection Criteria, and make a Constraint on the number of tokens in that Subset.

  Back to top

  Queue Strategy

  The Queue Strategy is a SQL statement, with only an ORDER BY component. When a token leaves the zone, the zone checks to see if any tokens are waiting to enter the zone. If there are, the zone sorts them according to the Queue Strategy. Then it tests each request in that order. You might use this to sort the request tokens by a priority label, or by a weight label, allowing the most important tokens into the zone first.

  If there is no Queue Strategy, the requests are tested the order they arrived.

  Back to top

  Enforcing Queue Order

  Normally, the zone tests all the waiting tokens to see if any of them can enter the zone. It may be that the second token is small enough to fit, while the first token is not.

  If you enforce the queue order (by checking the Enforce Queue Order box), then the zone will not check any tokens past the first token that cannot enter the zone. This ensures that tokens enter the zone in the order they arrived on an Enter zone, or in the order created by the Queue Strategy.

  Back to top

  Evaluate Calculations On Exit

  This option is found in the Subset Calculations area of each Subset's panel on the Subsets tab. If the box is checked, then a token's effect on the calculation is reevaluated. This is only necessary if the token's label values used by the Calculations change while the token is in the zone. This will keep the Cacluation statistics accurate, but it will invalidate all other statistics kept by the zone and its Subsets.

  Back to top

  Proxy Entry And Exit

  A token can enter for itself, or it can enter for a group of tokens (now deemed a proxy token), such as all of the children of the entering token. This can e defined on the Enter zone's Enter For property.

  When a token attempts to enter a zone, it does so on behalf of all the tokens it represents. If allowing all the members of that group into the zone would violate the Max Content or any of the Constraints, the token will not leave the Enter zone activity, and the members of its group will not become members of the zone. Otherwise, the token exits the Enter zone activity and all the tokens it represents become members of the zone.

  The request statistics kept by the zone are always calculated using the tokens that will become members of the zone, not by the tokens on the Enter zone activity. This difference is not important if tokens are entering for themselves.

  When the token exits the zone it can exit for itself or as a proxy for other tokens. The Exit zone activity has an Exit For property that allows you to specify which token(s) the token is exiting the zone for. The zone's statistics will be updated for all tokens that exit the zone.

  If entering or exiting for multiple tokens, these properties should return a treenodearray of tokens. This can be created on a label by using the Assign Labels activity.

  Back to top

  Non-Member Exit

  The Exit zone activity has the Non-Member Exit option on its Quick Properties panel. This option controls the zone's behavior when the following occurs:

  • A token arrives on an Exit zone activity, and
  • Any of the tokens it is exiting for were never added to the zone.

  The default behavior does not allow this to occur; an exception is thrown, appearing in the System Console.

  The second option is to ignore these tokens. They do not affect the zone's statistics, and the simulation continues.

  The third option is to update the zone's statistics. The token is evaluated, so that its affect on any Subset Calculations can be applied as it leaves. You might want to do this if a token enters the zone with some value on a label, and that value is split among many tokens that then leave the zone. The zone allows you to track the total label value in this case. However, only the Calculation statistics will be valid in this case. Content, Input, Output, and Staytime statistics for the zone and its subsets will no longer be valid.

  Back to top