
TX/MAM Database Protocol Manual
Document version: 2.2 - 2013-04-02

1. Grass Valley Product Support ......................................................................................................................... 3
2. About this document ........................................................................................................................................ 3
3. TX/MAM functions and syntax......................................................................................................................... 3
4. Defines ............................................................................................................................................................. 4
5. Initializing the library ....................................................................................................................................... 6
5.1 Initializing the library to use a local playout database ............................................................................ 6
5.2 Initializing the library to use a remote database ..................................................................................... 7
6. Database search functions .............................................................................................................................. 8
6.1 Clearing all criteria used in a previous search ......................................................................................... 8
6.2 Adding a criterion that defines a restriction for integer database fields ................................................... 9
6.3 Adding a criterion that defines a restriction for int64 (='long long') database fields .............................. 10
6.4 Adding a criterion that defines a restriction for string database fields ................................................... 11
6.5 Adding a criterion that contains a SQL-query ....................................................................................... 12
6.6 Adding a criterion that contains a parameter for a previously added SQL-query .................................. 13
6.7 Retrieving the list of IDs that are the result of evaluating the previously added criteria ....................... 14
7. Retrieve functions ......................................................................................................................................... 15
7.1 Clearing all requests for fields that may have been used in a previous retrieve call ............................. 15
7.2 Adding a field request for an integer database field ............................................................................. 16
7.3 Adding a field request for an int64 (= long long) database field ............................................................ 17
7.4 Adding a field request for a string database field ................................................................................. 18
7.5 Adding a field request for a text blob database field .............................................................................. 19
7.6 Retrieving the requested fields for the record with id == id and from the table == table ....................... 20
8. Update functions ........................................................................................................................................... 21
8.1 Adding a field update for an integer database field ............................................................................... 21
8.2 Adding a field update for an int64 (= long long) database field ............................................................. 22
8.3 Adding a field update for a string database field.................................................................................... 23
8.4 Adding a field update for a text blob database field ............................................................................... 24
8.5 Updating the record (from table with ID) with the previously added field values .................................. 25
8.6 Creating a record in the table with previously added fieldvalues .......................................................... 26
8.7 Creating the assetjobs, asset_index and group_access records for an asset in the
database ............................................................................................................................................................ 27
8.8 Deleting a record (indicated by the ID) from a table .............................................................................. 28
9. Finalization functions .................................................................................................................................... 29
9.1 Cleaning up the library ........................................................................................................................... 29
10. Date & time functions ................................................................................................................................. 30
10.1 Converting a Cobalt time field to two strings containing resp. the time and date part .......................... 30
10.2 Converting human readable time and date string to a Cobalt time field ............................................... 31
10.3 Getting the current system time and converting to a Cobalt time field .................................................. 32
11. Scheduling functions ................................................................................................................................. 33
11.1 Creating a new main event with import fields and formats ....................................................................... 33
11.2 Checking if the asset indicated by asset_id is in a schedule with the time indicated by
start_timedate and end_timedate ...................................................................................................................... 36
12. Utility functions........................................................................................................................................... 37
12.1 Returning the current library version ...................................................................................................... 37
Copyright © Grass Valley USA, LLC. All rights reserved. This product may be covered by one or
more U.S. and foreign patents.
TX/MAM Database Protocol Manual - document version: 2.2 – Page 2

1. Grass Valley Product Support
Contact information: http://www.grassvalley.com/support/contact
U.S Technical Support: +1 800-547-4989 or +1 530 478 4148 or E-mail: Please use our online
form
All other countries Technical Support: +800 80 80 20 20 or +33 1 48 25 20 20 or E-mail:
callcentre@grassvalley.com
FAQ: http://grassvalley.novosolutions.net/
Training: https://grassvalley.csod.com/LMS/catalog/Main.aspx?tab_page_id=-67&tab_id=6
2. About this document
This document applies to TX/MAM version 2.2, nexos version 3.0 and Channel Composer version
1.6 and higher.
The K2 Edge Protocol Manual describes how to launch Channel Composer templates on nexos.
3. TX/MAM functions and syntax
Applets are written in C. The extension for applet files is .app. To be able to retrieve information from
the TX/MAM database, a library (libcolbalt.so) and a header file (cobalt.h) are available on request.
Following functions are available in the library:
Initialize the library
Database search functions
Retrieve functions
Update functions
Finalization functions
Date & time functions
Scheduling functions
Utility functions
When defining an applet in Channel Composer, make sure to specify the parameters that are used
by the applet.
TX/MAM Database Protocol Manual - document version: 2.2 – Page 3

The maximum number of rows that
can be retrieved from the database in
one call.
The size for a small text blob
database field.
This criterion will use the
'AND' operator with the next
criterion.
This criterion will use the 'OR'
operator with the next
criterion.
Get all records from a table.
Get all records where the
provided value equals the field
value.
Get all records where the
provided value is part of the
field value. Can only be used
with string or text blob fields.
Get all records where the field
value is greater than the
provided value; usually
applied for integer or int64
fields.
Get all records where the field
value is smaller than the
provided value; usually
applied for integer or int64
fields.
COP_GREATER_THAN_OR
_EQUALS
“GREATER_THAN_OR_EQ
UALS”
Get all records where the field
value is greater than or equals
the provided value; usually
applied for integer or int64
fields.
COP_SMALLER_THAN_OR
_EQUALS
“SMALLER_THAN_OR_EQU
ALS”
Get all records where the field
value is smaller than or equals
the provided value; usually
applied for integer or int64
fields.
Order the results by the
indicated field.
Use the ascending sort order.
4. Defines
The following defines are used within the library:
TX/MAM Database Protocol Manual - document version: 2.2 – Page 4

The field is a database field.
1 The field is stored within the
'custom_metadata' field in the
'asset_element' table.
2 The field is stored within the
'type_metadata' field in the
'asset_element' table.
3 The field is stored within the
'transfer_metadata' field in the
'asset_element' table.
The field is a text blob field.
5 The field is stored within the
'import_fields' field in the
'main_event' table.
LOCAL_TRANSFER
Only used for demo systems.
The asset files are stored locally in
the
/system/objects/cobassets/media
directory.
The files are stored on a ftp-server as
indicated in the
'transfer_metadata' field.
FMS_TRANSFER
Not used anymore.
3 The files are stored on an fms-system
as indicated in the
'transfer_metadata' field.
TX/MAM Database Protocol Manual - document version: 2.2 – Page 5

Not used, can be used with "no_name".
Success, the library can now be used to retrieve information from the local
Playout database.
Failure, setting up a connection to the local playout database failed.
5. Initializing the library
The following functions are used to configure the library.
5.1 Initializing the library to use a local playout database
Use this function to verify if the local playout database can be accessed.
int cob_init( char *channel_name );
Parameters
Result
The result of the function is an integer that can have following values:
Example
if ( cob_init("no_name")==0 ){
/* continue with the rest of the applet */
} else {
/* not possible to connect to database, report error and stop...*/
return -1;
}
TX/MAM Database Protocol Manual - document version: 2.2 – Page 6

The ip-address of the machine with the remote database, e.g. "192.168.7.186".
The port on the remote machine to connect to, default 5020.
Success, the library can now be used to retrieve information from the
remote database.
Failure, setting up a connection to the remote database failed.
5.2 Initializing the library to use a remote database
Use this function to verify if a remote database can be accessed.
int cob_init_remote( char *database_ip, int port );
Parameters
Result
The result of the function is an integer that can have following values:
Example
if ( cob_init_remote("192.168.7.186",5020) == 0 ) {
/* continue with the rest of the applet */
} else {
/* not possible to connect to database, report error and stop... */
return -1;
}
TX/MAM Database Protocol Manual - document version: 2.2 – Page 7

Success, all criteria cleared.
6. Database search functions
Use the functions described in this section to search the database.
A search command consists of a number (>=1) of criteria that constitute the query that will be used to
match the records. Criteria can be used with the 'and' and 'or' logical operators. The result of a search
command is a list of IDs of records that matched the criteria.
Most criteria can only use fields that reside in the same table. SQL-criteria are an exception to this
rule.
Restrict the number of records in the result list as much as possible, especially when retrieving a
main_event from a Playlist. Too many records will result in a failure on the call. Returning a great
number of records can have a negative effect on system performance.
6.1 Clearing all criteria used in a previous search
int cob_criteria_clear( void );
Parameters
No parameters required
Result
The result of the function is an integer with the following values:
Example
cob_criteria_clear(); /* continue with the rest of the applet */
TX/MAM Database Protocol Manual - document version: 2.2 – Page 8

The table from which to use the field, e.g. “main_event".
Which logical operator to use, e.g. LOP_AND.
The criterion type to use, e.g. COP_EQUALS.
The field to compare, e.g. "status".
The value to compare, e.g. 2048.
Success, the criterion has been added.
Failure, the criterion could not be added.
6.2 Adding a criterion that defines a restriction for integer database
fields
int cob_criteria_add_integer( char *table, char *logical, char *criteria,
char *field , int value );
Parameters
Result
The result of the function is an integer with the following values:
Example
This example will retrieve all asset_elements with status_int == 1:
cob_criteria_clear();
cob_criteria_add_integer( "asset_element", LOP_AND, COP_EQUALS, "status_int" , 1 );
number_of_ids = cob_get_id_list( id_array, max_id_size );
TX/MAM Database Protocol Manual - document version: 2.2 – Page 9

The table from which to use the field, e.g. "main_event".
Which logical operator to use, e.g. LOP_AND.
The criterion type to use, e.g. COP_EQUALS.
The field to compare, e.g. "status".
The value to compare e.g. 2048.
Success, the criterion has been added.
Failure, the criterion could not be added.
cob_criteria_clear();
cob_criteria_add_long( "main_event", LOP_AND, COP_EQUALS, "id_Playlist" , 1 );
cob_criteria_add_integer( "main_event", LOP_AND, COP_EQUALS, "status" , 2048 );
number_of_ids = cob_get_id_list( id_array, max_id_size );
6.3 Adding a criterion that defines a restriction for int64 (='long long')
database fields
int cob_criteria_add_long( char *table, char *logical, char *criteria,
char *field, long long value );
Parameters
Result
The result of the function is an integer that can have following values:
Example
This example will retrieve all main events for id_Playlist = 1 and status = 2048:
TX/MAM Database Protocol Manual - document version: 2.2 – Page 10

The table from which to use the field, e.g."asset_element".
Which logical operator to use, e.g. LOP_AND.
The criteria type to use, e.g. COP_EQUALS.
The field to compare, e.g. "asset_string".
The value to compare e.g. "Clips".
Success, the criterion has been added.
Failure, the criterion could not be added.
cob_criteria_clear();
cob_criteria_add_integer( "asset_element", LOP_AND, COP_EQUALS, "status_int" , 1 );
cob_criteria_add_string( "asset_element", LOP_AND, COP_EQUALS, "asset_string" , "Clips" );
number_of_ids = cob_get_id_list( id_array, max_id_size );
6.4 Adding a criterion that defines a restriction for string database
fields
int cob_criteria_add_string( char *table, char *logical, char *criteria,
char *field , char *value );
Parameters
Result
The result of the function is an integer that can have following values:
Example
This example will retrieve a list of all asset_elements with an asset_string value that equals to "Clips"
and with status_int value that equals to 1:
TX/MAM Database Protocol Manual - document version: 2.2 – Page 11

The table from which to use the field, e.g. "asset_element".
The SQL-query e.g. "select id, save_stamp from asset_element where
status_int = 1".
Success, the criterion has been added
Failure, the criterion could not be added
6.5 Adding a criterion that contains a SQL-query
The SQL-query can only be a 'read only' query and should always return the fields 'ID' and
'SAVE_STAMP'. For a reference on the SQL 'select' statement, please refer to
http://www.ibphoenix.com/downloads/60LangRef.zip
The values to compare the fields with can be put directly into the SQL-statement (e.g. “where
id_Playlist = 1”), except when the field is a string field. In this case the value should be passed using
a parameter. This means that the SQL-statement will contain for example “where asset_string
= :asset_string” and the cob_criteria_add_sqlparam function will be used to provide the
value, for example cob_criteria_add_sqlparam( “asset_element”, “asset_string”,
”Clips” ).
A cob_criteria_add_sqlquery() should only be executed once for every
cob_get_id_lis()call. Multiple parameters can be added per cob_get_id_list()call.
int cob_criteria_add_sqlquery( char *table, char *value );
Parameters
Result
The result of the function is an integer that can have following values:
Example
This example will retrieve a list of all asset_elements with an asset_string value that equals "Clips"
and with status_int value that equals 1:
cob_criteria_clear();
cob_criteria_add_sqlquery( "asset_element","select id,savestamp from asset_element where ”
"asset_string = :asset_string and status_int=1" );
cob_criteria_add_sqlparam( "asset_element", "asset_string", "Clips" );
number_of_ids = cob_get_id_list( id_array, max_id_size );
TX/MAM Database Protocol Manual - document version: 2.2 – Page 12