TRIPsystem Kernel API 8.3
|
Query related operations. More...
Functions | |
int | TdbCurrentBase (char *base) |
Retrieve the name of the currently open database. | |
Indexing and batch Jobs | |
Functions for the execution of database indexing and other bactch-oriented jobs. | |
int | TdbBatchLoadIndex (int mode, const char *base, const char *tformFile) |
Submit a batch job to load data into a database or index a database. | |
int | TdbIndex (const char *base, int recordNumber) |
Index a specified record in a database. | |
CCL Execution | |
Functions for the execution of CCL commands | |
int | TdbCheckCcl (char *cclorder, int *status) |
Performs syntax analysis of a CCL order. | |
int | TdbExecuteCcl (char *cclorder, int *status) |
Execute a CCL order. | |
int | TdbDidYouMean (char *buffer, int *length) |
Retrieve an alternate search expression that may yield better results. | |
int | TdbGetParsedCcl (int mode, char **parsed_order, int *length) |
Get parsed version of the latest executed CCL order. | |
Search Sets | |
Functions for the manipulation of search results | |
int | TdbCheckSearch (int *search) |
Check that a search with the given number exists. | |
int | TdbSearchInfo (int search_number, int mode, int64_t *integer_value, char *string_buffer, size_t string_buffer_size) |
Retrieve information about a search set. | |
Term Lists, Sets and Trees | |
Functions for the manipulation of DISPLAY order results | |
int | TdbCreateTermSet (int *termsetId) |
Create a term set based on the most recent DISPLAY result. | |
int | TdbDeleteTermSet (int termsetId) |
Deletes a term set. | |
int | TdbCreateBaselineTermSet (int *termsetId, const char *shin, int mode) |
int | TdbUpdateTermSet (int termsetId, const char *shin, int mode) |
int | TdbTermSetCount (int termsetId, int64_t *recordCount, int64_t *updateCount) |
int | TdbGetDisplay (int *termCount, int *termType) |
Retrieve information about the current display list. | |
int | TdbGetDisplayTerm (int termNumber, char *term, int *termLength, int *recordCount) |
Retrieve a term from the current display list. | |
int | TdbGetDisplayTermEx (int termNumber, char *term, int *termLength, int64_t *recordCount) |
Retrieve a term from the current display list. | |
int | TdbGetTermSetTerm (int termsetId, int termNumber, char *termValue, int *length, int *recordCount) |
Retrieves a term from a term set. | |
int | TdbGetTermSetTermEx (int termsetId, int termNumber, char *termValue, int *length, int64_t *recordCount, int64_t *updateCount) |
Retrieves a term from a term set. | |
Query related operations.
This group of functions cover execution of CCL commands, term list operations and querying status on conducted searches.
int TdbBatchLoadIndex | ( | int | mode, |
const char * | base, | ||
const char * | tformFile | ||
) |
Submit a batch job to load data into a database or index a database.
mode | Type of operation to be performed. |
base | Name of database. |
tformFile | Name of TForm file. |
The TdbBatchLoadIndex() function can load data from a file, index a database, or both. To load data (which must be in TForm format), set the mode argument to LOAD and specify both a database name and a filename. To index a database, set the mode argument to INDEX and specify just the database name. To perform both operations, set the mode argument to LOADIX and specify both the database name and the filename.
The name of the file in this setting can be the full RMS file specification, including any logical names which will be recognised by the batch process.
The mode
parameter is passed an integer value to select the type of operation to be performed on the database. Valid values are:
Symbolic Constant | Constant Value | Purpose |
---|---|---|
LOADIX | 1 | Load the TForm file and then index the database |
INDEX | 2 | Index the database |
LOAD | 3 | Load the TForm file |
The base
parameter is passed a character string containing the name of the database to be modified.
The tformFile
parameter is passed a character string containing the name of the TFORM file which is to be loaded into the database. The file must reside on the TRIP server machine.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
514 | TFORM input file not found. | The TFORM file passed to the function cannot be found. |
9314 | Subprocess quota reached, try later (OS status: 2). | If the process quota for maximum number of subprocesses is reached during a call to this function the TRIPkernel will return this error. The error message text will include the status code from the underlying operating system. |
15010 | 1 is a database cluster. | The database name passed to the function refers to a database cluster and not a single database. |
16610 | Cannot submit job (OS status: 2). | An operating system error has prevented the batch job from being submitted. The error message text will include the operating system specific status code. |
17762 | TFORM file not specified. |
int TdbCheckCcl | ( | char * | cclorder, |
int * | status | ||
) |
Performs syntax analysis of a CCL order.
cclorder | CCL order string |
status | CCL order identifier |
Checks the syntax of a CCL order. The status argument returns the command number as listed in the include file tripbase.h or tdbdef.h (macro constants in the form CMD_xxx, e.g "CMD_FIND").
The cclorder
parameter is passed a character string as the CCL order to parse.
The status
parameter receives the command number corresponding to the CCL command contained in cclorder
as listed in the include file tripapi_defs.h. See TdbExecuteCcl() for a list of the command numbers.
The return codes from this function depends on the nature of the CCL command given. Since most of TRIP operations can be executed via CCL, this function may return almost any return code.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbCheckSearch | ( | int * | search | ) |
Check that a search with the given number exists.
search | Search number |
The TdbCheckSearch() verifies that the given search exists, when identified by number. For instance, to verify that S=5 is in the calling process' history, use 5 as the search number.
If a search number of zero is passed via the search
parameter then upon return from the function this parameter will contain the number of the latest search.
The search
parameter is passed the number of the search whose existence is to be verified.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | The specified search set does not exist. |
int TdbCreateBaselineTermSet | ( | int * | termsetId, |
const char * | shin, | ||
int | mode | ||
) |
Create a termset with a baseline-oriented term list.
termsetId | Receives the number of the created termset on success. |
shin | A term list CCL order without the DISPLAY command and sort options. |
mode | Sorting mode (TERM_SORT_FREQ or TERM_SORT_TEXT, optionally with TERM_SORT_BL_ATEND added to the bitmask). |
A baseline termset is a termset that can be further refined without losing any terms. Updates to a baseline termset is done using the TdbUpdateTermSet() function. Any term not present in the update will be retained, but with an update count of zero. The original count will also be availanble. Use the TdbTermSetCount() function to obtain the current record counts for the termset, and TdbGetTermSetTermEx() to get the baseline and update counts for individual terms.
The mode
parameter is a bitmask used to indicate the sorting of the baseline termset. Sorting can either be by term frequency (TERM_SORT_FREQ) or alphabetically (TERM_SORT_TEXT). Adding the TERM_SORT_BL_ATEND value to the bitmask indicates that terms that after update have a count of zero should be sorted at the end.
int TdbCreateTermSet | ( | int * | termsetId | ) |
Create a term set based on the most recent DISPLAY result.
termsetId | Output parameter that receives the identity of the created term set upon success. |
Create a term set based on the most recent DISPLAY result.
A term set is a display list generated by a DISPLAY order but possible to use also after a new DISPLAY-order has been executed.
The termsetId
parameter receive the term set number, by which the term set is identified to the TdbGetTermSetTerm() and TdbDeleteTermSet() functions.
This function was introduced in TRIP version 7.0-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | No term list is available. |
int TdbCurrentBase | ( | char * | base | ) |
Retrieve the name of the currently open database.
base | Name of database or of (predefined) database cluster |
The function TdbCurrentBase() returns the name of the most recently opened database, cluster or multi-base view. It does not provide any information about which databases make up either a cluster or a multi-file view, To obtain such information call TdbGetClusterDesign() for a database cluster or TdbSearchInfo() for a multi-file view.
The base
parameter is passed a character string to receive the name of the database or the database cluster that is currently open. The character buffer must be at least 65 bytes in length so that it can accommodate a database/cluster name of maximum size.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | There is no database currently open. |
int TdbDeleteTermSet | ( | int | termsetId | ) |
Deletes a term set.
termsetId | The identity of the created term set to delete |
Deletes a term set created using the TdbCreateTermSet() function.
The termsetId
parameter is the term set number as returned by the TdbCreateTermSet() function.
This function was introduced in TRIP version 7.0-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Term set does not exist. |
int TdbDidYouMean | ( | char * | buffer, |
int * | length | ||
) |
Retrieve an alternate search expression that may yield better results.
buffer | Receives a alternate CCL expression on success |
length | [OUT] Receives the length of the data in buffer on success |
After performing a search using the FUZZ
command, it is possible that there may be an alternate search expression that can yield better results. To find out, call the TdbDidYouMean() function. If it succeeds, the buffer
parameter will contain a new search expression that can be passed as input to TdbExecuteCcl().
This function was introduced in TRIP version 6.2-1
int TdbExecuteCcl | ( | char * | cclorder, |
int * | status | ||
) |
Execute a CCL order.
cclorder | CCL command string |
status | CCL order identifier |
The status
parameter receive the command number as listed in the include files tripbase.h (server version) and tdbdef.h (client version). See the list below for command numbers:
Number | Symbol |
---|---|
0 | CMD_ERROR |
1 | CMD_CUT |
2 | CMD_SELECT |
3 | CMD_FIND |
4 | CMD_SHOW |
5 | CMD_MORE |
6 | CMD_BASE |
7 | CMD_CALL |
8 | CMD_DISPLAY |
9 | CMD_IMPORT |
10 | CMD_EXPORT |
11 | CMD_MACRO |
12 | CMD_STOP |
13 | CMD_DEFINE |
14 | CMD_LIST |
15 | CMD_NEXT |
15 | CMD_PREV |
16 | CMD_HELP |
17 | CMD_EXPAND |
18 | CMD_PRINT |
19 | CMD_RUN |
20 | CMD_SAVE |
21 | CMD_DELETE |
22 | CMD_TRACE |
23 | CMD_CONTINUE |
24 | CMD_STATUS |
25 | CMD_PRINT_LOCAL |
26 | CMD_EDIT |
27 | CMD_INSERT |
28 | CMD_UPDATE |
29 | CMD_BACK |
30 | CMD_TOP |
31 | CMD_MEASURE |
32 | CMD_FREQ |
33 | CMD_INDEX |
34 | CMD_CONT_EDIT |
35 | CMD_CLOSE |
36 | CMD_HIDE |
37 | CMD_REVEAL |
38 | CMD_CONT_SHOW |
39 | CMD_FUZZ |
40 | CMD_SFORM |
41 | CMD_LEAVE |
42 | CMD_LOAD |
43 | CMD_RENUM |
44 | CMD_FIND_SAVE |
45 | CMD_DELETE_SEARCH |
This function was introduced in TRIP version 3.4-0.
The return codes from this function depends on the nature of the CCL command given. Since most of TRIP operations can be executed via CCL, this function may return almost any return code.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbGetDisplay | ( | int * | termCount, |
int * | termType | ||
) |
Retrieve information about the current display list.
termCount | Number of (main) terms retrieved |
termType | Type of CCL display command. |
The function TdbGetDisplay() obtains information about the results of the most recent CCL Display order. It should be called immediately after a call to the function TdbExecuteCcl() which returns a DAO_DISPLAY
status code, indicating that a Display command has been executed.
The terms in the display list may be obtained by calling the TdbGetDisplayTerm() .
The termCount
parameter recieves tbe number of terms retrieved by the previous CCL display command. For a thesaurus display, it is the number of main terms only.
The termType
parameter receives a code for the type of CCL display command actually executed. Valid values returned are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
DISPLAY_NORMAL | 1 | A standard CCL display order was executed. |
DISPLAY_THES | 2 | A thesaurus specific CCL display order was executed. |
DISPLAY_INDIRECT | 3 | An indirect CCL display command was executed. |
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbGetDisplayTerm | ( | int | termNumber, |
char * | term, | ||
int * | termLength, | ||
int * | recordCount | ||
) |
Retrieve a term from the current display list.
termNumber | Ordinal number of term in list, starting with 1 |
term | Term string |
termLength | Length of term |
recordCount | Number of record occurrences. |
The function TdbGetDisplayTerm() is used to obtain a term and information about it from the current display list. A display list is generated by the CCL Display command.
If the current display list is a thesaurus display list the function TdbGetRecordInThes() must be called before TdbGetDisplayTerm() .
The termNumber
parameter is passed the 1-based ordinal number of the term to be extracted from the term list .
The term
parameter receives the term to be returned.
The termLength
parameter receives the length of the term extracted.
The recordCount
parameter receives the count of the number of records in which the term occurs. If the record count for a term exceeds 2147483647 (2^31 - 1), this function will retrun 2147483647 as the count. To get the correct count for such terms, use the TdbGetDisplayTermEx() function instead.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Display term could not be retrieved. |
int TdbGetDisplayTermEx | ( | int | termNumber, |
char * | term, | ||
int * | termLength, | ||
int64_t * | recordCount | ||
) |
Retrieve a term from the current display list.
termNumber | Ordinal number of term in list, starting with 1 |
term | Term string, receives the term to be returned. |
termLength | Receives the length of the term extracted |
recordCount | Receives the count of the number of records in which the term occurs. |
This function is used to obtain a term and information about it from the current display list. It differs from the TdbGetDisplayTerm() function in that this function is able to return a term record count larger than 2147483647 (2^31 - 1). A display list is generated by the CCL Display command.
If the current display list is a thesaurus display list the function TdbGetRecordInThes() must be called before TdbGetDisplayTermEx() .
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Display term could not be retrieved. |
int TdbGetParsedCcl | ( | int | mode, |
char ** | parsed_order, | ||
int * | length | ||
) |
Get parsed version of the latest executed CCL order.
mode | Pass 1 to retrieve a normalized version of the original CCL order. Pass 0 (zero) to retrieve the order in DAO format. |
parsed_order | String buffer that receives the latest CCL order in parsed form. |
length | Receives the length of the value returned in the parsed_order parameter. |
Returns, depending on mode
, the parsed CCL or DAO form of a previously entered CCL order.
This function was introduced in TRIP version 3.4-0.
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbGetTermSetTerm | ( | int | termsetId, |
int | termNumber, | ||
char * | termValue, | ||
int * | length, | ||
int * | recordCount | ||
) |
Retrieves a term from a term set.
termsetId | The identity of the created term set from which to retrieve a term |
termNumber | Ordinal number of the term to retrieve from the term set |
termValue | Buffer at least 256 bytes long to receive the term value |
length | Size of 'termValue' buffer in input, and length of the term returned in 'ternValue' on output. |
recordCount | Number of record occurrences for the term. |
The function TdbGetTermSet() is used to obtain a term and information about it from a term set. A term set is generated by declaring a term list generated by the CCL Display command as a term set using the TdbCreateTermSet() function.
The termsetId
parameter is the term set number as returned by the TdbCreateTermSet() function.
The termNumber
parameter is passed the ordinal number of the term to be extracted from the term set.
The termValue
parameter receives the term to be returned.
The length
parameter is assigned the size of the 'termValue' buffer and on return receives the count of the number of bytes returned in it.
The recordCount
parameter receives the count of the number of records in which the term occurs. If the record count for a term exceeds 2147483648 (2^31), this function will return 2147483648 as the count. To get the correct count for such terms, use the TdbGetTermSetTermEx() function instead.
This function was introduced in TRIP version 7.0-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Term could not be retrieved. |
int TdbGetTermSetTermEx | ( | int | termsetId, |
int | termNumber, | ||
char * | termValue, | ||
int * | length, | ||
int64_t * | recordCount, | ||
int64_t * | updateCount | ||
) |
Retrieves a term from a term set.
termsetId | The identity of the created term set from which to retrieve a term |
termNumber | Ordinal number of the term to retrieve from the term set |
termValue | Buffer at least 256 bytes long to receive the term value |
length | Size of 'termValue' buffer in input, and length of the term returned in 'ternValue' on output. |
recordCount | Number of record occurrences for the term. |
updateCount | Number of record occurrences for the term after TdbUpdateTermSet() |
This function is used to obtain a term and information about it from a term set. A term set is generated by declaring a term list generated by the CCL Display command as a term set using the TdbCreateTermSet() function or the TdbCreateBaselineTermSet() function.
The termsetId
parameter is the term set number as returned by the TdbCreateTermSet() function.
The termNumber
parameter is passed the ordinal number of the term to be extracted from the term set.
The termValue
parameter receives the term to be returned.
The length
parameter is assigned the size of the 'termValue' buffer and on return receives the count of the number of bytes returned in it.
The recordCount
parameter receives the count of the number of records in which the term occurs. If the term set is created using the TdbCreateBaselineTermSet() function, the record count returned here is always the baseline count.
The updateCount
parameter receives the count of the number of records in which the term occurs. It is primarily used with term sets that have been created using the TdbCreateBaselineTermSet(). The value returned in this parameter is in such cases the count for the term after the most recent call to TdbUpdateTermSet().
This function was introduced in TRIP version 8.0-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Term could not be retrieved. |
int TdbIndex | ( | const char * | base, |
int | recordNumber | ||
) |
Index a specified record in a database.
base | The name of the database that contains the record to index. |
recordNumber | Record id of record to index, or INDEX_ALL to index all new and modified records |
The TdbIndex() function is used to index a single specified record in a database in a synchronous fashion. Alternatively, pass SYNCH_INDEX_ALL recordNumber
instead of a record number to index all new and modified records in the database, or SYNCH_REINDEX_ALL to reindex the entire database synchronously.
This function was introduced in TRIP version 3.4-0, but requires version 7.0-0 or later for it to work correctly.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
3106 | Old version of BIF/VIF files. | The index files have been created by an older version of TRIP. The database will have to be reindexed. |
11362 | Max 250 databases can be opened during a TRIP session.. | Too many databases are open. Close a few and try again. |
2530 | No access to database name. | The logged on user does not have any access to the database. |
9538 | No write access to the database name. | The logged on user does not have write access to the database. |
15010 | Name is a database cluster. | A database cluster cannot be indexed. |
962 | File name error, check logical names for database. | The BAF/BIF/VIF file names are not valid. |
0000 | Database name is OS read protected. | File system protection for the database files prohibits read access. |
22594 | The type file is not found or not available. | The specified file for the database could not be located. |
22626 | No disk write access to the type file. | The BAF, BIF or VID file for the database is write protected. |
22434 | The type file is currently locked by another user. | Another user is locking the database or its index. Try again later. |
22690 | The database name is empty. | There is no data in the database. |
17218 | The BAF file of database is no BAF file. | The file specified as the BAF file for the database in the database definition could not be recognized as a BAF file. |
22722 | Old version of the type file, reindex database. | The database BAF, BIF or VIF file is of an older version. Reindexing is required. |
15202 | The BAF file of database needs reorganization (See PACKIT). | Run PACKIT on the TRIPsystem server machine to correct this problem. |
22498 | No disk write access to directory for the type file. | The directory in which the database file of the stated type is specified to be located cannot be written to. Check file system protection for the directory. |
22562 | Cannot create the type file. | The specified file could not be created. |
22754 | The DB indices are being updated. | |
22786 | Invalid rescan, database contains unindexed records. | |
22530 | Not enough disk space for the type file. | Out of disk space! |
17858 | Chinese vocabulary files not found. | |
22818 | Not enough memory for indexing. |
int TdbSearchInfo | ( | int | search_number, |
int | mode, | ||
int64_t * | integer_value, | ||
char * | string_buffer, | ||
size_t | string_buffer_size | ||
) |
Retrieve information about a search set.
search_number | Set set number to query, or 0 for the latest one |
mode | The ID of the information to obtain |
integer_value | A pointer to a 64-bit signed integer that receives information represented as integer values. |
string_buffer | A pointer to a character string buffer that receives information represented as charcter data. |
string_buffer_size | The allocated size of the string_buffer parameter |
This function returns information on search sets, and replaces the older functions TdbGetSearch() and TdbSearchResult().
The mode
parameter is passed a constant that identifies what information to retrieve about the search set identified by the search_number
parameter. Valid values are:
Symbolic Name | Constant Value | Description |
---|---|---|
SEARCHINFO_SET_NUMBER | 1 | Search set ID, if 0 is passed to search_number |
SEARCHINFO_RECORD_COUNT | 2 | Number of records in the search set |
SEARCHINFO_HIT_COUNT | 3 | Number of hits in the search set |
SEARCHINFO_COMMAND | 4 | The CCL command used to generate the set |
SEARCHINFO_DATABASE | 5 | The name of the database or cluster searched |
This function was introduced in TRIP version 8.0-0.
int TdbTermSetCount | ( | int | termsetId, |
int64_t * | recordCount, | ||
int64_t * | updateCount | ||
) |
Receives the record counts for a termset
termsetId | ID of termset |
recordCount | Receives the (baseline) record count of the termset. |
updateCount | Receives the baseline update record count (not relevant for regular termsets). |
int TdbUpdateTermSet | ( | int | termsetId, |
const char * | shin, | ||
int | mode | ||
) |
Update termset list with restricting display command.
termsetId | Receives the number of the created termset on success. |
shin | A term list CCL order without the DISPLAY command and sort options. |
mode | Sorting mode (TERM_SORT_FREQ or TERM_SORT_TEXT, optionally with TERM_SORT_BL_ATEND added to the bitmask). |
The shin
parameter is expected to hold the conditional part of a DISPLAY command that is assumed to refine the DISPLAY command supplied to the TdbCreateBaselineTermSet() function, resulting in a subset of terms.
If shin
is NULL or an empty string, the no update/refine operation will be performed. Instead, the baseline is reset to reflect the record counts from the last call to TdbUpdateTermSet(), replacing the old baseline.