List

List.backOrders()

backOrders( Variant partitionID = 0 )

Parameters

startValue

The ID of the partition you want to get the back orders for.

Description

Gets an array of the back orders on a certain partition.

This array is read only, but you can query the length of the array as well as accessing individual back orders to query their data. See the List.BackOrder class for more information. List("ItemList").backOrders().lengthList("ItemList").backOrders(3)[1].puller

List.entries()

entries( Variant partitionID = 0 )

Parameters

startValue

The ID of the partition you want to get the entries for.

Description

Gets an array of the entries on a certain partition.

This array is read only, but you can query the length of the array as well as accessing individual entries to query their data. See the List.Entry class for more information. List("ItemList").entries().lengthList("ItemList").entries(3)[1].value

List.getEntryFromValue()

List.Entry getEntryFromValue( Variant value , Variant partitionID = 0 )

Parameters

value	The value that was pushed to the list.
partitionID	The ID of the partition the value was pushed to.

Description

Returns the entry associated with a value.

Searches the partition for an entry that is associated with the value. If there is no entry associated with the value the method returns null. If Unique Values Only is set to false this method will always return null.

List stations = List("StationList");
List.Entry entry = stations.getEntryFromValue(current);
stations.reevaluateBackOrders(entry);
			

List.pull()

List.PullResult pull( string sqlQuery , double requestNum , double requireNum = 0 , Variant puller = nullvar , Variant partitionID = nullvar , int flags = 0 )

List.PullResult pull( treenode object , double requestNum = 1 , double requireNum = 0 , Variant puller = nullvar , Variant partitionID = nullvar , int flags = 0 )

List.PullResult pull( Array matchValues , string sqlQuery , double requestNum = 1 , double requireNum = 0 , Variant puller = nullvar , Variant partitionID = nullvar , int flags = 0 )

Parameters

object	The object or node what you would like to pull from the list.
matchValues	A set of values to match entry values against. The pull operation will only pull values that are in the set of values defined in the matchValues array. This works as an additional filter on the set of values to pull, in addition to any WHERE clause that is defined in the sqlQuery parameter.
sqlQuery	An sql query that defines what you would like to pull from the list.
requestNum	The maximum number of things you want to pull from the list.
requireNum	The minimum number of things you want to pull from the list.
puller	The thing pulling from the list.
partitionID	The ID of the partition you want to pull from.
flags	Flags that modify the behavior of the pull.

Description

Attempts to pull values from the list.

Pulls things from the list that meet the requirements in the sql query. Returns a List.PullResult. List.PullResult pullResult = List("ItemList").pull("", 1, 1);Object item = List("ItemList").pull("WHERE type = 3 ORDER BY age", 3, 2, current, current.station);

sqlQuery - Defines the SQL query to use in pulling. The SQL query should only use the WHERE, ORDER BY, SELECT or LIMIT clauses. By default, field names correlate with object label names. For example, if your query is

WHERE type > 5 ORDER BY priority DESC

then the list will search for objects on the list who have a "type" label with a value greater than 5, and will order by objects' "priority" label value in descending order, i.e. it will prioritize higher "priority" label values. If you need more flexibility than just labels, you can add to the list's defined fields through its properties window.

requestNum - Defines the number of entries that you are requesting to pull from the list. If requestNum is greater than zero, then entries that satisfy the query will be immediately removed from the list. If requestNum is zero, the list will do the query and return the result, but it will not remove any satisfying entries. If you want to query for a limited number of entries, but you also do not want to remove them, pass 0 as the requestNum, and use the LIMIT clause in the pull query.

requireNum - Defines the number of entries that you require to be pulled from the list. This must be less than or equal to requestNum. If requireNum is greater than zero and the required number is not met, then a back order will be created for the pull request, and as items are pushed onto the list, they will be pulled off by the back order until the back order's requireNum is met, at which point the back order will be removed. If no back order queue strategy is defined on the list, back orders are fulfilled in FIFO order assuming they do not allocate all-or-nothing.

If a back order is created and you would like to be notified when the back order is fulfilled, use the eventlisten() command as follows:

eventlisten(pullResult.backOrder, "OnFulfill", callbackNode, 0, ...)

This will cause callbackNode's code to be evaluated when the back order is fulfilled. If the back order may be incrementally fulfilled multiple times, the callbackNode's code will be evaluated each time a partial fulfillment is made. Additional parameters (the ... optional parameters) may be defined for callbackNode's param(1), param(2), etc. You may replace these parameters with one of the following macros to have that parameter be replaced with a fulfillment-dependent value when the callback is made.

LIST_ON_FULFILL_VALUE - The value of the entry or entries that were pulled.LIST_ON_FULFILL_NUM_FULFILLED - The quantity that was fulfilled as part of this fulfillment. Usually 1 unless the query has a SELECT clause.LIST_ON_FULFILL_TOTAL_FULFILLED - The total quantity fulfilled for the back order up to this point.LIST_ON_FULFILL_NUM_REQUESTED - The number requested initially when the pull request was made.LIST_ON_FULFILL_NUM_REQUIRED - The number required initially when the pull request was made.

For example, if you use the command:

eventlisten(pullResult.backOrder, "OnFulfill", callbackNode, 0, LIST_ON_FULFILL_VALUE)

Here, when a fulfillment is made, param(1) of callbackNode's code will be replaced with the value for the entry that satisfied the fulfillment.

puller - Defines who or what is pulling the entries from the list. This can be 0. Reasons to use a puller may be:

• You can access the puller's labels in the query. For example, a query of WHERE Type = puller.Type would match entries whose "Type" label is equal to the puller's "Type" label.


• The list's pushers can know who is pulling them off the list. The push() method will return the back order pullers who pulled the item off the list.


• If you use the list's custom query fields, some require a valid puller to evaluate properly.

partitionId - Defines the partition id to pull from. Using a partitionId will make the list act like multiple separate lists, each uniquely identified by its partitionId. If you pushed an entry onto the list with a defined partition id, you should pull the entry off with the same partitionId.

flags - Defines behavior flags for pulling. Valid values may be one or more of the following:

• LIST_PULL_ALL_OR_NOTHING The pull request will only pull entries if it can pull all required entries. If this value is not specified, the pull/back order will pull entries off the list as they are available.
  
• LIST_PARSE_QUERY Instead of actually doing a pull operation, the list will simply parse the defined query. It will return a reference to a node that holds the cached query. This node can subsequently be passed as the query parameter to subsequent pull() calls. This can improve simulation run speed because it only has to do the parsing once, instead of every time you call pull(). Ownership of the node is given to the caller, i.e. it is your responsibility to store and later delete the node once you're done with it. You should use transfernode() to move the node where you can access it.
  
• LIST_PULL_ENTRY_NODES Instead of returning the pulled values, the command will return the set of entry nodes that reference those pulled values. Primarily this is useful only if you need to know the time that the entries were pushed onto the list (getsdtvalue(entryNode, "pushTime")). The list uses the same rules of whether to remove the entries from the list (requestNum > 0), but in this case when it removes them, it will put them into a temporary location and return them instead of destroying them. You are required to destroy them yourself (if they were removed) once you have the needed information.
  
• LIST_DO_NOT_REMOVE Matching entries on the list will be returned by this command, however, the entries will remain on the list. This is useful when creating a directory or routing that doesn't dynamically change.
  
• LIST_DO_NOT_BACK_ORDER If the number of matching entries is less than the required number, no back order will will be created.
  
• LIST_PULL_BACK_ORDERS Instead of querying the entries on the list, this command will query the back orders and return a list of all back orders that matched the specified query. If the query contains an ORDER BY, the back orders will be sorted. This will also reevaluate the back orders and will remove any back orders that are fulfilled.
  
• LIST_DO_NOT_FULFILL Used in conjunction with LIST_PULL_BACK_ORDERS, this will cause the back orders to not be reevaluated or removed. This allows you to purely query the list's back orders or to sort back orders without fulfilling any back order.
  
• LIST_RETURN_BACK_ORDER_IF_NOT_FULFILL Use in conjunction with LIST_PULL_ALL_OR_NOTHING. If the pull is unable to be fulfilled, a back order will be created. A reference to this back order node will be returned by the pull() method. This can then be used to add a listener for the onFulfill of the backorder using eventlisten().
  
  

Return Value - If the pull is successful, the command will return a List.PullResult which is a Variant holding the pulled value(s). If there are multiple values pulled, they will be in an Array. If the pull is not completely successful and a back order is created, you can access the created back order on the pull result.

pullResult.backOrder

List.push()

Variant push( Variant value )

Variant push( Variant value , Variant partitionID )

Variant push( Variant value , Variant partitionID , Variant pushArg1 , Variant pushArg2 , Variant pushArg3 , Variant pushArg4 , Variant pushArg5 , Variant pushArg6 , Variant pushArg7 , Variant pushArg8 )

Parameters

value	The value to push on the list.
partitionID	The ID of the partition you want to push to.
pushArgs	An argument you want to push with the value.

Description

Pushes a value on the list.

Puts the value on the list making it available to anyone who can pull from the list. List("ItemList").push(item);

If partitionId is specified then the list will act like multiple lists, each list uniquely identified by its partitionId. When you push a value onto a list with a given partitionId, you must later pull the value off the list by using the same partitionId.

List("ItemList").push(item, item.type);

Pushing a nullvar value will just re-evaluate all back orders without pushing anything onto the list.

List("ItemList").push(nullvar);

When you push the item onto the list, if it is immediately pulled by a back order, then the command will return the puller(s) who pulled the item off the list. Otherwise the command returns 0. To access the node that represents the entry pushed onto the list, most of the time you can use this code after pushing:

list.entries(pID)[list.entries(pID).length]

However, if Unique Values Only has been checked and the pushed value is already on the list, the entry will remain at its previous rank in the list. Finding the entry requires a manual search through the content of the list entries:

var entries = List("MyList").entries();
for (int i = 1; i <= entries.length; i++) {
	if (entries[i].value == pushedValue) {
		//Found entry
	}
}			

You may also push an array of values onto the list. This is similar to just looping through each value and pushing it onto the list, except that all entries will be pushed onto the list BEFORE evaluating back orders. This means that back orders with all-or-nothing pull requests for multiple entries can be fulfilled before they are "stolen" away by back orders without all-or-nothing requests or who are requesting fewer entries.

List.reevaluateBackOrders()

void reevaluateBackOrders( )

void reevaluateBackOrders( List.Entry entry )

Parameters

entry

The entry the back orders will be reevaluated against.

Description

Reevaluates back orders against all entries or a specific entry.

If an entry is specified, all the back orders in the same partition will be reevaluated against the enty. If no entry is specified, all back orders in every partition will be reevaluated against all the entries in the same partition. List("ItemList").reevaluateBackOrders()List("ItemList").reevaluateBackOrders(List("ItemList").entries()[1])

List Constructor

List( string name )

Parameters

name	The name of the global list.

Description

Creates a reference to a global list.

List itemList = List("ItemList");