Transformer Pipeline Module API Reference  7.1.10.30066-248dcbc
DSData Update Packets

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:

1 function update_func(update)
2  update:setsubject("/NEWNAME")
3 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

Generated on Mon Aug 24 2020 15:30:26 for Transformer Pipeline Module API Reference