How it Works
Grass Valley
Loading...
K
Loading...
Loading...
K2 TX-MAM Database
User Manual v.2.2
38 pgs727.62 Kb0

Grass Valley K2 TX-MAM Database User Manual v.2.2

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
6. Database search functions .............................................................................................................................. 8
7. Retrieve functions ......................................................................................................................................... 15
8. Update functions ........................................................................................................................................... 21
8.7 Creating the assetjobs, asset_index and group_access records for an asset in the
9. Finalization functions .................................................................................................................................... 29
10. Date & time functions ................................................................................................................................. 30
11. Scheduling functions ................................................................................................................................. 33
11.2 Checking if the asset indicated by asset_id is in a schedule with the time indicated by
12. Utility functions........................................................................................................................................... 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
Name
Value
Description
Maximum values
MAX_IDS
1024
The maximum number of rows that can be retrieved from the database in one call.
SMALL_BLOB
1024
The size for a small text blob database field.
Logical Search operators
LOP_AND
“AND”
This criterion will use the 'AND' operator with the next criterion.
LOP_OR
“OR”
This criterion will use the 'OR' operator with the next criterion.
Criterion types
COP_GET_ALL
“GET_ALL”
Get all records from a table.
COP_EQUALS
“EQUALS”
Get all records where the provided value equals the field value.
COP_CONTAINING
“CONTAINING”
Get all records where the provided value is part of the field value. Can only be used with string or text blob fields.
COP_GREATER_THAN
“GREATER_THAN”
Get all records where the field value is greater than the provided value; usually applied for integer or int64 fields.
COP_SMALLER_THAN
“SMALLER_THAN”
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.
COP_ORDER_BY
“ORDER_BY”
Order the results by the indicated field.
CRIT_ORDER_ASCENDING
“ASCENDING“
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
FIELD Origins
ORIGINAL_DATA
0
The field is a database field.
CUSTOM_DATA
1 The field is stored within the 'custom_metadata' field in the 'asset_element' table.
TYPE_DATA
2 The field is stored within the 'type_metadata' field in the 'asset_element' table.
TRANSFER_DATA
3 The field is stored within the 'transfer_metadata' field in the 'asset_element' table.
BLOB_DATA
4
The field is a text blob field.
IMPORT_DATA
5 The field is stored within the 'import_fields' field in the 'main_event' table.
File Transfer types
LOCAL_TRANSFER
Only used for demo systems.
1
The asset files are stored locally in the
/system/objects/cobassets/media directory.
FTP_TRANSFER
2
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
Name
Description
char *channel_name
Not used, can be used with "no_name".
Value
Description
0
Success, the library can now be used to retrieve information from the local Playout database.
-1
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
Name
Description
char *database_ip
The ip-address of the machine with the remote database, e.g. "192.168.7.186".
int port
The port on the remote machine to connect to, default 5020.
Value
Description
0
Success, the library can now be used to retrieve information from the remote database.
-1
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
Value
Description
0
Success, all criteria cleared.
-1
Failure.
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
Name
Description
char *table
The table from which to use the field, e.g. “main_event".
char *logical
Which logical operator to use, e.g. LOP_AND.
char *criteria
The criterion type to use, e.g. COP_EQUALS.
char *field
The field to compare, e.g. "status".
int value
The value to compare, e.g. 2048.
Value
Description
0
Success, the criterion has been added.
-1
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
Name
Description
char *table
The table from which to use the field, e.g. "main_event".
char *logical
Which logical operator to use, e.g. LOP_AND.
char *criteria
The criterion type to use, e.g. COP_EQUALS.
char *field
The field to compare, e.g. "status".
long long value
The value to compare e.g. 2048.
Value
Description
0
Success, the criterion has been added.
-1
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
Name
Description
char *table
The table from which to use the field, e.g."asset_element".
char *logical
Which logical operator to use, e.g. LOP_AND.
char *criteria
The criteria type to use, e.g. COP_EQUALS.
char *field
The field to compare, e.g. "asset_string".
long long value
The value to compare e.g. "Clips".
Value
Description
0
Success, the criterion has been added.
-1
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
Name
Description
char *table
The table from which to use the field, e.g. "asset_element".
char *value
The SQL-query e.g. "select id, save_stamp from asset_element where status_int = 1".
Value
Description
0
Success, the criterion has been added
-1
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
+ 26 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use