TRIPsystem Kernel API 8.3
|
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. | |
Control functions.
The TDBS control functions provides access to ASEs, filters, etc.
int TdbAseRetCode | ( | void | ) |
Get the return code from the most recently called ASE routine.
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.
If the called ASE itself calls privileged functions then the calling user must possess those privileges for correct operation.
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 |
int TdbBreak | ( | void | ) |
Allow an application to detect a user-initiated interrupt signal.
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.
Code | Description | Explanation |
---|---|---|
0 | No interrupt signal detected | |
1 | User interrupt signal detected |
int TdbCallAse | ( | void * | aseID, |
char * | argstr, | ||
int * | arglen | ||
) |
Call an ASE routine.
aseID | Identifier of an ASE function. |
argstr | The argument passed to/from the ASE. |
arglen | Length of the argument string. |
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().
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.
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}). |
int TdbExport | ( | FilterData * | fd | ) |
Calls a filter ASE for export of data from a TRIP database.
fd | Filter ASE argument structure |
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.
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.
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}). |
int TdbImport | ( | FilterData * | fd | ) |
Calls a filter for import of data into a TRIP database.
fd | Filter ASE argument structure |
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.
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.
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}). |
int TdbLoadAse | ( | char * | ase_name, |
void ** | ase_id | ||
) |
Load an ASE routine.
ase_name | Name of ASE |
ase_id | ASE handle |
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.
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.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
10402 | ASE routine {1} not found (OS status: {2]). |
int TdbLoadStatus | ( | int | mode | ) |
Reset the TRIP session status.
mode | Mode of status restoration |
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.
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. |
This function always succeeds.
int TdbSaveStatus | ( | void | ) |
Save the current TRIP session status.
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.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbSetBreakChars | ( | int | mask, |
void(*)(int) | routine, | ||
int | mode | ||
) |
Set the Command Break Characters.
mask | Break character mask |
routine | User-written procedure |
mode | Procedure AST mode |
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.
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.
This function was introduced in TRIP version 3.4-0.
This function always succeeds.
int TdbSetBreakFlag | ( | void | ) |
Tells TRIPsystem to abort an ongoing search.
The function TdbSetBreakFlag() can be used to tell TRIPsystem to abort an ongoing search.
This function always succeeds.
int TdbSetComforterInterval | ( | int | seconds, |
void(*)(int) | proc | ||
) |
Set the Comforter Interval.
seconds | Number of seconds between calls |
proc | User-written procedure |
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.
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).
This function was introduced in TRIP version 3.4-0.
This function always succeeds.
int TdbStrNormalize | ( | char * | string, |
int * | length, | ||
int | mode | ||
) |
Normalizes a string.
string | Character string |
length | Length of string |
mode | Normalization flag |
The TdbStrNormalize() function is used to normalize a text string according to one of TRIP's normalization schemes.
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 |
This routine returns 1 on success and 0 on failure (mode value out of range).