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 cache.subscribe_pipelines() and cache.remove_current_pipeline_subscription() are similar to the functions cache.request() and cache.discard() but serve different purposes.

cache.subscribe_pipelines() and cache.remove_current_pipeline_subscription() start and stop data flowing into pipelines.
cache.request() and cache.discard() start and stop data flowing into the Transformer.

The cache.subscribe_pipelines() 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.

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.remove_current_pipeline_subscription ()
	Cancel the current subscription on this pipeline. More...

	cache.uncancelsub (var symbol)
	Subscribe to a symbol on all pipelines. More...

	cache.subscribe_pipelines (var symbol)
	Subscribe to a symbol 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...

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.

Deprecated:: Use cache.remove_current_pipeline_subscription()

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.remove_current_pipeline_subscription ( )

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.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.subscribe_pipelines ( var symbol )

Subscribe to a symbol on all pipelines.

Parameters

symbol - Symbol to subscribe to

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.subscribe_pipelines("/FX/EURGBP")

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 )

Subscribe to a symbol on all pipelines.

Deprecated:: Use cache.subscribe_pipelines()

Detailed Description

Functions

Function Documentation