TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
Data Manipulation

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.
 

Detailed Description

Data manipulation functions.

The data manipulation functions cover all functionality for manipulation of database contents.

Function Documentation

◆ TdbAccumulateSummarization()

int TdbAccumulateSummarization ( void *  handle,
TdbHandle  cursor 
)

Add data to the summarizer.

Parameters
handleHandle to the summarizer
cursorCursor referring to a field value to add
Returns
1 or other odd value on success, even value on error

Description

Adds data to the summarizer referred to by handle (obtained by a call to TdbStartSummarization()).

See also
TdbStartSummarization()
TdbGenerateSummary()
TdbEndSummarization()

◆ TdbAppendRecordPart()

int TdbAppendRecordPart ( TdbHandle  cursor,
const char *  partName 
)

Append a record part to the end of the part list for the currently loaded record.

Parameters
cursorThe handle to a cursor object.
partNameThe name of the record part to be appended, or an empty string if the database has no part name field.
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbGetRecordInBase()
TdbGetRecordInSearch()
TdbSetRecordPart()
TdbSetCursor()
TdbPutRecord()

◆ TdbCheckCursor()

int TdbCheckCursor ( TdbHandle  cursor,
TdbHandle *  recordControl,
int *  field,
int *  paragraph,
int *  item 
)

Check the domain of a cursor object.

Parameters
cursorCursor object identifier
recordControlPointer handle that receives the record control
fieldNumber of field addressed by cursor object
paragraphReceives the paragraph number
itemReceives the item (sentence or subfield) number
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
14658 Undefined cursor.
See also
TdbGetLine()
TdbSetCursor()

◆ TdbCheckData()

int TdbCheckData ( TdbHandle  recordControl,
int  field,
int  item,
char *  data,
int  length 
)

Validate data for a particular field prior to attempting a commit operation.

Parameters
recordControlRecord control object identifier.
fieldField number
itemSubfield number
dataData string to be validated
lengthNumber of data bytes
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbCheckDate()
TdbValidValues()

◆ TdbCheckExistence()

int TdbCheckExistence ( TdbHandle  recordControl,
int  field,
char *  data,
int  length 
)

Check for existence of indexed data in a PHRase field.

Parameters
recordControlRecord control identifier
fieldField number
dataData string
lengthNumber of data bytes
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbCheckData()
TdbSetBase()
TdbValidValues()

◆ TdbCheckField()

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.

Parameters
recordControlRecord control identifier
nameField name
numberField number
typeField type
flagsInteger (bit vector)
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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

Return Codes

 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}.
See also
TdbGetFieldSpec()
TdbSetBase()

◆ TdbCheckPartName()

int TdbCheckPartName ( TdbHandle  recordControl,
int *  partID,
char *  partName 
)

Retrieve the number or name of a record part.

Parameters
recordControlRecord control identifier
partIDNumber of part to check, receives number when check is done by name
partNameName of part to check, receives name when check is done by number
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbAppendRecordPart()
TdbDeleteRecordPart()
TdbInsertRecordPart()
TdbSetRecordPart()
TdbUndeleteRecordPart()

◆ TdbCheckRecordName()

int TdbCheckRecordName ( TdbHandle  recordControl,
int *  recordID,
char *  name 
)

Retrieve the record number of a record indicated by name.

Parameters
recordControlRecord control identifier
recordIDRecord identifier
nameName of the record
Returns
See the Return Codes table below.

Description

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.

Parameter Values

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.

Return Codes

 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}.
See also
TdbGetRecordInBase()
TdbSetBase()

◆ TdbCheckSymbol()

int TdbCheckSymbol ( int *  symClass,
char *  symbol,
int *  length 
)

Check a character string for conflict with a reserved word.

Parameters
symClassSymbol class
symbolCharacter string
lengthLength of symbol
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 Code Description Explanation
0 Symbol not found
1 Operation completed successfully The function completed its operations without error.
See also
TdbShellSymbol()

◆ TdbCreateRecordControl()

int TdbCreateRecordControl ( TdbHandle *  recordControl)

Create a record control object.

Parameters
recordControlRecord control identifier
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The recordControl parameter is passed a pointer to a TdbHandle variable that will receive a handle to the created record control object.

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbCheckRecordName()
TdbDeleteRecordControl()
TdbEraseRecordControl()
TdbGetRecordInBase()
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()
TdbPutRecord()
TdbSetBase()
TdbSetCursor()
TdbSetRecordPart()

◆ TdbCreateTimeStamp()

int TdbCreateTimeStamp ( unsigned int *  tstamp,
int  type 
)

Create a time stamp.

Parameters
tstampTime stamp
typeTime stamp style
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

This function always succeeds

◆ TdbCurrentItem()

int TdbCurrentItem ( char *  base,
TdbHandle *  recordControl,
int *  record,
int *  part,
int *  field,
int *  paragraph,
int *  item 
)

Retrieve information about the current context.

Parameters
baseName of database
recordControlRecord control identifier
recordSequence number of record in database
partPart number
fieldField number
paragraphParagraph number
itemItem number
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
3170 Unexpected error.

◆ TdbCursorInfo()

int TdbCursorInfo ( TdbHandle  cursor,
int  mode,
char *  stringValue,
int *  intValue 
)

Returns information about a cursor.

Parameters
cursorCursor from which to retrieve information
modeType of information to retrieve.
stringValueOutput parameter for information of string type.
intValueOutput parameter for information of integer type.
Returns
1 or other odd value on success, even value on error

Description

The TdbCurosrInfo() function provides a way to obtain various information about a TRIP cursor.

Parameter Values

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.

Since

This function was introduced in TRIP version 6.2-9.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
18466 Unrecognised option: {1}.
See also
TdbSetCursor()
TdbRecordInfo()

◆ TdbDeleteCursor()

int TdbDeleteCursor ( TdbHandle *  cursor)

Delete a cursor object.

Parameters
cursorCursor identifier
Returns
1 or other odd value on success, even value on error

Description

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().

Note
When processing large amounts of data, it is strongly recommended to reuse existing cursor objects rather than deleteing and recreating them. Reusing cursors will have a positive performance impact.

Parameter Values

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.

Return Codes

 Code Description Explanation
0 Invalid cursor
1 Operation completed successfully The function completed its operations without error.
See also
TdbSetCursor()
TdbSetRecordPart()

◆ TdbDeleteItem()

int TdbDeleteItem ( TdbHandle  cursor)

Delete a data item in a cursor domain.

Parameters
cursorRecord cursor
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The cursor parameter is passed a pointer to the handle containing the cursor to delete.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
130 Record control structure not created.
See also
TdbGetItem()
TdbInsertItem()
TdbReplaceItem()
TdbSetCursor()

◆ TdbDeleteRecordControl()

int TdbDeleteRecordControl ( TdbHandle *  recordControl)

Delete a record control.

Parameters
recordControlRecord control identifier
Returns
1 or other odd value on success, even value on error

Description

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.

Note
Care should be taken not to delete record control structures created as internal work spaces by the TRIP kernel, such as the record control used by the TdbCurrentItem() function.

Parameter Values

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.

Return Codes

This function always succeeds.

See also
TdbCreateRecordControl()
TdbEraseRecordControl()

◆ TdbDeleteRecordInBase()

int TdbDeleteRecordInBase ( TdbHandle  recordControl)

Delete a record from a database.

Parameters
recordControlRecord control
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The recordControl is passed a TdbHandle as a record control that is associated with the record to delete.

Return Codes

 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.
See also
TdbSetBase()
TdbGetRecordInBase()
TdbGetRecordInSearchRis()

◆ TdbDeleteRecordPart()

int TdbDeleteRecordPart ( TdbHandle  cursor,
int  mode 
)

Delete a record part.

Parameters
cursorCursor identifier
modeDeletion mode
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
130 Record control structure not created.
See also
TdbSetRecordPart()
TdbUndeleteRecordPart()
TdbSetCursor()

◆ TdbEndSummarization()

int TdbEndSummarization ( void *  handle)

Ends a summarization run.

Parameters
handleHandle to the summarizer
Returns
1 or other odd value on success, even value on error

Description

Closes a summarization run as opened by a call to TdbStartSummarization().

See also
TdbStartSummarization()
TdbAccumulateSummarization()
TdbGenerateSummary()

◆ TdbEraseRecordControl()

int TdbEraseRecordControl ( TdbHandle  recordControl)

Reinitialize a record control.

Parameters
recordControlRecord control
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbCreateRecordControl()
TdbDeleteRecordControl()

◆ TdbExportBlob()

int TdbExportBlob ( TdbHandle  cursor,
char *  filename 
)

Export a STring field to a file.

Parameters
cursorCursor identifier
filenameFilename
Returns
1 or other odd value on success, even value on error

Description

The function TdbExportBlob() writes the content of a STRING field to an external file.

Parameter Values

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.

Return Codes

 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.
See also
TdbSetCursor()
TdbImportBlob()
TdbGetBlobBlock()

◆ TdbGenerateSummary()

int TdbGenerateSummary ( void *  handle,
Char **  summary 
)

Generate a summary.

Parameters
handleHandle to the summarizer
summaryReceievs a null-terminated string containing a summary
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbStartSummarization()
TdbAccumulateSummarization()
TdbEndSummarization()

◆ TdbGetBlobBlock()

int TdbGetBlobBlock ( TdbHandle  cursor,
int  blockNr,
int  blockSize,
char *  block,
int *  blockLen 
)

Retrieve the content of a STRING field.

Parameters
cursorCursor pointing to a STRING field.
blockNrBlock number to retrieve. Increase by 1 for each time around until the entire blob has been transferred.
blockSizeThe size of the block to retrieve.
blockOutput parameter receiving the requested blob block.
blockLenNumber of bytes returned in the block output parameter.
Returns
1 or other odd value on success, even value on error

Description

The TdbGetBlobBlock() function is used to retrieve the contents of a STRING field.

Parameter Values

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.

Return Codes

 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.
See also
TdbGetBlobSize()
TdbSetCursor()

◆ TdbGetBlobSize()

int TdbGetBlobSize ( TdbHandle  cursor,
int *  blobSize 
)

Returns the size of the content of a STRING field.

Parameters
cursorCursor pointing to the STRING field to return size for.
blobSizeSize (byte count) of the field contents.
Returns
1 or other odd value on success, even value on error

Description

The TdbGetBlobSize() function is used to retrieve the size of STRING fields.

Parameter Values

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.

Return Codes

 Code Description Explanation
14658 Invalid cursor.
21634 field is not a BLOB field.
See also
TdbGetBlobBlock()
TdbSetCursor()

◆ TdbGetFieldInfo()

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.

Parameters
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
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbSetCursor()
TdbDeallocate()

◆ TdbGetHitPart()

int TdbGetHitPart ( TdbHandle  recordControl,
int  seqNumber,
int *  partNumber 
)

Return Hit Part details.

Parameters
recordControlRecord control
seqNumber1-based sequence number of hit part
partNumberPart number
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Since

This function was introduced in TRIP version 3.3-1.

Return Codes

 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.
See also
TdbGetRecordInSearchRis()
TdbSetRecordPart()

◆ TdbGetItem()

int TdbGetItem ( TdbHandle  cursor,
char *  data_item,
int *  item_length 
)

Load a data item into a buffer.

Parameters
cursorCursor identifier
data_itemData item string
item_lengthLength of data item
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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
See also
TdbSetCursor()

◆ TdbGetLine()

int TdbGetLine ( TdbHandle  cursor,
char *  line,
int *  line_length,
int  maximum_length 
)

Load a text line into a buffer.

Parameters
cursorRecord cursor
lineReturned text line
line_lengthLength of string transferred
maximum_lengthMaximum number of bytes to be transferred
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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
See also
TdbSetCursor()

◆ TdbGetLinkBase()

int TdbGetLinkBase ( char *  base,
char *  recordNameField 
)

Load the design of a link database.

Parameters
baseName of link database
recordNameFieldName of record name field
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.

◆ TdbGetLinkRecord()

int TdbGetLinkRecord ( TdbHandle  recordControl,
char *  record_name,
int  length 
)

Load a record from a link database during data entry.

Parameters
recordControlRecord control identifier
record_nameName of record
lengthLength of record name
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbSetLinkBase()

◆ TdbGetNextHitWord()

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.

Parameters
recordControlRecord control identifier
partNumber of part containing next hit word
fieldNumber of field containing next hit word.
paragraphNumber of paragraph containing next hit word
itemNumber of subfield or sentence containing next hit word.
word_positionStart position of next hit word within item
lengthLength of word.
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 Code Description Explanation
0 Operation failed There are no more hit words
1 Operation completed successfully The function completed its operations without error.
See also
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()

◆ TdbGetNextItem()

int TdbGetNextItem ( TdbHandle  cursor,
char *  data_item,
int *  length 
)

Load the next data item into a buffer.

Parameters
cursorCursor identifier
data_itemReturned data item
lengthLength of string transferred
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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
See also
TdbSetCursor()

◆ TdbGetRecord()

int TdbGetRecord ( TdbHandle  recordControl,
int  mode,
int  search,
int64_t  ordinal 
)

Get a record from a search set or a database.

Parameters
recordControlRecord control to receive the loaded record
modeRetrieval mode; one of the RECORD_FROM_* constant values
searchNumber of the search if mode indicates search set retrieval
ordinalOrdinal number of record in search result or the record number in the database
Returns
1 or other odd value on success, even value on error

Description

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.

Note
This function replaces the functions TdbGetRecordInSearch(), TdbGetRecordInSearchRis(), TdbGetRecordInBase() and TdbGetSortedRecord(), providing all their functionality in single interface, plus allows for extremely large search sets with RIS numbers over 2bn.

Retriving additional information on a record, such as record ID or the database it belongs to, requires use of the TdbRecordInfo() function.

Parameter Values

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.

Return Codes

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().

See also
TdbCreateRecordControl()
TdbGetSortedRecord()

◆ TdbGetRecordBuffer()

int TdbGetRecordBuffer ( TdbHandle  cursor,
char *  buffer_address,
int  buffer_length,
int  part_number,
int *  filled_length 
)

Gets the content of a buffer.

Parameters
cursorCursor identifier
buffer_addressAddress of buffer
buffer_lengthSize of the buffer in number of bytes
part_numberPart record number
filled_lengthNumber of bytes written to buffer
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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
See also
TdbSetCursor()
TdbPutRecordBuffer()

◆ TdbGetRecordInBase()

int TdbGetRecordInBase ( TdbHandle  recordControl,
int  RID 
)

Load a record from a database.

Parameters
recordControlRecord control
RIDRecord number in database
Returns
1 or other odd value on success, even value on error

Description

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.

Note
The records will be retrieved in the order that they were loaded into the database. However, if records have been deleted from the database then the RID numbers will not be consecutive.

Parameter Values

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.

Return Codes

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().

See also
TdbCreateRecordControl()
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()
TdbSetBase()

◆ TdbGetRecordInSearch()

int TdbGetRecordInSearch ( TdbHandle  recordControl,
int *  search,
int *  RID,
char *  base 
)

Load a record from a search result.

Parameters
recordControlRecord control identifier
searchSearch number
RIDRecord number in TRIP database
baseDatabase name.
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

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().

See also
TdbCreateRecordControl()
TdbGetRecord()

◆ TdbGetRecordInSearchRis()

int TdbGetRecordInSearchRis ( TdbHandle  recordControl,
int *  search,
int  RIS,
int *  RID,
char *  base 
)

Load a record from a search result, specified by RIS.

Parameters
recordControlTRIP record control.
searchSearch number
RISOrdinal number of record in search result
RIDTRIP record identifier
baseDatabase name
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

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().

See also
TdbCreateRecordControl()
TdbGetSortedRecord()
TdbGetRecord

◆ TdbGetRecordInThes()

int TdbGetRecordInThes ( TdbHandle  recordControl,
int  termNumber,
int *  level 
)

Load a record from a thesaurus.

Parameters
recordControlRecord control
termNumberOrdinal term number in display list
levelHierarchical level of record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbCreateRecordControl()
TdbGetDisplayTerm()

◆ TdbGetSortedRecord()

int TdbGetSortedRecord ( int  search_no,
TdbHandle  rec_ctl,
int  ris,
int *  rid,
char *  base 
)

Loads a record from a sorted search result.

Parameters
search_noSearch number
rec_ctlTRIP record control
risOrdinal number of record in the sorted search result
ridTRIP record identifier
baseDatabase name
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

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().

See also
TdbCreateRecordControl()
TdbSortRecords()

◆ TdbGetTimeStamp()

int TdbGetTimeStamp ( TdbHandle  recordControl,
unsigned int *  timestamp,
int  type 
)

Retrieve the TRIP time stamp of a record.

Parameters
recordControlRecord control identifier
timestampTime stamp value
typeTime stamp format
Returns
1 or other odd value on success, even value on error

Description

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() .

Parameter Values

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

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbGetRecordInBase()
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()

◆ TdbHitParts()

int TdbHitParts ( TdbHandle  recordControl,
int *  parthits,
int *  partcount,
int *  partmax 
)

Retrieve information about part records in a search.

Parameters
recordControlTRIP record control identifier
parthitsCount of hits within parts
partcountCount of parts
partmaxmaximum part number
Returns
1 or other odd value on success, even value on error

Description

The function TdbHitParts() returns the following information about part records of a record retrieved from a search set using TdbGetRecord() or similar function.

Parameter Values

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.

Since

This function was introduced in TRIP version 3.3-1.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
130 Record control structure not created.
See also
TdbGetRecord()

◆ TdbImportBlob()

int TdbImportBlob ( TdbHandle  cursor,
const char *  filename 
)

Import a binary large object from a file.

Parameters
cursorCursor identifier
filenameFilename to import
Returns
1 or other odd value on success, even value on error

Description

The function TdbImportBlob() loads an object from the server-side file specified via the filename parameter into the field referenced by the cursor parameter.

Parameter Values

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.

Return Codes

 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.
See also
TdbExportBlob()
TdbPutBlobBlock()

◆ TdbInsertItem()

int TdbInsertItem ( TdbHandle  cursor,
char *  data_item,
int  item_length 
)

Load a data item from a buffer into a record control area.

Parameters
cursorCursor identifier
data_itemData item string to copied to record
item_lengthNumber of bytes to transfer
Returns
1 or other odd value on success, even value on error

Description

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().

Parameter Values

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.

Return Codes

 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.
See also
TdbSetCursor()

◆ TdbInsertRecordPart()

int TdbInsertRecordPart ( TdbHandle  cursor,
const char *  partname 
)

Insert a record part.

Parameters
cursorCursor identifier
partnameName of record part to insert
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbSetRecordPart()
TdbPutRecord()

◆ TdbItemCount()

int TdbItemCount ( TdbHandle  cursor,
int *  count 
)

Retrieve the number of items in a field.

Parameters
cursorCursor identifier
countCount of items in domain
Returns
1 or other odd value on success, even value on error

Description

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 number of subfields for all non-TEXT fields
  • The number of sentences within a paragraph
  • The number of sentences within a field

Parameter Values

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.

Return Codes

 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.
See also
TdbSetCursor()

◆ TdbLockRecord()

int TdbLockRecord ( TdbHandle  recordControl)

Lock the record in the record control area.

Parameters
recordControlRecord control identifier
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The recordControl is passed a TdbHandle as the record control identifier associated with the record to be locked into memory.

Return Codes

 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.
See also
TdbDeleteRecordControl()
TdbEraseRecordControl()
TdbGetRecordInBase()
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()
TdbGetRecord()
TdbPutRecord()
TdbReleaseRecord()
TdbSetBase()

◆ TdbNextControl()

int TdbNextControl ( TdbHandle *  recordControl)

Load a CONTROL file record.

Parameters
recordControlRecord control identifier
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The recordControl parameter is passed a pointer to TdbHandle variable that will receive a handle to a record control associated with the CONTROL database.

Privileges Required

The current TRIPsystem user needs no special privileges to execute this function.

Return Codes

 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.
See also
TdbShowControl()

◆ TdbParaCount()

int TdbParaCount ( TdbHandle  cursor,
int *  count 
)

Returns the number of paragraphs within a field.

Parameters
cursorCursor identifier
countParagraph count
Returns
1 or other odd value on success, even value on error

Description

Returns the number of paragraphs within a field specified by the cursor position.

Parameter Values

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.

Return Codes

 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.
See also
TdbSetCursor()

◆ TdbPartCount()

int TdbPartCount ( TdbHandle  cursor,
int *  count 
)

Returns the number of part records within a record.

Parameters
cursorCursor identifier
countParagraph count
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
14658 Undefined cursor.
See also
TdbGetRecord()
TdbGetRecordInBase()
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()
TdbSetCursor()

◆ TdbPutBlobBlock()

int TdbPutBlobBlock ( TdbHandle  cursor,
int  blockLen,
char *  block 
)

Write data to a STRING field.

Parameters
cursorCursor pointing to a STRING field.
blockBuffer with data to write.
blockLenNumber of bytes in the block to write.
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbGetBlobSize()
TdbGetBlobBlock()
TdbSetCursor()

◆ TdbPutFieldInfo()

int TdbPutFieldInfo ( TdbHandle  cursor,
int  buf_len,
char *  rec_buf 
)

Assign a value to a TEXT field.

Parameters
cursorCursor set to a text field
buf_lenLength of the value in rec_buf
rec_bufValue to store
Returns
1 or other odd value on success, even value on error

◆ TdbPutLine()

int TdbPutLine ( TdbHandle  cursor,
char *  line,
int  line_length 
)

Load a text line from a buffer into a record control area.

Parameters
cursorCursor identifier
lineText line to write
line_lengthNumber of bytes to transfer
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbPutRecord()
TdbSetCursor()

◆ TdbPutRecord()

int TdbPutRecord ( TdbHandle  recordControl,
int *  recordId 
)

Write a record into a database.

Parameters
recordControlRecord control identifier
recordIdRecord number
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbCreateRecordControl()
TdbGetRecord()

◆ TdbPutRecordBuffer()

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.

Parameters
cursorcursor identifier
buffer_addressBuffer address
buffer_lenLength of buffer
err_partnrNumber of first part record with error
err_fieldnrNumber of first field with error
err_itemnrNumber of first item with error
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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
See also
TdbPutRecord()
TdbSetCursor()

◆ TdbRecordInfo()

int TdbRecordInfo ( TdbHandle  recordControl,
int  mode,
char *  stringValue,
int *  intValue 
)

Returns information about a record.

Parameters
recordControlRecord control for record to get information about.
modeType of information to retrieve.
stringValueOutput parameter for information of string type.
intValueOutput parameter for information of integer type.
Returns
1 or other odd value on success, even value on error

Description

The TdbRecordInfo() function provides a way to obtain various information about a TRIP database record.

Parameter Values

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.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

 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}.
See also
TdbCreateRecordControl()
TdbGetRecord()
TdbGetRecordInSearchRis()
TdbGetRecordInBase()

◆ TdbReleaseRecord()

int TdbReleaseRecord ( TdbHandle  recordControl)

Release a lock on a record.

Parameters
recordControlRecord control identifier
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The recordControl parameter is passed a handle to a record control.

Return Codes

 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.
See also
TdbLockRecord()
TdbGetRecord()
TdbGetRecordInBase()
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()
TdbSetBase()

◆ TdbRenameRecordPart()

int TdbRenameRecordPart ( TdbHandle  cursor,
const char *  part_name 
)

Rename a record part.

Parameters
cursorCursor identifier
part_nameName of record part
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbPutRecord()
TdbSetRecordPart()

◆ TdbReplaceItem()

int TdbReplaceItem ( TdbHandle  cursor,
char *  data_item,
int  item_length 
)

Replace a data item in a record control area.

Parameters
cursorCursor identifier
data_itemData item to replace existing data
item_lengthNumber of bytes in data item buffer
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbPutRecord()
TdbSetCursor()

◆ TdbSetBase()

int TdbSetBase ( TdbHandle  recordControl,
char *  base,
int  access_mode 
)

Set the access mode for a database.

Parameters
recordControlRecord control identifier
baseDatabase name
access_modeAccess mode for database
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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

Return Codes

 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}.
See also
TdbGetRecord()
TdbGetRecordInBase()
TdbGetRecordInSearch()
TdbGetRecordInSearchRis()
TdbPutRecord()

◆ TdbSetCursor()

int TdbSetCursor ( TdbHandle *  cursor,
TdbHandle  recordControl,
int  field,
int  paragraph,
int  item 
)

Set a cursor domain.

Parameters
cursorCursor identifier
recordControlRecord control identifier
fieldField number
paragraphParagraph number
itemItem number
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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}
See also
TdbCreateRecordControl()
TdbDeleteCursor()

◆ TdbSetLinkBase()

int TdbSetLinkBase ( TdbHandle  recordControl,
char *  base_name,
TdbHandle *  base_id 
)

Make a database accessible for data entry linkage.

Parameters
recordControlRecord control
base_nameName of linked database
base_idTRIP internal identification number for database.
Returns
1 or other odd value on success, even value on error

Description

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() .

Parameter Values

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.

Return Codes

 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
See also
TdbGetLinkRecord()
TdbGetLinkBase()
TdbSetCursor()
TdbGetLine()

◆ TdbSetRecordPart()

int TdbSetRecordPart ( TdbHandle *  cursor,
TdbHandle  recordControl,
int  part_number 
)

Specify the record part.

Parameters
cursorCursor identifier
recordControlRecord control identifier
part_numberPart number
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbSetCursor()

◆ TdbShowControl()

int TdbShowControl ( int  mode,
int  all_flag,
char *  name1,
char *  name2 
)

Initialize reading of CONTROL records.

Parameters
modeOperation mode
all_flagAll flag
name1Name string
name2Name string
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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
See also
TdbNextControl()
TdbStartControl()

◆ TdbSortRecords()

int TdbSortRecords ( int  searchNumber,
char *  sortSpecification 
)

Sort an existing search set.

Parameters
searchNumberThe number of the search set to sort.
sortSpecificationThis is the SORT specification.
Returns
1 or other odd value on success, even value on error

Description

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 .

Parameters

The sortSpecification parameter specifiess only the part that is to the right of the '=' sign in the CCL "SHOW SORT=" statement.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

 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.
See also
TdbGetRecord()

◆ TdbSortRecordsEx()

int TdbSortRecordsEx ( int  searchNumber,
const char *  sortSpecification,
int  mode 
)

Sort an existing search set with clusters and/or record parts.

Parameters
searchNumberThe number of the search to sort.
sortSpecificationThis is the SORT specification.
modeSearch mode bitmask
Returns
1 or other odd value on success, even value on error

Description

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 .

Parameters

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.

Since

This function was introduced in TRIP version 8.1-1:3

Return Codes

 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.
See also
TdbGetRecord()

◆ TdbSortTerms()

int TdbSortTerms ( int  termSetNumber,
int  sortFlags 
)

Sorts a display order or term set.

Parameters
termSetNumberThe number of the term set to sort, or 0 (zero) to sort the latest regular term list.
sortFlagsSort specification bit mask
Returns
1 or other odd value on success, even value on error

Description

The TdbSortTerms() function is used to apply a new sort order to the latest executed DISPLAY order or registered term set.

Parameter Values

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

Return Values

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
See also
TdbCreateTermSet()
TdbExecuteCcl()

◆ TdbStartControl()

int TdbStartControl ( char *  name)

Set the initial value for reading CONTROL records.

Parameters
nameName of first CONTROL record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The name parameter is passed a character string as the name of the first CONTROL record to show.

Return Codes

 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.
See also
TdbNextControl()
TdbShowControl()

◆ TdbStartSummarization()

int TdbStartSummarization ( void **  handle,
int  engine_id 
)

Initialize the text summarization engine.

Parameters
handleReceives a handle to the summarizer as a void pointer
engine_idID of the summarization engine to use. Reseverd for future use. Always pass 1 as value.
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbAccumulateSummarization()
TdbGenerateSummary()
TdbEndSummarization()

◆ TdbUndeleteRecordPart()

int TdbUndeleteRecordPart ( TdbHandle  cursor)

Undelete the previously deleted record part.

Parameters
cursorCursor identifier
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.
See also
TdbDeleteRecordPart()

◆ TdbValidValues()

int TdbValidValues ( int  field_number,
TdbHandle  base_id,
char *  term 
)

Produce term lists in combination with link databases.

Parameters
field_numberNumber of field(s) to check
base_idLink database id
termTerm to display
Returns
1 or other odd value on success, even value on error

Description

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.

Note
Make sure to use a negative term number for all calls to TdbGetDisplayTerm() in order to get the terms in its original form.

Parameter Values

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.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
194 No terms!
578 No index found for {1}.
See also
TdbSetLinkBase()
TdbGetLinkRecord()
TdbGetDisplayTerm()