TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
Database Management

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.
 

Detailed Description

Database administration and information.

The TRIPtoolkit database management functions offer functionality for querying status on and defining databases, clusters and thesauri.

Function Documentation

◆ TdbBaseInfo()

int TdbBaseInfo ( const char *  base,
int  mode,
char *  cvalue,
int *  ivalue 
)

Retrieve selected information about a database.

Parameters
baseDatabase name
modeMode of operation
cvalueInformation as character string
ivalueInformation as integer
Returns
1 or other odd value on success, even value on error

Description

Returns various information about a database.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

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

◆ TdbBaseStatus()

int TdbBaseStatus ( const char *  base,
char *  revisionDate,
char *  indexDate,
int *  recordCount 
)

Retrieve certain information concerning the state of a given database.

Parameters
baseName of the database.
revisionDateDate of last revision to database design.
indexDateDate of last index.
recordCountNumber of records in database.
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

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

◆ TdbCheckBase()

int TdbCheckBase ( const char *  base,
int  accessMode 
)

Check access rights to a database.

Parameters
baseName of database
accessModeAccess mode to be checked.
Returns
1 or other odd value on success, even value on error

Description

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 .

Parameter Values

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.

Return Codes

 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.
See also
TdbCheckDbCluster()
TdbGetDbAccess()
TdbPutDbAccess()
TdbSetBase()

◆ TdbCheckDbCluster()

int TdbCheckDbCluster ( const char *  clusterName,
int  accessMode 
)

Check access rights to a database cluster.

Parameters
clusterNameName of database cluster
accessModeAccess mode
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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

Return Codes

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

◆ TdbCheckFieldName()

int TdbCheckFieldName ( const char *  field_name)

Check for the existence of a field.

Parameters
field_nameName of field to check
Returns
1 or other odd value on success, even value on error

Description

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

See also
TdbGetBaseDesign()

◆ TdbCheckForeignKey()

int TdbCheckForeignKey ( Char *  keyfield,
Char *  parentdb,
Char *  parentfld 
)

Validates that the defined foreign key, when set, will succeed.

Parameters
keyfieldForeign key field in current database
parentdbName of associated database
parentfldField in associated database
Returns
1 or other odd value on success, even value on error

◆ TdbCheckThes()

int TdbCheckThes ( const char *  thesaurus,
int  accessMode 
)

Check access rights to a thesaurus.

Parameters
thesaurusName of thesaurus
accessModeAccess mode to be checked
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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

Return Codes

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

◆ TdbCloseBaseDesign()

int TdbCloseBaseDesign ( TdbHandle *  handle)

Close a database design handle.

Parameters
handlePointer to a handle to database obtained via the TdbGetBaseDesign() function. The handle value will be set to NULL upon successful completion of this function.
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbGetBaseDesign()

◆ TdbCloseBaseField()

int TdbCloseBaseField ( TdbHandle *  handle)

Closes a field specification handle.

Parameters
handlePointer to field handle returned from TdbGetBaseField()
Returns
1 or other odd value on success, even value on error

Description

The function TdbCloseBaseField() must be called to close a handle to a field specification when the application not longer needs it.

Parameter Values

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseField()
TdbGetFieldProperty()
TdbPutBaseField()
TdbPutFieldProperty()

◆ TdbCloseBaseFieldGroup()

int TdbCloseBaseFieldGroup ( TdbHandle *  handle)

Close a database field group.

Parameters
handle[IN/OUT] Pointer to field group handle returned from TdbGetBaseFieldGroup()
Returns
1 or other odd value on success, even value on error

Description

The function TdbCloseBaseFieldGroup() must be called to close a handle to a field specification when the application not longer needs it.

Parameter Values

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseFieldGroup()

◆ TdbCloseClusterDesign()

int TdbCloseClusterDesign ( TdbHandle *  handle)

Close a cluster design handle.

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

Description

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.

See also
TdbGetClusterDesign()

◆ TdbClusterAddMember()

int TdbClusterAddMember ( TdbHandle  handle,
const char *  name 
)

Add a member to a cluster.

Parameters
handleHandle to a database cluster design obtained using the TdbGetClusterDesign() function.
nameName of database or cluster to add as member.
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbGetClusterDesign()
TdbPutClusterDesign()
TdbClusterDelMember()
TdbClusterDelMember()

◆ TdbClusterDelMember()

int TdbClusterDelMember ( TdbHandle  handle,
int  position,
const char *  name 
)

Delete a member from a cluster.

Parameters
handleHandle to a database cluster design obtained using the TdbGetClusterDesign() function.
position1-based position of member to delete or 0 (zero) to delete a member by name.
nameName of member to delete, or NULL to delete a member by its position.
Returns
1 or other odd value on success, even value on error

Description

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

See also
TdbGetClusterDesign()
TdbPutClusterDesign()
TdbClusterDelMember()
TdbClusterGetMember()
TdbClusterEnumMembers()

◆ TdbClusterDelMembers()

int TdbClusterDelMembers ( TdbHandle  handle)

Delete all members from a cluster.

Parameters
handleHandle to a database cluster design obtained using the TdbGetClusterDesign() function.
Returns
1 or other odd value on success, even value on error

Description

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

See also
TdbGetClusterDesign()
TdbPutClusterDesign()
TdbClusterAddMember()

◆ TdbClusterEnumMembers()

int TdbClusterEnumMembers ( TdbHandle  handle,
int *  position,
char *  name,
int  namesize 
)

Iterator function to retrieve the names of all cluster members.

Parameters
handleHandle 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.
nameCharacter string buffer to receive a cluster member name
namesizeThe allocated size of the name buffer
Returns
1 or other odd value on success, even value on error

Description

This function is used to retrieve the names of the members of a cluster, as in the following example:

char name[128];
int position;
TdbHandle handle;
if (IsSuccess(TdbGetClusterDesign(&handle,"MYCLUSTER",MODE_READ))
{
position = 1;
while (IsSuccess(TdbClusterEnumMembers(handle,&position,name,128)))
{
printf("%s\n",name);
}
}
int TdbCloseClusterDesign(TdbHandle *handle)
Close a cluster design handle.
int TdbClusterEnumMembers(TdbHandle handle, int *position, char *name, int namesize)
Iterator function to retrieve the names of all cluster members.
int TdbGetClusterDesign(TdbHandle *cluster_handle, const char *cluster_name, int access_mode)
Load a database cluster specification.
See also
TdbGetClusterDesign()
TdbCloseClusterDesign()

◆ TdbClusterGetMember()

int TdbClusterGetMember ( TdbHandle  handle,
int  position,
char *  name,
int  namesize 
)

Retrieive the name of a cluster member.

Parameters
handleHandle to a database cluster design obtained using the TdbGetClusterDesign() function.
positionThe 1-based position of the cluster member to retrieve.
nameCharacter string buffer to receive a cluster member name
namesizeThe allocated size of the name buffer
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbGetClusterDesign()
TdbGetClusterProperty()

◆ TdbCopyBaseDesign()

int TdbCopyBaseDesign ( const char *  from_base,
const char *  to_base,
TdbHandle *  design 
)

Create a copy of a database definition.

Parameters
from_baseName of (existing) database
to_baseName of (new) database
designDatabase specification record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

 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.

Since

This function was introduced in TRIP version 8.0-0.

See also
TdbGetBaseDesign()
TdbPutBaseDesign()
TdbCloseBaseDesign()

◆ TdbCopyClusterDesign()

int TdbCopyClusterDesign ( TdbHandle  sourceHandle,
const char *  newName,
TdbHandle *  targetHandle 
)

Copy a database cluster.

Parameters
sourceHandleHandle to cluster to copy
newNameName of new cluster to create
targetHandleReceives a handle to the cluster copy
Returns
1 or other odd value on success, even value on error

Description

This function copies a database cluster. The new cluster must be committed by passing the targetHandle to the TdbPutClusterDesign() function.

Parameter Values

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.

See also
TdbGetClusterDesign()
TdbPutClusterDesign()
TdbCloseClusterDesign()

◆ TdbCopyThesDesign()

int TdbCopyThesDesign ( const char *  from_thes,
const char *  to_thes,
TdbHandle *  design 
)

Create a copy of a thesaurus definition.

Parameters
from_thesName of source thesaurus
to_thesName of new thesaurus
designThesaurus specification record for new thesaurus.
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

See also
TdbCopyThesDesign()
TdbPutThesDef()

◆ TdbDeleteBaseDef()

int TdbDeleteBaseDef ( )

Delete a previously loaded database design.

Returns
1 or other odd value on success, even value on error

Description

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.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

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

◆ TdbDeleteBaseField()

int TdbDeleteBaseField ( TdbHandle *  fieldHandle)

Delete a field from a database design.

Parameters
fieldHandle[IN/OUT] Handle to a field in a database design
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Since

This function was introduced in TRIP version 8.0.

Return Codes

 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.
See also
TdbGetBaseField()
TdbGetBaseDesign()
TdbPutBaseDesign()

◆ TdbDeleteBaseFieldGroup()

int TdbDeleteBaseFieldGroup ( TdbHandle *  handle)

Delete a database field group.

Parameters
handle[IN/OUT] Pointer to field group handle for the field group to delete
Returns
1 or other odd value on success, even value on error

Description

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

Parameter Values

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseFieldGroup()
TdbPutBaseDesign()

◆ TdbDeleteDbCluster()

int TdbDeleteDbCluster ( void  )

Delete a database cluster.

Returns
1 or other odd value on success, even value on error

Description

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.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

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

◆ TdbDeleteDefaultValue()

int TdbDeleteDefaultValue ( Char *  fieldName)

Remove any existing default value for a field.

Parameters
fieldNameName of field to remove the default value from
Returns
1 or other odd value on success, even value on error

Description

The database design must have been opened in write mode using either TdbGetBaseDesign() or TdbGetBaseDef().

See also
TdbGetDefaultValue
TdbPutDefaultValue

◆ TdbDeleteForeignKey()

int TdbDeleteForeignKey ( Char *  keyfield)

Remove a foreign key from the current database.

Parameters
keyfieldName of a foreign key field in the current database
Returns
1 or other odd value on success, even value on error

Description

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

See also
TdbGetBaseDesign()

◆ TdbDeleteIntegrityRules()

int TdbDeleteIntegrityRules ( )

Delete all integrity rules for the current database.

Returns
1 or other odd value on success, even value on error

Description

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

See also
TdbGetIntegrityRules()

◆ TdbDeleteThesDef()

int TdbDeleteThesDef ( void  )

Delete a thesaurus definition.

Returns
1 or other odd value on success, even value on error

Description

The function TdbDeleteThesDef() deletes the thesaurus definition previously loaded via a call to the TdbCheckThes() function.

Privileges Required

The current TRIPsystem user must possess the (file manager) FM privilege to execute this function.

Return Codes

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

◆ TdbFieldGroupAddField()

int TdbFieldGroupAddField ( TdbHandle  handle,
const char *  field_name 
)

Add a field to a field group.

Parameters
handleField group handle
field_nameName of field to add
Returns
1 or other odd value on success, even value on error

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseFieldGroup()
TdbPutBaseFieldGroup()
TdbGetBaseDesign()
TdbPutBaseDesign()

◆ TdbFieldGroupDelField()

int TdbFieldGroupDelField ( TdbHandle  handle,
const char *  field_name 
)

Remove a field from a field group.

Parameters
handleField group handle
field_nameName of field to remove
Returns
1 or other odd value on success, even value on error

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseFieldGroup()
TdbPutBaseFieldGroup()
TdbGetBaseDesign()
TdbPutBaseDesign()

◆ TdbFieldGroupGetField()

int TdbFieldGroupGetField ( TdbHandle  field_group_handle,
TdbHandle *  field_handle,
const char *  field_name,
int  ordinal 
)

Retrieve a field from a field group.

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

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseFieldGroup()
TdbGetBaseDesign()

◆ TdbFreeIntegrityRules()

int TdbFreeIntegrityRules ( base_integrity_spec rules)

Release an integrity rules structure.

Parameters
rulesPointer to the rules instance to release
Returns
1 or other odd value on success, even value on error

Description

This function must be called to release the memory and resources associated with the data returned by TdbGetIntegrityRules().

See also
TdbGetIntegrityRules()

◆ TdbGetBaseDesign()

int TdbGetBaseDesign ( TdbHandle *  handle,
const char *  base,
int  accessMode 
)

Load a database design.

Parameters
handlePointer to a TdbHandle variable that receives a handle to the database design.
baseName of database
accessModeAccess rights required to the database design
Returns
1 or other odd value on success, even value on error

Description

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

Privileges Required

The current TRIPsystem user must possess the (file manager) FM privilege to execute this function unless the accessMode is set to MODE_READ.

Return Codes

 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.
See also
TdbPutBaseDesign()
TdbGetBaseProperty()
TdbCloseBaseDesign()

◆ TdbGetBaseField()

int TdbGetBaseField ( TdbHandle *  fieldHandle,
TdbHandle  baseHandle,
const char *  fieldName,
int  ordinal 
)

Load a field specification from a database design.

Parameters
fieldHandlePointer to a handle receieving the field design
baseHandleHandle to a database design
fieldNameName of field to retrieve or NULL to retrieve by ordinal
ordinalOrdinal number of field to retrieve or 0 (zero) to retrieve by name
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

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.

Since

This function was introduced in TRIP version 8.0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 Could not get field specification.
See also
TdbGetBaseDesign()
TdbGetBaseFieldByNumber()

◆ TdbGetBaseFieldByNumber()

int TdbGetBaseFieldByNumber ( TdbHandle *  fieldHandle,
TdbHandle  baseHandle,
int  fieldNumber 
)

Load a field specification from a database design.

Parameters
fieldHandlePointer to a handle receieving the field design
baseHandleHandle to a database design
fieldNumberThe number of the field to retrieve
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

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.

Since

This function was introduced in TRIP version 8.0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 Could not get field specification.
See also
TdbGetBaseDesign()
TdbGetBaseField()

◆ TdbGetBaseFieldGroup()

int TdbGetBaseFieldGroup ( TdbHandle *  fgrp_design_handle,
TdbHandle  base_design_handle,
const char *  name,
int  ordinal 
)

Load a field group definition from a database design.

Parameters
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)

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbPutBaseFieldGroup()
TdbGetFieldGroupProperty()
TdbPutFieldGroupProperty()
TdbFieldGroupAddField()

◆ TdbGetBaseProperty()

int TdbGetBaseProperty ( TdbHandle  handle,
int  property_id,
int *  numeric_value,
char *  string_value_buffer,
int  string_buffer_size 
)

Retreieve database design properties.

Parameters
handleHandle to a database design obtained from TdbGetBaseDesign()
property_idThe ID of the property to retrieve
numeric_valueReceives property values returned as integers.
string_value_bufferReceives property values returned as strings.
string_buffer_sizethe allocated size of string_value_buffer.
Returns
1 or other odd value on success, even value on error

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseDesign()

◆ TdbGetClusterDesign()

int TdbGetClusterDesign ( TdbHandle *  cluster_handle,
const char *  cluster_name,
int  access_mode 
)

Load a database cluster specification.

Parameters
cluster_handleReceives a handle to the cluster specification
cluster_nameName of cluster to retrieve
access_modeHow to open the cluster specification
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetClusterDesign() loads and makes current the specification of a stored database cluster.

Parameter Values

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

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function with an access mode other than MODE_READ.

Return Codes

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

◆ TdbGetClusterProperty()

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.

Parameters
handleHandle to a database cluster design obtained using the TdbGetClusterDesign() function.
property_idID of property to retrieve.
numeric_valuePointer to an integer that receives property values returned as integers.
string_value_bufferA character string buffer that receives property values returned as character string data.
string_buffer_sizeThe allocated size of the string_value_buffer parameter.
Returns
1 or other odd value on success, even value on error

Description

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

◆ TdbGetDbAccess()

int TdbGetDbAccess ( char *  user,
base_access_rec baseAccess 
)

Load the base access record for a TRIP user.

Parameters
userName of user
baseAccessBase access record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

 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.
See also
TdbCheckBase()
TdbCheckThes()
TdbCheckDbCluster()

◆ TdbGetDefaultValue()

int TdbGetDefaultValue ( Char *  fieldName,
Char *  fieldValue,
int *  fieldLength 
)

Retrieve the default value for the specified field.

Parameters
fieldNameName of field for which to retrieve the default value
fieldValueBuffer to receive the default value
fieldLengthAllocated size of the fieldValue buffer
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbPutDefaultValue
TdbDeleteDefaultValue

◆ TdbGetFieldGroupProperty()

int TdbGetFieldGroupProperty ( TdbHandle  handle,
int  property_id,
int *  numeric_value,
char *  string_value_buffer,
int  string_buffer_size 
)

Retrieve field group properties.

Parameters
handleField group handle
property_idID of the field group property to retrieve
numeric_valueReceives property values returned as integers.
string_value_bufferReceives property values returned as strings.
string_buffer_sizethe allocated size of string_value_buffer.
Returns
1 or other odd value on success, even value on error

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseFieldGroup()

◆ TdbGetFieldProperty()

int TdbGetFieldProperty ( TdbHandle  handle,
int  property_id,
int *  numeric_value,
char *  string_value_buffer,
int  string_buffer_size 
)

Retrieve a field design property.

Parameters
handleHandle to a field obtained using TdbGetBaseField()
property_idID of property to retrieve
numeric_valueReceives integer property values
string_value_bufferReceives string property values
string_buffer_sizeAllocated size of string_value_buffer
Returns
1 or other odd value on success, even value on error

Description

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

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseField()

◆ TdbGetIntegrityRules()

int TdbGetIntegrityRules ( base_integrity_spec **  rules)

Retrieve the integrity rules for the current database.

Parameters
rulesReceives a pointer to an integrity rules structure
Returns
1 or other odd value on success, even value on error

Description

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

See also
TdbGetBaseDesign()
TdbFreeIntegrityRules()

◆ TdbGetTextSeparators()

int TdbGetTextSeparators ( text_sepa_rec separatorSpec)

Load a text separator specification.

Parameters
separatorSpecSeparator specification record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The separatorSpec parameter is passed a separator specification record to receive the separator specification record for the database.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

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

◆ TdbGetThesDesign()

int TdbGetThesDesign ( TdbHandle *  handle,
const char *  name,
int  accessMode 
)

Load a thesaurus design.

Parameters
handlePointer to a TdbHandle variable that receives a handle to the thesaurus design.
nameName of thesaurus
accessModeAccess rights required to the thesaurus design
Returns
1 or other odd value on success, even value on error

Description

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

Privileges Required

The current TRIPsystem user must possess the (file manager) FM privilege to execute this function unless the accessMode is set to MODE_READ.

Return Codes

 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.
See also
TdbPutThesDesign()
TdbGetBaseProperty()
TdbCloseBaseDesign()

◆ TdbPutBaseDesign()

int TdbPutBaseDesign ( TdbHandle  handle)

Store a database definition.

Parameters
handleDatabase design handle
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The handle parameter is passed handle to the database obtained via either of the TdbGetBaseDesign() or TdbCopyBaseDesign() functions.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

 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.
See also
TdbPutBaseDesign()
TdbCopyBaseDesign()
TdbGetBaseDesign()

◆ TdbPutBaseField()

int TdbPutBaseField ( TdbHandle  handle)

Store a field specification record.

Parameters
handleField specification handle
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The handle parameter is passed a handle to a field specification record with updated details of a field in the relevant database.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Since

This function was introduced in TRIP version 8.0.

Return Codes

 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.
See also
TdbCloseBaseField()
TdbGetBaseField()
TdbPutFieldProperty()

◆ TdbPutBaseFieldGroup()

int TdbPutBaseFieldGroup ( TdbHandle  handle)

Store a field group definition.

Parameters
handleHandle to a field group obtained from TdbGetBaseFieldGroup()
Returns
1 or other odd value on success, even value on error

Description

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

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

See also
TdbGetBaseFieldGroup()
TdbGetBaseDesign()
TdbPutBaseDesign()

◆ TdbPutBaseProperty()

int TdbPutBaseProperty ( TdbHandle  handle,
int  property_id,
int  numeric_value,
const char *  string_value 
)

Assign a database design property.

Parameters
handleHandle to a database design obtained from TdbGetBaseDesign()
property_idThe ID of the property to assign
numeric_valueNumeric property value
string_valueString property value
Returns
1 or other odd value on success, even value on error

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseDesign()
TdbPutBaseDesign()

◆ TdbPutClusterDesign()

int TdbPutClusterDesign ( TdbHandle  handle)

Store a database cluster specification.

Parameters
handleHandle to cluster obtained via TdbGetClusterDesign()
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The handle parameter is passed a handle to a cluster specification, with changes to the named predefined cluster of databases.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

 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.
See also
TdbGetClusterDesign()
TdbClusterGetMember()
TdbClusterAddMember()
TdbClusterDelMember()
TdbClusterDelMembers()
TdbClusterEnumMembers()
TdbGetClusterProperty()
TdbPutClusterProperty()

◆ TdbPutClusterProperty()

int TdbPutClusterProperty ( TdbHandle  handle,
int  property_id,
int  numeric_value,
const char *  string_value 
)

Assign a property of a database cluster.

Parameters
handleHandle to a database cluster design obtained using the TdbGetClusterDesign() function.
property_idID of property to retrieve.
numeric_valueAssign the value of an integer based property.
string_valueAssign the value of a character string based property.
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbGetClusterDesign()
TdbPutClusterDesign()

◆ TdbPutDbAccess()

int TdbPutDbAccess ( base_access_rec baseAccess)

Store the base access record for a TRIP user.

Parameters
baseAccessBase access record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The baseAccess parameter is passed a base access record to describe the access rights to the database for the user.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

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

◆ TdbPutDefaultValue()

int TdbPutDefaultValue ( Char *  fieldName,
Char *  fieldValue 
)

Set the default value for a field.

Parameters
fieldNameName of field to assign a default value to
fieldValueDefault value to assign
Returns
1 or other odd value on success, even value on error

Description

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.

See also
TdbGetDefaultValue
TdbDeleteDefaultValue

◆ TdbPutFieldGroupProperty()

int TdbPutFieldGroupProperty ( TdbHandle  handle,
int  property_id,
int  numeric_value,
const char *  string_value 
)

Assign field group properties.

Parameters
handleField group handle
property_idID of the field group property to assign
numeric_valueNumeric property value
string_valueString property value
Returns
1 or other odd value on success, even value on error

Description

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

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseFieldGroup()

◆ TdbPutFieldProperty()

int TdbPutFieldProperty ( TdbHandle  field_design_handle,
int  property_id,
int  numeric_value,
const char *  string_value 
)

Assign a field design property.

Parameters
field_design_handleHandle to a field obtained using TdbGetBaseField()
property_idID of property to assign
numeric_valueInteger property value
string_valueString property value
Returns
1 or other odd value on success, even value on error

Description

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.

Since

This function was introduced in TRIP version 8.0.

See also
TdbGetBaseField()
TdbPutBaseField()
TdbPutBaseDesign()

◆ TdbPutTextSeparators()

int TdbPutTextSeparators ( text_sepa_rec separatorSpec)

Store a text separator specification.

Parameters
separatorSpecSeparator specification record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The separatorSpec parameter is passed a separator specification record.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

 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.
See also
TdbGetTextSeparators()
TdbGetBaseDesign()
TdbPutBaseDesign()

◆ TdbPutThesDesign()

int TdbPutThesDesign ( TdbHandle  handle)

Store a thesaurus definition.

Parameters
handleHandle to the thesaurus design to store
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The handle parameter is passed handle to the database obtained via either of the TdbGetThesDesign() or TdbCopyThesDesign() functions.

Privileges Required

The current TRIPsystem user must possess the file manager (FM) privilege to execute this function.

Return Codes

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

◆ TdbSetForeignKey()

int TdbSetForeignKey ( Char *  keyfield,
Char *  parentdb,
Char *  parentfld,
int  upd,
int  del 
)

Establishes a new foreign key relationship.

Parameters
keyfieldPhrase field to use as foreign key in current (dependent) database
parentdbName of database the foreign key will refer to
parentfldPhrase field in parentdb that the foreign key will refer to
updIntegrity constraint for update operations in the parent database
delIntegrity constraint for delete operations in the parent database
Returns
1 or other odd value on success, even value on error

Description

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