TRIPsystem Kernel API 8.3
|
Data manipulation functions. More...
Functions | |
int | TdbAccumulateSummarization (void *handle, TdbHandle cursor) |
Add data to the summarizer. | |
int | TdbAppendRecordPart (TdbHandle cursor, const char *partName) |
Append a record part to the end of the part list for the currently loaded record. | |
int | TdbCheckCursor (TdbHandle cursor, TdbHandle *recordControl, int *field, int *paragraph, int *item) |
Check the domain of a cursor object. | |
int | TdbCheckData (TdbHandle recordControl, int field, int item, char *data, int length) |
Validate data for a particular field prior to attempting a commit operation. | |
int | TdbCheckExistence (TdbHandle recordControl, int field, char *data, int length) |
Check for existence of indexed data in a PHRase field. | |
int | TdbCheckField (TdbHandle recordControl, char *name, int *number, int *type, int *flags) |
Check a field for existence in a database design, and read its characteristics if present. | |
int | TdbCheckPartName (TdbHandle recordControl, int *partID, char *partName) |
Retrieve the number or name of a record part. | |
int | TdbCheckRecordName (TdbHandle recordControl, int *recordID, char *name) |
Retrieve the record number of a record indicated by name. | |
int | TdbCheckSymbol (int *symClass, char *symbol, int *length) |
Check a character string for conflict with a reserved word. | |
int | TdbCreateRecordControl (TdbHandle *recordControl) |
Create a record control object. | |
int | TdbCreateTimeStamp (unsigned int *tstamp, int type) |
Create a time stamp. | |
int | TdbCurrentItem (char *base, TdbHandle *recordControl, int *record, int *part, int *field, int *paragraph, int *item) |
Retrieve information about the current context. | |
int | TdbCursorInfo (TdbHandle cursor, int mode, char *stringValue, int *intValue) |
Returns information about a cursor. | |
int | TdbDeleteCursor (TdbHandle *cursor) |
Delete a cursor object. | |
int | TdbDeleteItem (TdbHandle cursor) |
Delete a data item in a cursor domain. | |
int | TdbDeleteRecordControl (TdbHandle *recordControl) |
Delete a record control. | |
int | TdbDeleteRecordInBase (TdbHandle recordControl) |
Delete a record from a database. | |
int | TdbDeleteRecordPart (TdbHandle cursor, int mode) |
Delete a record part. | |
int | TdbEndSummarization (void *handle) |
Ends a summarization run. | |
int | TdbEraseRecordControl (TdbHandle recordControl) |
Reinitialize a record control. | |
int | TdbExportBlob (TdbHandle cursor, char *filename) |
Export a STring field to a file. | |
int | TdbGenerateSummary (void *handle, Char **summary) |
Generate a summary. | |
int | TdbGetBlobBlock (TdbHandle cursor, int blockNr, int blockSize, char *block, int *blockLen) |
Retrieve the content of a STRING field. | |
int | TdbGetBlobSize (TdbHandle cursor, int *blobSize) |
Returns the size of the content of a STRING field. | |
int | TdbGetFieldInfo (TdbHandle cursor, int *buf_len, char **rec_buf, int *hit_cnt, int **hit_vec, int *para_cnt) |
Returns data with original formatting from a field of any kind. | |
int | TdbGetHitPart (TdbHandle recordControl, int seqNumber, int *partNumber) |
Return Hit Part details. | |
int | TdbGetItem (TdbHandle cursor, char *data_item, int *item_length) |
Load a data item into a buffer. | |
int | TdbGetLine (TdbHandle cursor, char *line, int *line_length, int maximum_length) |
Load a text line into a buffer. | |
int | TdbGetLinkBase (char *base, char *recordNameField) |
Load the design of a link database. | |
int | TdbGetLinkRecord (TdbHandle recordControl, char *record_name, int length) |
Load a record from a link database during data entry. | |
int | TdbGetNextHitWord (TdbHandle recordControl, int *part, int *field, int *paragraph, int *item, int *word_position, int *length) |
Retrieve the next hit word from a record. | |
int | TdbGetNextItem (TdbHandle cursor, char *data_item, int *length) |
Load the next data item into a buffer. | |
int | TdbGetRecord (TdbHandle recordControl, int mode, int search, int64_t ordinal) |
Get a record from a search set or a database. | |
int | TdbGetRecordBuffer (TdbHandle cursor, char *buffer_address, int buffer_length, int part_number, int *filled_length) |
Gets the content of a buffer. | |
int | TdbGetRecordInBase (TdbHandle recordControl, int RID) |
Load a record from a database. | |
int | TdbGetRecordInSearch (TdbHandle recordControl, int *search, int *RID, char *base) |
Load a record from a search result. | |
int | TdbGetRecordInSearchRis (TdbHandle recordControl, int *search, int RIS, int *RID, char *base) |
Load a record from a search result, specified by RIS. | |
int | TdbGetRecordInThes (TdbHandle recordControl, int termNumber, int *level) |
Load a record from a thesaurus. | |
int | TdbGetSortedRecord (int search_no, TdbHandle rec_ctl, int ris, int *rid, char *base) |
Loads a record from a sorted search result. | |
int | TdbGetTimeStamp (TdbHandle recordControl, unsigned int *timestamp, int type) |
Retrieve the TRIP time stamp of a record. | |
int | TdbHitParts (TdbHandle recordControl, int *parthits, int *partcount, int *partmax) |
Retrieve information about part records in a search. | |
int | TdbImportBlob (TdbHandle cursor, const char *filename) |
Import a binary large object from a file. | |
int | TdbInsertItem (TdbHandle cursor, char *data_item, int item_length) |
Load a data item from a buffer into a record control area. | |
int | TdbInsertRecordPart (TdbHandle cursor, const char *partname) |
Insert a record part. | |
int | TdbItemCount (TdbHandle cursor, int *count) |
Retrieve the number of items in a field. | |
int | TdbLockRecord (TdbHandle recordControl) |
Lock the record in the record control area. | |
int | TdbNextControl (TdbHandle *recordControl) |
Load a CONTROL file record. | |
int | TdbParaCount (TdbHandle cursor, int *count) |
Returns the number of paragraphs within a field. | |
int | TdbPartCount (TdbHandle cursor, int *count) |
Returns the number of part records within a record. | |
int | TdbPutBlobBlock (TdbHandle cursor, int blockLen, char *block) |
Write data to a STRING field. | |
int | TdbPutFieldInfo (TdbHandle cursor, int buf_len, char *rec_buf) |
Assign a value to a TEXT field. | |
int | TdbPutLine (TdbHandle cursor, char *line, int line_length) |
Load a text line from a buffer into a record control area. | |
int | TdbPutRecord (TdbHandle recordControl, int *recordId) |
Write a record into a database. | |
int | TdbPutRecordBuffer (TdbHandle cursor, char *buffer_address, int buffer_len, int *err_partnr, int *err_fieldnr, int *err_itemnr) |
Load a TRIP record with TFORM-formatted data. | |
int | TdbRecordInfo (TdbHandle recordControl, int mode, char *stringValue, int *intValue) |
Returns information about a record. | |
int | TdbReleaseRecord (TdbHandle recordControl) |
Release a lock on a record. | |
int | TdbRenameRecordPart (TdbHandle cursor, const char *part_name) |
Rename a record part. | |
int | TdbReplaceItem (TdbHandle cursor, char *data_item, int item_length) |
Replace a data item in a record control area. | |
int | TdbSetBase (TdbHandle recordControl, char *base, int access_mode) |
Set the access mode for a database. | |
int | TdbSetCursor (TdbHandle *cursor, TdbHandle recordControl, int field, int paragraph, int item) |
Set a cursor domain. | |
int | TdbSetLinkBase (TdbHandle recordControl, char *base_name, TdbHandle *base_id) |
Make a database accessible for data entry linkage. | |
int | TdbSetRecordPart (TdbHandle *cursor, TdbHandle recordControl, int part_number) |
Specify the record part. | |
int | TdbShowControl (int mode, int all_flag, char *name1, char *name2) |
Initialize reading of CONTROL records. | |
int | TdbSortRecords (int searchNumber, char *sortSpecification) |
Sort an existing search set. | |
int | TdbSortRecordsEx (int searchNumber, const char *sortSpecification, int mode) |
Sort an existing search set with clusters and/or record parts. | |
int | TdbSortTerms (int termSetNumber, int sortFlags) |
Sorts a display order or term set. | |
int | TdbStartControl (char *name) |
Set the initial value for reading CONTROL records. | |
int | TdbStartSummarization (void **handle, int engine_id) |
Initialize the text summarization engine. | |
int | TdbUndeleteRecordPart (TdbHandle cursor) |
Undelete the previously deleted record part. | |
int | TdbValidValues (int field_number, TdbHandle base_id, char *term) |
Produce term lists in combination with link databases. | |
Data manipulation functions.
The data manipulation functions cover all functionality for manipulation of database contents.
int TdbAccumulateSummarization | ( | void * | handle, |
TdbHandle | cursor | ||
) |
Add data to the summarizer.
handle | Handle to the summarizer |
cursor | Cursor referring to a field value to add |
Adds data to the summarizer referred to by handle
(obtained by a call to TdbStartSummarization()).
int TdbAppendRecordPart | ( | TdbHandle | cursor, |
const char * | partName | ||
) |
Append a record part to the end of the part list for the currently loaded record.
cursor | The handle to a cursor object. |
partName | The name of the record part to be appended, or an empty string if the database has no part name field. |
The TdbAppendRecordPart() function adds a new part record to the record identified through the cursor
parameter. The new part is placed at the end of the list of existing part records.
The record being updated must have been loaded into memory using one of the functions TdbGetRecordInBase() or TdbGetRecordInSearch(), which will establish a record control.
The cursor must have been attached to the record control pointer by using TdbSetCursor() function prior to calling this function.
The added record part is only committed to the database after a successful call to the TdbPutRecord() function has been made using the same record control that was associated with the cursor
parameter. Otherwise the part record is ignored.
The cursor
parameter is passed a cursor reference. This must have been created by a call to the TdbSetCursor() function. This parameter is read-only.
The partName
parameter is passed s string of characters as the name of the part record name for the newly created part record. If the database has no part name field, the partName
parameter should set to an empty string.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
16034 | Already existing record part name: {1} | |
17986 | Database {1} has no part name field. | |
21698 | Argument {1} - value out of range. |
int TdbCheckCursor | ( | TdbHandle | cursor, |
TdbHandle * | recordControl, | ||
int * | field, | ||
int * | paragraph, | ||
int * | item | ||
) |
Check the domain of a cursor object.
cursor | Cursor object identifier |
recordControl | Pointer handle that receives the record control |
field | Number of field addressed by cursor object |
paragraph | Receives the paragraph number |
item | Receives the item (sentence or subfield) number |
The TdbCheckCursor() function decomposes a cursor object and returns each component in the appropriate argument. In order these are the record control object associated with the cursor, then the field, paragraph and item set by a call to the TdbSetCursor() function.
Note that the domain of the cursor object may reflect implicit updates from use of the TdbGetLine() or TdbGetNextItem() functions.
The cursor
parameter is passed a cursor object identifier, which was created by a call to the TdbSetCursor() function.
The recordControl
parameter is passed a record control identifier. The record control identifier returned is the one to which the cursor was attached in a call to the TdbSetCursor() function.
The field
parameter is passed a pointer to an int
variable to receive the number of the field that the cursor object is currently addressing.
The paragraph
paragraph is passed a pointer to an int
variable to receive the number of the paragraph that the cursor object is currently addressing. Note that this parameter is only meaningful if the field in the cursor domain is of a TExt type field.
The item
parameter is passed a pointer to an int
variable to receieve the number of the item currently addressed by the cursor object. If the field in the cursor domain is of field type TExt then the item corresponds to the sentence number within the paragraph. If, however, the field in the cursor domain is of any other field type then the item corresponds to the subfield within the field.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
14658 | Undefined cursor. |
int TdbCheckData | ( | TdbHandle | recordControl, |
int | field, | ||
int | item, | ||
char * | data, | ||
int | length | ||
) |
Validate data for a particular field prior to attempting a commit operation.
recordControl | Record control object identifier. |
field | Field number |
item | Subfield number |
data | Data string to be validated |
length | Number of data bytes |
The TdbCheckData() function validates supplied data against the database design to ensure that the data can be committed at a later time.
The checks this function makes are that the maximum number of subfields is not exceeded, the minimum number of subfields is satisfied and that the data value(s) are within any range limits or pattern/list restrictions specified in the database design.
Note that this validation is performed only for fields of PHRase, NUMber, INteger, DAte or TIme type. No validation is performed for fields of type TExt
or STring
.
Any changes to a database design must be made with extreme care because existing records could fail subsequent calls to this function if the constraints are different.
The recordControl
parameter is passed a record control handle. The record control object must have been previously attached to a database design by calling the TdbSetBase() function.
The field
parameter is passed an int
value that is the number of the field for which the given data is to be validated.
The item
parameter is passed an int
as the number of item within the field for which given data is to be validated. This ensures that TRIPkernel can verify the maximum allowed items in a field has not been exceeded.
The data
parameter is passed a character string as the data to be validated.
The length
parameter is passed a pointer to an int
variable to receieve the number of bytes in the data
parameter that are to be validated.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
2178 | Invalid NUM. | |
2210 | Invalid DAT. | |
21698 | Argument {1} - value out of range. |
int TdbCheckExistence | ( | TdbHandle | recordControl, |
int | field, | ||
char * | data, | ||
int | length | ||
) |
Check for existence of indexed data in a PHRase field.
recordControl | Record control identifier |
field | Field number |
data | Data string |
length | Number of data bytes |
The function TdbCheckExistence() performs a search against the database to which the record control object is attached, in the PHRase field specified. If an exact match is found, i.e. the supplied data string corresponds to a full subfield in the given field, the routine returns a success code.
The record control must have been attached to a database design using the function TdbSetBase() prior to attempting this call.
Note that in order to successfully locate the data in the field, the database index must be up to date.
The recordControl
parameter is passed a record control handle. This record control must have been associated with a database design by calling the function TdbSetBase() prior to calling TdbCheckExistence().
The field
parameter is passed an int
as the field number of a PHRase field where the data is located. Note that only PHRase fields are permitted!
The data
parameter is passed a character string as the data whose existence in the database is to be checked.
The length
parameter is passed an int
as the number of bytes in the data
parameter to be checked.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
2114 | The DB-indices are being updated. Please, try later. | |
2594 | Specified PHR does not exist in the database. | |
8290 | OS open file limit of {1} reached. | |
17218 | The {1} file of {2} is no {1} file. |
int TdbCheckField | ( | TdbHandle | recordControl, |
char * | name, | ||
int * | number, | ||
int * | type, | ||
int * | flags | ||
) |
Check a field for existence in a database design, and read its characteristics if present.
recordControl | Record control identifier |
name | Field name |
number | Field number |
type | Field type |
flags | Integer (bit vector) |
Return type and index mode for a field, and return its name if indicated by a positive field number argument, or its number if indicated by name with zero as the number argument.
The function TdbCheckField() will perform two functions based on the arguments to the routine call.
If the number
parameter is set to zero, the field name is searched for in the database design. If, however, the number
parameter is non-zero and the name
parameter is blank, the field number is searched for in the database design.
If a field is found, by either method, then the type of the field and its associated flags are returned in the type
and flags
parameters respectively.
The recordControl
parameter is passed a record control handle. This object must have been attached to a database design in a call to the function TdbSetBase() prior to calling TdbCheckField().
The name
parameter is passed a character string as the field name to be checked. If The check is performed by number, this buffer must be at least 65 bytes long to allow for the maximum field name length (64 bytes) plus the terminating null character.
The number
is passed a pointer to an int
variable that must be set to zero if the field characteristics are retrieved by name
, or a field number if the field characteristics are to be retrived by number.
The type
parameter is passed a pointer to an int
variable to receive the type of field found. Valid values are:
Symbolic Constant | Constant Value | Purpose |
---|---|---|
FIELD_TEXT | 1 | Named field is of type TExt |
FIELD_PHRASE | 3 | Named field is of type PHRase |
FIELD_INTEGER | 9 | Named field is of type INteger |
FIELD_NUMBER | 10 | Named field is of type NUMber |
FIELD_DATE | 11 | Named field is of type DAte |
FIELD_TIME | 12 | Named field is of type TIme |
FIELD_STRING | 14 | Named field is of type STring |
The flags
parameter is passed a pointer to an int
variable to receieve a bit vector representing a number of flags concerning the processing options of the field. In the list of valid values, below, the name of server-side C macros are given that can be used by server-side TRIPtoolkit applications to query the flags. Valid values are:
Bit number | C macro | Purpose |
---|---|---|
0 | IsIndexed(x) | If bit is set then the field is indexed |
1 | IsWriteable(x) | If set the calling process have write access to the field |
2 | IsPartField(x) | If set the field is a part field |
3 | Undefined. The setting of this bit cannot be guaranteed to be maintained between different version of TRIPsystem | |
4 | IsMandatory(x) | If set the field is a mandatory field |
5 | IsLayoutRetained(x) | If set the field has the layout retained attribute enabled |
6 | IsReadable(x) | If set the calling process has read access to the field |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
2146 | Non-existing field: {1} | |
14434 | Field no {1} has previously been deleted. | |
14466 | Highest field number is {1}. |
int TdbCheckPartName | ( | TdbHandle | recordControl, |
int * | partID, | ||
char * | partName | ||
) |
Retrieve the number or name of a record part.
recordControl | Record control identifier |
partID | Number of part to check, receives number when check is done by name |
partName | Name of part to check, receives name when check is done by number |
The function TdbCheckPartName() checks the currently loaded record for the existence of a part record, identified by number or name.
If the partID
parameter is zero when calling the function the record is searched for a part with the supplied part name and, if found, the number of the part is returned in the partID
parameter. If the partID
parameter is non-zero the name of the specified part is returned in the partName
parameter.
The return code indicates failure in some cases, and so should be checked against the special constants that are defined for this routine.
The record for which the record parts are checked must have been previously loaded into the record control area by a call to the TdbGetRecordInBase() , TdbGetRecordInSearch() or TdbGetRecordInSearchRis() functions.
The recordControl
parameter is passed a record control object. This object must have been attached to a database design by a call to the TdbSetBase() function and a record loaded into this record control before calling TdbCheckPartName() .
The partID
parameter is passed pointer to an integer that holds the number of the part to check. This number can be zero if the check is to be made using the partName
value. Note that this number is not guaranteed to remain the same between invocations of this routine as the list of record parts is always renumbered because of the deletion or insertion of record parts. Programs should not, therefore, rely on this number for their correct behavior.
The partName
parameter is passed a character string as the name of the record part for which to get the part number. This name is taken to be the content of the record part name field specified in the database general properties. The part name can be up to 255
characters long.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
16002 | Non-existing record part: {1} | |
16034 | Already existing record part name: {1} | |
17986 | Database {1} has no part name field. | |
21698 | Argument {1} - value out of range. |
int TdbCheckRecordName | ( | TdbHandle | recordControl, |
int * | recordID, | ||
char * | name | ||
) |
Retrieve the record number of a record indicated by name.
recordControl | Record control identifier |
recordID | Record identifier |
name | Name of the record |
The function TdbCheckRecordName() searches the record name field of a database for the specified value. The return code from this function is always a failure code, thus there are special constants to check whether it has failed because the record exists or because it does not exist. In the case where it does exist, the record ID will reflect the unique number assigned to the record with that name.
The recordControl
parameter is passed a record control handle. This object must have been associated with a database design by calling the function TdbSetBase() before a call to TdbCheckRecordName().
The recordID
parameter is passed a pointer to an int
variable to receive the number of the record in the database.
The name
parameter is passed a character string as the name of the record. This name is taken to be the content of the record name field specified in the associated database's general properties. The record name can be up to 255
characters long.
Code | Description | Explanation |
---|---|---|
130 | Record control structure not created. | |
2882 | Non-existing record: {1} | |
7074 | Already existing record name: {1} | |
7394 | No record name field defined in {1}. |
int TdbCheckSymbol | ( | int * | symClass, |
char * | symbol, | ||
int * | length | ||
) |
Check a character string for conflict with a reserved word.
symClass | Symbol class |
symbol | Character string |
length | Length of symbol |
The function TdbCheckSymbol() directs a check against the TRIP data dictionary for conflict between a supplied term and a reserved word, such as the name of an open database or the name of a field in an open database.
If the symbol is found, the routine returns the symbol class and the length in the symClass
and length
respectively. Also the content of the symbol
parameter are normalized to upper case and any abbreviated symbol expanded.
The symClass
parameter is passed a pointer to an int
variable that represents the symbol class. This variable should be specified on input as one of the following choices. If you specify a wildcard class, such as CHECK_ALL, on return from the routine the class argument will contain the exact class of the symbol if it wasfound. Valid values are:
Symbolic Constant | Constant Value | Symbol |
---|---|---|
CHECK_BASENAME | 2 | Database name |
CHECK_VIEWNAME | 3 | View name |
CHECK_TEXT | 4 | TExt field |
CHECK_PHRASE | 5 | PHRase field |
CHECK_NUMBER | 6 | NUMber field |
CHECK_DATE | 7 | DAte field |
CHECK_TIME | 8 | TIme field |
CHECK_ALL | 9 | All classes |
CHECK_FIELDS | 10 | All field and view type classes |
CHECK_MAPS | 14 | Indirect or mapped fields |
The symbol
parameter is passed a character string as the string to be checked. On return from TdbCheckSymbol() the symbol
parameter contains the matched symbol, normalized and extended to its full length if an abbreviated symbol was input.
The length
parameter is passed a pointer to an int
variable that on input must be set to the allocated size of the symbol
buffer, allowing for terminating null character. On output, the length
parameter will contain the number of bytes in the matched symbol name returned via the symbol
parameter.
Code | Description | Explanation |
---|---|---|
0 | Symbol not found | |
1 | Operation completed successfully | The function completed its operations without error. |
int TdbCreateRecordControl | ( | TdbHandle * | recordControl | ) |
Create a record control object.
recordControl | Record control identifier |
The function TdbCreateRecordControl() creates a record control object to give access to a record within a database. In order to be used for such a purpose, the calling process must follow one of two paths.
If the database to which the object is to be attached is known, the calling process should call the function TdbSetBase() to load the database definition and to define the access level. Later records can be read from the database using the TdbGetRecordInBase() function.
If, instead, the database to which the object is to be attached can change based on the result of a search, the calling process should call TdbGetRecordInSearch() or TdbGetRecordInSearchRis() to retrieve the record, and then if necessary call TdbSetBase() to elevate the access level from read only.
The only form of searching supported via the record control object is record name lookup, using the TdbCheckRecordName().
As the record control object can be large, it should be deleted when not further required. For this, use the TdbDeleteRecordControl(). Because of the size of this internal data structure it is unwise to call TdbCreateRecordControl() within a loop. Use TdbEraseRecordControl() instead of TdbDeleteRecordControl() if you wish to reuse an existing record control object.
The recordControl
parameter is passed a pointer to a TdbHandle
variable that will receive a handle to the created record control object.
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbCreateTimeStamp | ( | unsigned int * | tstamp, |
int | type | ||
) |
Create a time stamp.
tstamp | Time stamp |
type | Time stamp style |
The TdbCreateTimeStamp() creates a unsigned 32-bit integer representation that can be used as a format independent comparison of times and dates. The selection between a date and time combination or a simple time value is decided by the value passed via the type
parameter.
The tstamp
parameter is passed a pointer to an unsigned 32-bit integer variable that will receive the created time stamp.
The type
parameter is passed an int
value defining the form of the tme stamp to return. Valid values are:
Symbolic Constant | Constant Value | Time Stamp Content |
---|---|---|
DATE_AND_TIME | 0 | The time stamp is to include both date and time values. |
DATE_ONLY | 1 | The time stamp in to include only a date value. |
This function always succeeds
int TdbCurrentItem | ( | char * | base, |
TdbHandle * | recordControl, | ||
int * | record, | ||
int * | part, | ||
int * | field, | ||
int * | paragraph, | ||
int * | item | ||
) |
Retrieve information about the current context.
base | Name of database |
recordControl | Record control identifier |
record | Sequence number of record in database |
part | Part number |
field | Field number |
paragraph | Paragraph number |
item | Item number |
The function TdbCurrentItem() returns information concerning the calling process' current context, such as the record control object currently in use, the database currently open, the record currently loaded, etc. The function can only be used in ASE routines. Note that the field, paragraph and item information is not always valid, at which times the arguments will be set zero upon return.
Care must be taken in treatment of the record control object as this object belongs to and is created by TRIP kernel itself and attempts to delete it will cause significant problems for the execution of further actions.
The base
parameter is passed a character string to receive the name of the database.The buffer must be at least 65 bytes in length so that it can accommodate a database/cluster name of maximum size.
The length
parameter is passed a pointer to an int
variable to receive the length of the string that was returned via the base
parameter.
The recordControl
parameter is a pointer to a TdbHandle variable that receives the handle to the record currently in use by the system. This record control will have been created earlier by a call to the TdbCreateRecordControl() function.
The record
parameter is a pointer to an int
variable to receive the unique sequence number of the record within the database and which the record control is referring.
The part
parameter is passed a pointer to an int
variable to receive the part number, if any, that is currently referenced by the record control identifier.
The field
parameter is passed a pointer to an int
variable to receive the field number, if any, that is currently referenced by the record control identifier.
The paragraph
is passed a pointer to an int
variable to receive the paragraph number that is currently referenced by the record control identifier. This parameter, although always provided with an call argument, is only meaningful if the field currently in use is of type TExt.
The item
parameter is passed a pointer to an int
variable to receive the item number. If the field of the current item is a TExt field the item corresponds to the sentence within the paragraph. If the field is of any type other than TExt the item corresponds to the subfield within the field.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
3170 | Unexpected error. |
int TdbCursorInfo | ( | TdbHandle | cursor, |
int | mode, | ||
char * | stringValue, | ||
int * | intValue | ||
) |
Returns information about a cursor.
cursor | Cursor from which to retrieve information |
mode | Type of information to retrieve. |
stringValue | Output parameter for information of string type. |
intValue | Output parameter for information of integer type. |
The TdbCurosrInfo() function provides a way to obtain various information about a TRIP cursor.
The cursor
parameter is a handle to a cursor that may refer to a TRIP database record, part record or field. The cursor is created using TdbSetCursor() .
The mode
parameter is used to tell the function what information to return and must be set to one of the following values:
Value | Output Parameter | Description |
---|---|---|
CURSORINFO_DB | stringValue | Return the name of the database associated with the cursor |
CURSORINFO_RID | intValue | Return the record identifier (RID) of the record to which the cursor refer. |
CURSORINFO_PARTID | intValue | Return number of the part record associated with the cursor. |
CURSORINFO_FIELDNR | intValue | Return number of the field associated with the cursor. |
CURSORINFO_PARANR | intValue | Return number of the text field paragraph associated with the cursor. |
CURSORINFO_ITEMNR | intValue | Return number of the field item associated with the cursor. |
CURSORINFO_HITS | intValue | Returns the total number of hits in the field. The cursor must refer to a field in a record that has been retrieved from the latest search set using TdbGetRecordInSearchRis. |
This function was introduced in TRIP version 6.2-9.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
18466 | Unrecognised option: {1}. |
int TdbDeleteCursor | ( | TdbHandle * | cursor | ) |
Delete a cursor object.
cursor | Cursor identifier |
The function TdbDeleteCursor() releases memory associated with the specified cursor object. This action has no effect on the data in the domain referenced by the cursor. Cursors are created automatically by TdbSetCursor() and TdbSetRecordPart().
The cursor
parameter is passed a pointer to a TdbHandle
variable that on input holds the cursor to delete. On successful output, the handle variable will be set to NULL.
Code | Description | Explanation |
---|---|---|
0 | Invalid cursor | |
1 | Operation completed successfully | The function completed its operations without error. |
int TdbDeleteItem | ( | TdbHandle | cursor | ) |
Delete a data item in a cursor domain.
cursor | Record cursor |
The function TdbDeleteItem() deletes the specific item referenced by the domain of the cursor, as previously established by calling the TdbSetCursor() function.
The domain may also cover a whole field or paragraph, in which case all of the domain is deleted.
The cursor
parameter is passed a pointer to the handle containing the cursor to delete.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. |
int TdbDeleteRecordControl | ( | TdbHandle * | recordControl | ) |
Delete a record control.
recordControl | Record control identifier |
The function TdbDeleteRecordControl() deletes temporary work space that was previously created via a call to TdbCreateRecordControl(). The memory used by the work space is returned to the system. This routine also deletes all of the cursors associated with the record control.
The data structure behind a record control is large and will take considerable effort to recreate; as far as possible these structures should be created and reused rather than being repeatedly created and deleted. Use TdbEraseRecordControl() for this purpose.
The recordControl
parameter is passed a pointer to a TdbHandle
variable that on input holds the handle of the record control to delete. On successful output, the parameter is set to NULL.
This function always succeeds.
int TdbDeleteRecordInBase | ( | TdbHandle | recordControl | ) |
Delete a record from a database.
recordControl | Record control |
The function TdbDeleteRecordInBase() deletes the record from the BAF file. The record to be deleted must first be loaded into the specified record control work area via a call to one of the functions TdbGetRecordInBase() , TdbGetRecordInSearch() or TdbGetRecordInSearchRis(). Each of these routines establishes a link between a record control and a particular database.
Use of this routine requires that the TRIPsystem user either be the owner of the database or has unrestricted write access to that database. The access mode for the database is set using the TdbSetBase() function.
The recordControl
is passed a TdbHandle
as a record control that is associated with the record to delete.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
18338 | No database connection. | |
14754 | Database {2} is open for read only. | |
14818 | No write access to this record. | |
33507 | Record {1} deleted. | The function completed its operations without error. |
int TdbDeleteRecordPart | ( | TdbHandle | cursor, |
int | mode | ||
) |
Delete a record part.
cursor | Cursor identifier |
mode | Deletion mode |
The function TdbDeleteRecordPart() is used to delete the record part to which a cursor refers. If the mode is set to one, the record part itself is not deleted but its name removed from the listing in the record head. It is then possible to later restore it by a call to the TdbUndeleteRecordPart() function within the same record.
The cursor must have been attached to the record control area by using TdbSetRecordPart() prior to attempting to call this function.
You must call TdbPutRecord() to commit the changes.
The cursor
parameter is passed a handle representing the cursor that was set earlier by a call to the TdbSetCursor() function.
The mode
parameter is passes an int
as the mode of deletion. Valid values are:
Constant Value | Purpose |
---|---|
0 | Delete the part without the possibility of restoration. |
1 | Delete the part name from the record's part name listing. The part itself is not deleted until the record is stored by a call to PUT RECORD. |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. |
int TdbEndSummarization | ( | void * | handle | ) |
Ends a summarization run.
handle | Handle to the summarizer |
Closes a summarization run as opened by a call to TdbStartSummarization().
int TdbEraseRecordControl | ( | TdbHandle | recordControl | ) |
Reinitialize a record control.
recordControl | Record control |
The function TdbEraseRecordControl() initializes an existing record control work space, previously created with a call to the TdbCreateRecordControl() function. The existing state of the record control is cleared, resetting the control structure to indicate an empty record. Any database associated with the record control structure is unaffected by this operation.
The recordControl
parameter is passed a handle to a record control. This record control will have been created earlier with a call to the TdbCreateRecordControl() or some similar function.
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbExportBlob | ( | TdbHandle | cursor, |
char * | filename | ||
) |
Export a STring field to a file.
cursor | Cursor identifier |
filename | Filename |
The function TdbExportBlob() writes the content of a STRING field to an external file.
The cursor
parameter is passed a TdbHandle
as the cursor that identifies the field whose content is to be exported. This cursor must have been defined earlier with a call to the TdbSetCursor() function.
The filename
parameter is passed a character string as the name of the server-side file where information is to be written.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
10626 | Error opening output file {1}{2}{3} | |
14658 | Undefined cursor. | |
21634 | {1} is not a blob field. |
int TdbGenerateSummary | ( | void * | handle, |
Char ** | summary | ||
) |
Generate a summary.
handle | Handle to the summarizer |
summary | Receievs a null-terminated string containing a summary |
This function generates a summary based on the data added to the summarizer via calls to the TdbAccumulateSummarization() function. The returned value in summary
is owned by the TRIP kernel and must not be deallocated by the application.
int TdbGetBlobBlock | ( | TdbHandle | cursor, |
int | blockNr, | ||
int | blockSize, | ||
char * | block, | ||
int * | blockLen | ||
) |
Retrieve the content of a STRING field.
cursor | Cursor pointing to a STRING field. |
blockNr | Block number to retrieve. Increase by 1 for each time around until the entire blob has been transferred. |
blockSize | The size of the block to retrieve. |
block | Output parameter receiving the requested blob block. |
blockLen | Number of bytes returned in the block output parameter. |
The TdbGetBlobBlock() function is used to retrieve the contents of a STRING field.
The cursor in the cursor
parameter must be set to refer to a STRING field. No other field types are valid with this function. This is a read-only value.
The blockNr
parameter must be set to 1 for the first block, then incremented by one for each time this function is called until the entire BLOB has been retrieved. This is a read-only value.
The blockSize
parameter is to be set to the size of the block to retrieve. Note that this value should not be larger than 32768, especially in the client-side version of this function. It is also vitally important (for both versions) that this figure remains the same for all calls to this function until the entire STRING value has been retrieved. This is a read-only value.
The block
output parameter recieves a byte sequence with the requested STRING value block.
The blockLen
output parameter recieves the byte count of the returned block
data.
Code | Description | Explanation |
---|---|---|
0 | Requested block does not exist. | This error occurs when the blockNr parameter is set too high. |
1 | Returned block is the last one. | |
3 | Block returned ok - more blocks are available. | When this return code is recieved, the application is expected to call this function again with the blockNr parameter incremented by one. |
14658 | Invalid cursor. | |
21634 | field is not a BLOB field. |
int TdbGetBlobSize | ( | TdbHandle | cursor, |
int * | blobSize | ||
) |
Returns the size of the content of a STRING field.
cursor | Cursor pointing to the STRING field to return size for. |
blobSize | Size (byte count) of the field contents. |
The TdbGetBlobSize() function is used to retrieve the size of STRING fields.
The cursor in the cursor
parameter must be set to refer to a STRING field. No other field types are valid with this function. This is a read-only value.
The blobSize
output parameter receives the size of the STRING field contents.
Code | Description | Explanation |
---|---|---|
14658 | Invalid cursor. | |
21634 | field is not a BLOB field. |
int TdbGetFieldInfo | ( | TdbHandle | cursor, |
int * | buf_len, | ||
char ** | rec_buf, | ||
int * | hit_cnt, | ||
int ** | hit_vec, | ||
int * | para_cnt | ||
) |
Returns data with original formatting from a field of any kind.
cursor | [IN] Cursor set to a field |
buf_len | [OUT] Return length of data in rec_buf |
rec_buf | [OUT] Receives a pointer to the field value |
hit_cnt | [OUT] Number of hits in the returned value |
hit_vec | [OUT] Hit vector (array with offset/length pairs) |
para_cnt | [OUT] Number of paragraphs returned |
When called for a TEXT field, the function will return each subfield separated by an LF (line feed) character.
The memory returned in the output parameters rec_buf
and hit_vec
must be released by the caller using the TdbDeallocate() function.
int TdbGetHitPart | ( | TdbHandle | recordControl, |
int | seqNumber, | ||
int * | partNumber | ||
) |
Return Hit Part details.
recordControl | Record control |
seqNumber | 1-based sequence number of hit part |
partNumber | Part number |
The function TdbGetHitPart() retrieves a part record identified by its ordinal number (using the seqNumber
parameter) within the part hit vector for a record in a search set. The actual part record number assoicated with the input seqNumber
is returned in the partNumber
output parameter. The partNumber
value can then be used to specify the part record by calling the TdbSetRecordPart() function.
For example, if a record has 24 part records and a search matches parts 8 and 13, passing seqNumber
1 yields partNumber
8, and seqNumber
2 yields partNumber
13.
The recordControl
parameter is passed a handle to the record control associated with the record to be retrieved.
The seqNumber
parameter is passed an int
as the sequence number of a hit part in the record.
The partNumber
parameter is passed a pointer to a variable of type int
to receive the number of the part record.
This function was introduced in TRIP version 3.3-1.
Code | Description | Explanation |
---|---|---|
0 | There are no more hit parts | |
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. |
int TdbGetItem | ( | TdbHandle | cursor, |
char * | data_item, | ||
int * | item_length | ||
) |
Load a data item into a buffer.
cursor | Cursor identifier |
data_item | Data item string |
item_length | Length of data item |
The function TdbGetItem() copies the data in the sentence or subfield specified by a cursor into the buffer provided, and must be preceded by a call to the TdbSetCursor() function.
The cursor
parameter is passed a TdbHandle
as a cursor identifier created by a call to the TdbSetCursor() function.
The data_item
parameter is passed a character string to receive the returned data item.
The item_length
parameter is passed a pointer to a 32-bit signed integer to receive the count of data characters transferred to the data item. The returned length excludes the terminating null-byte.
Code | Description | Explanation |
---|---|---|
0 | Operation failed | The sentence/subfield to which the cursor refers is empty |
1 | Operation completed successfully | The whole sentence/subfield was transferred |
3 | Operation completed successfully | Part of the sentence/subfield was transferred, but there is more to get |
12610 | The cursor does not specify a field number |
int TdbGetLine | ( | TdbHandle | cursor, |
char * | line, | ||
int * | line_length, | ||
int | maximum_length | ||
) |
Load a text line into a buffer.
cursor | Record cursor |
line | Returned text line |
line_length | Length of string transferred |
maximum_length | Maximum number of bytes to be transferred |
The function TdbGetLine() loads a line from the field specified by the cursor into the text buffer provided. Repeated calls to this function loads the data in the field, one line at a time, into the buffer, until the call fails with a return status not equal to one.
Lines are divided by word boundaries, with the partitioning governed by the maximum_length
parameter.
The cursor
parameter is passed a TdbHandle
as the record cursor identifier, which was created in an earlier call to the TdbSetCursor() function.
The line
parameter is passed a character string to receive the returned text line.
The line_length
parameter is passed a pointer to an int
variable to receive the length of the string transferred into the text line buffer. For portable applications, the length does not include the terminating null-byte.
The maximum_length
parameter is passed an int
as the maximum number of bytes (null-byte excluded) to be transferred into the text line buffer.
Code | Description | Explanation |
---|---|---|
0 | Operation failed | The sentence/subfield to which the cursor refers is empty |
1 | Operation completed successfully | The function completed its operations without error. |
14658 | Undefined cursor. | |
12610 | The cursor does not specify a field number |
int TdbGetLinkBase | ( | char * | base, |
char * | recordNameField | ||
) |
Load the design of a link database.
base | Name of link database |
recordNameField | Name of record name field |
The function TdbGetLinkBase() loads the design of a link database if it is available to the user (read access is enough). It is used within TRIPclassic during the creation of entry form links to list the fields of the link database.
The base
parameter is passed a character string as the name of the link database.
The recordNameField
parameter is passed a character string as the name of the record name field.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
610 | Database 1 not found. | |
2530 | No access to database 1. | |
3042 | 1 is not a database. | |
8802 | Only alphanumerics/underscores allowed in database/cluster names. | |
9890 | Link database must have a record name field. | |
15234 | Missing database name. |
int TdbGetLinkRecord | ( | TdbHandle | recordControl, |
char * | record_name, | ||
int | length | ||
) |
Load a record from a link database during data entry.
recordControl | Record control identifier |
record_name | Name of record |
length | Length of record name |
The function TdbGetLinkRecord() loads a record from a link database during data entry. The record is specified by record name. The function TdbSetLinkBase() must be called prior to this.
This function is intended primarily for use within the TRIPclassic environment.
The recordControl
parameter is passed a handle to a record control.
The record_name
parameter is passed a character string as the name of the record to be retrieved.
The length
parameter is passed an int
as the length of the record name.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
1314 | Database {1} is OS read protected. | |
8290 | OS open file limit of 1 reached. | |
11426 | No such string in linked database 1. | |
17218 | The {1} file of {2} is no {1} file. |
int TdbGetNextHitWord | ( | TdbHandle | recordControl, |
int * | part, | ||
int * | field, | ||
int * | paragraph, | ||
int * | item, | ||
int * | word_position, | ||
int * | length | ||
) |
Retrieve the next hit word from a record.
recordControl | Record control identifier |
part | Number of part containing next hit word |
field | Number of field containing next hit word. |
paragraph | Number of paragraph containing next hit word |
item | Number of subfield or sentence containing next hit word. |
word_position | Start position of next hit word within item |
length | Length of word. |
The function TdbGetNextHitWord() returns the position of the next hit word within the record. A call to either the TdbGetRecordInSearch() or TdbGetRecordInSearchRis() functions must have been made to load the record control area.
The recordControl
parameter is passed a TdbHandle
as the record control identifier.
The part
parameter is passed a pointer to an int
variable to receive the number of the part that contains the next hit word. If the database design does not specify part records then the value returned is zero.
The field
parameter is passed a pointer to an int
variable that will receive the number of the field containing the next hit word.
The paragraph
parameter is passed a pointer to an int
variable that will receive the number of the paragraph containing the next hit word.
The item
parameter is passed a pointer to an int
variable to receive the number of the item that contains the next hit word. If the field type is TExt then the item
number is the number of the sentence in which the hit word is located. Otherwise, the item
number is the number of the subfield in which the hit word is located.
The word_position
parameter is passed a pointer to an int
variable to receive the start position of the next hit word within the item. The position is the number of characters from the start of the item and is counted from zero.
The length
parameter is passed a pointer to an int
variable to receive the length of the word.
Code | Description | Explanation |
---|---|---|
0 | Operation failed | There are no more hit words |
1 | Operation completed successfully | The function completed its operations without error. |
int TdbGetNextItem | ( | TdbHandle | cursor, |
char * | data_item, | ||
int * | length | ||
) |
Load the next data item into a buffer.
cursor | Cursor identifier |
data_item | Returned data item |
length | Length of string transferred |
The function TdbGetNextItem() copies the next item specified by the cursor (set with a call to TdbSetCursor() ) into the data_item
parameter. Repeated calls to TdbGetNextItem() will transfer all of the data from the field in the data_item
parameter and adjusting the length
parameter as necessary. Calls can continue until there is a return code of one, which indicates that all the data in the domain of the cursor has been returned.
If the cursor domain specifies a single subfield or sentence TdbGetNextItem() will behave as though the domain started at the subfield or sentence indicated, and continued to the end of the field. That is by specifying a cursor domain of a single sentence or subfield, the domain is implicitly set to cover all of the data within the field that follows the sentence or subfield indicated in the cursor setting.
The cursor
parameter is passed a TdbHandle
as the cursor identifier set in a prior call to the TdbSetCursor() function.
The data_item
parameter is passed an application-allocated memory buffer large enough to contain the largest item value to retrieve.
The length
parameter is passed a signed 32-bit integer to receive the length of the string transferred to the data item buffer. The returned length excludes the terminating null-byte.
Code | Description | Explanation |
---|---|---|
0 | Operation failed | There is no more data in the field |
1 | Operation completed successfully | The final piece of data in the current sentence/subfield has been copied |
3 | Operation completed successfully | A piece of data has been copied, but there is more to get in the current sentence/subfield |
int TdbGetRecord | ( | TdbHandle | recordControl, |
int | mode, | ||
int | search, | ||
int64_t | ordinal | ||
) |
Get a record from a search set or a database.
recordControl | Record control to receive the loaded record |
mode | Retrieval mode; one of the RECORD_FROM_* constant values |
search | Number of the search if mode indicates search set retrieval |
ordinal | Ordinal number of record in search result or the record number in the database |
The function TdbGetRecord() loads a record from a search set or directly from a database into a work area for further processing. This work area must have been created by a call to the TdbCreateRecordControl() function. The ordinal
parameter must always be specified.
Retriving additional information on a record, such as record ID or the database it belongs to, requires use of the TdbRecordInfo() function.
The recordControl
parameter is passed a TdbHandle
as the TRIP record control.
The mode
parameter indicates from which source to retrieve the record and must be set to one of the following values:
Symbol | Description |
---|---|
RECORD_FROM_BASE | Record is to be retrieved from the a database, like with TdbGetRecordInBase(). The ordinal parameter specifies a RID. The search parameter is ignored. |
RECORD_FROM_SEARCH | Record is to be retrieved from a search set. The ordinal parameter specifies a RIS. |
RECORD_FROM_SORTED_SEARCH | Record is to be retrieved from a sorted search set. The ordinal parameter specifies a RIS. |
If mode
set to RECORD_FROM_SEARCH
or RECORD_FROM_SORTED_SEARCH
, the search
parameter is passed an integer as the number of the search set from which the record is to be loaded. If mode
is set to RECORD_FROM_BASE
, this parameter is ignored.
The ordinal
parameter is passed an integer as the ordinal number of the record in the search result if mode
set to RECORD_FROM_SEARCH
or RECORD_FROM_SORTED_SEARCH
. If mode
is set to RECORD_FROM_BASE
this parameter specifies a record ID.
The return code from the TdbGetRecord() function is a bit mask that has the following structure. The return value is a combination of one or more of these bits.
Bit # | Value | Explanation |
---|---|---|
0 | 1 | The operation completed successfully. |
1 | 2 | The first hit record in an open database has been retrieved. This is only useful when searching in clusters. |
2 | 4 | The record has been deleted from the database. |
3 | 8 | The record is locked by another process. |
4 | 16 | At end - no more records. |
If an error occurs (i.e. the function returns an even value equal to zero or greater than 32) the associated TRIP error code can be retrieved by calling TdbRetCode().
int TdbGetRecordBuffer | ( | TdbHandle | cursor, |
char * | buffer_address, | ||
int | buffer_length, | ||
int | part_number, | ||
int * | filled_length | ||
) |
Gets the content of a buffer.
cursor | Cursor identifier |
buffer_address | Address of buffer |
buffer_length | Size of the buffer in number of bytes |
part_number | Part record number |
filled_length | Number of bytes written to buffer |
The function TdbGetRecordBuffer() fills the provided buffer with TFORM-formatted data from the record specified by the cursor
. The cursor
, which is set by calling TdbSetCursor(), may specify the entire record or a single field.
The cursor
parameter is passed a TdbHandle
as the identifier of a cursor previously created in a call to the TdbSetCursor() function.
The buffer_address
parameter is passed the address of the memory buffer that will receive the TFORM data.
The buffer_length
parameter is passed the size (number of bytes) of the buffer.
The filled_length
parameter is passed a pointer to an int
variable to receive the number of bytes written to the buffer indicated by the buffer_address
parameter.
Code | Description | Explanation |
---|---|---|
0 | Operation failed | There is no data to fetch |
1 | Operation completed successfully | The function completed its operations without error. |
3 | Operation completed successfully | A piece of data has been copied, but there is more to get in the current sentence/subfield |
int TdbGetRecordInBase | ( | TdbHandle | recordControl, |
int | RID | ||
) |
Load a record from a database.
recordControl | Record control |
RID | Record number in database |
The function TdbGetRecordInBase() loads a single record from a database into a work area for further processing. The work area (created by a previous call to the function TdbCreateRecordControl() ) must have already been labelled with the name of the database via a call to the TdbSetBase() function.
The particular record to be loaded into the work area is specified by its RID, i.e. its internal record number provided and maintained internally by the TRIPsystem.
A RID value of zero will cause the record that follows the current one to be loaded. On the first call, this will be the first record in the database. Repeated calls to TdbGetRecordInBase() with the RID
parameter set to zero will consequently process all existing records in the database until the end is reached and the function returns 16. Similarly, giving the RID
parameter a value of -1 will result in the previous record being loaded.
The recordControl
is passed a TdbHandle
as the record control associated with the record to be retrieved from the database.
The RID
parameter is passed an int
as the number of the record in a TRIP database.
The return code from the TdbGetRecordInBase() function is a bit mask that has the following structure. The return value is a combination of one or more of these bits.
Bit # | Value | Explanation |
---|---|---|
0 | 1 | The operation completed successfully. |
1 | 2 | The first hit record in an open database has been retrieved. This is only useful when searching in clusters and does not apply to this function. |
2 | 4 | The record has been deleted from the database. |
3 | 8 | The record is locked by another process. |
4 | 16 | At end - no more records. |
If an error occurs (i.e. the function returns an even value equal to zero or greater than 32) the associated TRIP error code can be retrieved by calling TdbRetCode().
int TdbGetRecordInSearch | ( | TdbHandle | recordControl, |
int * | search, | ||
int * | RID, | ||
char * | base | ||
) |
Load a record from a search result.
recordControl | Record control identifier |
search | Search number |
RID | Record number in TRIP database |
base | Database name. |
The function TdbGetRecordInSearch() loads a record from a search set into a work area, created by a call to TdbCreateRecordControl(), for further processing. On the first call the RID
parameter should be set to zero; on return from the routine the RID
parameter indicates the actual RID of the retrieved record. Subsequent calls to TdbGetRecordInSearch() will cause all of the records within the search set to be passed, one at a time, into the record control work area.
The recordControl
parameter is passed a TdbHandle
as the record control identifier associated with the record.
The search
parameter is passed a pointer to an int
variable that rerepresents the number of a search set. If this variable is set to zero on input, the latest search set will be used and its actual number will be returned in this parameter on output. A non-zero value on input for the variable that this parameter points to indicates a specific search set from which to obtain a record.
The RID
parameter is passed an int
as the number of the TRIP record to retrieve.
The base
parameter is passed a character string of at least 65 bytes in length to receive the name of the database that the retrieved records are taken from. For a search of a single database this name will remain the same however for searches of multi-file views or predefined database clusters this name will change to reflect the database that contains the record.
The return code from the TdbGetRecordInSearch() function is a bit mask that has the following structure. The return value is a combination of one or more of these bits.
Bit # | Value | Explanation |
---|---|---|
0 | 1 | The operation completed successfully. |
1 | 2 | The first hit record in an open database has been retrieved. This is only useful when searching in clusters. |
2 | 4 | The record has been deleted from the database. |
3 | 8 | The record is locked by another process. |
4 | 16 | At end - no more records. |
If an error occurs (i.e. the function returns an even value equal to zero or greater than 32) the associated TRIP error code can be retrieved by calling TdbRetCode().
int TdbGetRecordInSearchRis | ( | TdbHandle | recordControl, |
int * | search, | ||
int | RIS, | ||
int * | RID, | ||
char * | base | ||
) |
Load a record from a search result, specified by RIS.
recordControl | TRIP record control. |
search | Search number |
RIS | Ordinal number of record in search result |
RID | TRIP record identifier |
base | Database name |
The function TdbGetRecordInSearchRis() loads a record from a search set into a work area for further processing. This work area will have been created by a call to the TdbCreateRecordControl() function. The RIS
parameter must always be specified.
The recordControl
parameter is passed a TdbHandle
as the TRIP record control.
The search
parameter is passed a pointer to an int
variable that represents the number of the search set from which the record is to be loaded. If this variable is set to zero on input, the latest search set will be used and its number returned in this parameter on output. If this variable is set to a non-zero value on input, it indicates the a specific search set from which to obtain a record.
The RIS
parameter is passed an integer as the 1-based ordinal number of the record in the search set.
The RID
parameter is passed a pointer to an int
variable that will receieve the TRIP record identifier number of as the retrieved record. This variable must be set to zero before calling the routine.
The base
parameter is passed a character string to receive the name of the database of the retrieved record. If the search was performed across a multi-file view or a predefined cluster then successive calls to this function will update this value with the name of the database the record has been read from. The memory area that the base
parameter refers to must be at least 65 bytes inlength.
The return code from the TdbGetRecordInSearchRis() function is a bit mask that has the following structure. The return value is a combination of one or more of these bits.
Bit # | Value | Explanation |
---|---|---|
0 | 1 | The operation completed successfully. |
1 | 2 | The first hit record in an open database has been retrieved. This is only useful when searching in clusters. |
2 | 4 | The record has been deleted from the database. |
3 | 8 | The record is locked by another process. |
4 | 16 | At end - no more records. |
If an error occurs (i.e. the function returns an even value equal to zero or greater than 32) the associated TRIP error code can be retrieved by calling TdbRetCode().
int TdbGetRecordInThes | ( | TdbHandle | recordControl, |
int | termNumber, | ||
int * | level | ||
) |
Load a record from a thesaurus.
recordControl | Record control |
termNumber | Ordinal term number in display list |
level | Hierarchical level of record |
The function TdbGetRecordInThes() loads a specified record from the current thesaurus display into a work area, created by a call to TdbCreateRecordControl(). Each numbered term in the display list corresponds to the controlled term ( CTX ) of a record in the thesaurus. The hierarchical level of the term within the display list is returned on completion of the loading operation.
The records should be processed in order, starting with the record whose controlled term is term number one in the list and then successively incrementing the term number until all records have been retrieved and the routine returns an error code. The term itself can be obtained by calling TdbGetDisplayTerm() or by reading the CTX field of the thesaurus record.
A call to this routine must be preceded by a call to the function TdbExecuteCcl() (for TRIPsystem versions 3.4 and later) or to the functions TdbShellToDao() and TdbDaoOrder() (for TRIPsystem versions earlier than 3.4) to execute a CCL order generating a display list of the thesaurus.
The recordControl
parameter is passed a TdbHandle
as the record control.
The termNumber
parameter is passed an int
as the ordinal number of the term in the (current) display list. The record loaded will be that whose controlled term ( CTX ) is the term specified by the term number.
The level
parameter is passed a pointer to an int
variable to receive the hierarchical level of the record. Zero indicates that the record's controlled term is a main term in the current list.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
1314 | Database {1} is OS read protected. | |
12514 | CT={2}{3} in thesaurus record {1} causes a loop. |
int TdbGetSortedRecord | ( | int | search_no, |
TdbHandle | rec_ctl, | ||
int | ris, | ||
int * | rid, | ||
char * | base | ||
) |
Loads a record from a sorted search result.
search_no | Search number |
rec_ctl | TRIP record control |
ris | Ordinal number of record in the sorted search result |
rid | TRIP record identifier |
base | Database name |
The function TdbGetSortedRecord() loads a record from a search set sorted with the TdbSortRecords() function into a work area for further processing. This work area must have been created by a call to the TdbCreateRecordControl() function. The ris
parameter must always be specified.
The rec_ctl
parameter is passed a handle to a TRIP record control.
The search_no
parameter is passed an int
as the number of the search from which the record is to be loaded. A search number of zero indicates the current search, in which case the argument will be updated to receive the number of the search on return from the routine.
The ris
parameter is passed an integer as the ordinal number of the record in the search result.
The rid
parameter is passed a pointer to an int
variable to receive the TRIP record identifier. The argument must be set to zero before calling the routine.
The base
parameter is passed a character string as the database name. If the search was performed across a multi-file view or a predefined cluster then successive calls to this function will update this argument with the name of the database the record has been read from.
This function was introduced in TRIP version 3.4-0.
The return code from the TdbGetSortedRecord() function is a bit mask that has the following structure. The return value is a combination of one or more of these bits.
Bit # | Value | Explanation |
---|---|---|
0 | 1 | The operation completed successfully. |
1 | 2 | The first hit record in an open database has been retrieved. This is only useful when searching in clusters. |
2 | 4 | The record has been deleted from the database. |
3 | 8 | The record is locked by another process. |
4 | 16 | At end - no more records. |
If an error occurs (i.e. the function returns an even value equal to zero or greater than 32) the associated TRIP error code can be retrieved by calling TdbRetCode().
int TdbGetTimeStamp | ( | TdbHandle | recordControl, |
unsigned int * | timestamp, | ||
int | type | ||
) |
Retrieve the TRIP time stamp of a record.
recordControl | Record control identifier |
timestamp | Time stamp value |
type | Time stamp format |
The function TdbGetTimeStamp() returns the time stamp of a record. The record must have been previously loaded into a record control area via a call to either TdbGetRecord(), TdbGetRecordInBase(), TdbGetRecordInSearch() or TdbGetRecordInSearchRis() .
The recordControl
parameter is passed a TdbHandle
as the record control identifying the record whose time stamp is to be returned.
The timestamp
parameter is passed a pointer to an unsigned 32-bit integer to receive the record's time stamp value.
The type
parameter is passed an int
as the formatting type of the time stamp to be returned. The acceptable values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
DATE_AND_TIME | 0 | Return both Date and Time components of the time stamp |
DATE_ONLY | 1 | Return only the Date component of the time stamp |
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbHitParts | ( | TdbHandle | recordControl, |
int * | parthits, | ||
int * | partcount, | ||
int * | partmax | ||
) |
Retrieve information about part records in a search.
recordControl | TRIP record control identifier |
parthits | Count of hits within parts |
partcount | Count of parts |
partmax | maximum part number |
The function TdbHitParts() returns the following information about part records of a record retrieved from a search set using TdbGetRecord() or similar function.
The parthits
is passed a pointer to an int
variable to receive the number of hit part records retrieved by the search.
The partcount
parameter is passed a pointer to an int
variable to receive the count of the part records.
The partmax
is passed a pointer to an int
variable to receive the highest part record number retrieved.
This function was introduced in TRIP version 3.3-1.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. |
int TdbImportBlob | ( | TdbHandle | cursor, |
const char * | filename | ||
) |
Import a binary large object from a file.
cursor | Cursor identifier |
filename | Filename to import |
The function TdbImportBlob() loads an object from the server-side file specified via the filename
parameter into the field referenced by the cursor
parameter.
The cursor
parameter is passed a handle to a cursor, which has previously been set (using the TdbSetCursor() function) to the field to receive the data. Typically the field that cursor
identifies will be a STRING type field.
The filename
parameter is passed a character string as the name of the server-side file from which data is to be imported. Syntax rules for specifying the name are dependent upon the operating system running the TRIP process. The rules may therefore be different is the call to this function is made by a client running on a platform that adopts a different format for filenames.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
834 | File {1}{2}{3} not found. | |
21634 | {1} is not a blob field. |
int TdbInsertItem | ( | TdbHandle | cursor, |
char * | data_item, | ||
int | item_length | ||
) |
Load a data item from a buffer into a record control area.
cursor | Cursor identifier |
data_item | Data item string to copied to record |
item_length | Number of bytes to transfer |
The function TdbInsertItem() inserts a value (a sentence, a phrase, a number, a date or a time) into the record indicated by the cursor. The cursor must have been previously positioned by a call to the TdbSetCursor() function. The value is inserted before the sentence or subfield indicated by the cursor, unless the cursor domain covers a field or a paragraph. In this case, the value is appended to the end of the domain.
The cursor should be repositioned by a call to the function TdbSetCursor() before attempting to call any function which references the cursor domain, as the cursor domain becomes undefined after calling TdbInsertItem().
The cursor
parameter is passed a TdbHandle
as the cursor identifier, which has been set by a an earlier call to the TdbSetCursor() function.
The data_item
parameter is passed a character string as the value copied to the record control area.
The item_length
parameter is passed an int
as the number of bytes in the data_item
buffer to transferred.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
2178 | Invalid {NUM}. | |
2242 | Invalid {TIM}. | |
12482 | Maximum number of subfields for {1} is {3}. | |
16706 | Invalid {INT}. | |
18178 | Use TdbCheckPartName() for checking/storing part names. |
int TdbInsertRecordPart | ( | TdbHandle | cursor, |
const char * | partname | ||
) |
Insert a record part.
cursor | Cursor identifier |
partname | Name of record part to insert |
The function TdbInsertRecordPart() is used to insert a record part before the part to which the cursor is currently referring. The cursor must have been attached to the record control area by using the function TdbSetRecordPart() prior to attempting to call this function.
The function can only be used to update databases that include a part record name field.
The record must be saved with a call to the TdbPutRecord() function.
The cursor
parameter is passed a TdbHandle
as the cursor identifier.
The partname
parameter is passed a character string as the name of the record part to insert.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
16034 | Already existing record part name: {1} | |
17986 | Database {1} has no part name field. | |
21698 | Argument {1} - value out of range. |
int TdbItemCount | ( | TdbHandle | cursor, |
int * | count | ||
) |
Retrieve the number of items in a field.
cursor | Cursor identifier |
count | Count of items in domain |
The function TdbItemCount() returns information about the domain of the cursor given in the cursor
parameter. Depending on the domain covered by the cursor
parameter this function returns one of the following:
The cursor
parameter is passed a handle to a cursor.
The count
parameter is passed an integer to receive the count of the number of items in the domain of the cursor.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
8290 | OS open file limit of {1} reached. | |
17218 | The {1} file of {2} is no {1} file. |
int TdbLockRecord | ( | TdbHandle | recordControl | ) |
Lock the record in the record control area.
recordControl | Record control identifier |
The function TdbLockRecord() locks the record that is currently in the record control area, thereby granting the calling process exclusive write access to it, until the record is released with a call to one of the TdbReleaseRecord(), TdbPutRecord(), TdbDeleteRecordControl(), or TdbEraseRecordControl() functions. Other users keep read access to the record.
A record is automatically locked by a call to the TdbGetRecord(), TdbGetRecordInBase(), TdbGetRecordInSearch(), or TdbGetRecordInSearchRis() functions, if the preceding call to TdbSetBase() specified write access.
The recordControl
is passed a TdbHandle
as the record control identifier associated with the record to be locked into memory.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
16418 | TRIPdaemon failed to respond (1), notify your System Mgr. | |
16450 | TRIPdaemon failure (1), notify your System Mgr. | |
16482 | Your process is unknown to the TRIP daemon, notify your System Mgr. | |
16898 | Concurrent user quota (1) exceeded. | |
17570 | Invalid TRIPdaemon process name. |
int TdbNextControl | ( | TdbHandle * | recordControl | ) |
Load a CONTROL file record.
recordControl | Record control identifier |
The function TdbNextControl() loads a CONTROL file record into a work area specified by the recordControl
parameter. This work area is maintained by TRIPkernel and must not be deleted or used for any other purpose. The record loaded must have been previously specified by a call to the TdbShowControl() function.
The recordControl
parameter is passed a pointer to TdbHandle variable that will receive a handle to a record control associated with the CONTROL database.
The current TRIPsystem user needs no special privileges to execute this function.
Code | Description | Explanation |
---|---|---|
0 | Function failed | There are no more control items |
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. |
int TdbParaCount | ( | TdbHandle | cursor, |
int * | count | ||
) |
Returns the number of paragraphs within a field.
cursor | Cursor identifier |
count | Paragraph count |
Returns the number of paragraphs within a field specified by the cursor position.
The cursor
parameter is passed a a cursor handle.
The count
parameter is passed a pointer to an integer to receive the count of the number of paragraphs in the domain of the cursor
system identifier.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
1314 | Database {1} is OS read protected. |
int TdbPartCount | ( | TdbHandle | cursor, |
int * | count | ||
) |
Returns the number of part records within a record.
cursor | Cursor identifier |
count | Paragraph count |
The function TdbPartCount() returns the number of part records within a record identified by the cursor
parameter. The record must have been loaded by a call to one of the TdbGetRecord(), TdbGetRecordInBase(), TdbGetRecordInSearch() or TdbGetRecordInSearchRis() functions.
The cursor
parameter is passed a TbdHandle
as a cursor identifier.
The count
parameter is passed a pointer to an integer that receives the count of the number of paragraphs in the domain of the cursor
system identifier.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
14658 | Undefined cursor. |
int TdbPutBlobBlock | ( | TdbHandle | cursor, |
int | blockLen, | ||
char * | block | ||
) |
Write data to a STRING field.
cursor | Cursor pointing to a STRING field. |
block | Buffer with data to write. |
blockLen | Number of bytes in the block to write. |
The TdbPutBlobBlock() function is used to store the contents of a STRING field. A block can be max 32KB, so for larger values, repated calls to this routine is required.
The cursor in the cursor
parameter must be set to refer to a STRING field. No other field types are valid with this function. This is a read-only value.
The block
is to be assigned a byte sequence to write to the STRING field.
The blockLen
parameter is to be set to the number of bytes in the block to write.
Code | Description | Explanation |
---|---|---|
0 | Requested block does not exist. | This error occurs when the blockNr parameter is set too high. |
1 | Returned block is the last one. | |
3 | Block returned ok - more blocks are available. | When this return code is recieved, the application is expected to call this function again with the blockNr parameter incremented by one. |
14658 | Invalid cursor. | |
21634 | field is not a BLOB field. |
int TdbPutFieldInfo | ( | TdbHandle | cursor, |
int | buf_len, | ||
char * | rec_buf | ||
) |
Assign a value to a TEXT field.
cursor | Cursor set to a text field |
buf_len | Length of the value in rec_buf |
rec_buf | Value to store |
int TdbPutLine | ( | TdbHandle | cursor, |
char * | line, | ||
int | line_length | ||
) |
Load a text line from a buffer into a record control area.
cursor | Cursor identifier |
line | Text line to write |
line_length | Number of bytes to transfer |
The function TdbPutLine() fills the field indicated by the cursor with the contents of the buffer provided as input. The first call to TdbPutLine() after setting the cursor
parameter causes the existing contents of the field to be replaced. Subsequent calls append the contents of the buffer to the end of the field specified in the domain of the cursor
parameter. The record can be saved with a call to the TdbPutRecord() function.
The cursor
parameter is passed a TdbHandle
as the cursor identifier for the record; this will have been set with a prior call to the TdbSetCursor() function.
The line
parameter is passed a character string as the line of text to copy to the record. Strictly this function copies the text line to the record control associated with the cursor
argument.
The line_length
parameter is passed an int
as the count of the number of bytes in the buffer ( line
) to transfer.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
610 | Database {1} not found. | |
962 | File name error, check logical names for {1}. | |
1314 | Database 1 is OS read protected. | |
2178 | Invalid {NUM}. | |
2210 | Invalid {DAT}. | |
2242 | Invalid {TIM}. | |
2530 | No access to database {1}. | |
3106 | Old version of BIF/VIF files. | |
7010 | Database LOG file cannot be opened. | |
9538 | No write access to the database {2}. | |
11362 | Max 250 databases can be opened during a TRIP session. | |
13762 | No write access to field: {1} | |
15010 | {1} is a database cluster. | The database name passed to the function refers to a database cluster and not a single database. |
16706 | Invalid {INT}. | |
17314 | No access to DB cluster {1}. | |
18178 | Use TdbCheckPartName() for checking/storing part names. | |
19490 | Ill-formed or invalid integer. | |
19522 | Ill-formed or invalid number. | |
19554 | Ill-formed or invalid date. | |
19586 | Ill-formed or invalid time. | |
19618 | Invalid phrase. | |
19650 | The phrase does not match the specified pattern. | |
19746 | Subfield contains more than 255 characters. | |
19778 | Subfield contains just blank characters. |
int TdbPutRecord | ( | TdbHandle | recordControl, |
int * | recordId | ||
) |
Write a record into a database.
recordControl | Record control identifier |
recordId | Record number |
The function TdbPutRecord() writes a record into the database. The record is held in an internal work area, i.e. the record control. If the record has previously been read into the record control (by calling one of the TdbGetRecord(), TdbGetRecordInBase(), TdbGetRecordInSearch() or TdbGetRecordInSearchRis() functions) this routine will update the record in the BAF file, otherwise a new record will be added, and the recordId
parameter will receive the number that was assigned to the record by the TRIPkernel. A requirement for updating the database is that the function TdbSetBase() was previously called with an access mode of MODE_WRITE
specified.
Alternatively, a copy of an existing record may be added to the database. The function TdbSetBase() should then be called to specify access mode MODE_READ
before loading the existing record into the record control via one of the aforementioned routines. Prior to storing the record, however, TdbSetBase() must be called again, this time with the access mode of MODE_COPY
specified.
Alternatively specifying the access mode MODE_COPY
indicates to TdbPutRecord() that a record is to be added, not updated as would normally be the case when an existing record is used.
The recordControl
parameter is passed a handle to a record control. The record control object must have been previously created by a call to the function TdbCreateRecordControl() and attached to a database by a call to the function TdbSetBase() (with the access mode set to either of MODE_WRITE
or MODE_COPY
depending upon the intended usage).
The recordId
parameter is passed a pointer to an int
variable as the record number identifying the record to be updated. For storage of a new record, set this variable to 0 on input. For update of a record, set this variable to the number of the record to update. On output this parameter always receives the number of the record that was written.
Code | Description | Explanation |
---|---|---|
130 | Record control structure not created. | |
290 | Invalid BAF,BIF,VIF or DBL file name. | |
1218 | Field 1 cannot be copied; different field types. | |
2882 | Non-existing record: {1} | |
7042 | Missing mandatory field: {1} | |
7074 | Already existing record name: {1} | |
7202 | Disk quota exceeded for database {2} | |
7298 | Record name field must not be blank. | |
7330 | Record name field must not be changed. | |
7522 | Database {2} is OS write protected. | |
9090 | Database {2} is locked by another user, try again later. | |
9122 | Database log for {2} is locked by another user, try again later. | |
9538 | No write access to the database {2}. | |
14402 | Field 1 cannot be copied; main/part record conflict. | |
15202 | The BAF file of 2 needs reorganization (See PACKIT). | |
17218 | The {1} file of {2} is no {1} file. | |
17634 | Minimum no of subfields for {1} is {3}. | |
17666 | Minimum no of paragraphs for {1} is {3}. | |
18338 | No database connection. | |
14754 | Database {2} is open for read only. | |
14818 | No write access to this record. | |
15714 | Field {1} conflict, {2} {1} paragraph only | |
19490 | Ill-formed or invalid integer. | |
19522 | Ill-formed or invalid number. | |
19554 | Ill-formed or invalid date. | |
19586 | Ill-formed or invalid time. | |
19618 | Invalid phrase. | |
19650 | The phrase does not match the specified pattern. | |
19746 | Subfield contains more than 255 characters. | |
19778 | Subfield contains just blank characters. | |
22722 | Old version of the {1} file, reindex {2}. | |
25954 | Cannot load foreign key link database's CONTROL record (1) | |
25986 | The operation on record {1} has been aborted because it would cause an integrity violation | |
26082 | Some records affected by the update could not be modified – database integrity has been compromised | |
33539 | Record {1} added. | The function completed its operations without error. |
33571 | Record {1} modified. | The function completed its operations without error. |
33891 | Empty record, not stored. | The function completed its operations without error. |
33923 | No changes made to this record. | The function completed its operations without error. |
int TdbPutRecordBuffer | ( | TdbHandle | cursor, |
char * | buffer_address, | ||
int | buffer_len, | ||
int * | err_partnr, | ||
int * | err_fieldnr, | ||
int * | err_itemnr | ||
) |
Load a TRIP record with TFORM-formatted data.
cursor | cursor identifier |
buffer_address | Buffer address |
buffer_len | Length of buffer |
err_partnr | Number of first part record with error |
err_fieldnr | Number of first field with error |
err_itemnr | Number of first item with error |
The function TdbPutRecordBuffer() is used to load a TRIP record with TFORM-formatted data. Remember to call TdbPutRecord() to commit the changes to the database.
The cursor
parameter is passed a handle to a cursor for the record.
The buffer_address
parameter is passed the address of the buffer with TFORM data to write to the database.
The buffer_len
parameter is passed an int
as the number of bytes in the buffer ( buffer_address
) to write to the database.
The err_partnr
parameter is passed a pointer to an int
variable to receive the number of the first part record that contains a field failing a constraint in the database design.
The err_fieldnr
parameter is passed a pointer to an int
variable to receive the number of the first field that fails to comply with a constraint in the database design.
The err_itemnr
parameter is passed a pointer to an int
variable to receive the number of the first item that fails to comply with a constraint in the database design.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
610 | Database {1} not found. | |
962 | File name error, check logical names for {1}. | |
1314 | Database {1} is OS read protected. | |
2178 | Invalid {NUM}. | |
2210 | Invalid {DAT}. | |
2242 | Invalid {TIM}. | |
2530 | No access to database {1}. | |
3106 | Old version of BIF/VIF files. | |
9538 | No write access to the database {2}. | |
11362 | Max 250 databases can be opened during a TRIP session. | |
12130 | Attempt to open a previously deleted database. | |
13762 | No write access to field: {1} | |
15010 | {1} is a database cluster. | The database name passed to the function refers to a database cluster and not a single database. |
16706 | Invalid {INT}. | |
17314 | No access to DB cluster 1. | |
18178 | Use TdbCheckPartName() for checking/storing part names. | |
19490 | Ill-formed or invalid integer. | |
19522 | Ill-formed or invalid number. | |
19554 | Ill-formed or invalid date. | |
19586 | Ill-formed or invalid time. | |
19618 | Invalid phrase. | |
19650 | The phrase does not match the specified pattern. | |
19746 | Subfield contains more than 255 characters. | |
19778 | Subfield contains just blank characters. | |
25602 | Out of memory |
int TdbRecordInfo | ( | TdbHandle | recordControl, |
int | mode, | ||
char * | stringValue, | ||
int * | intValue | ||
) |
Returns information about a record.
recordControl | Record control for record to get information about. |
mode | Type of information to retrieve. |
stringValue | Output parameter for information of string type. |
intValue | Output parameter for information of integer type. |
The TdbRecordInfo() function provides a way to obtain various information about a TRIP database record.
The recordControl
parameter is a record control that refers to a TRIP database record. The record control is created using TdbCreateRecordControl() and initialized to a specific record using TdbGetRecord() or one of the deprecated functions such as TdbGetRecordInSearchRis() or TdbGetRecordInBase().
The mode
parameter is used to tell the function what information to return and must be set to one of the following values:
Value | Output Parameter | Description |
---|---|---|
RECORDINFO_RID | intValue | Return the record identifier (RID) of the record. |
RECORDINFO_DBNAME | stringValue | Return the name of the database the record is stored in. |
RECORDINFO_RNAME | stringValue | Return the record name value of the record. |
RECORDINFO_TSTAMP_CODED | intValue | Returns the modification timestamp of the record in a numeric representation. |
RECORDINFO_TSTAMP_ASCII | stringValue | Returns the modification timestamp of the record in the current date form. |
RECORDINFO_CLASS_NAME | stringValue | Returns the name of the class assigned to this record. Requires that the database is associated with a classification scheme. |
RECORDINFO_HITS | intValue | Returns the total number of hits in the record. The record must be retrieved from the latest search set using TdbGetRecordInSearchRis. |
This function was introduced in TRIP version 3.4-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
7298 | Record name field must not be blank. | |
7394 | No record name field defined in {1}. | |
17826 | No of subfields in 3 exceeds the limit of {1}. |
int TdbReleaseRecord | ( | TdbHandle | recordControl | ) |
Release a lock on a record.
recordControl | Record control identifier |
The function TdbReleaseRecord() releases the lock on the record that is currently in the record control area. The record could have been locked by a call to one of the functions TdbLockRecord(), TdbgGetRecord(), TdbGetRecordInBase(), TdbGetRecordInSearch() or TdbGetRecordInSearchRis(), if the preceding call to the function TdbSetBase() had an access mode of MODE_WRITE
specified. A record is automatically locked if it is loaded in write-access mode.
The recordControl
parameter is passed a handle to a record control.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
16418 | TRIPdaemon failed to respond (1), notify your System Mgr. | |
16450 | TRIPdaemon failure (1), notify your System Mgr. | |
16482 | Your process is unknown to the TRIP daemon, notify your System Mgr. |
int TdbRenameRecordPart | ( | TdbHandle | cursor, |
const char * | part_name | ||
) |
Rename a record part.
cursor | Cursor identifier |
part_name | Name of record part |
The function TdbRenameRecordPart() is used to rename the record part that the cursor
parameter is currently addressing. The cursor must have been attached to the record control area by using the function TdbSetRecordPart() prior to attempting to call this function.
The routine can only be used to update databases that include a part record name field.
The function TdbPutRecord() must be called in order to save record.
The cursor
parameter is passed a handle to a cursor identifying a part record.
The part_name
parameter is passed a character string specifying the new name of the record part.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
17986 | Database {1} has no part name field. |
int TdbReplaceItem | ( | TdbHandle | cursor, |
char * | data_item, | ||
int | item_length | ||
) |
Replace a data item in a record control area.
cursor | Cursor identifier |
data_item | Data item to replace existing data |
item_length | Number of bytes in data item buffer |
The function TdbReplaceItem() replaces the value of the sentence or subfield indicated by the cursor with the value contained in the buffer. This routine may be called directly after a call to the TdbSetCursor() has set the domain of the supplied cursor. If the domain covers a field or a paragraph, all of the domain is replaced by the buffer contents.
In order to save the updated record the function TdbPutRecord() must be called.
The cursor
parameter is passed a handle to a cursor. This argument will have been set with a prior call to the TdbSetCursor() function.
The data_item
parameter is passed a character string as the data item to replace the existing data in the domain of the cursor
argument.
The item_length
parameter is passed an int
as the count of the number of bytes in the data item buffer to use. The entire item in the domain of cursor
will be replaced irrespective of the value of this argument.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
2178 | Invalid {NUM}. | |
2210 | Invalid {DAT}. | |
2242 | Invalid {TIM}. | |
13762 | No write access to field: {1} | |
16706 | Invalid {INT}. | |
18178 | Use TdbCheckPartName() for checking/storing part names. | |
19490 | Ill-formed or invalid integer. | |
19522 | Ill-formed or invalid number. | |
19554 | Ill-formed or invalid date. | |
19586 | Ill-formed or invalid time. | |
19618 | Invalid phrase. | |
19650 | The phrase does not match the specified pattern. | |
19746 | Subfield contains more than 255 characters. | |
19778 | Subfield contains just blank characters. |
int TdbSetBase | ( | TdbHandle | recordControl, |
char * | base, | ||
int | access_mode | ||
) |
Set the access mode for a database.
recordControl | Record control identifier |
base | Database name |
access_mode | Access mode for database |
The function TdbSetBase() is used to make a database accessible for input and/or update operations via the TdbGetRecord(), TdbGetRecordInBase(), TdbGetRecordInSearch(), TdbGetRecordInSearchRis() and TdbPutRecord() functions.
If a copy of an existing record is to be added to the database, the function TdbSetBase() must be called twice. The first time (before loading the record into the record control) an access mode of MODE_READ
should be specified. The second time (before adding the record to the database) an access mode of MODE_COPY
must be set.
The recordControl
parameter is passed a handle to a record control. This record control object must have been previously created by a call to the TdbCreateRecordControl() function.
The base
parameter is passed a character string as the name of the database to be associated with the record control argument. On a successful call, this parameter receives the normalized name of the database.
The access_mode
parameter is passed an int
as the access mode for the database. Valid values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
MODE_READ | bit 0 | Require read access to the database |
MODE_WRITE | bit 1 | Require modify access to the database |
MODE_DELETE | bit 2 | Require delete access to the database |
MODE_COPY | bit 3 and bit 1 | Require copy access to the database |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
1218 | Field {1} cannot be copied; different field types. | |
10594 | No delete rights to database {1}. | |
14402 | Field {1} cannot be copied; main/part record conflict. | |
15714 | Field {1} conflict, {2} {1} paragraph only | |
16738 | No database specified for data entry. | |
17826 | No of subfields in {3} exceeds the limit of {1}. |
int TdbSetCursor | ( | TdbHandle * | cursor, |
TdbHandle | recordControl, | ||
int | field, | ||
int | paragraph, | ||
int | item | ||
) |
Set a cursor domain.
cursor | Cursor identifier |
recordControl | Record control identifier |
field | Field number |
paragraph | Paragraph number |
item | Item number |
The function TdbSetCursor() is used to create and/or set a cursor indicating a record or record substructure. The domain of the cursor is defined by field, paragraph and subfield or sentence numbers within the record contained in the record control area.
The cursor domain can be made to cover more than a single sentence/subfield by setting the item argument to zero. For any non-TExt field, this will cause the entire field to be included in the domain, whereas for a TExt field, the paragraph argument must also be set to zero, or else the domain will be limited to the specified paragraph.
The cursor
parameter is passed a pointer to a TdbHandle variable that either specifies the cursor to set or receives a newly created cursor. The first time the function TdbSetCursor() is called for a specific cursor, the variable to which the parameter points must be set to NULL to indicate that the cursor has to be created before it is positioned.
The recordControl
parameter is passed a handle to a record control. The record control specified is that which the cursor is to address. The record control must already exist, typically with a call to the TdbCreateRecordControl() function.
The field
parameter is passed an integer as the field number to set as the cursor domain.
The paragraph
parameter is passed an integer as the paragraph number to set as the cursor domain. This argument is only meaningful if the field currently addressed by the cursor is a TExt type field. If a value of zero is provided then the domain will be the entire field.
The item
parameter is passed an integer as the item number to set as the cursor domain. If the field addressed by the cursor is a TExt field, the item corresponds to the sentence within the paragraph. If the field is of any type other than TExt, the item corresponds to the subfield within the field. If a value of zero is provided then the domain will be the entire paragraph (for TExt fields) or the entire field for all other types.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
2146 | Non-existing field: {1} |
int TdbSetLinkBase | ( | TdbHandle | recordControl, |
char * | base_name, | ||
TdbHandle * | base_id | ||
) |
Make a database accessible for data entry linkage.
recordControl | Record control |
base_name | Name of linked database |
base_id | TRIP internal identification number for database. |
The function TdbSetLinkBase() opens a database for searching and makes it accessible for linkage during data entry. The database identifier must be set to zero on the first call. The base_id
parameter will contain the actual identifier on return from the function.
The function TdbGetLinkRecord() is used to get at records from the link database by the record name. If a record is found, the data can be fetched by setting a cursor with TdbSetCursor() using the link record record control and then call TdbGetLine() .
The recordControl
parameter is passed a handle to a record control.
The base_name
parameter is passed a character string as the name of the linked database.
The base_id
parameter is passed a pointer to a TdbHandle variable that will receive the TRIP identification for the database.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
610 | Database {1} not found. | |
962 | File name error, check logical names for {1}. | |
1314 | Database {1} is OS read protected. | |
2530 | No access to database {1}. | |
3106 | Old version of BIF/VIF files. | |
7010 | Database LOG file cannot be opened. | |
7522 | Database {2} is OS write protected. | |
9538 | No write access to the database {2}. | |
11362 | Max 250 databases can be opened during a TRIP session. | |
12130 | Attempt to open a previously deleted database. | |
15010 | {1} is a database cluster. | The database name passed to the function refers to a database cluster and not a single database. |
17314 | No access to DB cluster {1}. | |
17858 | Chinese vocabulary files not found. | |
25602 | Out of memory |
int TdbSetRecordPart | ( | TdbHandle * | cursor, |
TdbHandle | recordControl, | ||
int | part_number | ||
) |
Specify the record part.
cursor | Cursor identifier |
recordControl | Record control identifier |
part_number | Part number |
The function TdbSetRecordPart() is used to specify the record part to which a cursor refers. If the part number is zero, the cursor will be set to refer to a new, not yet created record part at the end of the part list.
The cursor
parameter is passed a pointer to a TdbHandle variable that specifies a cursor handle. If the handle is set to NULL on input, then a new cursor is created; otherwise, the value is taken as that of an existing cursor and it is modified to refer to the specified record part.
The recordControl
parameter is passed a handle to the record control to associate with the cursor
argument.
The part_number
parameter is passed an integer as the part number. A value of zero indicates a that a new part is to be created. Passing zero also indicates the head record in the context of reading data from the record.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Failure | Operation failed |
1 | Cursor was set to refer to an existing part | The function completed its operations without error. |
3 | Non-existing part, i.e. new part record to be created. | The function completed its operations without error. |
130 | Record control structure not created. |
int TdbShowControl | ( | int | mode, |
int | all_flag, | ||
char * | name1, | ||
char * | name2 | ||
) |
Initialize reading of CONTROL records.
mode | Operation mode |
all_flag | All flag |
name1 | Name string |
name2 | Name string |
The function TdbShowControl() initializes a series of calls to TdbNextControl() . This routine will provide the same functionality as the CCL commands for showing contents from the CONTROL file, sorted alphabetically. It must be called before the first call the TdbNextControl() function in order to specify which records are to be transferred. Also see TdbStartControl(), which can be used to set a starting point in the list of selected records.
The mode
parameter is passed an int
to indicate the type of information to retrieve from the CONTROL file. Valid values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
DATABASE_LIST | 1 | Return database list (equivalent to CCL: order BASE) |
USER_LIST | 2 | Return user list (equivalent to CCL order SHOW USER) |
DATABASE_STATUS | 3 | Return status information equivalent to CCL order SHOW BASE) |
PROCEDURE_LIST | 4 | Return procedure list (equivalent to CCL order SHOW PROC) |
DATABASE_ACCESS | 5 | Return database access list (equivalent to CCL order SHOW ACCESS) |
OUTPUT_FORMAT_LIST | 6 | Return output format list (equivalent to CCL order SHOW FORMAT) |
ENTRY_FORM_LIST | 7 | Return entry form list (equivalent to CCL order SHOW EFORM) |
SEARCH_FORM_LIST | 8 | Return search form list (equivalent to CCL order SHOW SFORM) |
THESAURUS_STATUS | 9 | Return thesauri status information (equivalent to CCL order SHOW THES) |
GROUP_LIST | 10 | Returns group information (equivalent to CCL order SHOW GROUP) |
CURRENT_STATUS | 11 | Returns single database/cluster status (equivalent to CCL order STATUS) |
USERS_PER_GROUP | 14 | Return information on all members of one group |
GROUPS_PER_USER | 15 | Return information on all groups for one user |
The all_flag
parameter is passed an int
as the indicator of scope of information to be returned. Valid values are:
Constant Value | Purpose |
---|---|
0 | Only possible value for a normal user. Limits scope of information to that which they can retrieve using the equivalent CCL order. |
1 | System manager can set this value to examine all records of the current mode |
The name1
parameter is passed a character string as the first name string. This argument is used to specify the first or only argument, e.g, database name , user name . A blank string indicates all records of the current mode.
The name2
parameter is passed a character string as the second name string. A blank string indicates all records that are connected to the name1
argument.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
610 | Database {1} not found. | |
930 | Syntax error. | |
6626 | No database is open, supply database name. | |
8866 | Missing argument. | |
9762 | You are not the creator of this record. | |
9794 | You are not a file manager. | |
9826 | You are not a user manager. | |
9922 | You are not a SYSTEM manager. | |
15746 | System Manager rights is needed for the ALL argument | |
15778 | The ALL argument must not be used with name arguments |
int TdbSortRecords | ( | int | searchNumber, |
char * | sortSpecification | ||
) |
Sort an existing search set.
searchNumber | The number of the search set to sort. |
sortSpecification | This is the SORT specification. |
The TdbSortRecords() function is used to sort search sets according to a SORT specification. To iterate through the sorted search set, use the TdbGetRecord() function with mode RECORD_FROM_SORTED_SEARCH
.
The sortSpecification
parameter specifiess only the part that is to the right of the '=' sign in the CCL "SHOW SORT=" statement.
This function was introduced in TRIP version 3.4-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
66 | Unbalanced parenthesis. | The SORT clause contained an unbalanced parenthesis. |
994 | There is no search for implicit use. | |
1698 | Non-existing field name: {2} | |
3970 | Sort order syntax error. | |
4002 | Too many records {1} for sort, current limit is {2}. | |
4034 | {1} field type not allowed in sort order. | |
4066 | Sort key creation error. | |
13186 | Set is empty. | The sort failed because the search set did not contain any records. |
19490 | Ill-formed or invalid integer. | |
22722 | Old version of the {1} file, reindex {2}. | Index structure is too old. Reindex the database. |
int TdbSortRecordsEx | ( | int | searchNumber, |
const char * | sortSpecification, | ||
int | mode | ||
) |
Sort an existing search set with clusters and/or record parts.
searchNumber | The number of the search to sort. |
sortSpecification | This is the SORT specification. |
mode | Search mode bitmask |
The TdbSortRecordsEx() function is used to sort search sets according to a SORT specification. When sorting a search set from a cluster or if sorting should consider record parts, this function should be used instead of the similarly named TdbSortRecords
function. To iterate through the sorted search set, use the TdbGetRecord() function with mode RECORD_FROM_SORTED_SEARCH
.
The sortSpecification
parameter specifiess only the part that is to the right of the '=' sign in the CCL "SHOW SORT=" statement.
The mode
parameter is passed an integer as a bitmask indicating additional control parameters for the sort operation. Valid values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
SORT_MERGE | 1 | Sort records from all databases in cluster together. Mutually exclusive with SORT_NOMERGE. |
SORT_NOMERGE | 2 | Sort records from database in cluster separately. Mutually exclusive with SORT_MERGE. |
SORT_PARTS | 3 | Perform part-record oriented sorting |
If the mode
parameter does not include either SORT_MEGRGE or SORT_NOMERGE, the sort operation will use the DEFINE [NO] MERGE value currently set in the session.
This function was introduced in TRIP version 8.1-1:3
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
66 | Unbalanced parenthesis. | The SORT clause contained an unbalanced parenthesis. |
994 | There is no search for implicit use. | |
1698 | Non-existing field name: {2} | |
3970 | Sort order syntax error. | |
4002 | Too many records {1} for sort, current limit is {2}. | |
4034 | {1} field type not allowed in sort order. | |
4066 | Sort key creation error. | |
13186 | Set is empty. | The sort failed because the search set did not contain any records. |
19490 | Ill-formed or invalid integer. | |
22722 | Old version of the {1} file, reindex {2}. | Index structure is too old. Reindex the database. |
int TdbSortTerms | ( | int | termSetNumber, |
int | sortFlags | ||
) |
Sorts a display order or term set.
termSetNumber | The number of the term set to sort, or 0 (zero) to sort the latest regular term list. |
sortFlags | Sort specification bit mask |
The TdbSortTerms() function is used to apply a new sort order to the latest executed DISPLAY order or registered term set.
Pass 0 (zero) to the termSetNumber
parameter to re-sort the latest DISPLAY order, or a positive number identifying the term set to re-sort.
The sortFlags
parameter is a bit mask that specifies how to sort the term list. The mask must contain exactly one of the following values:
Symbol | Description |
---|---|
TERM_SORT_TEXT | Sort alphabetically, ascending |
TERM_SORT_FREQ | Sort on frequency, descending |
TERM_SORT_TEXT_DESC | Sort alphabetically, descending |
TERM_SORT_FREQ_ASC | Sort on frequency, descending |
When sorting a baseline term set, the sortFlags
bit mask may also include the following:
Symbol | Description |
---|---|
TERM_SORT_BL_ATEND | Sort zero-sized baseline terms at end |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbStartControl | ( | char * | name | ) |
Set the initial value for reading CONTROL records.
name | Name of first CONTROL record |
The function TdbStartControl() loads the name of the CONTROL database record that is to be used as the start point for a sequence of calls to the TdbShowControl() and TdbNextControl() functions.
The name
parameter is passed a character string as the name of the first CONTROL record to show.
Code | Description | Explanation |
---|---|---|
0 | Failure | No CONTROL records could not be found at or after the specified starting point. |
1 | Operation completed successfully | The function completed its operations without error. |
3 | No exact match was found, but the next CONTROL record (in alphabetical order) was selected. | The function completed its operations without error. |
int TdbStartSummarization | ( | void ** | handle, |
int | engine_id | ||
) |
Initialize the text summarization engine.
handle | Receives a handle to the summarizer as a void pointer |
engine_id | ID of the summarization engine to use. Reseverd for future use. Always pass 1 as value. |
Initializes the specified summarization engine for a summarization run. The engine_id
parameter currently only accepts 1 as valid value.
After having called this function, call TdbAccumulateSummarization() any number of times to accumulate data to summarize. Generate the summary by calling TdbGenerateSummary(), and close the summarization run by a call to the TdbEndSummarization() function.
int TdbUndeleteRecordPart | ( | TdbHandle | cursor | ) |
Undelete the previously deleted record part.
cursor | Cursor identifier |
The function TdbUndeleteRecordPart() is used to restore the record part that was previously deleted by a call to the function TdbDeleteRecordPart(), the mode argument to that routine set to one. The record part will be inserted before the part to which the cursor is currently referring.
The routine can only be used to update databases that include a part record name field.
The function TdbPutRecord() must be called in order to save the record.
The cursor
parameter is passed a handle to a cursor. The cursor is used as a reference to data in a TRIP internal work area.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
130 | Record control structure not created. | |
16066 | There is no deleted part record to undelete. |
int TdbValidValues | ( | int | field_number, |
TdbHandle | base_id, | ||
char * | term | ||
) |
Produce term lists in combination with link databases.
field_number | Number of field(s) to check |
base_id | Link database id |
term | Term to display |
The TdbValidValues() function is used to produce term lists in combination with link databases. This call will fill the display window (if defined), and selection of terms must be carried out by the application.
After the call to TdbValidValues(), do the following to retrive the terms.
The list is from the current database or a restriction database:
The list is from a link database:
Call TdbGetLinkRecord() to read the corresponding record from the link database. Then use standard methods to read desired fields from this database.
The content of the field_number
parameter depends on what kind of list is to be produced. The choice of list is made by TRIP in the priority order shown here. A list from a link database; one or two field numbers. A list from a restriction database; one field number. A list from the current database; one field number.
For a link database, the field numbers should be those which are to be loaded from the link database. If two fields are to be shown, field_number
must have the value: f2*65536+f1, where f1 and f2 are the field names.
The base_id
parameter is passed a TdbHandle
as the link database id. This is the value returned from TdbSetLinkBase(). If a link database is not used, this parameter must be NULL.
The term
parameter is an input string that defines what to display.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
194 | No terms! | |
578 | No index found for {1}. |