Adding Records to a Database (lkt_dbrecadd)

This command adds one or more records to a database.

 

dvkerr_t lkt_dbrecadd(lpar_t host, lpar_t dbname, lpar_t reclist, 
                       lpar_t params,lpar_t *dbstats );
dvkerr_t lkt_dbrecaddT(lpar_t host, lpar_t dbname, lpar_t tran, lpar_t reclist,
                       lpar_t params, lpar_t *dbstats );

Statistics are returned for the modified database. The existing records are not replaced; the commands lkt_dbrecreplace and lkt_dbrecupdate provide that functionality (see Replacing Records in a Database (lkt_dbrecreplace) and Updating Records in a Database (lkt_dbrecupdate)).

Starting with release 4.4.1 adding of records is optimized based on the number of records to be added. Passing the LPAR_INT_DBNUMRECORDS value in the params list informs the TIBCO Patterns servers of the approximate number of records in reclist so that it can choose the best loading strategy. If this value is not given or incorrect all records are still added, the only consequence is that loading performance might not be optimal.

In general larger record batches give better overall throughput. To take advantage of the new multi-threaded faster loads the record batches should be over 40,000 records. For smaller numbers of records, a low overhead single threaded load is performed.

The best strategy for adding records depends on your hardware and the number and nature of the databases involved. If optimal load times are critical consult your TIBCO representative for the best means of optimizing loads for your particular case.

Note however that the large batch loading strategy checks the memory cap only once at the start of the load, thus memory cap limits can be greatly exceeded when using the faster loads for large batches. If you are using memory caps and it is critical to stay within the cap you should force the server to use the small batch load strategy by giving an estimated size of 0 records.

Input

host (optional)

This is used to identify the server. For more information, see Communicating with TIBCO Patterns Servers.

dbname (required)

is the name of the database (LPAR_STR_DBDESCRIPTOR) to which records are added.

reclist (required)

is a list of the records to be added. The record keys of the records in this list must be unique (no duplicates), and must not already exist in database dbname.

If some, but not all, of the record keys already exist in database dbname (error DVK_ERR_RECEXISTS), failure of the whole command can be prevented by setting the parameter LPAR_BOOL_DOMAXWORK (see next item).

Like the lkt_dbload command, a file specification might be used in place of an explicitly constructed record list. When using files which do not contain record keys, it is important to set the initial key in the file to a value sufficiently large to not conflict with records already in the database.

params (optional)

This is a list of parameters:

•

LPAR_BOOL_DOMAXWORK: If this parameter is false, any error (including the error DVK_ERR_RECEXISTS) causes the complete failure of the command (For example, no records are added to database dbname).

If this parameter is true, maximum work is done. Records in reclist that can't be loaded due to errors such as duplicate keys or character conversion errors, are quietly ignored and all other records are loaded.

Default value: false

•

LPAR_INT_LOCKKEY allows this update to go through on a database containing a keyed lock if the key value matches the lock value.

Default value: N/A

•

LPAR_INT_DBNUMRECORDS gives an estimate of the number of records in the record list. It is not necessary that this value be exact or even close. This is used by the TIBCO Patterns servers to determine the most efficient means of loading the records.

Default value: 0 (It assumes a small batch of records). The exception is if loading using an LPAR_LST_REMOTEFILE file specification the assumption is that it is a large batch of records.

tran (optional)

identifies the user transaction (LPAR_LONG_TRAN_ID) under which the add record operation is to be performed.

Output

dbstats (optional)

is a list of lpars that give statistics on the modified database similar to those returned by lkt_dbload.

If you do not care to have these statistics, just pass lkt_dbrecadd a pointer value of NULL for dbstats.

 

Error codes and items returned by lkt_dbrecadd

CHARCONV	record that contains improperly encoded characters
DBNOTFOUND	name of nonexistent database
EXPECTDBDESC	item that should have been a database name
EXPECTLIST	item that should have been a list lpar
EXPECTRECORD	item that should have been a record
INTERNAL	item that was being processed at time of error
NODBDESC	(none)
NOMEM	record being processed when memory cap was hit
NORECKEY	record that lacks a record key
NOSRCHTXT	record that lacks searchable text
NOSYSINIT	(none)
NUMFIELDS	record that contains the wrong number of fields
PARAMTYPE	lpar that has invalid ID
RECEXISTS	record with duplicate key value
TRAN_UNKNOWN	lpar that contains the unknown transaction id
TRAN_IN_USE	lpar that contains the transaction id
TRANCONFLICT	list that contains LPAR_LONG_INT_TRAN_ID and LPAR_STR_ERRORDETAILS
UPDPARAM	item that should have been an update parameter