TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
TDBS Control

Control functions. More...

Functions

int TdbAseRetCode (void)
 Get the return code from the most recently called ASE routine.
 
int TdbBreak (void)
 Allow an application to detect a user-initiated interrupt signal.
 
int TdbCallAse (void *aseID, char *argstr, int *arglen)
 Call an ASE routine.
 
int TdbExport (FilterData *fd)
 Calls a filter ASE for export of data from a TRIP database.
 
int TdbImport (FilterData *fd)
 Calls a filter for import of data into a TRIP database.
 
int TdbLoadAse (char *ase_name, void **ase_id)
 Load an ASE routine.
 
int TdbLoadStatus (int mode)
 Reset the TRIP session status.
 
int TdbSaveStatus (void)
 Save the current TRIP session status.
 
int TdbSetBreakChars (int mask, void(*routine)(int), int mode)
 Set the Command Break Characters.
 
int TdbSetBreakFlag (void)
 Tells TRIPsystem to abort an ongoing search.
 
int TdbSetComforterInterval (int seconds, void(*proc)(int))
 Set the Comforter Interval.
 
int TdbStrNormalize (char *string, int *length, int mode)
 Normalizes a string.
 

Detailed Description

Control functions.

The TDBS control functions provides access to ASEs, filters, etc.

Function Documentation

◆ TdbAseRetCode()

int TdbAseRetCode ( void  )

Get the return code from the most recently called ASE routine.

Description

The TdbAseRetCode() function returns the result value of the most recently called ASE routine. Note that this value is distinct from that signalled by TdbCallAse() which denotes the success of actually calling the routine.

Privileges Required

If the called ASE itself calls privileged functions then the calling user must possess those privileges for correct operation.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 The ASE failed to complete successfully.

The return values 1 (success) and 0 (failure) may be combined with boolean indicators to affect the calling application. Typically these indicators are used with data entry forms in the TRIP Classic environment. Valid values are:

Bit number Purpose (when set)
Bit 1 Refresh screen upon return from the ASE
Bit 2 Continue with the previous keyboard action
Bit 4 Flush any pending messages
Bit 5 Keep the data entry cursor in the last field used
Bit 6 Do not allow any data entry to fields on the current page
See also
TdbCallAse()
TdbLoadAse()
TdbRetCode()

◆ TdbBreak()

int TdbBreak ( void  )

Allow an application to detect a user-initiated interrupt signal.

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

Description

The TdbBreak() function returns a value which signifies whether the user has caused an interrupt, for example by hitting CTRL-C in a host application. The TRIPkernel itself handles interrupts during searching and sorting, but if the user application is involved in a lengthy process, this function should be used within code loops to allow that process to abort cleanly.

The control character is set up by TRIPclassic to be CTRL-C, but this can be altered by a call to the TdbSetBreakChars() function.

Return Codes

 Code Description Explanation
0 No interrupt signal detected
1 User interrupt signal detected
See also
TdbSetBreakChars()

◆ TdbCallAse()

int TdbCallAse ( void *  aseID,
char *  argstr,
int *  arglen 
)

Call an ASE routine.

Parameters
aseIDIdentifier of an ASE function.
argstrThe argument passed to/from the ASE.
arglenLength of the argument string.
Returns
1 or other odd value on success, even value on error

Description

The TdbCallAse() function calls an ASE routine that has previously been identified and loaded by the TdbLoadAse() function. All ASE routines expect two arguments, a string and the string's length, which are specified by argstr and arglen. The argstr argument must reference a buffer of at least 256 bytes.

The TdbLoadAse() function has to be called before TdbCallAse().

Parameter Values

The aseID parameter is an operating system specific handle as returned by the TdbLoadAse() function.

The argstr parameter is a string passed as the first argument of the ASE routine. As this argument can be read and written by the ASE routine care should be exercised when calling this function.

The arglen parameter is the second argument to the ASE routine and contains an integer value as the length of the argument string being passed.

Return Codes

The return codes in the table below are what may be returned by the kernel routine calling the ASE. If the ASE has successfully been called, the return code from this function is implementation-specific to the ASE.

 Code Description Explanation
10402 ASE routine {1} not found (OS status: {2}).
See also
TdbAseRetCode()
TdbLoadAse()

◆ TdbExport()

int TdbExport ( FilterData fd)

Calls a filter ASE for export of data from a TRIP database.

Parameters
fdFilter ASE argument structure
Returns
1 or other odd value on success, even value on error

Description

Calls a user defined filter ASE function to export data from a TRIPsystem database. The FilterData structure indentifies both the filter to call and the data to be exported. Although a filter is similar to an ASE, the TdbLoadAse() function does not have to be called.

Filter functions are like ASEs, but takes a wider range of in- and output parameter which allows for a greater range of usage.

Parameter Values

The fd parameter is passed a pointer to a FilterData structure that identifies the ASE function that will called and other relevant information. The fields buffer and filter_arguments in the FilterData structure may on output be allocated by the filter ASE routine. The caller is responsible for releasing this memory; take care to use the appropriate function for this (normally free(), but is on Windows likely to be HeapFree instead). Refer to the documentation of the ASE you are calling for information on which to use.

Return Codes

The return codes in the table below are what may be returned by the kernel routine calling the filter. If the filter has successfully been called, the return code from this function is implementation-specific to the filter.

 Code Description Explanation
10402 ASE routine {1} not found (OS status: {2}).
See also
TdbImport()

◆ TdbImport()

int TdbImport ( FilterData fd)

Calls a filter for import of data into a TRIP database.

Parameters
fdFilter ASE argument structure
Returns
1 or other odd value on success, even value on error

Description

The function TdbImport() calls a user defined filter ASE function to import data into a TRIPsystem database. The FilterData structure defines both the filter to call and the data to be imported.

Filter functions are like ASEs, but takes a wider range of in- and output parameter which allows for a greater range of usage.

Parameter Values

The fd parameter is passed a pointer to a FilterData structure that identifies the ASE function that will called and other relevant information. In contrast to the TdbExport() function, the fields in the TdbImport structure are expected to not be allocated by the ASE, but by the caller before making the call. An import ASE is not expected to reassign any fields in the FilterData structure.

Return Codes

The return codes in the table below are what may be returned by the kernel routine calling the filter. If the filter has successfully been called, the return code from this function is implementation-specific to the filter.

 Code Description Explanation
10402 ASE routine {1} not found (OS status: {2}).
See also
TdbExport()

◆ TdbLoadAse()

int TdbLoadAse ( char *  ase_name,
void **  ase_id 
)

Load an ASE routine.

Parameters
ase_nameName of ASE
ase_idASE handle
Returns
1 or other odd value on success, even value on error

Description

The function TdbLoadAse() checks that the ASE routine exists. The routine returns the address to be used in TdbCallAse().

The specifics of calling the ASE using the returned address are system dependent.

Parameter Values

The ase_name parameter is passed a character string as the ASE name.

The ase_id parameter receives the ASE identity. The variable to which the ase_id parameter points must be set to NULL upon entry to the routine. The value returned is the run-time address of the ASE function.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
10402 ASE routine {1} not found (OS status: {2]).
See also
TdbCallAse()

◆ TdbLoadStatus()

int TdbLoadStatus ( int  mode)

Reset the TRIP session status.

Parameters
modeMode of status restoration
Returns
1 or other odd value on success, even value on error

Description

The function TdbLoadStatus() will reset the search status of the current TRIP session to that current when a previous call to TdbSaveStatus() was made. The restoration can be done to various degrees. If mode one is specified, the database or database cluster which was open at the time TdbSaveStatus() was called will be reopened. If mode two is specified, all search sets created after the call to TdbSaveStatus() will be deleted, but the currently open database will remain open so that subsequent searches are still performed on the same database. For a complete restoration of the status, the mode must be set to three, causing both of the above actions to be taken.

This function must only be called if a call to TdbSaveStatus() has previously been made that has not yet been matched by a TdbLoadStatus() call.

Parameter Values

The mode parameter is passed an ineger as the indication of how previous search status is restored. Valid values are:

Constant Value Purpose
1 Reopen the databases that were open when the function SAVE STATUS was last called.
2 Delete all search sets created since the last call to the function SAVE STATUS, but leave the current databases open.
3 Delete all search sets created since the last call to the function SAVE STATUS, and reopen the databases that were open immediately prior to that call.

Return Codes

This function always succeeds.

See also
TdbSaveStatus()

◆ TdbSaveStatus()

int TdbSaveStatus ( void  )

Save the current TRIP session status.

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

Description

The function TdbSaveStatus() will save the current search status of the TRIP session, defined by a) the last search made, and b) the set of currently opened databases.

Each call to TdbSaveStatus() must always be matched by a call to the TdbLoadStatus() function. If an application has called TdbSaveStatus() three times in a row, then it must also call TdbLoadStatus() three times.

Return Codes

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

◆ TdbSetBreakChars()

int TdbSetBreakChars ( int  mask,
void(*)(int)  routine,
int  mode 
)

Set the Command Break Characters.

Parameters
maskBreak character mask
routineUser-written procedure
modeProcedure AST mode
Returns
1 or other odd value on success, even value on error

Description

The function TdbSetBreakChars() allows the TRIP user running a Linux or UNIX server-side console application to define one or more control characters that can be used to interrupt the processing of a CCL command. The characters are indicated by the bits set in the mask parameter which is an integer where bit 1 corresponds to CTRL-A , bit 2 to CTRL-B, etc. On receiving the break character, the user-supplied routine defined by the routine parameter is called.

If TRIP Classic is used in conjunction with other software that also intercepts control characters from the terminal, the mode argument to TdbSetBreakChars() should be set to 1.

Parameter Values

The mask parameter is passed an int as a bit-vector for the break character mask. The break characters argument consists of a bit mask for the break characters to be set; bit 1 corresponds to CTRL-A, bit 2 to CTRL-B , etc.

The routine parameter is passed the address of a user-written procedure. The routine argument is the entry mask for the user-supplied procedure invoked whenever one of the break characters set in the mask is received.

The mode parameter is passed an int as the AST mode for the user-written procedure.

This function does not have any effect on Windows.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

This function always succeeds.

See also
TdbBreak()
TdbSetBreakFlag()

◆ TdbSetBreakFlag()

int TdbSetBreakFlag ( void  )

Tells TRIPsystem to abort an ongoing search.

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

Description

The function TdbSetBreakFlag() can be used to tell TRIPsystem to abort an ongoing search.

Return Codes

This function always succeeds.

See also
TdbBreak()
TdbSetComforterInterval()

◆ TdbSetComforterInterval()

int TdbSetComforterInterval ( int  seconds,
void(*)(int)  proc 
)

Set the Comforter Interval.

Parameters
secondsNumber of seconds between calls
procUser-written procedure
Returns
1 or other odd value on success, even value on error

Description

The function TdbSetComforterInterval() is used to specify the number of seconds that are allowed to elapse between call to the user-supplied routine defined by the proc parameter.

Parameter Values

The seconds parameter is passed an int as the number of seconds between successive calls to the user-supplied comforter routine.

The proc parameter is passed a the address of a user-written procedure. The proc argument is the entry mask for the user-supplied procedure invoked after each period of elapsed seconds supplied in the seconds parameter. When called, the user-written procedure will receive one argument which specifies the current type of activity (1 = searching, 2 = sorting).

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

This function always succeeds.

◆ TdbStrNormalize()

int TdbStrNormalize ( char *  string,
int *  length,
int  mode 
)

Normalizes a string.

Parameters
stringCharacter string
lengthLength of string
modeNormalization flag
Returns
1 or other odd value on success, even value on error

Description

The TdbStrNormalize() function is used to normalize a text string according to one of TRIP's normalization schemes.

Parameter Values

The string parameter is passed a character string to normalize. The string is normalized in place.

The length parameter is passed an integer as the count of the number of characters in the string.

The mode parameter is passed a value to control the normalization. Valid values are:

Constant Value Purpose
1 To uppercase without compression of blank equivs.
2 To uppercase with compression of blank equivs.
3 CONTROL normalization
4 Current database(s) normalization
5 Translation according to printer table
6 Translation according to local printer table
7 Translation for sorting

Return Codes

This routine returns 1 on success and 0 on failure (mode value out of range).