TRIPsystem Kernel API 8.3
|
Database administration and information. More...
General Database Functions | |
General database administration and information functions. | |
int | TdbBaseInfo (const char *base, int mode, char *cvalue, int *ivalue) |
Retrieve selected information about a database. | |
int | TdbBaseStatus (const char *base, char *revisionDate, char *indexDate, int *recordCount) |
Retrieve certain information concerning the state of a given database. | |
Access Management Functions | |
Functions for access management to databases, clusters and thesauri. | |
int | TdbCheckBase (const char *base, int accessMode) |
Check access rights to a database. | |
int | TdbCheckDbCluster (const char *clusterName, int accessMode) |
Check access rights to a database cluster. | |
int | TdbCheckThes (const char *thesaurus, int accessMode) |
Check access rights to a thesaurus. | |
int | TdbGetDbAccess (char *user, base_access_rec *baseAccess) |
Load the base access record for a TRIP user. | |
int | TdbPutDbAccess (base_access_rec *baseAccess) |
Store the base access record for a TRIP user. | |
Database Design Functions | |
Functions for management of database designs. | |
int | TdbCheckFieldName (const char *field_name) |
Check for the existence of a field. | |
int | TdbCopyBaseDesign (const char *from_base, const char *to_base, TdbHandle *design) |
Create a copy of a database definition. | |
int | TdbDeleteBaseDef () |
Delete a previously loaded database design. | |
int | TdbPutBaseDesign (TdbHandle handle) |
Store a database definition. | |
int | TdbGetTextSeparators (text_sepa_rec *separatorSpec) |
Load a text separator specification. | |
int | TdbPutTextSeparators (text_sepa_rec *separatorSpec) |
Store a text separator specification. | |
int | TdbGetBaseDesign (TdbHandle *handle, const char *base, int accessMode) |
Load a database design. | |
int | TdbCloseBaseDesign (TdbHandle *handle) |
Close a database design handle. | |
int | TdbGetBaseProperty (TdbHandle handle, int property_id, int *numeric_value, char *string_value_buffer, int string_buffer_size) |
Retreieve database design properties. | |
int | TdbPutBaseProperty (TdbHandle handle, int property_id, int numeric_value, const char *string_value) |
Assign a database design property. | |
Field Design Functions | |
Functions for management of database fields. | |
int | TdbGetBaseField (TdbHandle *fieldHandle, TdbHandle baseHandle, const char *fieldName, int ordinal) |
Load a field specification from a database design. | |
int | TdbGetBaseFieldByNumber (TdbHandle *fieldHandle, TdbHandle baseHandle, int fieldNumber) |
Load a field specification from a database design. | |
int | TdbDeleteBaseField (TdbHandle *fieldHandle) |
Delete a field from a database design. | |
int | TdbPutBaseField (TdbHandle handle) |
Store a field specification record. | |
int | TdbCloseBaseField (TdbHandle *handle) |
Closes a field specification handle. | |
int | TdbGetFieldProperty (TdbHandle handle, int property_id, int *numeric_value, char *string_value_buffer, int string_buffer_size) |
Retrieve a field design property. | |
int | TdbPutFieldProperty (TdbHandle field_design_handle, int property_id, int numeric_value, const char *string_value) |
Assign a field design property. | |
Field Group Design Functions | |
Functions for management of database field groups. | |
int | TdbGetBaseFieldGroup (TdbHandle *fgrp_design_handle, TdbHandle base_design_handle, const char *name, int ordinal) |
Load a field group definition from a database design. | |
int | TdbCloseBaseFieldGroup (TdbHandle *handle) |
Close a database field group. | |
int | TdbDeleteBaseFieldGroup (TdbHandle *handle) |
Delete a database field group. | |
int | TdbGetFieldGroupProperty (TdbHandle handle, int property_id, int *numeric_value, char *string_value_buffer, int string_buffer_size) |
Retrieve field group properties. | |
int | TdbPutFieldGroupProperty (TdbHandle handle, int property_id, int numeric_value, const char *string_value) |
Assign field group properties. | |
int | TdbFieldGroupAddField (TdbHandle handle, const char *field_name) |
Add a field to a field group. | |
int | TdbFieldGroupDelField (TdbHandle handle, const char *field_name) |
Remove a field from a field group. | |
int | TdbFieldGroupGetField (TdbHandle field_group_handle, TdbHandle *field_handle, const char *field_name, int ordinal) |
Retrieve a field from a field group. | |
int | TdbPutBaseFieldGroup (TdbHandle handle) |
Store a field group definition. | |
Refererential Integrity and Defaults | |
Functions for management of database referential integrity constraints and default values. | |
int | TdbGetIntegrityRules (base_integrity_spec **rules) |
Retrieve the integrity rules for the current database. | |
int | TdbFreeIntegrityRules (base_integrity_spec *rules) |
Release an integrity rules structure. | |
int | TdbDeleteIntegrityRules () |
Delete all integrity rules for the current database. | |
int | TdbCheckForeignKey (Char *keyfield, Char *parentdb, Char *parentfld) |
Validates that the defined foreign key, when set, will succeed. | |
int | TdbSetForeignKey (Char *keyfield, Char *parentdb, Char *parentfld, int upd, int del) |
Establishes a new foreign key relationship. | |
int | TdbDeleteForeignKey (Char *keyfield) |
Remove a foreign key from the current database. | |
int | TdbGetDefaultValue (Char *fieldName, Char *fieldValue, int *fieldLength) |
Retrieve the default value for the specified field. | |
int | TdbPutDefaultValue (Char *fieldName, Char *fieldValue) |
Set the default value for a field. | |
int | TdbDeleteDefaultValue (Char *fieldName) |
Remove any existing default value for a field. | |
Thesaurus Design Functions | |
Functions for management of thesaurus designs. | |
int | TdbCopyThesDesign (const char *from_thes, const char *to_thes, TdbHandle *design) |
Create a copy of a thesaurus definition. | |
int | TdbDeleteThesDef (void) |
Delete a thesaurus definition. | |
int | TdbGetThesDesign (TdbHandle *handle, const char *name, int accessMode) |
Load a thesaurus design. | |
int | TdbPutThesDesign (TdbHandle handle) |
Store a thesaurus definition. | |
Cluster Management Functions | |
Functions for management of database clusters. | |
int | TdbDeleteDbCluster (void) |
Delete a database cluster. | |
int | TdbGetClusterDesign (TdbHandle *cluster_handle, const char *cluster_name, int access_mode) |
Load a database cluster specification. | |
int | TdbPutClusterDesign (TdbHandle handle) |
Store a database cluster specification. | |
int | TdbCloseClusterDesign (TdbHandle *handle) |
Close a cluster design handle. | |
int | TdbCopyClusterDesign (TdbHandle sourceHandle, const char *newName, TdbHandle *targetHandle) |
Copy a database cluster. | |
int | TdbClusterAddMember (TdbHandle handle, const char *name) |
Add a member to a cluster. | |
int | TdbClusterDelMember (TdbHandle handle, int position, const char *name) |
Delete a member from a cluster. | |
int | TdbClusterDelMembers (TdbHandle handle) |
Delete all members from a cluster. | |
int | TdbClusterEnumMembers (TdbHandle handle, int *position, char *name, int namesize) |
Iterator function to retrieve the names of all cluster members. | |
int | TdbClusterGetMember (TdbHandle handle, int position, char *name, int namesize) |
Retrieive the name of a cluster member. | |
int | TdbGetClusterProperty (TdbHandle handle, int property_id, int *numeric_value, char *string_value_buffer, int string_buffer_size) |
Retrieve a property of a database cluster. | |
int | TdbPutClusterProperty (TdbHandle handle, int property_id, int numeric_value, const char *string_value) |
Assign a property of a database cluster. | |
Database administration and information.
The TRIPtoolkit database management functions offer functionality for querying status on and defining databases, clusters and thesauri.
int TdbBaseInfo | ( | const char * | base, |
int | mode, | ||
char * | cvalue, | ||
int * | ivalue | ||
) |
Retrieve selected information about a database.
base | Database name |
mode | Mode of operation |
cvalue | Information as character string |
ivalue | Information as integer |
Returns various information about a database.
The base
parameter is passed a character string as the name of the database to interogate.
The mode
parameter is passed an int
as a flag to request information about the database named by the base
parameter. Valid values are:
Symbolic Name | Output Parameter | Purpose |
---|---|---|
BASEINFO_XML | ivalue | The ivalue parameter receives the value 1 (one) if the database is XML enabled, and 0 (zero) if it is not. |
BASEINFO_CHARFOLD | ivalue | Character folding class |
BASEINFO_RNAMEFLD | cvalue | Record name field |
BASEINFO_MAXFLD | ivalue | Highest field number used |
BASEINFO_PNAMEFLD | cvalue | Part name field |
BASEINFO_LANGUAGE | ivalue | Database language code. The ivalue parameter receieves a value as defined by the LANGUAGE_* constants (e.g. LANGUAGE_ENGLISH, etc). |
BASEINFO_CHARSET | ivalue | The character set set for the database. The ivalue parameter receieves a value as defined by the CHARSET_* constants (e.g. CHARSET_UTF8, CHARSET_LA1, etc). |
BASEINFO_RNUMFLD | ivalue | The record number field for the database. |
BASEINFO_MAXRNUM | ivalue | The highest record number in the database. |
BASEINFO_OWNER | cvalue | The name of the TRIP user that owns the database |
BASEINFO_GRAPH | ivalue | The ivalue parameter receives the value 1 (one) if the database is a graph database, and 0 (zero) if it is not. |
BASEINFO_CLUSTERBASES | cvalue | If the database is an opened cluster, the cvalue parameter receives a comma-separated list of the clustered databases. |
BASEINFO_DBNUMBER | ivalue | The number of the CONTROL database record that holds the database design |
BASEINFO_DBDESC | cvalue | The description/comment text for the database |
BASEINFO_CONNECTOR | ivalue | The ivalue parameter receives the value 1 (one) if the database is a TRIPcof connector database, and 0 (zero) if it is not. |
BASEINFO_RECORDCOUNT | ivalue | The number of records in the database |
BASEINFO_DESIGN_CREDATE | cvalue | The date at which the database design was created |
BASEINFO_DESIGN_CRETIME | cvalue | The time at which the database design was created |
BASEINFO_DESIGN_MODDATE | cvalue | The date at which the database design was last modified |
BASEINFO_DESIGN_MODTIME | cvalue | The time at which the database design was last modified |
BASEINFO_THESAURUS | ivalue | The ivalue parameter receives the value 1 (one) if the name is that of a thesaurus, or 0 (zero) if it is not. |
BASEINFO_CONTAINER | ivalue | The ivalue parameter receives the value 1 (one) if the name is that of a classification container, or 0 (zero) if it is not. |
The cvalue
is passed a character string buffer that receives information represented as charcter data.
The ivalue
is passed a pointer to a 32-bit signed integer that receives information represented as an integer value.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
This function was introduced in TRIP version 3.4-0.
Code | Description | Explanation |
---|---|---|
7394 | No record name field defined in base. | The specified database has no record name field. May occur when the mode parameter is set to BASEINFO_RNAMEFLD and the specified database has no part record name field. |
17986 | Database base has no part name field. | The specified database has no part name field. May occur when mode is set to BASEINFO_PNAMEFLD and the specified database has no part name field. |
18466 | Unrecognized option: mode | The option value specified in the mode parameter is not valid. |
int TdbBaseStatus | ( | const char * | base, |
char * | revisionDate, | ||
char * | indexDate, | ||
int * | recordCount | ||
) |
Retrieve certain information concerning the state of a given database.
base | Name of the database. |
revisionDate | Date of last revision to database design. |
indexDate | Date of last index. |
recordCount | Number of records in database. |
The TdbBaseStatus() returns information describing the current state of the specified TRIPsystem database. The information returned is the date of the last update to the database design, the date when the database was last indexed, and the total number of records in the database (un-indexed records included).
For the revision date and the index date, the format the date is returned in depends on the dateform setting established by the calling process. Changes to the system default dateform can be made using dateform setting in the user's profile, or by calling the TdbShellDefDateForm() function.
The base
parameter is passed a string containing the name of the database.
The revisionDate
parameter receives a string containing the date of last revision to database design. The string buffer passed as this parameter has to be large enough to accommodate a date in the current format.
The indexDate
parameter receives a string containing the date of last index.
The recordCount
parameter receives an integer count of the number of records currently in the database.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
15234 | Missing database name. | The name of the database to retrieve information about must be specified. |
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 database name contained invalid characters. |
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. |
2530 | No access to database name. | The logged on user did not have access to the specified database. |
int TdbCheckBase | ( | const char * | base, |
int | accessMode | ||
) |
Check access rights to a database.
base | Name of database |
accessMode | Access mode to be checked. |
The TdbCheckBase() will report whether the calling process has the specified degree of access to the database in question. This can be useful if, for instance, the calling process needs to ensure that only the owner of a database can perform a certain action.
Note that in order to be able to change a user's access to a database, using either of the functions TdbGetDbAccess() or TdbPutDbAccess(), the calling process must first register itself as the file manager by calling this function with the mode set to CHECK_OWNERSHIP
.
The base
parameter is passed a character string as the name of a database to be checked for the user's current level of access.
The accessMode
parameter is passed a ( long ) int value for the access mode to be checked. Valid values are:
Symbolic Value | Constant Value | Purpose |
---|---|---|
CHECK_READ | 1 | The calling process requires read access to the database |
CHECK_UPDATE | 2 | The calling process requires update access to the database |
CHECK_OWNERSHIP | 3 | The calling process requires file manager (FM) access to the database |
CHECK_DELETE | 4 | The calling process requires access to delete records, i.e. that it has write access to ALL fields in the database. |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
15234 | Missing database name. | The name of the database to retrieve information about must be specified. |
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 database name contained invalid characters. |
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. |
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. |
16770 | You are not the owner of this DB cluster.. | |
2498 | You have no FM access to the database. |
int TdbCheckDbCluster | ( | const char * | clusterName, |
int | accessMode | ||
) |
Check access rights to a database cluster.
clusterName | Name of database cluster |
accessMode | Access mode |
The TdbCheckDbCluster() is used to ensure a level of access to a specific database cluster. This can be used, for instance, to guarantee that only the owner of a cluster can perform certain operations.
The clusterName
parameter is passed a character string as the name of the (predefined) database cluster to be examined.
The accessMode
parameter is passed an int
that represents the access mode to be checked. Valid values are:
Symbolic Constant | Value of Constant | Purpose |
---|---|---|
CHECK_READ | 1 | The calling process requires read access to the cluster |
CHECK_UPDATE | 2 | The calling process requires updating of the cluster |
CHECK_OWNERSHIP | 3 | The calling process requires file manager (FM access to the cluster |
CHECK_DELETE | 4 | The calling process requires delete access to records, i.e. has write access to ALL fields in the cluster |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
15234 | Missing database name. | The name of the database to retrieve information about must be specified. |
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 database name contained invalid characters. |
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. |
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. |
16770 | You are not the owner of this DB cluster.. | |
2498 | You have no FM access to the database. |
int TdbCheckFieldName | ( | const char * | field_name | ) |
Check for the existence of a field.
field_name | Name of field to check |
Checks for the existence of a field in the currently loaded database design, so a call to this function must be preceded by a call to TdbGetBaseDesign().
int TdbCheckForeignKey | ( | Char * | keyfield, |
Char * | parentdb, | ||
Char * | parentfld | ||
) |
Validates that the defined foreign key, when set, will succeed.
keyfield | Foreign key field in current database |
parentdb | Name of associated database |
parentfld | Field in associated database |
int TdbCheckThes | ( | const char * | thesaurus, |
int | accessMode | ||
) |
Check access rights to a thesaurus.
thesaurus | Name of thesaurus |
accessMode | Access mode to be checked |
The function TdbCheckThes() is used to verify that the calling process can gain a specified level of access to the thesaurus named in the thesaurus
parameter. This can be useful if, for example, you wish to guarantee that only the owner of the thesaurus can perform certain functions.
The thesaurus
parameter is passed a character string as the name of the thesaurus.
The accessMode
parameter is passed an int
as the access mode to be checked. Valid values are:
Symbolic Constant | Constant Value | Purpose |
---|---|---|
CHECK_READ | 1 | The calling process requires read access to the thesaurus |
CHECK_UPDATE | 2 | The calling process requires update access to the thesaurus |
CHECK_OWNERSHIP | 3 | The calling process requires owner access to the thesaurus |
CHECK_DELETE | 4? | The calling process requires delete access, i.e. has write access to ALL fields in the thesaurus |
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
15234 | Missing database name. | The name of the database to retrieve information about must be specified. |
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 database name contained invalid characters. |
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. |
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. |
16770 | You are not the owner of this DB cluster.. | |
2498 | You have no FM access to the database. |
int TdbCloseBaseDesign | ( | TdbHandle * | handle | ) |
Close a database design handle.
handle | Pointer to a handle to database obtained via the TdbGetBaseDesign() function. The handle value will be set to NULL upon successful completion of this function. |
A database handle must be closed using this function when the application not longer needs it. Failure to do so will result in memory leaks.
int TdbCloseBaseField | ( | TdbHandle * | handle | ) |
Closes a field specification handle.
handle | Pointer to field handle returned from TdbGetBaseField() |
The function TdbCloseBaseField() must be called to close a handle to a field specification when the application not longer needs it.
The handle
parameter is passed a pointer to the field specification handle to close. The handle variable that the parameter points to will be set to NULL upon successful completion of this function.
This function was introduced in TRIP version 8.0.
int TdbCloseBaseFieldGroup | ( | TdbHandle * | handle | ) |
Close a database field group.
handle | [IN/OUT] Pointer to field group handle returned from TdbGetBaseFieldGroup() |
The function TdbCloseBaseFieldGroup() must be called to close a handle to a field specification when the application not longer needs it.
The handle
parameter is passed a pointer to the field group handle to close. The handle variable that the parameter points to will be set to NULL upon successful completion of this function.
This function was introduced in TRIP version 8.0.
int TdbCloseClusterDesign | ( | TdbHandle * | handle | ) |
Close a cluster design handle.
handle | Pointer to a handle to database cluster obtained via the TdbGetClusterDesign() function. The handle value will be set to NULL upon successful completion of this function. |
A cluster handle must be closed using this function when the application not longer needs it. Failure to do so will result in memory leaks.
int TdbClusterAddMember | ( | TdbHandle | handle, |
const char * | name | ||
) |
Add a member to a cluster.
handle | Handle to a database cluster design obtained using the TdbGetClusterDesign() function. |
name | Name of database or cluster to add as member. |
This function adds a member to a database cluster. The named member be a database or another cluster. The change must be committed by calling TdbPutClusterDesign().
There is no set upper limit for how large a cluster can be, but in order for clusters to remain possible to adninistrate with TRIPclassic, clusters should not have more than 30 members.
int TdbClusterDelMember | ( | TdbHandle | handle, |
int | position, | ||
const char * | name | ||
) |
Delete a member from a cluster.
handle | Handle to a database cluster design obtained using the TdbGetClusterDesign() function. |
position | 1-based position of member to delete or 0 (zero) to delete a member by name. |
name | Name of member to delete, or NULL to delete a member by its position. |
This function deletes a specified member from a cluster. The member is specified by either its name
or its 1-based position
in the cluster design. The change must be committed by calling TdbPutClusterDesign().
int TdbClusterDelMembers | ( | TdbHandle | handle | ) |
Delete all members from a cluster.
handle | Handle to a database cluster design obtained using the TdbGetClusterDesign() function. |
This function deletes all members from a cluster, e.g. in preparation for supplying a new list of cluster members. So instead of adding and deleting individual members, one can first use this function to clear the cluster design, then call TdbClusterAddMember() repeatedly to add the new list of members. The change must be committed by calling TdbPutClusterDesign().
int TdbClusterEnumMembers | ( | TdbHandle | handle, |
int * | position, | ||
char * | name, | ||
int | namesize | ||
) |
Iterator function to retrieve the names of all cluster members.
handle | Handle to a database cluster design obtained using the TdbGetClusterDesign() function. |
position | [IN/OUT] Initialize to 1 to start retrieving. The value will be updated by the function as member names are returned. |
name | Character string buffer to receive a cluster member name |
namesize | The allocated size of the name buffer |
This function is used to retrieve the names of the members of a cluster, as in the following example:
int TdbClusterGetMember | ( | TdbHandle | handle, |
int | position, | ||
char * | name, | ||
int | namesize | ||
) |
Retrieive the name of a cluster member.
handle | Handle to a database cluster design obtained using the TdbGetClusterDesign() function. |
position | The 1-based position of the cluster member to retrieve. |
name | Character string buffer to receive a cluster member name |
namesize | The allocated size of the name buffer |
This function is used to retrieve the name of the cluster member identified by the position
parameter. The upper range limit of the position
is the number of members in the cluster, and can be obtained using the TdbGetClusterProperty() function with the CLUSTER_PROPERTY_MEMBERCOUNT property ID.
int TdbCopyBaseDesign | ( | const char * | from_base, |
const char * | to_base, | ||
TdbHandle * | design | ||
) |
Create a copy of a database definition.
from_base | Name of (existing) database |
to_base | Name of (new) database |
design | Database specification record |
The function TdbCopyBaseDesign() initiates the copying of one database design to another of a different name. Upon a successful return the design
parameter will contain a handle to a new database design 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 TdbPutBaseDesign() function.
Note that the database file name properties (for the BAF, BIF, VIF and LOG files) are not copied by this operation.
The from_base
parameter is passed a character string as the name of the existing database whose design is to be copied.
The to_base
parameter is passed a character string as the name of the new database.
The design
parameter is passed a pointer to a TdbHandle variable that will receive the database design record for the new database. Values will be copied form the equivalent record for the old database. The handle must be explicitly released using TdbCloseBaseDesign() when the application no longer needs it.
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. |
This function was introduced in TRIP version 8.0-0.
int TdbCopyClusterDesign | ( | TdbHandle | sourceHandle, |
const char * | newName, | ||
TdbHandle * | targetHandle | ||
) |
Copy a database cluster.
sourceHandle | Handle to cluster to copy |
newName | Name of new cluster to create |
targetHandle | Receives a handle to the cluster copy |
This function copies a database cluster. The new cluster must be committed by passing the targetHandle
to the TdbPutClusterDesign() function.
The sourceHandle
parameter is passed a handle to a cluster design to be copied. This handle is obtained using TdbGetClusterDesign().
The newName
parameter identifies the name of the new cluster to create.
The targetHandle
parameter is a pointer to a TdbHandle variable that recieves a handle to the copy the the source cluster. The new cluster must be committedto the CONTROL database by calling the TdbPutClusterDesign() function with this handle as argument.
int TdbCopyThesDesign | ( | const char * | from_thes, |
const char * | to_thes, | ||
TdbHandle * | design | ||
) |
Create a copy of a thesaurus definition.
from_thes | Name of source thesaurus |
to_thes | Name of new thesaurus |
design | 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 design
parameter is passed a pointer to a TdbHandle variable that will receive the thesaurus specification for the newly created thesaurus.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
int TdbDeleteBaseDef | ( | ) |
Delete a previously loaded database design.
The function TdbDeleteBaseDef() deletes the database design previously loaded by a call to TdbCheckBase() or TdbGetBaseDesign(). Any entry forms or output formats defined for the database are also deleted.
This deletion affects not only the database itself, but also any users or groups who had access to that database have their access removed. Considerable care should be exercised in calling this function as other users may have the database open when this function is called. Those other users may experience unexpected behavior from any TRIP application including TRIPclassic and TRIPmanager.
The database must be empty at the time of deletion.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
32579 | Database design for name deleted. | 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. |
2498 | You have no FM access to the database. | The logged on user need to have file manager rights in order to use this function. |
7938 | The database name is not empty. | There must not be any records in a database that is to be deleted. |
int TdbDeleteBaseField | ( | TdbHandle * | fieldHandle | ) |
Delete a field from a database design.
fieldHandle | [IN/OUT] Handle to a field in a database design |
The function TdbDeleteFieldSpec() deletes a given field from a database design in memory, which must have previously been loaded using TdbGetBaseDesign(), and the field design must have been loaded by calling the TdbGetBaseField() function. Upon a subsequent call to TdbPutBaseDesign(), the field will be deleted from the data dictionary. This routine can only be used successfully when the database is empty.
The fieldHandle
parameter is passed a pointer to a TdbHandle
variable that refers to the field design to delete. The handle variable that the parameter points to will be set to NULL upon successful completion of this function.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
This function was introduced in TRIP version 8.0.
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 TdbDeleteBaseFieldGroup | ( | TdbHandle * | handle | ) |
Delete a database field group.
handle | [IN/OUT] Pointer to field group handle for the field group to delete |
The function TdbDeleteBaseFieldGroup() removes a field group from its database design. The field group must have been loaded by a call to the TdbGetBaseFieldGroup() function and the database design must have been opened in write mode.
To commit the removal of the field group to CONTROL, along with other modifications made to the database design, call TdbPutBaseDesign().
The handle
parameter is passed a pointer to the field group handle to delete. The handle variable that the parameter points to will be set to NULL upon successful completion of this function.
This function was introduced in TRIP version 8.0.
int TdbDeleteDbCluster | ( | void | ) |
Delete a database cluster.
The function TdbDeleteDbCluster() deletes a database cluster from the data dictionary. Any user access to that cluster is also removed. The cluster to be deleted must have been previously loaded by a call to the TdbGetClusterDesign() function.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
36163 | Database cluster name deleted. | 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. |
16770 | You are not the owner of this DB cluster. |
int TdbDeleteDefaultValue | ( | Char * | fieldName | ) |
Remove any existing default value for a field.
fieldName | Name of field to remove the default value from |
The database design must have been opened in write mode using either TdbGetBaseDesign() or TdbGetBaseDef().
int TdbDeleteForeignKey | ( | Char * | keyfield | ) |
Remove a foreign key from the current database.
keyfield | Name of a foreign key field in the current database |
This will also follow the reference and remove it from the the associated database design.
The database design must have been opened in write mode using either TdbGetBaseDesign() or TdbGetBaseDef().
int TdbDeleteIntegrityRules | ( | ) |
Delete all integrity rules for the current database.
Each rule is followed to its associated other database and corresponding rule in that database is also deleted.
The database design must have been opened in write mode using either TdbGetBaseDesign() or TdbGetBaseDef().
int TdbDeleteThesDef | ( | void | ) |
Delete a thesaurus definition.
The function TdbDeleteThesDef() deletes the thesaurus definition previously loaded via a call to the TdbCheckThes() function.
The current TRIPsystem user must possess the (file manager) FM privilege to execute this function.
Code | Description | Explanation |
---|---|---|
34403 | Thesaurus design for name deleted. | 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. |
12450 | Predefined system thesaurus THES cannot be deleted. | |
8386 | You have no FM access to the thesaurus name. | The current user need to be file manager in order to access this function. |
8322 | The thesaurus name is not empty. | Only empty thesauri may be deleted. |
int TdbFieldGroupAddField | ( | TdbHandle | handle, |
const char * | field_name | ||
) |
Add a field to a field group.
handle | Field group handle |
field_name | Name of field to add |
Add a field to a field group from the database that the field group is associated with. The database design must have been opened in write mode.
A field group with part record fields can only contain part record fields. You cannot mix head and part record fields in the same group.
To save the changes to the field group, call TdbPutBaseFieldGroup() when all fields have been added. To commit the database design with the new or updated field group to CONTROL, call TdbPutBaseDesign() afterwards.
This function was introduced in TRIP version 8.0.
int TdbFieldGroupDelField | ( | TdbHandle | handle, |
const char * | field_name | ||
) |
Remove a field from a field group.
handle | Field group handle |
field_name | Name of field to remove |
Remove a field from a field group. The database design must have been opened in write mode.
To save the changes to the field group, call TdbPutBaseFieldGroup(). To commit the database design with the updated field group to CONTROL, call TdbPutBaseDesign() afterwards.
This function was introduced in TRIP version 8.0.
int TdbFieldGroupGetField | ( | TdbHandle | field_group_handle, |
TdbHandle * | field_handle, | ||
const char * | field_name, | ||
int | ordinal | ||
) |
Retrieve a field from a field group.
field_group_handle | [IN] Handle to a field group |
field_handle | [OUT] Receives a handle to the requested field design |
field_name | [IN] Name of field to retrieve, or NULL to retrieve by ordinal |
ordinal | [IN] Ordinal number of field to retrieve, or 0 (zero) to retrieve by name |
Retrieve the design object for a field in a field group. The database design must have been opened in at least read mode. The ordinal
parameter, if assigned, has a value unique to the field group and goes from 1 to the total number of fields in the group.
The properties of the returned field can be inspected and modified using the TdbGetFieldProperty() and TdbPutFieldProperty() methods. To modify the field design, the database design must have been opened in write mode.
This function was introduced in TRIP version 8.0.
int TdbFreeIntegrityRules | ( | base_integrity_spec * | rules | ) |
Release an integrity rules structure.
rules | Pointer to the rules instance to release |
This function must be called to release the memory and resources associated with the data returned by TdbGetIntegrityRules().
int TdbGetBaseDesign | ( | TdbHandle * | handle, |
const char * | base, | ||
int | accessMode | ||
) |
Load a database design.
handle | Pointer to a TdbHandle variable that receives a handle to the database design. |
base | Name of database |
accessMode | Access rights required to the database design |
This function loads the definition of the specified TRIP database and returns a handle
to it. Use the TdbGetBaseProperty() function to read the properties of the database design.
The accessMode
parameter specifies how the calling process intends to use the database design. Valid values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
MODE_READ | bit 0 | Require read access to the database design |
MODE_WRITE | bit 1 | Require modify access to the database design |
MODE_DELETE | bit 2 | Require delete access to the database design |
MODE_COPY | bit 3 and bit 1 | Require copy access to the database design |
The current TRIPsystem user must possess the (file manager) FM privilege to execute this function unless the accessMode
is set to MODE_READ.
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. This is expected when creating a new database. |
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 TdbGetBaseField | ( | TdbHandle * | fieldHandle, |
TdbHandle | baseHandle, | ||
const char * | fieldName, | ||
int | ordinal | ||
) |
Load a field specification from a database design.
fieldHandle | Pointer to a handle receieving the field design |
baseHandle | Handle to a database design |
fieldName | Name of field to retrieve or NULL to retrieve by ordinal |
ordinal | Ordinal number of field to retrieve or 0 (zero) to retrieve by name |
This function loads the specification for a database field and returns a handle to it in the fieldHandle
parameter. The field can either be loaded via its name or by its ordinal number. The ordinal number for a field is not the same as the field number, and always goes from 1 to the total number of fields.
A call to the function TdbGetBaseDesign() has to have preceded a call to this function.
The fieldHandle
parameter is passed a pointer to a TdbHandle variable that will receive a handle to the field on output. The handle must be released by calling TdbCloseBaseField() when the application no longer needs it.
The baseHandle
parameter is a handle to a database design opened via the TdbGetBaseDesign() function.
The fieldName
parameter names the field to load, or NULL if the field is to be loaded via its ordinal number.
The ordinal
parameter specifies the ordinal number of the field to load, or 0 (zero) if the field is to be loaded via its name. The ordinal number is always in the range 1 to the number of fields in the database, and is not related to field number.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function if the database design handle has been opened with any other access mode than MODE_READ.
This function was introduced in TRIP version 8.0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Could not get field specification. |
int TdbGetBaseFieldByNumber | ( | TdbHandle * | fieldHandle, |
TdbHandle | baseHandle, | ||
int | fieldNumber | ||
) |
Load a field specification from a database design.
fieldHandle | Pointer to a handle receieving the field design |
baseHandle | Handle to a database design |
fieldNumber | The number of the field to retrieve |
This function loads the specification for a database field and returns a handle to it in the fieldHandle
parameter. The field is loaded by its assigned number.
A call to the function TdbGetBaseDesign() has to have preceded a call to this function.
The fieldHandle
parameter is passed a pointer to a TdbHandle variable that will receive a handle to the field on output. The handle must be released by calling TdbCloseBaseField() when the application no longer needs it.
The baseHandle
parameter is a handle to a database design opened via the TdbGetBaseDesign() function.
The fieldNumber
parameter specifies the number of the field to load. Note that this is not an ordinal number and that fields in a database may have gaps in their numbering.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function if the database design handle has been opened with any other access mode than MODE_READ.
This function was introduced in TRIP version 8.0.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
0 | Could not get field specification. |
int TdbGetBaseFieldGroup | ( | TdbHandle * | fgrp_design_handle, |
TdbHandle | base_design_handle, | ||
const char * | name, | ||
int | ordinal | ||
) |
Load a field group definition from a database design.
fgrp_design_handle | [OUT] Receives a handle to the field group |
base_design_handle | [IN] Handle to a database design |
name | [IN] Name of field group to retrieve (or NULL to retrieve by ordinal) |
ordinal | [IN] Ordinal number of field group to retrieve (or zero to retrieve by name) |
Loads a field group definition from a database design and makes it accessible via a handle (the fgrp_design_handle
parameter). If the named field group does not exist and the database design is opened in write mode, a new field group will be initialized.
This function was introduced in TRIP version 8.0.
int TdbGetBaseProperty | ( | TdbHandle | handle, |
int | property_id, | ||
int * | numeric_value, | ||
char * | string_value_buffer, | ||
int | string_buffer_size | ||
) |
Retreieve database design properties.
handle | Handle to a database design obtained from TdbGetBaseDesign() |
property_id | The ID of the property to retrieve |
numeric_value | Receives property values returned as integers. |
string_value_buffer | Receives property values returned as strings. |
string_buffer_size | the allocated size of string_value_buffer . |
This function retrieves the value of the database design property identified by the property_id
parameter. Valid property IDs are:
Property ID | Returned As | Description |
---|---|---|
BASE_PROPERTY_NAME | String | The name of the database |
BASE_PROPERTY_COMMENT | String | The description of the database |
BASE_PROPERTY_LOCATION | String | The storage loction of the database. This is the configuration symbol (as entered into TDBS_CONF) or the directory path, depending on which was entered into the database design. This property is only valid if all database files share the same storage location. |
BASE_PROPERTY_BAF_FILE | String | The BAF file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.BAF) |
BASE_PROPERTY_BIF_FILE | String | The BIF file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.BIF) |
BASE_PROPERTY_VIF_FILE | String | The VIF file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.VIF) |
BASE_PROPERTY_LOG_FILE | String | The LOG file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.LOG) |
BASE_PROPERTY_WORD_CHARS | String | A list of special searchable characters for the database |
BASE_PROPERTY_BAFFIT_ASE1 | String | The name of an ASE to be called during TFORM load before a record is committed to the BAF. |
BASE_PROPERTY_BAFFIT_ASE2 | String | The name of an ASE to be called during TFORM load after a record is committed to the BAF. |
BASE_PROPERTY_CONTAINER | String | The name of the classification container used by the database. |
BASE_PROPERTY_IS_XML | Integer | A True/False flag determining whether the database is XML enabled. |
BASE_PROPERTY_IS_GRAPH | Integer | A True/False flag determining whether the database is graph enabled. |
BASE_PROPERTY_IS_CONNECTOR | Integer | A True/False flag determining whether the database is a connector database. |
BASE_PROPERTY_CHI_WORDS | Integer | Type type of Chinese word segmentation to use with this database. 0 = none, 1 = max, 2 = all, 3 = word. |
BASE_PROPERTY_USE_AUTO_REORG | Integer | A True/False flag determining whether the database is allowed to perform automatic index reorganisation during the indexing process. |
BASE_PROPERTY_USE_AUDIT | Integer | A True / False flag determining whether the database is to create an audit trail for each user of the database. Note that this functionality has been superceded by the DEBIT functions as documented in the TRIP Manager Guide. |
BASE_PROPERTY_USE_LOG_DELETE | Integer | A True / False flag determining whether the database logfile will record the entire content of deleted records. |
BASE_PROPERTY_PID_FIELD | Integer | The name of the record part name field. |
BASE_PROPERTY_CHARSET | String | The name of the character set that the database uses. New databases should use UTF. For a complete list, consult the TRIP Manager Guide. |
BASE_PROPERTY_LANGUAGE | String | The three-letter code for the natural language primarily used by the text and phrase values in the database. |
BASE_PROPERTY_APPL_ID | String | An application specific id string, not used by TRIP itself. |
BASE_PROPERTY_OUTPUT_FORMAT | String | The name of the default output format |
BASE_PROPERTY_ENTRY_FORM | String | The name of the default TRIPclassic entry form |
BASE_PROPERTY_RID_FIELD | String | The name of the record name field |
BASE_PROPERTY_COUNTER_FIELD | String | The name of the record number field |
BASE_PROPERTY_CHAR_FOLDING | String | The character folding class for the database. This is a three-letter code for a natural language supported by TRIP. |
This function was introduced in TRIP version 8.0.
int TdbGetClusterDesign | ( | TdbHandle * | cluster_handle, |
const char * | cluster_name, | ||
int | access_mode | ||
) |
Load a database cluster specification.
cluster_handle | Receives a handle to the cluster specification |
cluster_name | Name of cluster to retrieve |
access_mode | How to open the cluster specification |
The function TdbGetClusterDesign() loads and makes current the specification of a stored database cluster.
The cluster_handle
parameter is passed a TdbHandle variable that will receieve a handle to the cluster specification on output. The handle must be closed by calling TdbCloseClusterDesign() when the application is done with it.
The cluster_name
parameter is passed a character string as the name of the cluster whose specification record is to be retrieved.
The access_mode
parameter is passed an int
as the access mode for the cluster specification. Valid values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
MODE_READ | bit 0 | Require read access to the cluster |
MODE_WRITE | bit 1 | Require modify access to the cluster |
MODE_DELETE | bit 2 | Require delete access to the cluster |
MODE_COPY | bit 3 and bit 1 | Require copy access to the cluster |
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function with an access mode other than MODE_READ
.
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 TdbGetClusterProperty | ( | TdbHandle | handle, |
int | property_id, | ||
int * | numeric_value, | ||
char * | string_value_buffer, | ||
int | string_buffer_size | ||
) |
Retrieve a property of a database cluster.
handle | Handle to a database cluster design obtained using the TdbGetClusterDesign() function. |
property_id | ID of property to retrieve. |
numeric_value | Pointer to an integer that receives property values returned as integers. |
string_value_buffer | A character string buffer that receives property values returned as character string data. |
string_buffer_size | The allocated size of the string_value_buffer parameter. |
This function retrieves the value of the cluster design property identified by the property_id
parameter. Valid property IDs are:
Property ID | Returned As | Description |
---|---|---|
CLUSTER_PROPERTY_NAME | String | The name of the cluster |
CLUSTER_PROPERTY_COMMENT | String | The description of the cluster |
CLUSTER_PROPERTY_MEMBERCOUNT | Integer | The number of members in the cluster |
int TdbGetDbAccess | ( | char * | user, |
base_access_rec * | baseAccess | ||
) |
Load the base access record for a TRIP user.
user | Name of user |
baseAccess | Base access record |
The function TdbGetDbAccess() reads from the CONTROL file the base access record for the specified user and the database, thesaurus or cluster previously loaded by a call to one of the TdbCheckBase(), TdbCheckThes() or TdbCheckDbCluster() functions. The base
access parameter to those routines must have specified the CHECK_OWNERSHIP
option.
Each byte in the base access record that is used to specify the total/selective field access is a bit mask where bit 0 indicates read access and bit 1 write access.
The user
parameter is passed a character string as the name of the user whose base access record is to be retrieved.
The baseAccess
parameter is passed a base access record structure to receive the base access record for the user.
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. |
2498 | You have no FM access to the database. | |
9794 | You are not a file manager. | |
9634 | No such user as name. | |
10562 | You are the owner of this database, and have all rights. |
int TdbGetDefaultValue | ( | Char * | fieldName, |
Char * | fieldValue, | ||
int * | fieldLength | ||
) |
Retrieve the default value for the specified field.
fieldName | Name of field for which to retrieve the default value |
fieldValue | Buffer to receive the default value |
fieldLength | Allocated size of the fieldValue buffer |
The database design must have been opened in read or write mode using either TdbGetBaseDesign() or TdbGetBaseDef().
If no default value is defined, the function returns 0, otherwise it copies the default value to the provider fieldValue
buffer. If the buffer pointed to by fieldValue
is of insufficient size (as defined by fieldLength
on input), the function will return an error and fieldLength
will contain the number of bytes required in the buffer.
int TdbGetFieldGroupProperty | ( | TdbHandle | handle, |
int | property_id, | ||
int * | numeric_value, | ||
char * | string_value_buffer, | ||
int | string_buffer_size | ||
) |
Retrieve field group properties.
handle | Field group handle |
property_id | ID of the field group property to retrieve |
numeric_value | Receives property values returned as integers. |
string_value_buffer | Receives property values returned as strings. |
string_buffer_size | the allocated size of string_value_buffer . |
This function retrieves the value of the field group design property identified by the property_id
parameter. Valid property IDs are:
Property ID | Returned As | Description |
---|---|---|
FGROUP_PROPERTY_NAME | String | The name of the field group |
FGROUP_PROPERTY_NUMBER | Integer | Numeric ID of the field group |
FGROUP_PROPERTY_TYPE | Integer | The type of the field group (FGROUP_TYPE_*) |
FGROUP_PROPERTY_TYPENAME | String | The type of the field group as a string |
FGROUP_PROPERTY_COMMENT | String | Description of the field group |
FGROUP_PROPERTY_SIZE | Integer | Number of fields in the field group |
FGROUP_PROPERTY_FIELDS | String or Integer | If numeric_value is provided and string_value_buffer is NULL, numeric_value will receive the size of the string buffer that is required. If string_value_buffer is not NULL, it will receive a comma separated list of the names of the fields in the group. |
This function was introduced in TRIP version 8.0.
int TdbGetFieldProperty | ( | TdbHandle | handle, |
int | property_id, | ||
int * | numeric_value, | ||
char * | string_value_buffer, | ||
int | string_buffer_size | ||
) |
Retrieve a field design property.
handle | Handle to a field obtained using TdbGetBaseField() |
property_id | ID of property to retrieve |
numeric_value | Receives integer property values |
string_value_buffer | Receives string property values |
string_buffer_size | Allocated size of string_value_buffer |
Retrieves a property of a field design. The field design is identified by the handle
parameter and the type of property to retreieve is identified by the property_id
parameter.
Valid values for property_id
are:
Property ID | Type | Description |
---|---|---|
FIELD_PROPERTY_NAME | String | Field name |
FIELD_PROPERTY_NUMBER | Integer | Field number |
FIELD_PROPERTY_TYPE_NAME | String | Field type name |
FIELD_PROPERTY_TYPE_NUMBER | Integer | Field type number |
FIELD_PROPERTY_TYPE | String + Integer | Field type and number |
FIELD_PROPERTY_COPYRIGHT_FIELD | String | Copyright field name |
FIELD_PROPERTY_INDEX_MODE | Integer | Field indexing mode |
FIELD_PROPERTY_IS_ORIG | Integer | Indicates if the TEXT or PHRASE field stores values in their exact, original form, or if processing to identify sentences and paragraphs is done. |
FIELD_PROPERTY_IS_RID_FIELD | Integer | Indicates if the PHRASE field is a record name field |
FIELD_PROPERTY_HAS_PATTERN | Integer | Indicates if the field has a value restriction pattern |
FIELD_PROPERTY_HAS_FILE_REF | Integer | Indicates if the field's values are restricted by a field in another database |
FIELD_PROPERTY_IS_PID_FIELD | Integer | Indicates if the field is a part name field |
FIELD_PROPERTY_HAS_DEFAULT | Integer | Indicates if the field has a default value |
FIELD_PROPERTY_IS_UNIQUE | Integer | Indicates if the field value must be unique |
FIELD_PROPERTY_HAS_CONCORDANCE | Integer | Indicates if the field is used with the built-in text classifiction |
FIELD_PROPERTY_IS_COUNTER_FIELD | Integer | Indicates if the field is a record number field |
FIELD_PROPERTY_IS_PART_FIELD | Integer | Indicates if the field is a part record field |
FIELD_PROPERTY_COST | Integer | Access cost of the field |
FIELD_PROPERTY_MIN_ITEMS | Integer | Minimum number of subfields |
FIELD_PROPERTY_MAX_ITEMS | Integer | Maximum number of subfields, or zero if there is no upper limit. |
FIELD_PROPERTY_COMMENT | String | Description of the fielf |
FIELD_PROPERTY_RESTRICTIONS | String | Field value restriction definition |
FIELD_PROPERTY_LOAD_ASE | String | Name of ASE routine to call during TFORM load |
FIELD_PROPERTY_INDEX_ASE | String | Name of ASE routine to call during indexing |
The field type number property (FIELD_PROPERTY_TYPE_NUMBER) can return the following values:
Symbolic Name | Constant Value | Purpose |
---|---|---|
FIELD_TEXT | 1 | TExt type field |
FIELD_PHRASE | 3 | PHRase type field |
FIELD_INTEGER | 9 | INteger type field |
FIELD_NUMBER | 10 | NUMber type field |
FIELD_DATE | 11 | DAte type field |
FIELD_TIME | 12 | TIme type field |
FIELD_STRING | 14 | STring type field |
The field index mode property (FIELD_PROPERTY_INDEX_MODE) is a bit mask that can have a combination of the following values:
Symbolic Name | Constant Value | Purpose |
---|---|---|
FIELD_INDEX_NONE | 0 | Not indexed |
FIELD_INDEX_NORMAL | 1 | Indexed normally |
FIELD_INDEX_WORD | 5 | Word-indexed |
FIELD_INDEX_SEPARATE | 17 | Separately indexed |
FIELD_INDEX_CLASS | 33 | Field is used in classification |
This function was introduced in TRIP version 8.0.
int TdbGetIntegrityRules | ( | base_integrity_spec ** | rules | ) |
Retrieve the integrity rules for the current database.
rules | Receives a pointer to an integrity rules structure |
The database design must have been opened in read or write mode using either TdbGetBaseDesign() or TdbGetBaseDef().
Rules will either define an outgoing or incoming foreign key specification. The function allocates memory as required, and returns a pointer to that memory in the rules
argument.
This memory cannot be released by the calling application as it is kernel memory, and must instead be released by calling TdbFreeIntegrityRules().
int TdbGetTextSeparators | ( | text_sepa_rec * | separatorSpec | ) |
Load a text separator specification.
separatorSpec | Separator specification record |
The function TdbGetTextSeparators() loads the separator specification record of a database into the given record area. It can only be used after calling the TdbGetBaseDesign() function.
The separatorSpec
parameter is passed a separator specification record to receive the separator specification record for the 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. |
int TdbGetThesDesign | ( | TdbHandle * | handle, |
const char * | name, | ||
int | accessMode | ||
) |
Load a thesaurus design.
handle | Pointer to a TdbHandle variable that receives a handle to the thesaurus design. |
name | Name of thesaurus |
accessMode | Access rights required to the thesaurus design |
This function loads the definition of the specified TRIP thesaurus and returns a handle
to it. Use the TdbGetBaseProperty() function to read the properties of the thesaurus design.
The accessMode
parameter specifies how the calling process intends to use the database design. Valid values are:
Symbolic Name | Constant Value | Purpose |
---|---|---|
MODE_READ | bit 0 | Require read access to the thesaurus design |
MODE_WRITE | bit 1 | Require modify access to the thesaurus design |
MODE_DELETE | bit 2 | Require delete access to the thesaurus design |
MODE_COPY | bit 3 and bit 1 | Require copy access to the thesaurus design |
The current TRIPsystem user must possess the (file manager) FM privilege to execute this function unless the accessMode
is set to MODE_READ.
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 TdbPutBaseDesign | ( | TdbHandle | handle | ) |
Store a database definition.
handle | Database design handle |
The function TdbPutBaseDesign() writes the database definition assocated with the provided handle
into the CONTROL file. A call to this function must have been preceded by a call to either of the TdbGetBaseDesign() or TdbCopyBaseDesign() functions.
The handle
parameter is passed handle to the database obtained via either of the TdbGetBaseDesign() or TdbCopyBaseDesign() functions.
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 TdbPutBaseField | ( | TdbHandle | handle | ) |
Store a field specification record.
handle | Field specification handle |
The function TdbPutBaseField() stores the field specification record referred to by the provided handle
into 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 design has been loaded by the TdbGetBaseDesign() and TdbGettBaseField() function have been called.
The handle
parameter is passed a handle to 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.
This function was introduced in TRIP version 8.0.
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 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 TdbPutBaseProperty | ( | TdbHandle | handle, |
int | property_id, | ||
int | numeric_value, | ||
const char * | string_value | ||
) |
Assign a database design property.
handle | Handle to a database design obtained from TdbGetBaseDesign() |
property_id | The ID of the property to assign |
numeric_value | Numeric property value |
string_value | String property value |
This function retrieves the value of the database design property identified by the property_id
parameter. Valid property IDs are:
Property ID | Value Type | Description |
---|---|---|
BASE_PROPERTY_NAME | String | The name of the database |
BASE_PROPERTY_COMMENT | String | The description of the database |
BASE_PROPERTY_LOCATION | String | The storage loction of the database. This is the configuration symbol (as entered into TDBS_CONF) or the directory path, depending on which was entered into the database design. This property is only valid if all database files share the same storage location. |
BASE_PROPERTY_BAF_FILE | String | The BAF file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.BAF) |
BASE_PROPERTY_BIF_FILE | String | The BIF file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.BIF) |
BASE_PROPERTY_VIF_FILE | String | The VIF file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.VIF) |
BASE_PROPERTY_LOG_FILE | String | The LOG file path. Is either a fully qualified path or the filename prefixed by a configuration symbol indicating a storage location (e.g. MYLOCATION:MYBASE.LOG) |
BASE_PROPERTY_WORD_CHARS | String | A list of special searchable characters for the database |
BASE_PROPERTY_BAFFIT_ASE1 | String | The name of an ASE to be called during TFORM load before a record is committed to the BAF. |
BASE_PROPERTY_BAFFIT_ASE2 | String | The name of an ASE to be called during TFORM load after a record is committed to the BAF. |
BASE_PROPERTY_CONTAINER | String | The name of the classification container used by the database. |
BASE_PROPERTY_IS_XML | Integer | A True/False flag determining whether the database is XML enabled. |
BASE_PROPERTY_IS_GRAPH | Integer | A True/False flag determining whether the database is graph enabled. |
BASE_PROPERTY_IS_CONNECTOR | Integer | A True/False flag determining whether the database is a connector database. |
BASE_PROPERTY_CHI_WORDS | Integer | Type type of Chinese word segmentation to use with this database. 0 = none, 1 = max, 2 = all, 3 = word. |
BASE_PROPERTY_USE_AUTO_REORG | Integer | A True/False flag determining whether the database is allowed to perform automatic index reorganisation during the indexing process. |
BASE_PROPERTY_USE_AUDIT | Integer | A True / False flag determining whether the database is to create an audit trail for each user of the database. Note that this functionality has been superceded by the DEBIT functions as documented in the TRIP Manager Guide. |
BASE_PROPERTY_USE_LOG_DELETE | Integer | A True / False flag determining whether the database logfile will record the entire content of deleted records. |
BASE_PROPERTY_PID_FIELD | Integer | The name of the record part name field. |
BASE_PROPERTY_CHARSET | String | The name of the character set that the database uses. New databases should use UTF. For a complete list, consult the TRIP Manager Guide. |
BASE_PROPERTY_LANGUAGE | String | The three-letter code for the natural language primarily used by the text and phrase values in the database. |
BASE_PROPERTY_APPL_ID | String | An application specific id string, not used by TRIP itself. |
BASE_PROPERTY_OUTPUT_FORMAT | String | The name of the default output format |
BASE_PROPERTY_ENTRY_FORM | String | The name of the default TRIPclassic entry form |
BASE_PROPERTY_RID_FIELD | String | The name of the record name field |
BASE_PROPERTY_COUNTER_FIELD | String | The name of the record number field |
BASE_PROPERTY_CHAR_FOLDING | String | The character folding class for the database. This is a three-letter code for a natural language supported by TRIP. |
The field language (BASE_PROPERTY_LANGUAGE) and character folding (BASE_PROPERTY_CHAR_FOLDING) properties have the following valid values:
Language Code | Language Name | Language Effects | Character Folding Effects |
---|---|---|---|
ENG | English | English stemmer may be used | Diacritic characters such as Ä will be indexed and searched as their non-diacritic form. |
FIN | Finnish | Finnish stemmer may be used | Diacritic characters other than ä and ö will be indexed and searched as their non-diacritic form. |
GER | German | German stemmer may be used | Diacritic characters other than ü, ö, ä and ß will be indexed and searched as their non-diacritic form. |
NOR | Norwegian | Norwegian stemmer may be used | Diacritic characters other than Æ, ü and ø will be indexed and searched as their non-diacritic form. |
SWE | Swedish | Swedish stemmer may be used | Diacritic characters other than å, ä and ö will be indexed and searched as their non-diacritic form. |
The character set (BASE_PROPERTY_CHARSET) property has the following valid values.
Character Set | Description |
---|---|
UTF | Unicode UTF-8 |
LA1 | Windows-1252 (a variant of ISO-8859-1) |
LA2 | ISO-8859-2 |
LA3 | ISO-8859-3 |
GBK | Chinese national standard charatcter set |
The changes made to the database design using this function do not take effect immediately. Call the TdbPutBaseDesign() function to commit the design changes.
This function was introduced in TRIP version 8.0.
int TdbPutClusterDesign | ( | TdbHandle | handle | ) |
Store a database cluster specification.
handle | Handle to cluster obtained via TdbGetClusterDesign() |
The function TdbPutClusterDesign() will store the specification of a database cluster defined in the cluster specification design that the provided handle
refers to.
The cluster specification record must previously have been obtained by a call to the TdbGetClusterDesign() function.
The handle
parameter is passed a handle to a cluster specification, 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 TdbPutClusterProperty | ( | TdbHandle | handle, |
int | property_id, | ||
int | numeric_value, | ||
const char * | string_value | ||
) |
Assign a property of a database cluster.
handle | Handle to a database cluster design obtained using the TdbGetClusterDesign() function. |
property_id | ID of property to retrieve. |
numeric_value | Assign the value of an integer based property. |
string_value | Assign the value of a character string based property. |
This function is used to assign the value of the cluster design property identified by the property_id
parameter. Valid property IDs are:
Property ID | Value Type | Description |
---|---|---|
CLUSTER_PROPERTY_COMMENT | String | The description of the cluster |
To commit the changes, call the TdbPutClusterDesign() function.
int TdbPutDbAccess | ( | base_access_rec * | baseAccess | ) |
Store the base access record for a TRIP user.
baseAccess | Base access record |
The function TdbPutDbAccess() writes to the CONTROL file the base access record previously loaded by a call to the TdbGetDbAccess() function. Before the access record can be obtained, however, the function TdbCheckBase() have been called, specifying access mode CHECK_OWNERSHIP option.
Each byte in the base access record used to specify the total/selective field access is a bit mask where bit 0 indicates read access and bit 1 write access.
The baseAccess
parameter is passed a base access record to describe the access rights to the database for the user.
The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
33219 | User username has access to database dbname. | Operation completed successfully - specified user was granted access to the database. |
33283 | Group groupname has access to database dbname. | Operation completed successfully - specified group was granted access to the database. |
33283 | Group groupname has lost access to database dbname. | Operation completed successfully - access to the database was revoked from the specified group. |
33347 | Group groupname has lost access to database dbname. | Operation completed successfully - access to the database was revoked from the specified group. |
38755 | User username has no access to database dbname. | Operation completed successfully. Access to the database was revoked from a user who did not have access to it. |
38787 | Group groupname has no access to database dbname. | Operation completed successfully. Access to the database was revoked from a group that did not have access to it. |
9794 | You are not a file manager. |
int TdbPutDefaultValue | ( | Char * | fieldName, |
Char * | fieldValue | ||
) |
Set the default value for a field.
fieldName | Name of field to assign a default value to |
fieldValue | Default value to assign |
The database design must have been opened in write mode using either TdbGetBaseDesign() or TdbGetBaseDef().
If the value is invalid for the field defined, the function returns an appropriate error code. Equally, if the field is not of a type that can accept a default, the function returns an appropriate error code.
int TdbPutFieldGroupProperty | ( | TdbHandle | handle, |
int | property_id, | ||
int | numeric_value, | ||
const char * | string_value | ||
) |
Assign field group properties.
handle | Field group handle |
property_id | ID of the field group property to assign |
numeric_value | Numeric property value |
string_value | String property value |
This function assigns the value of the field group design property identified by the property_id
parameter. Valid property IDs are:
Property ID | Returned As | Description |
---|---|---|
FGROUP_PROPERTY_NAME | String | The name of the field group |
FGROUP_PROPERTY_TYPE | Integer | The type of the field group (FGROUP_TYPE_*) |
FGROUP_PROPERTY_TYPENAME | String | The type of the field group as a string |
FGROUP_PROPERTY_COMMENT | String | Description of the field group |
This function was introduced in TRIP version 8.0.
int TdbPutFieldProperty | ( | TdbHandle | field_design_handle, |
int | property_id, | ||
int | numeric_value, | ||
const char * | string_value | ||
) |
Assign a field design property.
field_design_handle | Handle to a field obtained using TdbGetBaseField() |
property_id | ID of property to assign |
numeric_value | Integer property value |
string_value | String property value |
Assigns a property to a field design. The field design is identified by the handle
parameter and the type of property to retreieve is identified by the property_id
parameter.
Valid values for property_id
are:
Property ID | Type | Description |
---|---|---|
FIELD_PROPERTY_NAME | String | Field name |
FIELD_PROPERTY_NUMBER | Integer | Field number |
FIELD_PROPERTY_TYPE_NAME | String | Field type name |
FIELD_PROPERTY_TYPE_NUMBER | Integer | Field type number |
FIELD_PROPERTY_TYPE | String + Integer | Field type and number |
FIELD_PROPERTY_COPYRIGHT_FIELD | String | Copyright field name |
FIELD_PROPERTY_INDEX_MODE | Integer | Field indexing mode |
FIELD_PROPERTY_IS_ORIG | Integer | Indicates if the TEXT or PHRASE field stores values in their exact, original form, or if processing to identify sentences and paragraphs is done. |
FIELD_PROPERTY_IS_RID_FIELD | Integer | Indicates if the PHRASE field is a record name field |
FIELD_PROPERTY_HAS_PATTERN | Integer | Indicates if the field has a value restriction pattern |
FIELD_PROPERTY_HAS_FILE_REF | Integer | Indicates if the field's values are restricted by a field in another database |
FIELD_PROPERTY_IS_PID_FIELD | Integer | Indicates if the field is a part name field |
FIELD_PROPERTY_HAS_DEFAULT | Integer | Indicates if the field has a default value |
FIELD_PROPERTY_IS_UNIQUE | Integer | Indicates if the field value must be unique |
FIELD_PROPERTY_HAS_CONCORDANCE | Integer | Indicates if the field is used with the built-in text classifiction |
FIELD_PROPERTY_IS_COUNTER_FIELD | Integer | Indicates if the field is a record number field |
FIELD_PROPERTY_IS_PART_FIELD | Integer | Indicates if the field is a part record field |
FIELD_PROPERTY_COST | Integer | Access cost of the field |
FIELD_PROPERTY_MIN_ITEMS | Integer | Minimum number of subfields |
FIELD_PROPERTY_MAX_ITEMS | Integer | Maximum number of subfields, or zero if there is no upper limit. |
FIELD_PROPERTY_COMMENT | String | Description of the fielf |
FIELD_PROPERTY_RESTRICTIONS | String | Field value restriction definition |
FIELD_PROPERTY_LOAD_ASE | String | Name of ASE routine to call during TFORM load |
FIELD_PROPERTY_INDEX_ASE | String | Name of ASE routine to call during indexing |
The field type number property (FIELD_PROPERTY_TYPE_NUMBER) can return the following values:
Symbolic Name | Constant Value | Purpose |
---|---|---|
FIELD_TEXT | 1 | TExt type field |
FIELD_PHRASE | 3 | PHRase type field |
FIELD_INTEGER | 9 | INteger type field |
FIELD_NUMBER | 10 | NUMber type field |
FIELD_DATE | 11 | DAte type field |
FIELD_TIME | 12 | TIme type field |
FIELD_STRING | 14 | STring type field |
The field index mode property (FIELD_PROPERTY_INDEX_MODE) is a bit mask that can have a combination of the following values:
Symbolic Name | Constant Value | Purpose |
---|---|---|
FIELD_INDEX_NONE | 0 | Not indexed |
FIELD_INDEX_NORMAL | 1 | Indexed normally |
FIELD_INDEX_WORD | 5 | Word-indexed |
FIELD_INDEX_SEPARATE | 17 | Separately indexed |
FIELD_INDEX_CLASS | 33 | Field is used in classification |
Note that some of the properties (such as field type) cannot be altered if the database has contents.
The changes made to the field design using this function do not take effect immediately. Call TdbPutBaseField() store the design changes to the in-memory field design object, and TdbPutBaseDesign() to commit the database design.
This function was introduced in TRIP version 8.0.
int TdbPutTextSeparators | ( | text_sepa_rec * | separatorSpec | ) |
Store a text separator specification.
separatorSpec | Separator specification record |
The function TdbPutTextSeparators() stores the separator specification record into the internal database definition buffer that has been loaded using the TdbGetBaseDesign() function. A subsequent call to the function TdbPutBaseDesign() commits the database definition to the CONTROL file.
The separatorSpec
parameter is passed a separator 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. |
16642 | {cls} is not a valid separator class. | |
16674 | {chr} is not a valid class cls character. |
int TdbPutThesDesign | ( | TdbHandle | handle | ) |
Store a thesaurus definition.
handle | Handle to the thesaurus design to store |
This function the thesaurus definition assocated with the provided handle
into the CONTROL file. A call to this function must have been preceded by a call to either of the TdbGetThesDesign() or TdbCopyThesDesign() functions.
The handle
parameter is passed handle to the database obtained via either of the TdbGetThesDesign() or TdbCopyThesDesign() functions.
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 TdbSetForeignKey | ( | Char * | keyfield, |
Char * | parentdb, | ||
Char * | parentfld, | ||
int | upd, | ||
int | del | ||
) |
Establishes a new foreign key relationship.
keyfield | Phrase field to use as foreign key in current (dependent) database |
parentdb | Name of database the foreign key will refer to |
parentfld | Phrase field in parentdb that the foreign key will refer to |
upd | Integrity constraint for update operations in the parent database |
del | Integrity constraint for delete operations in the parent database |
Establishes a new foreign key relationship from a field in the child database to a field in a parent database (i.e. this function must always be called from the database holding the foreign key, not the database holding the master data). This API validates the foreign key definition, and then records an incoming link in the current database's CONTROL record, and an outgoing link in the parent database's CONTROL record.
The database design must have been opened in write mode using either TdbGetBaseDesign() or TdbGetBaseDef().
The integrity constraint values that may be used for the upd
and del
parameters are:
Constraint | Description |
---|---|
INTEGRITY_RESTRICT | Block the operation if foreign key constrains would be violated |
INTEGRITY_CASCADE | Cascade the update or delete operation to the dependent database |
INTEGRITY_NOACTION | Allow the operation, even if foreign key constrains would be violated |
INTEGRITY_SETNULL | Remove the value from the record(s) in the dependent database |
INTEGRITY_SETDEFAULT | Assign the value from the record(s) in the dependent database to their default. Requires that the foreign key field has been declared with a default value. |