Transformer Pipeline Module API Reference  6.2.11.309924
Transformer Cache Access

Functions

 cache.sendnodata (var symbol, var flags)
 Send a nodata message to the Transformer. More...
 
 cache.getfield (var symbol, var field)
 Get a field from the cache. More...
 
 cache.getupdate (var symbol)
 Obtain the cached image for a symbol. More...
 
 cache.request (var symbol, var accessory)
 Request updates for a symbol to flow into the Transformer. More...
 
 cache.discard (var symbol, var accessory)
 Stop updates for a symbol flowing into the Transformer. More...
 
 cache.match (var pattern)
 Return a list of symbols matching a pattern. More...
 
 cache.getstatus (var symbol)
 Return the status of a symbol. More...
 
 cache.sendstatus (var symbol, var status, var message)
 Send a status message. More...
 
 cache.getsymboltype (var symbol)
 Obtain the type for a symbol in the cache. More...
 
 cache.cancelsub ()
 Cancel the current subscription on this pipeline. More...
 
 cache.uncancelsub (var symbol)
 Uncancel the current subscription on all pipelines. More...
 
 cache.blocksub ()
 Block updates for the current symbol on this pipeline. More...
 
 cache.unblocksub (var symbol)
 Unblock future updates for the given symbol on all pipelines. More...
 

Detailed Description

The functions in this package provide access to the contents of the Transformer's cache.

This package also contains functionality for managing the subscription of objects requested from and by other DataSource peers.

Note
The functions uncancelsub() and cache.cancelsub() are similar to the functions cache.request() and cache.discard() but serve different purposes.
The cache.uncancelsub() function requires that a requested symbol match at least one pipeline's listener-regex configuration option. To request a symbol without this restriction, use the cache.request() function.

These functions may not result in the Transformer sending a discard or request for a symbol. A request will only be sent if there is no existing subscription for the symbol. A discard will only be sent if the last subscription is being removed.

Function Documentation

cache.blocksub ( )

Block updates for the current symbol on this pipeline.

Returns
Nothing

This function blocks the updates for the symbol currently being handled by the pipeline from entering the pipeline. Updates still enter the Transformer but they are blocked from entering the current pipeline. No other pipelines matching the symbol are affected. Note that only updates are affected: status, nodata, request and discard messages are not blocked.

Example:

The following example shows an update function blocking updates for the received symbol based on a given field. If the "Block" field is 1 then updates are blocked and will not reach the update function until they are unblocked - see cache.unblocksub().

Note that there is no else case to unblock the update because once cache.blocksub() has been called, update() will not be entered for the symbol. Hence unblocking will normally be called from another pipeline.

    function update(dsdata)
       
       local block = dsdata:getfield("Block")
 
       if tonumber(block) == 1 then
          cache.blocksub()
       end
    end
cache.cancelsub ( )

Cancel the current subscription on this pipeline.

Returns
Nothing

This function cancels the subscription for the symbol currently being handled by the pipeline. The subscription is only cancelled for the current pipeline.

cache.discard ( var  symbol,
var  accessory 
)

Stop updates for a symbol flowing into the Transformer.

Parameters
symbol- Symbol to discard
accessory- [Optional] If defined, then this subscription is an accessory
cache.getfield ( var  symbol,
var  field 
)

Get a field from the cache.

Parameters
symbol- Symbol whose field should be retrieved
field- Field to return
Returns
Field value
Return values
nil- Field not cached or symbol not known

The field may either be a number (eg 22), or a full name as defined in fields.conf (eg BID)

cache.getstatus ( var  symbol)

Return the status of a symbol.

Parameters
symbol- Symbol to query the status of
Return values
cache.STATUS_OK- Symbol status is ok
cache.STATUS_LIMITED- Symbol status is limited
cache.STATUS_STALE- Symbol status is stale
cache.STATUS_UNKNOWN- No status available for symbol

A second return parameter contains the status message as a string

cache.getsymboltype ( var  symbol)

Obtain the type for a symbol in the cache.

Parameters
symbol- Symbol whose type should be retrieved
Returns
The type of the symbol
Return values
-1- Symbol not cached
cache.getupdate ( var  symbol)

Obtain the cached image for a symbol.

Parameters
symbol- Symbol whose cached update should be retrieved
Returns
The cached update
Return values
nil- Symbol not cached or symbol is in cache but has no fields
cache.match ( var  pattern)

Return a list of symbols matching a pattern.

Parameters
pattern- [Optional] a pattern to match
Returns
A table containing matched symbols.

If no pattern is supplied, then the pattern is implicitly "/*"

The example below returns a list of all symbols in the cache and prints their names to stdout.

syms = cache.match()
for i = 1, #syms do
   print(i, syms[i])
end
cache.request ( var  symbol,
var  accessory 
)

Request updates for a symbol to flow into the Transformer.

Parameters
symbol- Symbol to request
accessory- [Optional] If defined, then this subscription is an accessory

A pipeline should be configured as a listener for this symbol

cache.sendnodata ( var  symbol,
var  flags 
)

Send a nodata message to the Transformer.

Parameters
symbol- Symbol that a nodata message should be sent for
flags- [Optional] optional flags

The default flag sent is dsdata_F_DELETEOBJECT.

The nodata will propagated onto any connected peers if they are receving updates for symbol.

cache.sendstatus ( var  symbol,
var  status,
var  message 
)

Send a status message.

Parameters
symbol- Symbol to send the status of
status- Status code to send
message- Status message to send
Returns
Nothing

The status should be one of the following values:

  • cache.STATUS_OK - The status of the object is ok
  • cache.STATUS_STALE - The status of the object is stale (and hence its values shouldn't be trusted)
  • cache.STATUS_INFO - Informational message

The status will be distributed to all interested peers and modules

Example:

The following example sends a STALE message for subject /FX/EURGBP=

    cache.sendstatus("/FX/EURGBP=", cache.STATUS_STALE, "Object is stale")
cache.unblocksub ( var  symbol)

Unblock future updates for the given symbol on all pipelines.

Parameters
symbol- Symbol whose updates are being unblocked.
Returns
Nothing

This function unblocks the updates for the given symbol on all pipelines which match the symbol, i.e. calling this function allows updates for the given symbol to be passed into all matching pipelines.

Example:

The following example unblocks the updates for subject /FX/EURGBP

    cache.unblocksub("/FX/EURGBP")
cache.uncancelsub ( var  symbol)

Uncancel the current subscription on all pipelines.

Parameters
symbol- Symbol whose subscription is being uncancelled.
Returns
Nothing

This function reinstates the subscription for the given symbol on all pipelines which match the symbol.

Example:

The following example reinstates the subscriptions for subject /FX/EURGBP

    cache.uncancelsub("/FX/EURGBP")

Generated on Sat Aug 26 2017 12:36:33 for Transformer Pipeline Module API Reference