TRIPsystem Kernel API 8.3
|
Functions no longer to be used. More...
Functions | |
int | TdbBeginTdbs (shell_dao_rec *shell_dao, boolean restart) |
Initialize TRIP for a new session or resume a previous session. | |
int | TdbCopyBaseDef (char *old_base, char *new_base, base_spec_rec *base_specification) |
Create a copy of a database definition. | |
int | TdbCopyThesDef (const char *old_thes, const char *new_thes, base_spec_rec *thes_specification) |
Create a copy of a thesaurus definition. | |
int | TdbDaoOrder (int *order) |
Execute a DAO order. | |
int | TdbDefineGraph (base_spec_rec *base_spec, boolean enable) |
Graph-enable a database design. | |
int | TdbDefineXml (boolean xml) |
XML enable a database design. | |
int | TdbDeleteFieldSpec (field_spec_rec *fldspec) |
Delete a field specification from a database design. | |
int | TdbEndTdbs (boolean restart) |
Terminates a TRIP session started with TdbBeginTdbs. | |
int | TdbGetBaseDef (char *base, base_spec_rec *baseSpecification) |
Load a database definition. | |
int | TdbGetBaseInfo (char *base, char *recordNameField, int *flags) |
Get record name field and other information about the database. | |
int | TdbGetDbCluster (char *cluster, cluster_spec_rec *clusterSpecification) |
Load a database cluster specification. | |
int | TdbGetDefragStatus (const char *base, boolean *baf, boolean *bif, boolean *vif) |
Check the specified database files for need of defragmentation. | |
int | TdbGetFieldName (field_spec_rec *field_specification, int ordinal) |
Load the name of a field. | |
int | TdbGetFieldSpec (field_spec_rec *fieldSpec) |
Load a field specification record. | |
int | TdbGetSearch (int *search, int *record_count, int *hit_count) |
Obtain search result information. | |
int | TdbGetSessionInfo (char *run_time, Char *logged_in, Char *FM, Char *UM, Char *SM) |
Get information about the current TRIP session. | |
int | TdbGetThesDef (char *thesaurus, base_spec_rec *thesaurusSpec) |
Load a thesaurus definition. | |
int | TdbNextRunCommand (void) |
Load the next command in a stored procedure. | |
int | TdbPutBaseDef (base_spec_rec *baseSpec) |
Store a database definition. | |
int | TdbPutDbCluster (cluster_spec_rec *clusterSpec) |
Store a database cluster specification. | |
int | TdbPutFieldSpec (field_spec_rec *fieldSpec) |
Store a field specification record. | |
int | TdbPutThesDef (base_spec_rec *thesaurusSpec) |
Store a thesaurus definition. | |
int | TdbSearchResult (int *searchNumber, int *recordCount, int *hitCount, char **cclOrder, int *length) |
Returns information about a conducted search. | |
int | TdbShellDaoPtr (shell_dao_rec **shell_dao) |
Retrieve the address of a shell dao record. | |
int | TdbShellInit (int language) |
Initialize the CCL parser. | |
int | TdbShellToDao (shell_dao_rec *shell_dao) |
Parse a CCL command. | |
Field Group Design Functions | |
Functions for management of database field groups. | |
int | TdbPutBaseFieldGroup (TdbHandle handle) |
Store a field group definition. | |
Functions no longer to be used.
These functions are no longer maintained. Replacement functions are available where possible. Application code should be modified to use the named alternate functions as soon as possible, since the deprecated functions may be removed in a future release.
int TdbBeginTdbs | ( | shell_dao_rec * | shell_dao, |
boolean | restart | ||
) |
Initialize TRIP for a new session or resume a previous session.
shell_dao | Address of the shell dao interface record application will use. |
restart | Start mode of the session. |
NOTE: This function has been superseded by TdbStartTrip() .
The TdbBeginTdbs() function is the first API function that should be called by an application program. Upon return, and assuming a success return code, the environment for further API functions will have been initialised. However, this function should never be called by an application software exit (ASE) as all required initialisation will have been successfully completed prior to the ASE being activated.
The value passed as the restart
argument specifies whether or not this session is to be restarted from a SIF file that was retained from some previous session. If the value of the restart
argument is TRUE then some internal initialization is bypassed and the context is read from the SIF file upon calling the TdbCheckUser() function. If the value of the restart
argument is FALSE then a new SIF file will always be generated and any existing file ignored.
The TdbBeginTdbs() function initializes the TRIP kernel for use by the calling process. It performs consistency checks upon the operating system environment, TRIPsystem installation, licence conditions, and initialises essential status variables and reporting mechanisms in the TRIP kernel. If the site running the application is controlled by a concurrent user license, the TRIP Daemon is consulted to gain a session token, if possible. It checks for the existence and accessibility of the data dictionary (the CONTROL database) and of the error message store (the TDBSERR database) that the kernel needs during execution.
The length of CCL statements in sessions started with TdbBeginTdbs() is limited to 400 bytes. The superseding function TdbStartTrip() does not impose any such limit.
The shell_dao
parameter is passed the address of a pointer to a shell dao structure. This is used by the system during the execution of DAO commands (see the TdbDaoOrder() function). It is also used to return additional information, which cannot be contained within a return code, from other information gathering functions such as the TdbGetSearch() function. Refer to the TRIP Data Structures Reference Guide for a complete description of the structure. The record must be initialized with null-bytes before calling the routine. Only one shell_dao record can be used by an application.
The restart
parameter is passed a flag to control the (re)start mode of a session during initialization of TRIP. Valid values are:
Value | Purpose |
---|---|
False | Start the session with a new SIF file. |
True | Restart the session from an existing SIF, if possible. |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
162 | System file {1} not found or OS read protected. | |
8290 | OS open file limit of {1} reached. | |
8418 | TRIP/TDBS availability has expired. | |
12098 | Cannot find TDBS access record. | |
16898 | Concurrent user quota (N) exceeded | The maximum number of licenced concurrent TRIP users has been reached. When this error code is returned the accompanying error text will include the maximum number of concurrent users licenced for the machine. |
16418 | TRIPdaemon failed to respond (1), notify your System Mgr. | |
16450 | TRIPdaemon failure (1), notify your System Mgr. | |
17570 | Invalid TRIPdaemon process name | The TRIPkernel cannot locate the process for the TRIPdaemon. |
18370 | The ShellDao input argument is NULL. | |
34435 | TRIP/TDBS availability expires {1}. | The function completed its operations without error. |
int TdbCopyBaseDef | ( | char * | old_base, |
char * | new_base, | ||
base_spec_rec * | base_specification | ||
) |
Create a copy of a database definition.
old_base | Name of (existing) database |
new_base | Name of (new) database |
base_specification | Database specification record |
The function TdbCopyBaseDef() initiates the copying of one database design to another of a different name. Upon a successful return the base_specification
parameter pointer will reference a base specification record containing all the general properties of the new database as copied from the old.
In order to commit the new database to CONTROL the process must subsequently call the TdbPutBaseDef() function.
Note that the filename properties are not copied by this operation.
The old_base
parameter is passed a character string as the name of the existing database whose design is to be copied.
The new_base
parameter is passed a character string as the name of the new database.
The base_specification
parameter is passed a base specification record for the new database. Values will be copied form the equivalent record for the old database.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
34019 | Database design copied. | Operation completed successfully. |
706 | You have no rights to create or alter database designs. | The current user needs FM (file manager) rights to access this function. |
17474 | A TRIP runtime version cannot create databases. | This function cannot be used with a runtime TRIP license. |
7586 | Already existing database design: name. | Target database must not exist. |
int TdbCopyThesDef | ( | const char * | old_thes, |
const char * | new_thes, | ||
base_spec_rec * | thes_specification | ||
) |
Create a copy of a thesaurus definition.
old_thes | Name of source thesaurus |
new_thes | Name of new thesaurus |
thes_specification | Thesaurus specification record for new thesaurus. |
The function TdbCopyThesDef() starts the copying of a thesaurus to different one of a new name. The calling process must subsequently call TdbPutThesDef() to commit the new thesaurus to the CONTROL file.
The old_thes
parameter is passed a character string as the name of the thesaurus design to be copied.
The new_thes
parameter is passed a character string as the name of the thesaurus to be created.
The thes_specification
parameter is passed a thesaurus specification record for the newly created thesaurus.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
int TdbDaoOrder | ( | int * | order | ) |
Execute a DAO order.
order | Type of command executed |
The function TdbDaoOrder() attempts to execute the DAO order stored in the field DAO
of the shell dao interface record passed as an argument to the call of the TdbBeginTdbs() function.
Normally, the DAO order will be created from a CCL order using the function TdbShellToDao() but the calling process can simply write DAO statements to the shell dao interface record and calling the TdbDaoOrder() function.
The syntax and semantics of DAO orders is not documented.
Upon return from this function the value of the order
argument can be used to branch to perform command specific post processing such as reporting on the number of records hit by a search, or running each line of a procedure. As most commands result in some kind of output, a simple generalized kernel window output handler will ensure that most commands are handled correctly.
The order
parameter is passed a pointer to an int
variable that will receive a value that corresponds to the type of DAO command which was executed the TdbDaoOrder() function. The returned values are:
Symbolic Name | Constant Value | Explanation |
---|---|---|
DAO_CUT | 1 | A CUT order was executed; equivalent to the keystrokes KP6 in TRIPclassic. |
DAO_SELECT | 2 | A SELect order was executed. |
DAO_FIND | 3 | A Find order was executed. |
DAO_SHOW | 4 | A Show order was executed. |
DAO_MORE | 5 | A More order was executed. |
DAO_BASE | 6 | A BASe order was executed. |
DAO_CALL | 7 | A CALl order was executed. |
DAO_DISPLAY | 8 | A Display order was executed. |
DAO_IMPORT | 9 | A IMPOrt order was executed. |
DAO_EXPORT | 10 | A EXPOrt order was executed. |
DAO_MACRO | 11 | A RUN macro order was executed. |
DAO_STOP | 12 | A STOP order was executed. |
DAO_DEFINE | 13 | A DEfine order was executed. |
DAO_LIST | 14 | A List order was executed. |
DAO_NEXT | 15 | A Next order was executed. |
DAO_PREV | 15 | A PREVious order was executed. |
DAO_HELP | 16 | A HELP order was executed. |
DAO_EXPAND | 17 | A EXPand order was executed. |
DAO_PRINT | 18 | A PRint order (but a not print local order) was executed. |
DAO_RUN | 19 | A RUN procedure order was executed. |
DAO_SAVE | 20 | A SAVe order was executed. |
DAO_DELETE | 21 | A DELete order was executed. |
DAO_TRACE | 22 | A TRace order was executed. |
DAO_CONTINUE | 23 | A CONTinue order was executed. |
DAO_STATUS | 24 | A STatus order was executed. |
DAO_PRINT_LOCAL | 25 | A PRint LOCal order was executed. |
DAO_EDIT | 26 | A EDit order was executed. |
DAO_INSERT | 27 | A INSert order was executed. |
DAO_UPDATE | 28 | A UPDate order was executed. |
DAO_BACK | 29 | A Back order was executed. |
DAO_TOP | 30 | A Top order was executed. |
DAO_MEASURE | 31 | A MEasure order was executed. |
DAO_FREQ | 32 | A FReq order was executed. |
DAO_INDEX | 33 | A INDex order was executed. |
DAO_CONT_EDIT | 34 | A CONTinue EDit order was executed. |
DAO_CLOSE | 35 | A CLOSE order was executed. |
DAO_HIDE | 36 | A HIDe order was executed. |
DAO_REVEAL | 37 | A REVeal order was executed. |
DAO_CONT_SHOW | 38 | A CONTinue Show order was executed. |
DAO_FUZZ | 39 | A FUZz order was executed. |
DAO_SFORM | 40 | A SFOrm order was executed. |
CMD_LEAVE | 41 | A LEAVE order was executed. |
CMD_LOAD | 42 | A LOAD order was executed. |
CMD_RENUM | 43 | A RENUM order was executed. |
CMD_FIND_SAVE | 44 | A FIND SAVE order was executed. |
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.
int TdbDefineGraph | ( | base_spec_rec * | base_spec, |
boolean | enable | ||
) |
Graph-enable a database design.
base_spec | Database design specification as returned by TdbGetBaseDef. |
enable | Pass true to declare this database as a graph, and false to declare it as a regular database. |
Defines a database loaded by a call to TdbGetBaseDef() to be graph-enabled.
Once a database has been graph-enabled this cannot be revoked.
This function was introduced in TRIP version 7.1-0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
18114 | XML enabling of a database cannot be reset. | A database cannot be graph-enabled if it is already XML-enabled. |
23106 | Graph enabling of a database cannot be reset. | A database cannot be graph-enabled if it is already graph-enabled. |
23138 | An existing database cannot be graph enabled. | A database cannot be graph-enabled if its design already contains fields. |
int TdbDefineXml | ( | boolean | xml | ) |
XML enable a database design.
xml | XML-enabled flag |
Defines a database loaded by a call to TdbGetBaseDef() to be XML enabled.
Once a database has been XML enabled this cannot be revoked.
The xml
parameter is passed a boolean as a flag that database is XML-enabled
This function was introduced in TRIP version 3.3-1.
Code | Description | Explanation |
---|---|---|
34019 | Database design copied. | Operation completed successfully. |
706 | You have no rights to create or alter database designs. | The current user needs FM (file manager) rights to access this function. |
18082 | An existing database cannot be XML enabled. | Only a database without any pre-existing fields can be XML-enabled. |
18114 | XML enabling of a database cannot be reset. | A database cannot be XML-disabled, once it has been XML-enabled. |
int TdbDeleteFieldSpec | ( | field_spec_rec * | fldspec | ) |
Delete a field specification from a database design.
fldspec | specification Field specification record |
The function TdbDeleteFieldSpec() deletes a given field from a database design in memory, which must have previously been loaded using TdbGetBaseDef(). Either of the functions TdbGetFieldName() or TdbGetFieldSpec() should also have been called to put the proper values in the field specification record. Upon a subsequent call to TdbPutBaseDef(), the field will be deleted from the data dictionary. This routine can only be used successfully when the database is empty.
The fldspec
parameter is passed a pointer to a field specification record structure.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
7906 | Field name is missing. | |
14978 | Thesaurus fields may not be deleted. | Predefined fields in a thesaurus may not be deleted. |
18146 | XML fields may not be deleted. | Predefined fields in an XML database may not be deleted. |
1698 | Non-existing field name: name | |
7810 | Deletion of fields is legal only when the database is empty. |
int TdbEndTdbs | ( | boolean | restart | ) |
Terminates a TRIP session started with TdbBeginTdbs.
restart | Mode of session reinitialization |
The function TdbEndTdbs() will end the current TRIP session. The session must have been started with TdbBeginTdbs() . When TRIP exits an option exists to save the current SIF file for future use. This function must be the last TRIP toolkit routine called by the application. It must be called only once per image activation.
No calls to this function should be made from an application software exit (ASE).
The restart
parameter is passes a byte ( char ) a flag for the mode of a subsequent session's initialization. Valid values are:
Constant Value | Purpose |
---|---|
0 | Delete the SIF file |
1 | Retain the SIF file for possible re-use in a later session |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
10434 | Background printing still in progress. | This may occur when a PRINT command is still executing on the server. |
16322 | Disk quota exceeded when writing to the SIF file. |
int TdbGetBaseDef | ( | char * | base, |
base_spec_rec * | baseSpecification | ||
) |
Load a database definition.
base | Name of database |
baseSpecification | Database specification record |
The function TdbGetBaseDef() loads the definition of the specified TRIP database into the base specification record passed via the baseSpecification
parameter. The TRIPsystem user ID of the calling process must be the owner of the database being examined.
The base
parameter is passed a character string as the name of the database.
The baseSpecification
is passed a base specification record as the database specification record.
The current TRIPsystem user must possess the (file manager) FM privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
611 | Database name not found. | The specified database did not exist. |
15234 | Missing database name. | |
17474 | A TRIP runtime version cannot create databases. | This function cannot be used with a runtime TRIP license. |
3042 | Name is not a database. | |
2530 | No access to database name. | The logged on user did not have access to the specified database. |
9538 | No write access to database name. | The logged on user did not have write access to the specified database. |
10594 | No delete rights to database name. | The logged on user did not have delete access to the specified database. |
2498 | You have no FM access to the database. |
int TdbGetBaseInfo | ( | char * | base, |
char * | recordNameField, | ||
int * | flags | ||
) |
Get record name field and other information about the database.
base | Name of database |
recordNameField | Name of record name field |
flags | Field specific flags |
The function TdbGetBaseInfo() returns the name of the record name field and other data about the database.
The base
parameter is passed a character string as the name of the database.
The recordNameField
is passed a character string as the record name field.
The flag
parameter is passed a pointer to an int
variable that receives a bit mask. The current acceptable values are:
Constant Value | Description |
---|---|
0 | Bit0 is set if the database is an XML database. |
This function was introduced in TRIP version 3.3-1.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
15234 | Missing database name. | |
17474 | A TRIP runtime version cannot create databases. | This function cannot be used with a runtime TRIP license. |
610 | Database name not found. | The specified database did not exist. |
3042 | Name is not a database. | |
2530 | No access to database name. | The logged on user did not have access to the specified database. |
2498 | You have no FM access to the database. |
int TdbGetDbCluster | ( | char * | cluster, |
cluster_spec_rec * | clusterSpecification | ||
) |
Load a database cluster specification.
cluster | name Cluster name |
clusterSpecification | Cluster Specification Record |
The function TdbGetDbCluster() loads and makes current the specification of a stored database cluster.
The cluster specification can only be loaded by the owner of the cluster.
The cluster
name parameter is passed a character string as the name of the cluster whose specification record is to be retrieved.
The cluster
specification parameter is passed a cluster specification record to receive the predefined database cluster specification record. Refer to the TRIP Data Structures Reference Guide for a description of the record.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
706 | You have no rights to create or alter database designs. | The current user needs FM (file manager) rights to access this function. |
8802 | Only alphanumerics/underscores allowed in database/cluster names. | The specified cluster name contained invalid characters. |
17442 | name is not a database cluster. | |
16770 | You are not the owner of this DB cluster. |
int TdbGetDefragStatus | ( | const char * | base, |
boolean * | baf, | ||
boolean * | bif, | ||
boolean * | vif | ||
) |
Check the specified database files for need of defragmentation.
base | Name of database to check |
baf | Receives true if the BAF file needs defragmentation else false |
bif | Receives true if the BIF file needs defragmentation else false |
vif | Receives true if the VIF file needs defragmentation else false |
This function has been been deprecated without replacement and will now always return false for all files. Use the file system tools available for your operating system to perform defragmentation checks instead.
int TdbGetFieldName | ( | field_spec_rec * | field_specification, |
int | ordinal | ||
) |
Load the name of a field.
field_specification | Field specification record |
ordinal | Ordinal field number |
The function TdbGetFieldName() loads the name of a field into the field specification record passed via the field
specification parameter. The field selected is specified by the ordinal field number in the database definition.
A call to TdbGetBaseDef() must be made before any attempts to load the field specification record are made with this function.
To obtain a complete field specification TdbGetFieldSpec() should subsequently be called in which that function reads the field name in the specification record to determine which field's specification is being requested.
The field_specification
parameter is passed a field specification record to be filled in with the name of the field.
The ordinal
number parameter is passed an integer as the ordinal field number. Acceptable values range from one to the number of fields in the database design. If no fields have been deleted from the database design, the ordinal field number will be equal to the actual field number.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Could not get field name. |
int TdbGetFieldSpec | ( | field_spec_rec * | fieldSpec | ) |
Load a field specification record.
fieldSpec | Field specification record |
The function TdbGetFieldSpec() loads the specification of a database field into the field specification record passed via the fieldSpec
parameter. Before calling the routine, the name of the desired field must be put into the field_name
member of the record by either calling TdbGetFieldName() or explicitly copying the field name into the ' record.
A call to the function TdbGetBaseDef() has to have preceded a call to this function.
The fieldSpec
parameter is passed a field specification record to be filled in with details of the request field.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Could not get field specification. |
int TdbGetSearch | ( | int * | search, |
int * | record_count, | ||
int * | hit_count | ||
) |
Obtain search result information.
search | Search number |
record_count | Number of records for search |
hit_count | Number of hits for search |
The function TdbGetSearch() returns information about the results of a previous CCL Find order. It returns the number of records found by the search, and the number of occurrences of the search terms found within these records.
The search
parameter is passed a pointer to an int
variable that represents the number of the search for which details are to be retrieved. If the number is set to zero on input, details for the current search will be returned and the actual search number will be returned in this parameter on succesful output. Otherwise, this parameter must be set to a positive number on input, which must correspond to an existing search set within the session.
The record_count
parameter is passed a pointer to an int
variable to receive the number of records found by the search.
The hit_count
parameter is passed a pointer to an int
variable to receive the count of terms actually hit by the search.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
2274 | Non-existing search number: {1} |
int TdbGetSessionInfo | ( | char * | run_time, |
Char * | logged_in, | ||
Char * | FM, | ||
Char * | UM, | ||
Char * | SM | ||
) |
Get information about the current TRIP session.
run_time | Run-time indicator |
logged_in | Flag for successful call to CHECK USER |
FM | File manager flag |
UM | User manager flag |
SM | System manager flag |
The function TdbGetSessionInfo() retrieves miscellaneous information about the current TRIP session and TRIP user. If the function TdbBeginTdbs() has not been called it will return an error code.
The run_time
parameter is passed a byte to receive the run-time indicator. The returned values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
False | 0 | Current TRIPsystem session is not a run-time session |
True | 1 | The session is a run-time session and database creation/modification is not allowed. |
The logged_in
parameter is passed a byte to receive the flag indicating whether a TRIP user identity has been established by a successful call to TdbCheckUser() . The returned values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
False | 0 | No user identity |
True | 1 | A TRIPkernel user has successfully logged in. |
The FM
parameter is passed a byte to receive the flag indicating the user's status as a File manager. This parameter is only valid if logged_in
is returned as True. The returned values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
False | 0 | The current TRIP user is not a file manager |
True | 1 | The TRIP user is a file manager and may create databases |
The UM
parameter is passed a byte to receive the flag indicating the user's status as a User manager. This parameter is only valid if logged_in
is returned as True. The return values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
False | 0 | The current TRIP user is not a user manager |
True | 1 | The TRIP user is a user manager and may create other users |
The SM
parameter is passed a byte to receive the flag indicating the user's status as System manager. This parameter is only valid if logged_in
is returned as True. The returned values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
False | 0 | The current TRIP user is not the system manager |
True | 1 | The TRIP user is the system manager |
int TdbGetThesDef | ( | char * | thesaurus, |
base_spec_rec * | thesaurusSpec | ||
) |
Load a thesaurus definition.
thesaurus | Name of thesaurus |
thesaurusSpec | Thesaurus specification record |
The function TdbGetThesDef() loads the definition of the specified TRIPsystem thesaurus into the base specification record provided. The TRIPsystem user ID of the calling process must be the owner of the thesaurus being examined.
The thesaurus
parameter is passed a character string as the name of the thesaurus.
The thesaurusSpec
parameter is passed a base specification record as the thesaurus specification record.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
706 | You have no rights to create or alter database designs. | The current user needs FM (file manager) rights to access this function. |
17474 | A TRIP runtime version cannot create databases. | This function cannot be used with a runtime TRIP license. |
1934 | Database name not found. | The specified database did not exist. |
3010 | name is not a thesaurus. | |
2498 | You have no FM access to the database. |
int TdbNextRunCommand | ( | void | ) |
Load the next command in a stored procedure.
The function TdbNextRunCommand() loads the next line from a stored TRIP procedure or macro into the shin
shell input field in the shell_dao
interface record that is currently being used by TRIPsystem.
This function should be called after a call to TdbDaoOrder() that has returned a DAO_RUN
( 19
) status indicating that a CCL command command has been executed. Repeated calls to TdbNextRunCommand() will cause each line of the stored procedure to be copied into the shell_dao
interface record, for subsequent parsing (by the function TdbShellToDao() ) and execution (by TdbDaoOrder() ).
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbPutBaseDef | ( | base_spec_rec * | baseSpec | ) |
Store a database definition.
baseSpec | Base specification record |
The function TdbPutBaseDef() writes the database definition contained in the base specification record provided into the CONTROL file. A call to TdbPutBaseDef() must have been preceded by a call to either of the TdbGetBaseDef() or TdbCopyBaseDef() functions.
The baseSpec
parameter is passed a base specification recordto write to the CONTROL file.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
32515 | Database design for name altered. | Database design successfully altered. |
32547 | Database design for name created. | Database design successfully created. |
33411 | Database design for name altered (check logical names). | Database design successfully altered, but there may be something wrong with the BAF/BIF/VIF file names. |
33443 | Database design for name created (check logical names). | Database design successfully created, but there may be something wrong with the BAF/BIF/VIF file names. |
706 | You have no rights to create or alter database designs. | The current user needs FM (file manager) rights to access this function. |
11842 | Unbalanced parenthesis in database description. | |
14786 | id is not a valid character folding class. |
int TdbPutBaseFieldGroup | ( | TdbHandle | handle | ) |
Store a field group definition.
handle | Handle to a field group obtained from TdbGetBaseFieldGroup() |
The function TdbPutBaseFieldGroup() stores the field group definition in the internal database definition buffer for later writing to the CONTROL file by a call to the TdbPutBaseDesign() function. This routine can only be called after a database definition has been loaded by the TdbGetBaseDesign() function, and the field group intiialized or fetched by the TdbGetBaseFieldGroup() function.
To commit the field group definition to CONTROL, along with other modifications made to the database design, call TdbPutBaseDesign().
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
int TdbPutDbCluster | ( | cluster_spec_rec * | clusterSpec | ) |
Store a database cluster specification.
clusterSpec | Cluster specification record |
The function TdbPutDbCluster() will store the specification of a database cluster defined in the cluster specification record.
The cluster specification record must previously have been obtained by a call to the TdbGetDbCluster() function.
The clusterSpec
parameter is passed a cluster specification record, with changes to the named predefined cluster of databases.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
39235 | Database cluster design for name altered. | Operation completed successfully. |
39267 | Database cluster design for name created. | Operation completed successfully. |
9794 | Database name name is the same as the DB cluster name. |
int TdbPutFieldSpec | ( | field_spec_rec * | fieldSpec | ) |
Store a field specification record.
fieldSpec | Field specification record |
The function TdbPutFieldSpec() stores the field specification record into the internal database definition buffer for later writing to the CONTROL file by a call to the TdbPutBaseDef() function. This routine can only be called after a database definition has been loaded by the TdbGetBaseDef() and TdbGetFieldSpec() function have been called.
The fieldSpec
parameter is passed a field specification record with updated details of a field in the relevant database. ´
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
2146 | Non-existing field: field. | |
6786 | Already existing field name. | |
6850 | Invalid field type. | |
7106 | Field name is already the unique record name field. | There can be only one record name field in a database. |
7266 | Record name field must be of type {PHR}. | |
7426 | field is already copyright protected by field. | |
7458 | Field name must be: letter followed by alphanums or underscores. | |
7618 | Changing of field type is legal only when the database is empty. | |
7650 | Removal of record id is legal only when the database is empty. | |
7714 | Pattern restriction is only valid for field type {PHR}. | |
7746 | File reference restriction is only valid for field type {PHR}. | |
8226 | Field name name coincides with the database name. | A field can not have the same name as the database. |
8258 | Record id field must not be specified for non-empty databases. | |
8482 | Field field is already the record number field. | |
8514 | Record number field must be of type {INT}. | |
8546 | Removal of rec no field is legal only when the database is empty. | |
8578 | Record number field must not be specified for non-empty databases. | |
9058 | Invalid interval. | |
11810 | Unbalanced parenthesis in field comment. | |
12674 | Changing part field status is allowed only for empty databases. | |
14946 | The fieldtype of a thesaurus field may not be changed. | |
15426 | Changing from/to one paragraph is only allowed for empty databases. | |
15650 | Only the CTX field in a thesaurus can be the record name field. | |
15810 | Field field is already the unique part name field. | |
15842 | Part name field must be of type {PHR}. | |
15874 | Removal of part name field is legal only when the database is empty. | |
15906 | Part name field must not be specified for non-empty databases. | |
15938 | Part name field must be specified as part field. | |
17154 | A part record field cannot be made the record name field. | |
17186 | A part record field cannot be made the record number field. | |
17378 | Word indexing is only valid for {PHR} fields. | |
18018 | The fieldtype of an XML field may not be changed. | The predefined fields of an XML database may not be altered. |
int TdbPutThesDef | ( | base_spec_rec * | thesaurusSpec | ) |
Store a thesaurus definition.
thesaurusSpec | Base specification record for thesaurus |
The function TdbPutThesDef() writes the thesaurus definition in the base specification record into the CONTROL file. A call to TdbPutThesDef() must be preceded by a call to the TdbGetThesDef() function.
The thesaurusSpec
parameter is passed a base specification record for the thesaurus.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
34275 | Thesaurus design for {name} altered (Check logical names). | Operation completed successfully. |
34307 | Thesaurus design for {name} created (Check logical names). | Operation completed successfully. |
34339 | Thesaurus design for {name} altered. | Operation completed successfully. |
34371 | Thesaurus design for {name} created. | Operation completed successfully. |
706 | You have no rights to create or alter database designs. | The current user needs FM (file manager) rights to access this function. |
11842 | Unbalanced parenthesis in database description. | |
14786 | {id} is not a valid character folding class. |
int TdbSearchResult | ( | int * | searchNumber, |
int * | recordCount, | ||
int * | hitCount, | ||
char ** | cclOrder, | ||
int * | length | ||
) |
Returns information about a conducted search.
searchNumber | The number of the search to request information about. Use 0 (zero) for the last search. The real search number is returned in this parameter. |
recordCount | This output parameter contains the number of records found in the specified search. |
hitCount | This output parameter contains the total number of hits in the specified search. |
cclOrder | The server version takes a pointer to an (unallocated) character buffer as input, and on output receives the CCL statement that generated the search set. The client version of this parameter is a by the application allocated character buffer that will receieve the CCL statement that generated the search set. |
length | Takes a pointer to an integer that recieves the length of the cclOrder on output. |
The TdbSearchResult() function returns information about a conducted search such as search number, record count, hit count, and the CCL order that generated the search set.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
2274 | Non-existing search number: number. | The specified search number did not correspond to a search set. |
int TdbShellDaoPtr | ( | shell_dao_rec ** | shell_dao | ) |
Retrieve the address of a shell dao record.
shell_dao | Address of SHELL/DAO record |
The function TdbShellDaoPtr() returns the address of the SHELL/DAO record area for the current TRIP session, as supplied to the TdbBeginTdbs() function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
9954 | Missing mandatory argument. |
int TdbShellInit | ( | int | language | ) |
Initialize the CCL parser.
language | CCL locale language to use |
The function TdbShellInit() initializes the CCL parser used in the TRIP search mode and is used to specify the language file which is to be used. The default language file is specified by the TRIPrcs setting TDBS_LANG. If no such setting is specified, the default will be English.
The language
parameter is passed an integer that indicates which CCL locale language to use. Valid values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
LANGUAGE_DEFAULT | 1 | Use the system default language |
LANGUAGE_ENGLISH | 9 | Use English dialect |
LANGUAGE_SWEDISH | 10 | Use Swedish dialect |
LANGUAGE_CHINESE | 11 | Use Chinese dialect |
LANGUAGE_GERMAN | 12 | Use German dialect |
LANGUAGE_FRENCH | 13 | Use French dialect |
LANGUAGE_FINNISH | 14 | Use Finnish dialect |
LANGUAGE_NORWEGIAN | 15 | Use Norwegian dialect |
Code | Description | Explanation |
---|---|---|
0 | Operation failed | |
1 | Operation completed successfully | The function completed its operations without error. |
int TdbShellToDao | ( | shell_dao_rec * | shell_dao | ) |
Parse a CCL command.
shell_dao | Address of SHELL TO DAO record |
The function TdbShellToDao() will parse the CCL command contained in the shell input field of the SHELL/DAO interface record. This routine is the interface to the embedded CCL parser within the TRIP system. The modified CCL command produced during this parsing process is stored in the shout shell output field of the interface record, and the DAO (internal) form of the command is stored in the dao DAO input field of the record.
To execute the order, call TdbDaoOrder() after successful completion of this function.
The shell_dao
parameter is passed a pointer to the SHELL/DAO record that was originally passed to the TdbShellInit() function. Refer to the TRIP Data Structures Reference Guide for a description of the SHELL/DAO interface record.
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.