TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
Session Commands

Manipulation of session state. More...

Functions

int TdbApiLogCheckpoint (int id)
 Sets an API log checkpoint position.
 
int TdbApiLogEnable (boolean enable)
 Enables or disables API logging for the current session.
 
int TdbApiLogRead (int checkpoint_id, long *position, char *buffer, size_t bufsize, size_t *readcount)
 Read data from the API log.
 
int TdbApiLogSetVerbosity (int level)
 Set verbosity level for the API log.
 
int TdbChangeUser (const char *user, const char *password, int mode)
 Change the currently logged on user, or temporarily logs out the current user.
 
int TdbCheckDate (int dateform, char *datestring, int *dateint)
 Checks that a supplied date is valid and transforms date strings to integers and vice versa.
 
int TdbCheckUser (const char *user, const char *password, char *FM, char *UM, char *SM)
 Perform a login operation to the TRIPkernel by validating both username and password.
 
int TdbCreateTicket (char *ticket, int maxlen)
 Create a login ticket for the currently logged in user.
 
int TdbDeleteTicket (const char *ticket)
 Delete login ticket(s) for the currently logged in user,.
 
int TdbGetConf (const char *symbolName, int section, char *valueBuffer, size_t bufferSize, const char *defaultValue)
 Get a configuration symbol value.
 
int TdbIsSuperUser (void)
 Check if current user has SUPERMAN privileges.
 
int TdbMessage (int messageNumber, char *message, int *length)
 Retrieve the text of a TRIP message indicated by number, or display a message.
 
int TdbResolvePath (const char *symbolPath, char *resolved, size_t bufsize)
 
int TdbRetCode (void)
 Return the TRIP message number.
 
int TdbSetConf (const char *symbolName, const char *symbolValue)
 
int TdbSetUICharset (int charset)
 Change the session character set.
 
int TdbShellDefDateform (int dateform, char *datestring)
 Get or set a TRIP date format.
 
int TdbShellModifyCcl (int language)
 Modify the CCL locale language being used.
 
int TdbShellType (char *fieldtypeName, int *fieldtypeNumber)
 Check a field type on its name or number.
 
int TdbStartTrip (char *username, char *password, int language, int mode)
 Initializes the client application for a new TRIP session.
 
int TdbStopTrip (boolean restart)
 Terminates a TRIP session started with TdbStartTrip.
 

Detailed Description

Manipulation of session state.

The session commands is a group of TRIP functions that operate on the session level. These are used to establish and tear down sessions and query and modify session-related information.

Function Documentation

◆ TdbApiLogCheckpoint()

int TdbApiLogCheckpoint ( int  id)

Sets an API log checkpoint position.

Parameters
idID of checkpoint to set; valid ID numbers are 1 to 8.

Description

API log checkpoints are used to set a position from which calls to the TdbApiLogRead() function will start to read the log. Use this behavior when you wish to get the API log for a specific part of your application only.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

See also
TdbApiLogEnable()
TdbApiLogRead()

◆ TdbApiLogEnable()

int TdbApiLogEnable ( boolean  enable)

Enables or disables API logging for the current session.

Parameters
enableTrue to enable and false to disable

Description

API logging can be useful to analyze the behavior of applications in situations where hard-to-locate errors occur.

API logs enabled this way are automatically removed when the process exits and do not show in the file system. If this log data should be retained, either call the TdbApiLogRead() function to read the log from your application, or define the TDBS_APILOG_RETAIN variable in tdbs.conf or the environment before you start the TRIP process.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

See also
TdbApiLogCheckpoint()
TdbApiLogRead()

◆ TdbApiLogRead()

int TdbApiLogRead ( int  checkpoint_id,
long *  position,
char *  buffer,
size_t  bufsize,
size_t *  readcount 
)

Read data from the API log.

Parameters
idID of checkpoint to read from
position[IN/OUT] Pointer to long int to hold read position; set to zero for first call.
buffer[OUT] Pointer to memory buffer to receieve API log data.
bufsize[IN] The size of the memory area that the buffer parameter points to.
readcount[OUT] Receieves the number of bytes copied to the buffer

Description

The API log is, if enabled via the TdbApiLogEnable() function, by default not visible in the file system. In order to read data from it, the application should call this function.

This function reads the API log from a position associated with a checkpoint, set by calling the TdbApiLogCheckpoint() function. A special checkpoint with value 0 (zero) can also be used in order to read data from the start of the log.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

◆ TdbApiLogSetVerbosity()

int TdbApiLogSetVerbosity ( int  level)

Set verbosity level for the API log.

Parameters
levelVerbosity level to set

Description

The API log verbosity can be set by calling this method. Verbosity levels control what API functions are included the log. The default level is used for most API calls, and while labeled minimal, it is sufficient for most needs. Functions whose impact on the log size is significant and/or whose inclusion are rarely required are emitted at higher verbosity levels.

levels are:

| Value | Description | | -—_ | --------— | | 0 | Minimal verbosity (default) | | 1 | Low verbosity | | 2 | Average verbosity | | 3 | High verbosity | | 4 | Max verbosity |

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

◆ TdbChangeUser()

int TdbChangeUser ( const char *  user,
const char *  password,
int  mode 
)

Change the currently logged on user, or temporarily logs out the current user.

Parameters
userName of new user to log on as
passwordThe password for the TRIP user
modeBitmask controlling how existing session state is to be handled
Returns
1 or other odd value on success, even value on error

Description

This function is used to switch the current session from one user to another. The mode parameter controls how to handle the current session state; to clear it or to keep it. See the table below for details.

If the username and password are both specified as empty strings, the current user will be logged off. The session will then be left in an intermediary state in which the only valid operation is a call to TdbChangeUser() to log in a new user into the session, or to call TdbStopTrip() to terminate the session altogether.

If the username is empty and the password is specified as a valid login ticket, the ticket owner will be assigned the current user of the session.

The mode parameter can have the following values:

Symbol Description
CHANGEUSER_KEEPALL All state is kept. Cannot be combined with any other value.
CHANGEUSER_CLEAR_SETS Delete all search sets. This also removes all held PRINT jobs.
CHANGEUSER_CLOSE_DATABASES Close all databases.
CHANGEUSER_RESTORE_DEFAULTS Restore DEFINEs to their default values.
CHANGEUSER_CLEARALL Combines CHANGEUSER_CLEAR_SETS, CHANGEUSER_CLOSE_DATABASES and CHANGEUSER_RESTORE_DEFAULTS.

The TdbSessionInfo() function can be used to query the current state of the session. Use the SESSIONINFO_SESSION_STATUS mode parameter. If the integer output parameter contains 4 or 5, the current user has been temporarily logged out.

Since

This function was introduced in TRIP version 8.0-0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
322 Cannot open *.SIF, disk quota exceeded or no write access.
9634 No such user as 2
9666 User id 2 is a group id.
10306 Invalid password - Please try again.
See also
TdbStartTrip()
TdbStopTrip()
TdbSessionInfo()

◆ TdbCheckDate()

int TdbCheckDate ( int  dateform,
char *  datestring,
int *  dateint 
)

Checks that a supplied date is valid and transforms date strings to integers and vice versa.

Parameters
dateformDate format
datestringDate string
dateintDatee numeric value.
Returns
1 or other odd value on success, even value on error

Description

The TdbCheckDate() function performs a number of operations upon TRIP dates depending on the value of the parameters passed to it.

If the dateform parameter value is positive (between 1 and 17), the datestring parameter is not an empty string, and the dateint parameter is 0 (zero), this function will check that the datestring parameter value is valid in that format.

If the dateform parameter value is positive (between 1 and 17), the datestring parameter is an empty string and the dateint parameter is not 0 (zero), this function transforms the value of the dateint parameter from a long representation of a date to a string form in the specified dateform.

The change to the date format lasts only for the duration of the current call to the TdbCheckDate() function. However, if the value of the dateform parameter is negative, the function performs all actions described above but will also alter the date format until the calling application terminates.

Parameter Values

The dateform parameter is passed an int value for the dateform that is to be checked or set. Valid values are:

Value Date format Example for May 1st 1988
1 YYYY-MM-DD 1988-05-01
2 YYYY-mM-dD 1988-5-1
3 yyYY-mM-dD 88-5-1
4 YYYY-mm-dD 1988-May-1
5 yyYY-mm-dD 88-May-1
6 MM-DD-YYYY 05-01-1988
7 mM-dD-YYYY 5-1-1988
8 mM-dD-yyYY 5-1-88
9 mm-dD-YYYY May-1-1988
10 mm-dD-yyYY May-1-88
11 DD-MM-YYYY 01-05-1988
12 dD-mM-YYYY 1-5-1988
13 dD-mM-yyYY 1-5-88
14 dD-mm-YYYY 1-May-1988
15 dD-mm-yyYY 1-May-88
16 YYYYMMDD 19880501
17 yyYYMMDD 880501

The datestring parameter is passed a character string as the date in string form. Whether this date string is to checked or set depends upon the value passed in the dateint parameter.

The dateint parameter is passed an integer representation of the date. As with the parameter whether this value is checked or set depends upon the dateform parameter.

Return Codes

On success, this function returns a success value of 1, and on failure it returns 0 (zero).

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 The date transformation failed.

Examples

Format a specified date according in the current date format:

char formattedDate[64] = "";
int year = 2004;
int month = 9;
int day = 29;
// Create an integer representation of the date.
int ymd = year << 9;
ymd += month << 5;
ymd += day;
// Convert to string and display.
TdbCheckDate(0,formattedDate,&ymd);
printf("%s\n",formattedDate);
int TdbCheckDate(int dateform, char *datestring, int *dateint)
Checks that a supplied date is valid and transforms date strings to integers and vice versa.

Check if a specified string is a valid date in the current date format:

int ymd = 0;
char dateString[64] = "2004-09-29";
// Check if the date string is a valid date.
if (IsError(TdbCheckDate(1,dateString,&ymd))
printf("String not recognized as a date in the current date format.\n");
else
printf("Date is ok. Integer representation of the date is %d\n",ymd);

◆ TdbCheckUser()

int TdbCheckUser ( const char *  user,
const char *  password,
char *  FM,
char *  UM,
char *  SM 
)

Perform a login operation to the TRIPkernel by validating both username and password.

Parameters
userName of user. Recieves the normalized user name on return.
passwordPassword
FMReceieves file manager privilege
UMReceieves user manager privilege
SMReceieves system manager privilege
Returns
1 or other odd value on success, even value on error

Description

The function TdbCheckUser() must be called to gain access to TRIP. All logins are validated upon the contents of the username and password parameters.

Note
A call to this function is now included in the TdbStartTrip() function except when TdbStartTrip() is called with an empty string as username and as password. In this case the application must call TdbCheckUser() afterwards.

If the user's profile record has the os_entry flag set then the password can be ignored if the operating system username is the same as the TRIP username. When the two usernames are the same the string in the password parameter can be left blank or set to a random value. Note that this only applies for the server-side version of this function.

Before calling TdbCheckUser() the calling process must have called the function TdbBeginTdbs() to initialize the TRIP kernel. Until a successful call of TdbCheckUser() the security subsystem will not allow any access to database functions.

This function can only be successfully invoked once per TRIP session; it can, however, be invoked any number of times unsuccessfully prior to that successful invocation.

On successful return, the three boolean flags FM , UM , and SM reflect the file, user and system management status of the calling process. These flags are returned in the parameters with the same names.

The SIF file for the current TRIP application session is created upon successful checking of the CONTROL file for the user/password combination.

Parameter Values

The user parameter is passed a character string as the name of the user being checked. Upon return from TdbCheckUser() the normalized form of the user name is returned in this parameter.

The password is passed a character string as the password for the user being checked.

The FM parameter is passed a char as a flag indicating whether the named user has FM rights. If the lowest bit of the char is set upon return the user has file manager privileges and the calling process may perform file management functions such as creating databases, clusters and thesauri, as well as granting existing users and groups access to those objects.

The UM parameter is passed a char as a flag indicating whether the named user has UM rights. If the lowest bit of the char is set upon return the user has user manager privileges and the calling process can perform user management functions such as creation and deletion of users, groups, and group-wide procedures.

The SM parameter is passed a char as a flag indicating whether the named user has SM rights. If the lowest bit of the char is set upon return the user is acting as the system manager, user SYSTEM and the calling process can perform system management functions such as changing other user's passwords, and transferring ownership of objects from other managers to itself.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
322 Cannot open *.SIF, disk quota exceeded or no write access.
2434 Restart file 1 not found.
2466 Password invalid for restart file.
9634 No such user as 2
9666 User id 2 is a group id.
10306 Invalid password - Please try again.
18594 Old version of restart file (SIF, PRT, RIF), aborting...
21602 Existing restart file belongs to another user - try again.
See also
TdbCreateUser()
TdbChangePassword()
TdbSetPassword()
TdbStartTrip()
TdbBeginTdbs()

◆ TdbCreateTicket()

int TdbCreateTicket ( char *  ticket,
int  maxlen 
)

Create a login ticket for the currently logged in user.

Parameters
ticketBuffer to receive the login ticket
maxlenAllocated size of buffer (should be at least 64 bytes)
Returns
1 or other odd value on success, even value on error

Description

A login ticket is a temporary access token that can be used to authenticate as the user that created the ticket. Logging in using a login ticket is done using the normal APIs for login, save for that the ticket is passed as the password and the username as an empty string.

The login tickcet is valid for the duration specified by the TDBS_TICKET_TIMEOUT logical name in the tdbs.conf configuration file, or until the TRIP daemon (tripd) is restarted. The ticket can also be revoked by calling TdbDeleteTicket() as the user to which the ticket applies, or as SYSTEM.

Note
Login tickets, if used, must be stored in a secure manner by the application.
See also
TdbDeleteTicket()

◆ TdbDeleteTicket()

int TdbDeleteTicket ( const char *  ticket)

Delete login ticket(s) for the currently logged in user,.

Parameters
ticketTicket to delete or an empty string for the current user's ticket
Returns
1 or other odd value on success, even value on error

Description

If the ticket parameter specifies a login ticket for another user, the currently logged on user must have SYSTEM privileges.

See also
TdbCreateTicket()

◆ TdbGetConf()

int TdbGetConf ( const char *  symbolName,
int  section,
char *  valueBuffer,
size_t  bufferSize,
const char *  defaultValue 
)

Get a configuration symbol value.

Parameters
symbolNameName of configuration symbol to get
sectionId of tdbs.conf section to read value from
valueBufferBuffer that recives a copy of the value, or NULL to return the requried buffer size
bufferSizeAllocated size of the valueBuffer
defaultValueDefault value to assign if not found or NULL
Returns
1 on success, 0 if not found, or 2 if the specified bufferSize is too small

Description

Retrieves the value of a configuration symbol, as read from either the tdbs.conf file.

Valid values for the section parameter:

Symbolic Name Constant Value Purpose
CONF_PRIVILEGED 1 Look for value in the the Privileged section of tdbs.conf
CONF_GROUP 2 Look for value in the the user group specific section of tdbs.conf
CONF_NONPRIVILEGED 4 Look for value in the the NonPrivileged section of tdbs.conf
CONF_ALL 7 Look for value in any section of tdbs.conf

◆ TdbIsSuperUser()

int TdbIsSuperUser ( void  )

Check if current user has SUPERMAN privileges.

Returns
Non-zero if user is SUPERMAN, and zero otherwise

Description

The tdbs.conf privileged configuration setting TDBS_SUPERMAN will, if defined, give the SYSTEM user extended privileges such that it will be allowed to access CONTROL objects (databases, clusters, etc) owned by other users. This function returns a non-zero value if the current user is SYSTEM and has been granted SUPERMAN privileges.

◆ TdbMessage()

int TdbMessage ( int  messageNumber,
char *  message,
int *  length 
)

Retrieve the text of a TRIP message indicated by number, or display a message.

Parameters
messageNumberMessage number
messageText of message
lengthLength of message string
Returns
1 or other odd value on success, even value on error

Description

The function TdbMessage() retrieves the help or error message associated with the specified message number. The number should be a value previously returned by another TRIPapi routine. Return values smaller than the predefined constant MSG_HAS_TEXT are however not associated with a message, but simply indicate the success or failure of the routine called.

In ASE routines, TdbMessage() can be used to display a message supplied by the ASE routine itself. The message will appear on the TRIPclassic status bar when the ASE returns control to TRIPclassic. To specify the message text as an input argument, the message number must be set to MSG_SET_ERROR or MSG_SET_INFO . Note that for some types of ASEs (such as data entry ASEs) the display of the message is also dependent upon the code returned by the ASE.

Parameter Values

The messageNumber parameter is passed an int as the message number for which the associated text is to be retrieved. The acceptable values are:

Symbolic Name Constant Value Purpose
MSG_HAS_TEXT >= 32 Retrieve the text of the associated message
MSG_SET_ERROR -1 Display the message argument as a user-supplied error message in the TRIPclassic status line
MSG_SET_INFO -2 Display the message argument as a user-supplied information message in the TRIPclassic status line.

The message parameter is passed a character string as the text of the message. When messageNumber is either MSG_SET_ERROR or MSG_SET_INFO then the string passed in used otherwise the message text associated with messageNumber is returned in this string.

The length parameter is passed the length of the message string. When messageNumber is either MSG_SET_ERROR or MSG_SET_INFO then the argument is taken to be the length of the string being passed to TRIP otherwise it is returned as the length of the message text returned in the message string.

Return Codes

This function always succeeds.

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

◆ TdbResolvePath()

int TdbResolvePath ( const char *  symbolPath,
char *  resolved,
size_t  bufsize 
)

Resolve database file name containing logical names from tdbs.conf into a file systenm path.

Parameters
symbolPathDatabase (BAF, BIF, VIF) file name as specified in the DB design
resolvedBuffer to receieve the resolved path
bufsizeThe allocated size of the resolved buffer
Returns
1 on successs and 0 if path could not be resolved.

The successful resolution of the symbol path does not guarantee that the path actually exists on the local file system. If resolution fails, the resolved buffer is left unmodified.

◆ TdbRetCode()

int TdbRetCode ( void  )

Return the TRIP message number.

Returns
The return value returned by the previous TRIP function call.

Description

The function TdbRetCode() returns the current TRIP message number set by TRIP upon completion of other function calls.

Return Codes

This function can return any TRIPsystem code.

See also
TdbMessage()

◆ TdbSetConf()

int TdbSetConf ( const char *  symbolName,
const char *  symbolValue 
)

Assign a configuration value to use for the remainder of the current TRIP session.

Parameters
symbolNameName of configuration symbol to assign
symbolValueValue of the configuration symbol
Returns
1 or other odd value on success, even value on error

◆ TdbSetUICharset()

int TdbSetUICharset ( int  charset)

Change the session character set.

Parameters
charsetCharacter set to use
Returns
1 or other odd value on success, even value on error

Description

The valid values for the charset parameter for this function are:

Symbolic Name Constant Value Purpose
CHSET_NONE 0 Default character set.
CHSET_LA1 1 Latin 1
CHSET_UTF8 16 Unicode

If charset is set to CHSET_NONE, the value will be taken from the TDBS_CHARS logical name in tdbs.conf. Regardless of how the charset is specified (explicitly or implicitly via CHSET_NONE/TDBS_CHARS), the only valid values for the new character set are LATIN-1 and UTF-8.

Since

This function was introduced in TRIP version 8.2-0.

◆ TdbShellDefDateform()

int TdbShellDefDateform ( int  dateform,
char *  datestring 
)

Get or set a TRIP date format.

Parameters
dateformDate form number
datestringdate format delimiter characters on inut, and an example formatted date on output.
Returns
1 or other odd value on success, even value on error

Description

The function TdbShellDefDateForm() sets the date format to one of the 17 date formats supported by TRIP.

Parameter Values

The dateform parameter is passed an integer representing the format of the date. Pass the number as a positive value to retrieve an example date formatted in the specified format. Pass the number as a negative value to also change the current session's date format to the specified one. Acceptable values are:

Value Date format Example for May 1st 1988
1 YYYY-MM-DD 1988-05-01
2 YYYY-mM-dD 1988-5-1
3 yyYY-mM-dD 88-5-1
4 YYYY-mm-dD 1988-May-1
5 yyYY-mm-dD 88-May-1
6 MM-DD-YYYY 05-01-1988
7 mM-dD-YYYY 5-1-1988
8 mM-dD-yyYY 5-1-88
9 mm-dD-YYYY May-1-1988
10 mm-dD-yyYY May-1-88
11 DD-MM-YYYY 01-05-1988
12 dD-mM-YYYY 1-5-1988
13 dD-mM-yyYY 1-5-88
14 dD-mm-YYYY 1-May-1988
15 dD-mm-yyYY 1-May-88
16 YYYYMMDD 19880501
17 yyYYMMDD 880501

The datestring parameter is passed a two-character string with the delimiter characters to use in the date string, e.g. "--" for the examples above. It receives an example of a date formatted in the specified form, which is why the buffer that datestring refers to must be large enough to accommodate the formatted example date.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 Could not set the date form.
See also
TdbCheckDate()
TdbShellModifyCcl()

◆ TdbShellModifyCcl()

int TdbShellModifyCcl ( int  language)

Modify the CCL locale language being used.

Parameters
languageCCL locale language to use
Returns
1 or other odd value on success, even value on error

Description

The function TdbShellModifyCcl() can be used to change the CCL language that is being used in the normal TRIP search mode.

Parameter Values

The language parameter is passed an int as the indicator for the CCL locale language to use. Valid values are:

Symbolic Name Constant Value Purpose
LANGUAGE_DEFAULT 1 Use the system default language
LANGUAGE_ENGLISH 9 Use English dialect
LANGUAGE_SWEDISH 10 Use Swedish dialect
LANGUAGE_CHINESE 11 Use Chinese dialect
LANGUAGE_GERMAN 12 Use German dialect
LANGUAGE_FRENCH 13 Use French dialect
LANGUAGE_FINNISH 14 Use Finnish dialect
LANGUAGE_NORWEGIAN 15 Use Norwegian dialect

Return Codes

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

◆ TdbShellType()

int TdbShellType ( char *  fieldtypeName,
int *  fieldtypeNumber 
)

Check a field type on its name or number.

Parameters
fieldtypeNameName of field type
fieldtypeNumberField type number
Returns
1 or other odd value on success, even value on error

Description

The function TdbShellType() returns information about a field type. If the field type is specified by a number, the routine will return the name in the user's current CCL dialect. The type number can also be set to zero, in which case the field type name (or the first part of the name) must be specified in order to obtain the number of the type.

Parameter Values

The fieldtypeName parameter is passed a character string as the name of the field type. The string has to be at least 16 characters long. If the type name is only partially specified, the name will be expanded on return.

The fieldtypeNumber parameter is passed a pointer to an integer to receive the field type number. Acceptable values are:

Symbolic Name Constant Value Purpose
0 The type number can also be set to zero, in which case the field type name (or the first part of the name) must be specified in order to obtain the number of the type.
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

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
0 Field check failed.
See also
TdbCheckField()

◆ TdbStartTrip()

int TdbStartTrip ( char *  username,
char *  password,
int  language,
int  mode 
)

Initializes the client application for a new TRIP session.

Parameters
usernameName of user or empty string.
passwordPassword of user or empty string
languageCCL locale language
modeTRIP initialization options. Pass 0 if not used.
Returns
1 or other odd value on success, even value on error

Description

The TdbStartTrip() function initializes TRIP for use by the calling process. It performs consistency checks upon the operating system environment, TRIPsystem installation, licence conditions, and initialises essential status variables and reporting mechanisms in TRIP. If the site running the application is controlled by a concurrent user license, the TRIPdaemon service is consulted to gain a session token, if possible. It checks for the existence and accessibility of the data dictionary (the CONTROL database) and of the error message store (the TDBSERR database) that the kernel needs during execution. If the site running the application is controlled by a concurrent user license, TRIPdaemon is consulted to gain a session token, if possible.

The TdbStartTrip() function is the first function that should be called by an application program. Upon return, and assuming a success return code, the session will have been initialised. However, this function should never be called by an application software exit (ASE) as all required initialisation will have been successfully completed prior to the ASE being activated.

The TdbStartTrip() function replaces TdbBeginTdbs(), TdbShellInit() and optionally TdbCheckUser() .

If login tickets are enabled and ticket based login is desired, the password parameter is passed a string with the login ticket, and the username parameter left as an empty string. If the username (parameter is left empty (and also password if login tickets are enabled), TdbStartTrip() will work as specified, except that it does not call TdbCheckUser(), which instead must be called afterwards by the application.

Parameter Values

The username parameter is passed a character string as the name of the user being checked or an empty string.

The password parameter is passed a character string as the password for the user being checked or an empty string.

The language parameter is passed an integer that indicates the CCL locale language to use. Valid values are:

Symbolic Name Constant Value Purpose
LANGUAGE_DEFAULT 1 Use the system default language
LANGUAGE_ENGLISH 9 Use English dialect
LANGUAGE_SWEDISH 10 Use Swedish dialect
LANGUAGE_CHINESE 11 Use Chinese dialect
LANGUAGE_GERMAN 12 Use German dialect
LANGUAGE_FRENCH 13 Use French dialect
LANGUAGE_FINNISH 14 Use Finnish dialect
LANGUAGE_NORWEGIAN 15 Use Norwegian dialect

The mode parameter is passed an integer that indicates the TRIP initialization options to use. The mode parameter is a bit mask. This means that the various option values can be easily combined, e.g. "16 | CHARSET_MODE(CHSET_UTF)". However, only one character set option may be assigned.

The mode parameter can also be used to indicate which character set to use for the session. This overrides the TDBS_CHARS value as specified in the TRIPrcs file. This is also the only way by which unicode (in the UTF-8 encoding) can be chosen as character set.

Valid character set values for the mode parameter:

Symbolic Name Constant Value Purpose
CHARSET_MODE(CHSET_NONE) 0 Default character set.
CHARSET_MODE(CHSET_LA1) 256 Latin 1
CHARSET_MODE(CHSET_LA2) 512 Latin 2
CHARSET_MODE(CHSET_LA3) 768 Latin 3
CHARSET_MODE(CHSET_UTF8) 4096 Unicode
CHARSET_MODE(CHSET_CHI) 4352 Chinese
CHARSET_MODE(CHSET_GBK) 4608 Chinese GBK
CHARSET_MODE(CHSET_EUC) 4864 EUC
CHARSET_MODE(CHSET_SJIS) 5120 Shift-JIS

Note that the character set value to pass to the mode parameter is shifted 8 bits in order to be able to fit into this bit mask. This shifting is done using the CHARSET_MODE macro, as illustrated in the table above. Using one of the character set contstants (e.g. CHSET_UTF8) directly will not work.

Miscellaneous other options for the mode parameter:

Constant Value Purpose
16 Restart a former session.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

Note
If the TdbStartTrip() function fails and haven't previously been successfully called with a blank username and password, the error message cannot be fetched by calling TdbMessage() since no session will yet exist.
 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
9634 No such user as username The supplied user name could not be identified as a TRIP user.
9666 User id username is a group id The supplied user name was identified as the name of a TRIP group.
10306 Invalid password - Please try again. The supplied password was not valid for the specified user.
15840 Concurrent user quota (N) exceeded The maximum number of licenced concurrent TRIP users has been reached. When this error code is returned the accompanying error text will include the maximum number of concurrent users licenced for the machine.
16512 Invalid TRIPdaemon process name TRIPsystem cannot locate the process for the TRIP daemon.
See also
TdbStopTrip()
TdbSessionInfo()
TdbChangeUser()
TdbShellDefDateForm()

◆ TdbStopTrip()

int TdbStopTrip ( boolean  restart)

Terminates a TRIP session started with TdbStartTrip.

Parameters
restartMode of session reinitialization. Use value 1 to restart session from saved SIF file, and 0 (zero) to reinitialize a new session. When using the client version of this API, only pass 0 (zero).
Returns
1 or other odd value on success, even value on error

Description

The TdbStopTrip() function will end a TRIP session that has been started with TdbStartTrip .

The TdbStopTrip() function replaces TdbEndTdbs().

When a server-side TRIP application exits, an option exists to save the current SIF file for future use. The restart parameter is given value 1 to save the SIF file, and 0 (zero) to delete it.

This function must be the last TRIP toolkit routine called by the application. The server-side version must be called only once per image activation.

Since

This function was introduced in TRIP version 3.4-0.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.
10434 Background printing still in progress. This may occur when a PRINT command is still executing on the server.
See also
TdbStartTrip()