Detailed Description

The functions in this package provide access to the update packets that pass through the pipeline system.

Functions
	dsdata.create (string subject, number type, number flags)
	Create a new update packet. More...

	dsdata.clone ()
	Copy an update packet. More...

	dsdata.send (number flags)
	Send an update packet. More...

	dsdata.getSubject ()
	Obtain the subject of an update packet. More...

	dsdata.setSubject (string subject)
	Set the subject of an update packet. More...

	dsdata.numFields ()
	Get the number of field/value pairs in the update packet. More...

	dsdata.getField (string field)
	Get a field within the update packet. More...

	dsdata.getFields ()
	Get the fields within the update packet. More...

	dsdata.setField (string field, string value)
	Set a field within the update packet. More...

	dsdata.setFieldbyindex (number index, string value)
	Update the value of a field in the update packet. More...

	dsdata.getFieldbyindex (number index)
	Get a field within the update packet. More...

	dsdata.merge (DSData sourceUpdate)
	Merge two update packets. More...

	dsdata.add (DSPage page, number r, number c, string value)
	Add data to a page. More...

	dsdata.add (DSRecord record, string field, string value)
	Add a field to a record update. More...

	dsdata.add (DSContainer container, string symbolname)
	Add an object to a container object. More...

	dsdata.add (DSPermission permission, string key)
	Add a key to a permission object. More...

	dsdata.add (DSPermission permission, string field, string value)
	Add a field to a permission update. More...

	dsdata.add (DSContainer container, number position, string constituent)
	Add a consituent to a container in a given position. More...

	dsdata.removeField (DSContainer container, string symbol)
	Remove a symbol from a container. More...

	dsdata.clearWithPrefix (DSContainer container, string prefix)
	Remove a set of constituents from a container. More...

	dsdata.remove (DSRecord record, string field)
	Remove a field from a record. More...

	dsdata.deleteFieldbyindex (DSData update, number index)
	Remove a field from an update based on an index. More...

	dsdata.getFlags (DSData update)
	Return the flags for an update packet. More...

	dsdata.setFlags (DSData update, number flags)
	Set the flags for an update packet. More...

	dsdata.getType (DSData update)
	Return the type of an update packet. More...

	dsdata.setType (DSData update, string type)
	Set the type for an update packet. More...

	dsdata.deleteFields (DSData update)
	Delete all fields in an update packet. More...

	dsdata.deleteField (DSData update, string field)
	Delete a field within an update packet. More...

DSRecord	createrecord (string subject, number flags)
	Create a record update. More...

DSRecord	creategenericobject (string subject, number flags)
	Create a generic record update. More...

DSContainer	createcontainer (string subject, number flags)
	Create a container update. More...

DSPage	createpage (string subject, number rows, number columns, number flags)
	Create a page update. More...

	dsdata.isFromMemory (DSData update)
	Return whether this update was read from the memory file. More...

	dsdata.getFeed ()
	Obtain the feed of an update packet. More...

Variables
const	dsdata.DS_PAGE_TYPE
	Define the page data type.

const	dsdata.DS_RECORD_TYPE
	Define the record data type.

const	dsdata.DS_RECORD_TYPE2
	Define the type 2 record (market depth) data type.

const	dsdata.DS_RECORD_TYPE3
	Define the type 3 record (history) data type.

const	dsdata.DS_NEWS_TYPE
	Define the news headline data type.

const	dsdata.DS_STORY_TYPE
	Define the news story data type.

const	dsdata.DS_CONTAINER_TYPE
	Define the container data type.

const	dsdata.DS_PERMISSION_TYPE
	Define the permission data type.

const	dsdata.DS_GENERIC_TYPE
	Define the generic data type.

const	dsdata.DS_JSON_TYPE
	Define the generic data type.

const	dsdata.F_CREATEOBJECT
	Create this object if it doesn't exist.

const	dsdata.F_CREATEPARENT
	Create the parent directory if it doesn't exist.

const	dsdata.F_CLEAR_TYPE3
	Clear all record type 3 entries this update's symbolname.

const	dsdata.F_FILTER_TYPE3
	Clears a type 3 entries with the same value as the first field in this update.

const	dsdata.F_CLEAR_TYPE2
	Clear all record type 2 entries for this update's symbolname.

const	dsdata.F_FILTER_TYPE2
	Clears type 2 entries with the same value as the first field in this update. More...

const	dsdata.F_NOCACHE
	Do not cache this update - pass directly through to client. More...

const	dsdata.F_DELETE_HEADLINE
	Delete the headline associated with the story code in this update. More...

const	dsdata.F_CHANGE_HEADLINE
	Change the headline associated with the story code in this update to the headline contained in this update. More...

const	dsdata.F_IMAGE
	This update is an image not a live update. All fields will be replaced by this update.

const	dsdata.F_AUTHUPDATE
	This news update contains permissioning information.

const	dsdata.F_CHANGEDFIELDS
	Tells the liberator to only send on any changed fields. This tells the liberator compare this update with the cached data and only send on any changed fields to any subscribers. See the Liberator Admin Guide for details.

const	dsdata.F_NONACTIVE
	Indicates that the object is not active, even if the DataSource is.

const	dsdata.F_NOTFOUND
	Indicates that the object was not found.

const	dsdata.F_DELETEOBJECT
	Instruction to delete this object.

const	dsdata.F_CONSTITUENT_NOAUTH
	Indicates that the constituents in this container should not be subject to permissioning. More...

const	dsdata.CACHE
	This update should be saved within the in-memory databse. More...

const	dsdata.PUBLISH
	This update should be (potentially) sent to interested peers. More...

const	dsdata.NOLISTENERS
	Indicate that this update should not be passed to modules. More...

Function Documentation

DSContainer createcontainer	(	string	subject,
		number	flags
	)

Create a container update.

Parameters

subject	- Subject of the update
flags	- Optional: Flags for the update packet

Returns: A container update (DSContainer)

DSRecord creategenericobject	(	string	subject,
		number	flags
	)

Create a generic record update.

Parameters

subject	- Subject of the update
flags	- Optional: Flags for the update packet

Returns: A generic record update (DSRecord)

DSPage createpage	(	string	subject,
		number	rows,
		number	columns,
		number	flags
	)

Create a page update.

Parameters

subject	- Subject of the update
rows	- Number of rows
columns	- Number of columns
flags	- Optional: Flags for the update packet

Returns: A page update (DSPage)

DSRecord createrecord	(	string	subject,
		number	flags
	)

Create a record update.

Parameters

subject	- Subject of the update
flags	- Optional: Flags for the update packet

Returns: A record update (DSRecord)

dsdata.add	(	DSPage	page,
		number	r,
		number	c,
		string	value
	)

Add data to a page.

Parameters

page	- A page object
r	- Row
c	- Column
value	- Value

Return values

nil	- Failed to data
1	- Success

dsdata.add	(	DSRecord	record,
		string	field,
		string	value
	)

Add a field to a record update.

Parameters

record	- A record object
field	- Field to set
value	- Value to assign to the field

Returns: The field number field corresponds to

Return values

nil	- Unknown field

Should field already exist in the update, then its value will be updated.

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

dsdata.add	(	DSContainer	container,
		string	symbolname
	)

Add an object to a container object.

Parameters

container	- A container object
symbolname	- Symbol name to add

Return values

nil	- Failed to data
1	- Success

dsdata.add	(	DSPermission	permission,
		string	key
	)

Add a key to a permission object.

Parameters

permission	- A permission object
key	- A permission key

Return values

nil	- Failed to add key
1	- Success

dsdata.add	(	DSPermission	permission,
		string	field,
		string	value
	)

Add a field to a permission update.

Parameters

permission	- A permission object
field	- Field to set
value	- Value to assign to the field

Returns: The field number field corresponds to

Return values

nil	- Unknown field

Should field already exist in the update, then its value will be updated.

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

dsdata.add	(	DSContainer	container,
		number	position,
		string	constituent
	)

Add a consituent to a container in a given position.

Parameters

container	- A container object
position	- Position to insert the constituent to
constituent	- Name of the constituent

Returns: Nothing

dsdata.clearWithPrefix	(	DSContainer	container,
		string	prefix
	)

Remove a set of constituents from a container.

Parameters

container	- A container object
prefix	- Prefix of constituents to be removed

Return values

nil	- Failed to remove constituents
1	- Success

All constituents whose subject prefix is the same as the prefix parameter will be removed from the container.

dsdata.clone ( )

Copy an update packet.

Returns: A new update packet

Example to copy an existing dsdata object:

1 cloned-update = update.clone()

dsdata.create	(	string	subject,
		number	type,
		number	flags
	)

Create a new update packet.

Parameters

subject	- Subject of the update
type	- [Optional] Type of the update.
flags	- [Optional] Flags for the update packet

The default type is dsdata.DS_RECORD_TYPE

The default flags are dsdata.F_CREATEOBJECT|dsdata.F_CREATEPARENT

Returns: A new update

See also: createrecord()

Example to create a dsdata object (of type record) with the subject /TEST:

1 update = dsdata.create("/TEST")

dsdata.deleteField	(	DSData	update,
		string	field
	)

Delete a field within an update packet.

Parameters

update	- Update packet
field	- Field to delete

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

dsdata.deleteFieldbyindex	(	DSData	update,
		number	index
	)

Remove a field from an update based on an index.

Parameters

update	- Update packet
index	- Field index to remove

Returns: The field number field corresponds to

Return values

nil	- Unknown field index

This function can be used on all types of update objects

dsdata.deleteFields ( DSData update )

Delete all fields in an update packet.

Parameters

update - Update packet

Return values

nil - Always

dsdata.getFeed ( )

Obtain the feed of an update packet.

Returns: The feed of the update packet

Example usage:

function updateFunc(update)
{
    print("This update was sent from feed " + update.getFeed());
}

dsdata.getField ( string field )

Get a field within the update packet.

Parameters

field - Field to obtain

Returns: The field value

Return values

nil	- Field not present in packet

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

dsdata.getFieldbyindex ( number index )

Get a field within the update packet.

Parameters

index - Field index to obtain

Returns: The field value; The field number; The field flags

Return values

nil	- Field not present in packet

The field index should be in the range 0 + . dsdata.numFields()

dsdata.getFields ( )

Get the fields within the update packet.

Returns: A table of the field values - table may be empty

Return values

nil	- Packet type not supported

dsdata.getFlags ( DSData update )

Return the flags for an update packet.

Parameters

update - Update packet

Returns: The current flags for an update packet

dsdata.getSubject ( )

Obtain the subject of an update packet.

Returns: The subject of the update packet

Example usage:

function updateFunc(update)
{
    print("Symbol name of this update is" + update.getSubject());
}

dsdata.getType ( DSData update )

Return the type of an update packet.

Parameters

update - Update packet

Returns: The type of the update packet

dsdata.isFromMemory ( DSData update )

Return whether this update was read from the memory file.

Parameters

update - Update packet

Return values

0	- Update wasn't read from the memory file
1	- Update was read from the memory file

The memory file is determined by the transformer option memory-file. On startup of the Transformer, the memory is read and updates are pushed into the cache and through all registered modules.

dsdata.merge ( DSData sourceUpdate )

Merge two update packets.

Parameters

sourceUpdate - Update packet to be used as source

Return values

1	- Merge was successful
nil	- Merge wasn't successful

A merge will fail if the two parameters aren't dsdata objects.

dsdata.numFields ( )

Get the number of field/value pairs in the update packet.

Returns: Number of field/value pairs in the update

dsdata.remove	(	DSRecord	record,
		string	field
	)

Remove a field from a record.

Parameters

record	- A record object
field	- Field to remove

Returns: The field number field corresponds to

Return values

nil	- Unknown field

Should field already exist in the update, then its value will be updated.

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

dsdata.removeField	(	DSContainer	container,
		string	symbol
	)

Remove a symbol from a container.

Parameters

container	- A container object
symbol	- Symbol to remove from the container

Return values

nil	- Failed to remove symbol
1	- Success

dsdata.send ( number flags )

Send an update packet.

Parameters

flags - [Optional] any or many of dsdata.CACHE, dsdata.PUBLISH, dsdata.NOLISTENERS

The default flags are dsdata.CACHE|dsdata.PUBLISH

Example to publish a dsdata object:

1 update.send()

dsdata.setField	(	string	field,
		string	value
	)

Set a field within the update packet.

Parameters

field	- Field to set
value	- Value to assign to the field

Returns: The field number field corresponds to

Return values

nil	- Unknown field

Should field already exist in the update, then its value will be updated.

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

dsdata.setFieldbyindex	(	number	index,
		string	value
	)

Update the value of a field in the update packet.

Parameters

index	- Index of the field to update
value	- Value to assign to the field

Returns: The field index

Return values

nil	- Field index was invalid

The field index should be in the range 0 + . dsdata.numFields()

dsdata.setFlags	(	DSData	update,
		number	flags
	)

Set the flags for an update packet.

Parameters

update	- Update packet
flags	- Flags to set

Returns: The current flags for an update packet

dsdata.setSubject ( string subject )

Set the subject of an update packet.

Parameters

subject - Subject for the update

Returns: Nothing

Example to change the name of an update:

 function updateFunc(update)
 {
     update.setSubject("/NEWNAME");
 }

dsdata.setType	(	DSData	update,
		string	type
	)

Set the type for an update packet.

Parameters

update	- Update packet
type	- Type to set

Returns: The current flags for an update packet

Variable Documentation

dsdata.CACHE

This update should be saved within the in-memory databse.

If an update is passed to packet_contrib() with this flag then the update will be added to the database.

dsdata.F_CHANGE_HEADLINE

Change the headline associated with the story code in this update to the headline contained in this update.

Note: This flag is only valid with dsdata.DS_NEWS_TYPE data objects. Erroneous behaviour may result if applied to other data types.

dsdata.F_CONSTITUENT_NOAUTH

Indicates that the constituents in this container should not be subject to permissioning.

This flag only has effect on the initial update or any subsequent updates with the F_IMAGE flag set for the container. Setting this flag will prevent Liberator from applying auth module mapping and permissioning rules.

dsdata.F_DELETE_HEADLINE

Delete the headline associated with the story code in this update.

Note: This flag is only valid with dsdata.DS_NEWS_TYPE data objects. Erroneous behaviour may result if paplied to other data types.

dsdata.F_FILTER_TYPE2

Clears type 2 entries with the same value as the first field in this update.

If the first field within the update is that of a type 2 index field, then that type 2 entry is removed.

However, if the first field is not an index field, then all type 2 entries with the specified field/value combination will be removed. A string comparison is performed thus "22" will not match "22.00"

This flag should only be supplied to packets which have a type of dsdata.DS_RECORD_TYPE2

dsdata.F_NOCACHE

Do not cache this update - pass directly through to client.

Note: This flag is only relevant for dsdata.DS_RECORD_TYPE data objects

dsdata.NOLISTENERS

Indicate that this update should not be passed to modules.

This flag will prevent this update being passed to any modules that may have registered any kind of interest in this symbol.

dsdata.PUBLISH

This update should be (potentially) sent to interested peers.

An update will be sent if one the following conditions are met:

An active peer has requested the symbol

Detailed Description

Functions

Variables

Function Documentation

Variable Documentation