Detailed Description

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

With the exception of create, these methods operate on a dsdata object as returned by dsdata.create() or createrecord(). As a result, the colon (':') operator should be used.

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.getfieldbyindex (number index)
	Get a field within the update packet. More...

	dsdata.merge (DSData source_update)
	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 ituent)
	Add a consituent to a container in a given position. More...

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

	dsdata.cleardownwithprefix (DSContainer container, string prefix)
	Remove a set of ituents from a container. More...

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

	dsdata.delfieldbyindex (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.delallfields (DSData update)
	Delete all fields in an update packet. More...

	dsdata.delfield (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.frommemoryfile (DSData update)
	Return whether this update was read from the memory file. More...

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

Variables
	dsdata.DS_PAGE_TYPE
	Define the page data type.

	dsdata.DS_RECORD_TYPE
	Define the record data type.

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

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

	dsdata.DS_NEWS_TYPE
	Define the news headline data type.

	dsdata.DS_STORY_TYPE
	Define the news story data type.

	dsdata.DS_CONTAINER_TYPE
	Define the container data type.

	dsdata.DS_PERMISSION_TYPE
	Define the permission data type.

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

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

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

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

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

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

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

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

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

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

	dsdata.F_AUTHUPDATE
	This news update contains permissioning information.

	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.

	dsdata.F_DELETEOBJECT
	Instruction to delete this object.

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

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

	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	ituent
	)

Add a consituent to a container in a given position.

Parameters

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

Returns: Nothing

dsdata.cleardownwithprefix	(	DSContainer	container,
		string	prefix
	)

Remove a set of ituents from a container.

Parameters

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

Return values

nil	- Failed to remove ituents
1	- Success

All ituents 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.delallfields ( DSData update )

Delete all fields in an update packet.

Parameters

update - Update packet

Return values

nil - Always

dsdata.delfield	(	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.delfieldbyindex	(	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.frommemoryfile ( 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.getfeed ( )

Obtain the feed of an update packet.

Returns: The feed of the update packet

Example usage:

function update_func(update)
    print("This update was sent from feed "..update:getfeed())
end

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 update_func(update)
    print("Symbol name of this update is"..update:getsubject())
end

dsdata.gettype ( DSData update )

Return the type of an update packet.

Parameters

update - Update packet

Returns: The type of the update packet

dsdata.merge ( DSData source_update )

Merge two update packets.

Parameters

source_update - 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	(	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.remove	(	DSRecord	record,
		string	field
	)

Remove a field from a record.

Parameters

record	- A record objecty
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.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.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 update_func(update)
     update:setsubject("/NEWNAME")
 end

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_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