Class: CAPI

The built-in functions in the CAPI package allow you to connect to generic SQL databases and perform general SQL statement operations. The CAPI package also manages the allocation of Livelink login objects and provides a number of convenience functions for use with any Livelink database.

The major functionalities offered in the CAPI Package are the following:

AllocConnect(), Disconnect(), ConnectionAttr(), ConnectionInfo(), and IsValid() to create or disconnect a connection to the database, or query information from or the the validity of an active connection.

StartTransaction(), RestartTransaction(), EndTransaction(), and TransactionDepth() to start, restart, end, and check the depth level of a transaction.

Exec() and ExecN() to execute a single, possibly parameterized SQL statement, and ExecSP() to execute a stored procedure in MSSQL.

AllocLog(), AllocLogin(), and AllocErr() to allocate a new CAPILOG, CAPILOGIN, or CAPIERR.

AttachLog() to attach to a CAPILOG object, with optional file output.

GetErrAt(), GetDetailAt(), NumErrs() , ErrOption(), and ClearErr() to retrieve errors, detail information, error count, set clear behavior, or clear errors in a CAPIERR error stack.

RightsList(), RightsSet(), RightsString(), UpdateRights() and CheckRight() to list, format, update, and check privilege rights.

UseRightsString() to check whether rights string query with multiple in clauses can be used.

IniGet(), IniList(), IniPut(), and IniDelete(), to get, list, add, or delete kIni information.

UserID(), UserInfo(), UniqueID(), and LoginInfo() to query the user information, new unique ID's, or information from a CAPILOGIN.

Log() (LogInfo()), LogError(), LogWarn() to log an INFO, ERROR or WARN message to the log file for a given login.

Now() to query the current time from the database.

Parent() to return the parent of various Livelink objects.

ContextData() sets or retrieves user-specific data associated with a CAPI-related object.

Example:

CAPILOG		logFile
CAPIERR		errHandler
CAPICONNECT	connection
Dynamic		execResult
RecArray	records
Record		rec
Dynamic		transResult

// Allocate a log and error object
logFile = CAPI.AllocLog( 'c:\capi.log' )
errHandler = CAPI.AllocErr()

// connect to the database
connection = CAPI.AllocConnect( \
					CAPI.CT_ORACLE,\
					'ORAHOST',\
					'',\
					'orauser',\
					'orauserpwd',\
					logFile, \
					errHandler, \
					0 )


if ( IsError( connection ) )
	echo( 'There was an error connecting' )
	DumpErrorStack( errHandler )
else
	// Fetch all the records from myTable
	execResult = CAPI.Exec( connection, 'select * from myTable' )
	
	if ( IsError( execResult ) )
		echo( 'The select statement failed' )
		DumpErrorStack( errHandler )
	else
		if ( IsError( CAPI.StartTransaction( connection ) ) )
			echo( 'The transaction could not be started' )
			DumpErrorStack( errHandler )
		else
			// Initialize the transaction result to COMMIT
			transResult = CAPI.COMMIT
			
			records = execResult

			// Loop through all the records, updating each one	
			for rec in records
				echo( rec.myField )
				
				// Update a record, using a parameterized statement
				execResult = CAPI.Exec(\
								 connection,\
								 "update myTable set myField=myField+1 where myField=:A1",\
								 rec.myField )
								 
				if ( IsError( execResult ) )
					echo( 'An error occurred while updating the records' )
					DumpErrorStack( errHandler )
					transResult = CAPI.ROLLBACK
					break
				end
			end
			
			CAPI.EndTransaction( connection, transResult )
		end
	end
end


function void DumpErrorStack( CAPIERR errLog )

	Integer		i
	Error		code
	String		errMsg
	String		detail
	String		msg
	
	Integer		numErrors = CAPI.NumErrs( errLog )
		
	if numErrors > 0
		echo( "		----> Error stack" )

		for i = 1 to numErrors
			code = CAPI.GetErrAt( errLog, i )
			errMsg = Error.ErrorToString( code )
			detail = CAPI.GetDetailAt( errLog, i )
			msg = Str.ValueToString( code )
			echo( "		----> ", i, ")", "  ", msg, ":", code, ":", detail )
		end
	end
	
	CAPI.ClearErr( errLog )
end

COMMIT: Commits database changes when passed to CAPI.EndTransaction function.
CT_DBLIB: Specifies MSSQL as the database type when calling the CAPI.AllocConnect function to create a CAPI connection.
CT_ODBC: Specifies ODBC as the database type when calling the CAPI.AllocConnect function to create a CAPI connection.
CT_ORACLE: Specifies Oracle as the database type when calling the CAPI.AllocConnect function to create a CAPI connection.
ERR_CLEAR: A flag used by CAPI.ErrOption() to set a given CAPIERR such that it retains accumulated errors when CAPI.ClearErr() is called on it.
ERR_KEEP: A flag used by CAPI.ErrOption() to set a given CAPIERR such that it discards accumulated errors when CAPI.ClearErr() is called on it.
LOG_APPEND: A flag used by CAPI.AllocLog() to set the log file open mode.
LOG_TRUNCATE: A flag used by CAPI.AllocLog() to set the log file open mode.
PROXY_NONE: A flag used in CAPI.RightsList() to retrieve the regular rights of the current user.
PROXY_WAPI: A flag used in CAPI.RightsList() to retrieve the proxy rights for WAPI of the current user.
ROLLBACK: Rolls back a database transaction when passed to the CAPI.EndTransaction function

AllocConnect( Integer type, String server, String database, String user, String password, [CAPILog log], [CAPIErr err], [Integer ctflags] ): Allocates a CAPI connection to the specified server and database.
AllocErr(): Allocates a CAPIERR object.
AllocLog( String logFilePath, [Integer openModeFlag] )
Allocates a CAPILOG object.
AllocLogin( CAPICONNECT connection, String username, String password, [String spaceName] ): Allocates a Livelink login object.
CheckRight( CAPILOGIN login, Integer rightID ): Determines if the user for the specified login has a specific right.
ClearErr( CAPIERR err ): Clears the error stack in the CAPIERR object.
ConnectionAttr( [CAPICONNECT connection] ): Returns attribute information about one or more CAPICONNECT objects.
ConnectionInfo( [CAPICONNECT connection] ): Returns basic information about one or more CAPICONNECT objects.
ContextData( Dynamic value, [Dynamic objectData] ): Allows user specific data to be stored and retrieved from a given CAPI related object.
Disconnect( CAPICONNECT connection ): Disconnects the specified CAPICONNECT object from the database.
EndTransaction( Dynamic connectOrLogin, Dynamic status ): Ends the current database transaction.
ErrOption( CAPIErr err, Integer flag ): Allows accumulated errors to be cleared in a CAPIErr.
Exec( CAPICONNECT connect, String statement, ... ): Executes a single SQL statement.
ExecN( CAPICONNECT connect, String statement, RecArray paramValues ): Executes a single, parameterized statement, multiple times, once for each set of parameter values in the paramValues array.
ExecSP( CAPICONNECT connect, String statement, ... ): Executes a single, optionally parameterized statement which will execute a stored procedure.
GetDetailAt( CAPIERR err, Integer index ): Gets the detailed error string from the error stack at the specified index.
GetErrAt( CAPIERR err, Integer index ): Returns the error code from the error stack at the specified index.
IniDelete( CAPILOGIN login, [String section], [String keyword] ): Deletes one or more items from the INI table in the SQL database.
IniGet( CAPILOGIN login, String section, String keyword, [Dynamic arg4] ): Retrieves an item from the INI table in the SQL database.
IniList( CAPILOGIN login, [String section], [String keyword] ): Lists items from the INI table in the SQL database.
IniPut( CAPILOGIN login, String section, String keyword, Dynamic value ): Saves a value to the INI table in the SQL database.
IsValid( CAPICONNECT connect ): Checks the IsValid flag for the specified connection.
Log( CAPILOG login, String message ): Writes a message to the log file associated with the specified login.
LoginInfo( [CAPILOGIN login] ): Returns basic information about one or more CAPILOGIN objects.
Now( CAPICONNECT connect ): Returns the current time from the database.
NumErrs( CAPIERR err ): Returns the number of errors currently on the error stack.
Parent( Dynamic object ): Returns the parent object for the specified object.
RestartTransaction( Dynamic object, Dynamic status ): Restarts the current transaction.
RightsList( CAPILOGIN login, [Integer proxyType] ): Returns the rights for the specified login.
RightsSet( CAPILOGIN login ): Returns an assoc with keys of right ids.
RightsString( CAPILOGIN login, String columnName ): Returns a string containing the rights for the specified login, formatted for use in an SQL statement.
StartTransaction( Dynamic loginOrConnect, [Integer numIds] ): Starts a new transaction.
TransactionDepth( Dynamic loginOrConnect ): Returns the current transaction depth for the database connection.
UniqueID( CAPILOGIN login, [Integer unused], [Integer numIds] ): Returns a new, unique id from the database.
UpdateRights( CAPILOGIN login ): Refreshes the local cached list of rights for the specified login object.
UserID( CAPILOGIN login, [Integer arg2] ): Returns the userid for the specified login object.
UseRightsString( CAPILOGIN login ): Returns TRUE if rights string query with multiple in clauses can be used.
UserInfo( CAPILOGIN login ): Returns the information about the current user for the specified login object.

COMMIT

 Integer COMMIT

Commits database changes when passed to CAPI.EndTransaction().

CT_DBLIB

 Integer CT_DBLIB

Specifies MSSQL as the database type when calling CAPI.AllocConnect() to create a CAPI connection.

CT_ODBC

 Integer CT_ODBC

Specifies ODBC as the database type when calling CAPI.AllocConnect() to create a CAPI connection.

CT_ORACLE

 Integer CT_ORACLE

Specifies Oracle as the database type when calling CAPI.AllocConnect() to create a CAPI connection.

ERR_CLEAR

 Integer ERR_CLEAR

A flag used by CAPI.ErrOption() to set a given CAPIERR such that it discards accumulated errors when CAPI.ClearErr() is called on it.

ERR_KEEP

 Integer ERR_KEEP

A flag used by CAPI.ErrOption() to set a given CAPIERR such that it retains accumulated errors when CAPI.ClearErr() is called on it.

LOG_APPEND

 Integer CAPI_LOG_APPEND

A flag used by CAPI.AllocLog() to set the open mode for the log file.

LOG_TRUNCATE

 Integer CAPI_LOG_TRUNCATE

A flag used by CAPI.AllocLog() to set the open mode for the log file.

PROXY_NONE

 Integer CAPI_PROXY_NONE

A flag used in CAPI.RightsList() to retrieve the regular rights of the current user.

PROXY_WAPI

 Integer CAPI_PROXY_WAPI

A flag used in CAPI.RightsList() to retrieve the proxy rights for WAPI of the current user.

ROLLBACK

 Error ROLLBACK

Rolls back a database transaction when passed to CAPI.EndTransaction().

AllocConnect

 CAPICONNECT AllocConnect(
                    Integer type,
                    String server,
                    String database,
                    String user,
                    String password,
                    CAPILOG log,
                    CAPIERR err,
                    Integer ctflags )

Allocates a CAPICONNECT object to the specified server and database. The type parameter must contain either CAPI.CT_CTLIB, CAPI.CT_MSDBLIB or CAPI.CT_ORACLE.

Parameters:

type	-	The type of connection to be established.
server	-	The name of the server to connect to.
database	-	The name of the database to be used. This parameter is left blank for Oracle.
user	-	The database user name.
password	-	The database user password.
log	-	An optional log object, returned by CAPI.AllocLog(), that will associate a log file with the connection.
err	-	An optional error object, returned by CAPI.AllocErr(), that will associate an error object with the connection.
ctflags	-	Connection flags for internal use, set to zero.

Returns:

A connection object to the specified database, Error otherwise.

AllocErr

 CAPIERR AllocErr()

Allocates a CAPIERR object for use when allocating a database connection with CAPI.AllocConnect().

Returns:: A CAPIERR object.

AllocLog

 CAPILOG AllocLog(
              String logFilePath,
              Integer openModeFlag )

Allocates a CAPILOG object for use when allocating a database connection with CAPI.AllocConnect().

Parameters:

logFilePath	-	The path to the log file created for this log object.
openModeFlag	-	Optional param either CAPI.LOG_APPEND or default CAPI.LOG_TRUNCATE.

Returns:

A CAPILOG object.

AttachLog

 CAPILOG AttachLog(
              String loggerName,
              [String logFilePath = '',
              Integer openModeFlag = CAPI.LOG_TRUNCATE] )

Attaches to or Allocates a CAPILOG object for use when allocating a database connection with CAPI, or for general logging functionality.

Parameters:

loggerName	-	The name of this logger (will be prefixed with Logging.CS_LOGGER_NAME_PREFIX, which is "com.opentext.contentserver.capi")
logFilePath	-	Optionally, the path to the log file created for this log object if direct file output is desired.
openModeFlag	-	Optional param either CAPI.LOG_APPEND or default CAPI.LOG_TRUNCATE.

Returns:

A CAPILOG object.

AllocLogin

 CAPILOGIN AllocLogin(
                 CAPICONNECT connection,
                 String username,
                 String password,
                 [String spaceName = ''] )

Allocates a CAPILOGIN object for the specified username and password.

Parameters:

connection	-	The database connection, returned by CAPI.AllocConnect(), which points to the Livelink database.
username	-	The username of the Livelink user to be logged in.
password	-	The password for the specified Livelink user.
spaceName	-	The space or domain which the user belongs to. The default is an empty string for standard space or domain.

Returns:

A CAPILOGIN object for the Livelink user that was logged in, Error otherwise.

CheckRight

 Integer CheckRight(
               CAPILOGIN login,
               Integer rightID )

Determines if a user has a certain right in their rights list. An ID in a rights list corresponds to a particular group. For example, a group named "Collaborative Computing" may have the ID 3892. If the user is a member of this group or has been granted rights by this group, the ID 3892 will be found on the user's rights list.

Parameters:

login	-	The CAPILOGIN object for the user whose rights are being checked.
rightID	-	The ID of the right that is being tested against the users rights list.

Returns:

Integer 0 if the specified right is in the user's rights list, an error otherwise.

ClearErr

 Integer ClearErr(
              CAPIERR err )

Clears the current error stack for the specified CAPIERR object, unless the CAPI.ERR_KEEP flag has been set on the CAPIERR with CAPI.ErrOption(), in which case errors will be retained despite the clear call (default behavior may be restored by calling CAPI.ErrOption() with the CAPI.ERR_CLEAR flag). When an error occurs for a given database connection, the error is placed on the error stack. This function allows all accumulated errors to be removed from that stack.

Parameters:

err

The CAPIERR object

Returns:

Integer 0 for success; error otherwise.

ConnectionAttr

 Assoc ConnectionAttr(
              CAPICONNECT connection )

Returns attribute information for the specified database connection.

Parameters:

connection

The connection for which information should be returned.

Returns:

An assoc containing all the attribute information for the specified database connection. This assoc will contain the following information:

ConnectionType	-	The type of connection (CT_ORACLE, CT_CTLIB, CT_MSDBLIB)
DatabaseType	-	An internal constant identifying type of database
DatabaseServer	-	The name of the server for this connection
DatabaseName	-	The name of the database for this connection
DatabaseUser	-	The database user for this connection
DatabasePWD	-	The password for the database connection
DatabaseAppl	-	The internal application name this connection is using
DatabaseHost	-	The host name for the client connection
Flags	-	Internal flags
Depth	-	The current transaction depth (0-n)
MaxLength	-	The maximum length of a character field for the database
MaxLongLength	-	The maximum length of a long data type for the database
SubQueriesCanAccessBlobs	-	TRUE if this database supports sub queries that access blob in a table, otherwise FALSE
CanInsertSelectWithSameTable	-	TRUE if this database supports inserts statements that use a select on the same table, otherwise FALSE
CanProcessTree	-	TRUE if this database can perform hierarchical joins in a select statement, otherwise FALSE
CanExecuteN	-	TRUE if this database can execute a statement multiple times with different parameters, otherwise FALSE
IsCaseSensitive	-	TRUE if this database is case sensitive, otherwise FALSE
SupportIdentity	-	TRUE if this database supports identity columns, otherwise FALSE
IsValid	-	TRUE if the connection is still valid, otherwise FALSE.

ConnectionInfo

 RecArray ConnectionInfo(
                 [CAPICONNECT connect] )

Returns information about one or all of the currently active connections. If no connection is specified, information about all open connections is returned.

Parameters:

connect

An optional parameter specifying the connection for which information is desired.

Returns:

A RecArray containing information about one or all of the active connections. If an optional connection is specified, the RecArray will contain only a single row. The columns in the RecArray are as follows:

CONNECT	-	The CAPICONNECT object itself
SQL	-	A reference to the internal SQL object
CTYPE	-	The connection type
CFLAGS	-	Internal flags
SERVER	-	The server name for this connection
DBNAME	-	The database name for this connection
USER	-	The database user for this connection
PASSWORD	-	The password for the database connection
REFCNT	-	The current refcount for this CAPICONNECT object

ContextData

 Dynamic ContextData(
               Dynamic value,
              [Dynamic valueIn] )

Gets or sets application specific information from a CAPICONNECT or one of its children. All objects which are derived from a CAPICONNECT object (CAPILOGIN, DAPISESSION, UAPISESSION, etc) can hold application specific information. If the optional second parameter is passed, the context data for the specified object will be set.

Parameters:

value	-	The Object which is having its context data either set or fetched.
valueIn	-	An optional parameter which, when present, sets the value of the context data besides returning it.

Returns:

The current value that is stored as context for the specified object.

Disconnect

 Integer Disconnect(
               CAPICONNECT connection )

Disconnects the CAPICONNECT from its database. Note, this does not deallocate the CAPICONNECT, the CAPICONNECT will only be deallocated when it goes out of scope. When a CAPICONNECT goes out of scope, it is automatically disconnected from its database.

Parameters:

connection

The connection object that is being disconnected from its database.

Returns:

Integer 0 if successful; error otherwise.

EndTransaction

 Integer EndTransaction(
                 Dynamic connectionOrLogin,
                 Dynamic commitOrRollback )

Ends the current database transaction on the specified database connection.

Note that CAPI keeps a running tally of the number of times that CAPI.StartTransaction() has been called since the last CAPI.EndTransaction(). In order for a commit to actually take place, the number of StartTransactions for a given operation must be balanced by an equal number of EndTransactions and all EndTransactions must pass CAPI.COMMIT. This structure allows multiple levels of an application to all call StartTransaction and EndTransaction while still allowing the highest level of the code to maintain ultimate controls over the transaction. If, at any level, CAPI.ROLLBACK is passed, the entire transaction will be rolled back at that point.

Parameters:

connectionOrLogin	-	A CAPICONNECT or CAPILOGIN object
commitOrRollback	-	CAPI.COMMIT for a commit, CAPI.ROLLBACK to rollback a transaction.

Returns:

Integer 0 if successful; error otherwise.

ErrOption

 Integer ErrOption(
                 CAPIERR err,
                 Integer flag )

Sets the flag controlling clear behavior within a CAPIERR given either the flag CAPI.ERR_CLEAR, to clear errors, or CAPI.ERR_KEEP to keep errors when CAPI.ClearErr() is called upon the CAPIERR.

Parameters:

err	-	A CAPIERR.
flag	-	Specifies what to do with the errors within the CAPIERR, either CAPI.ERR_CLEAR to clear them or CAPI.ERR_KEEP to retain them upon clear.

Returns:

The current clear flag.

Exec

 Dynamic Exec(
            CAPICONNECT connection,
            String statement,
           [Dynamic sub<n>] )

Executes a given SQL statement.

Parameterized statements where each parameter is denoted by :A<n> may be used for increased performance. When a parameterized statement is used, the values for the SQL statement parameters are passed as optional arguments to the builtin function. Alternatively, a single List may be passed as the third argument, in which case the elements of the list are used as the values for the parameters in the statement. Any number of parameters may be specified in the statement. If specifying a List as the third argument, no more than three arguments should be passed to the Exec builtin function.

Parameters:

connection	-	The CAPICONNECT object.
statement	-	The SQL statement to be executed.
arg3-n	-	Any parameter values required by the statement. The values to be used for SQL statment parameters may be passed as either a single List argument, or as a variable number of arguments, as with Str.Format(). If passing a List of parameter values, no more than three arguments should be passed to the Exec builtin function.

Returns:

A RecArray if the executed statement is a select statement, containing rows and columns for all the returned data.

An Integer value if the executed statement was a data modification statement, counting the number of rows affected.

An error otherwise.

Here are two short examples:

// Return all values in myTable
Dynamic result = CAPI.Exec( connect, "select * from myTable" )

// Insert the value 1 into myTable
Dynamic result = CAPI.Exec( connect, "insert into myTable values ( :A1 )", 1 )

ExecN

 Dynamic ExecN(
            CAPICONNECT connection,
            String statement,
            RecArray values )

Executes a given SQL statement once for each row in the RecArray.

This function is most useful for efficiently executing the same parameterized statement multiple times with different values. For example, a parameterized insert or update statement may be executed 20 times with different values for its parameters based on the 20 rows in the passed in RecArray.

Parameters:

connection	-	The CAPICONNECT object.
statement	-	The SQL statement to be executed.
values	-	A RecArray for containing the substitution values for the parameters in the statement.

Returns:

On success, an integer representing the number of rows effected by the SQL statement, otherwise an error.

ExecSP

 Dynamic ExecSP(
            CAPICONNECT connection,
            String statement,
           [Dynamic sub<n>] )

Executes a given SQL statement which will execute a stored procedure.

Parameterized statements where each parameter is denoted by :A<n> may be used for increased performance. When a parameterized statement is used, the value for the parameters are passed as optional parameters. Any number of parameters may be specified in the statement.

Parameters:

connection	-	The CAPICONNECT object.
statement	-	The SQL statement to be executed.
arg3-n	-	Any parameter values required by the statement.

Returns:

A RecArray if the executed stored procedure returns tabular data, containing rows and columns for all the returned data.

An Integer value if the executed statement was a data modification statement, counting the number of rows affected.

An error otherwise.

Here is a short examples:

// Who is logged onto the DBMS
Dynamic result = CAPI.ExecSP( connect, "sp_who" )

GetDetailAt

 String GetDetailAt(
              CAPIERR err,
              Integer index )

Retrieves the detail information associated with a specified error.

This function is often used in looping constructs to examine all errors currently stored in a specified error object. Use CAPI.NumErrs() to retrieve the total number of errors stored in the error object.

Parameters:

err	-	The CAPIERR object.
index	-	The index location of the desired error in the error stack.

Returns:

A string containing the detail information for the specified error, undefined if no detail exists.

GetErrAt

 Error GetErrAt(
            CAPIERR err,
            Integer index )

Retrieves the identified error from the specified error object.

This is often used in looping constructs to examine all errors currently stored in a specified error object. Use CAPI.NumErrs() to retrieve the total number of errors stored in the error object.

Parameters:

err	-	The CAPIERR object.
index	-	The index location of the desired error in the error stack.

Returns:

The specified error, if successful; Undefined otherwise.

IniDelete

 Integer IniDelete(
              CAPILOGIN login,
             [String section],
             [String keyword] )

Deletes information from the KIni table.

If the optional section parameter if not passed, all rows in the KIni table will be deleted. If the optional keyword parameter is not passed, all values in the specified section will be deleted.

Parameters:

login	-	The CAPILOGIN object.
section	-	An optional string specifying the section to affect in the KIni table.
keyword	-	An optional string specifying the keyword to delete from the specified section.

Returns:

An Integer 0 if successful, an error otherwise.

IniGet

 Dynamic IniGet(
             CAPILOGIN login,
             String section,
             String keyword,
            [Dynamic dftValue] )

Retrieves the value associated with the specified section and keyword from the KIni table.

Parameters:

login	-	The CAPILOGIN object.
section	-	The section in the KIni table where the keyword is located.
keyword	-	The keyword for the value to be returned
dftValue	-	A default value to be returned if the specified section and keyword pair cannot be found.

Returns:

The value associated with the specified keyword, if successful; Error otherwise.

IniList

 RecArray IniList(
              CAPILOGIN login,
             [String section],
             [String keyword] )

Returns all keyword values in the specified section of the KIni table.

If the optional section parameter is not passed, all the data from the KIni table will be returned.

If the optional keyword parameter is not passed, all the data from the section in the KIni table will be returned.

Parameters:

login	-	The CAPILOGIN object.
section	-	An optional parameter specifying the section to be listed from the KIni table.
keyword	-	An optional parameter specifying the keyword to be listed in the section from the KIni table.

Returns:

A RecArray containing the information requested if successful; Error otherwise.

IniPut

 Integer IniPut(
             CAPILOGIN login,
             String section,
             String keyword,
            [Dynamic value] )

Allows values to be added into the KIni table or to overwrite existing information.

If the value parameter is not passed, the section/keyword value will be set to NULL in the database.

Parameters:

login	-	The CAPILOGIN object.
section	-	The section where the value will be inserted.
keyword	-	The keyword for the value.
value	-	An optional value to be inserted for the section and keyword.

Returns:

The Integer 0 if successful; Error otherwise.

IsValid

 Boolean IsValid(
             CAPICONNECT connection )

Checks to ensure a previously established database connection is still valid.

This is very useful for determining cases where the database connection has unexpectedly dropped due to network or database server problems.

Parameters:

connection

The CAPICONNECT object.

Returns:

TRUE if the connection is still valid, False otherwise.

Log

 Dynamic Log(
           CAPILOG log,
           String message )

Writes the specified INFO message to the connection log file. This is an alias of LogInfo

Parameters:

log	-	The CAPILOG object.
message	-	The message to be written to the log file.

Returns:

The Integer 0 if successful; Error otherwise.

LogError

 Dynamic LogError(
           CAPILOG log,
           String message )

Writes the specified ERROR message to the connection log file.

Parameters:

log	-	The CAPILOG object.
message	-	The error message to be written to the log file.

Returns:

The Integer 0 if successful; Error otherwise.

LogInfo

 Dynamic LogInfo(
           CAPILOG log,
           String message )

Writes the specified INFO message to the connection log file.

Parameters:

log	-	The CAPILOG object.
message	-	The info message to be written to the log file.

Returns:

The Integer 0 if successful; Error otherwise.

LogWarn

 Dynamic LogWarn(
           CAPILOG log,
           String message )

Writes the specified WARN message to the connection log file.

Parameters:

log	-	The CAPILOG object.
message	-	The warning message to be written to the log file.

Returns:

The Integer 0 if successful; Error otherwise.

LoginInfo

 RecArray LoginInfo(
              [CAPILOGIN login] )

Returns information about one or all of the currently active logins. If no login is specified, information about all current logins is returned

Parameters:

An optional parameter specifying the login for which information is desired.

Returns:

A RecArray containing information about one or all of the active logins. If an optional login is specified, the RecArray will contain only a single row. The columns in the RecArray are as follows:

LOGIN	-	The CAPILOGIN object itself
CONNECT	-	The CAPICONNECT that this login was allocated from.
USERNAME	-	The Livelink user
USERPWD	-	The password for the Livelink user
USERID	-	The unique ID for this user
GROUPID	-	The default group for this user
PRIVS	-	The privileges for this user
REFCNT	-	The current refcount for this CAPILOGIN object

Now

 Date Now(
        CAPICONNECT connect )

Returns the current date and time for the database server specified by the CAPICONNECT.

Parameters:

connect

The CAPICONNECT object indicating the database server for which the current date and time is returned.

Returns:

The current date and time of the database server, if successful; Error otherwise.

NumErrs

 Integer NumErrs(
             CAPIERR error )

Determines the number of errors stored in the specified error object.

Parameters:

error

The CAPIERR object for which the number of errors is returned.

Returns:

An Integer indicating the number of errors currently stored in the specified error object, if successful; Undefined otherwise.

Parent

 Dynamic Parent(
             Dynamic value )

Retrieves the parent object for the specified object. For example, CAPILOGIN objects will return their associated CAPICONNECT object. DAPISESSION objects, UAPISESSION objects and WAPISESSION objects will return their associated CAPILOGIN object.

Parameters:

value

The object for which the parent object is desired.

Returns:

The parent connection of the specified object, if successful; Error otherwise. The connection type of the parent is determined by the object specified in the following way:

CAPILOGIN	-	A CAPICONNECT object
DAPISESSION	-	A CAPILOGIN object
UAPISESSION	-	A CAPILOGIN object
WAPISESSION	-	A CAPILOGIN object
DAPINODE	-	A DAPISESSION object
DAPIVERSION	-	A DAPINODE object

RestartTransaction

 Integer RestartTransaction(
                   Dynamic connectOrLogin,
                   Dynamic status )

Restarts a database transaction that was previously started by CAPI.StartTransaction(), preserving the current transaction depth.

Parameters:

connectOrLogin	-	The CAPICONNECT or CAPILOGIN owning the transaction.
status	-	A constant indicating what action to perform on the specified transaction. Acceptable values are CAPI.COMMIT and CAPI.ROLLBACK.

Returns:

The Integer 0 if successful; Error otherwise.

RightsList

 RecArray RightsList(
                CAPILOGIN login,
		[Integer proxyType] )

Returns a RecArray containing the ID numbers of all groups and projects of which the specified user is a member.

Parameters:

login	-	The CAPILOGIN object for the user.
proxyType	-	The proxy type. The default is CAPI.PROXY_NONE.

Returns:

A RecArray containing the ID numbers of those projects and groups of which the specified user is a member. The fields returned are as follows:

Name	-	The name of the right.
Type	-	The type of the right.
Description	-	A description of the right.

RightsSet

 Assoc RightsSet(
                CAPILOGIN login )

Returns an assoc with keys containing the rights ID of the current user.

Parameters:

The CAPILOGIN object for the user.

Returns:

An assoc with keys of right IDs.

RightsString

 String RightsString(
               CAPILOGIN login,
               String columnName )

Returns a string containing all the right ids for the specified user formatted for use in an SQL statement's "where" clause. The column name in the second parameter will be used to format the "where" clause.

Parameters:

login	-	The CAPILOGIN object for the specified user.
columnName	-	The column name to use when formatting the string.

Returns:

A string containing all the right ids for the specified user formatted for use in an SQL statement's "where" clause.

StartTransaction

 Integer StartTransaction(
                  Dynamic connectOrLogin,
                 [Integer numberOfIds] )

Begins a new database transaction on the specified CAPICONNECT or CAPILOGIN. If a CAPILOGIN is specified, the connection used to allocate the login will be used in the transaction. The optional second parameter is useful for specifying the number of unique database ids this transaction will use. If the number of unique ids in a given user's cache is exhausted during the transaction, locking problems on the KID table may result.

Transactions created via the CAPI interface are reference counted. This means that the initial call to StartTransaction will actually begin the transaction and subsequent calls to StartTransaction, made before an EndTransaction, will simply increment a count. This way, multiple levels of an application can implement transaction control without having to be aware of the controlling code.

Parameters:

connectOrLogin	-	The CAPICONNECT or CAPILOGIN to be used for the transaction.
numberOfIds	-	The number of unique ids to reserve for this transaction.

Returns:

The Integer 0 if successful; Error otherwise.

Here is an example:

Integer		status

status = CAPI.StartTransaction( myConnect )	// A transaction starts.  Refcount=1
...
MyFunction( myConnect )				// Call a subroutine
...
CAPI.EndTransaction( myConnect, CAPI.COMMIT )	// The transaction is actually committed

Function MyFunction( CAPICONNECT connect )
	Integer	status

	status = CAPI.StartTransaction( connect )	// Transaction refcount goes to 2
	...
	CAPI.EndTransaction( myConnect, CAPI.COMMIT )	// The refcount drops back to 1
end

TransactionDepth

 Integer TransactionDepth(
                  Dynamic connectOrLogin )

Determines the current transaction depth or the current refCount for the specified connection or login. If a login is specified, the connection that is associated with the login will be used.

Parameters:

connectOrLogin

The CAPICONNECT or CAPILOGIN to be used for the transaction

Returns:

An Integer representing the current transaction depth; Error otherwise.

UniqueID

 Integer UniqueID(
              Dynamic connectOrLogin,
              Integer unused,
             [Integer numIds] )

Generates a new, unique ID from the internal Livelink ID cache. Each unique ID that is generated will be unique across the entire Livelink database. If the optional numIds parameter is used, the first id that was allocated will be returned but, the next n ids will be in consecutive order.

Parameters:

connectOrLogin	-	The CAPICONNECT or CAPILOGIN to be used for the transaction.
unused	-	This parameter is no longer used. It should be 0.
numIds	-	The number of unique ids to be allocated.

Returns:

The ID that was generated; Error otherwise.

UpdateRights

 Integer UpdateRights(
                CAPILOGIN login )

Updates the rights list that is cached by the specified login. This call is useful for making sure that the rights list inside of a specified login remains in sync with the actual data in the Livelink database.

Parameters:

The CAPILOGIN which is to be refreshed.

Returns:

The Integer 0 if successful; Error otherwise.

UserID

 Integer UserID(
             CAPILOGIN login,
            [Integer userId] )

Returns the specified user's ID or allows an administrator to log-in as a particular user. If the optional userId is specified and the login is the Administrator's login, the Administrator login will be changed to represent a login for the specified user Id.

Parameters:

login	-	The CAPILOGIN for the user to be examined.
userId	-	The user ID that the Administrator requests to login as.

Returns:

An Integer indicating the user ID, if successful; Error otherwise.

UseRightsString

 Boolean UseRightsString(
             CAPILOGIN login )

Returns TRUE if the rights string query with multiple in clauses can be used for this current user.

Parameters:

The CAPILOGIN for the user to be examined.

Returns:

A boolean indicating if the rights string query with multiple in clauses can be used.

UserInfo

 RecArray UserInfo(
               CAPILOGIN login )

Returns information about the current user for the specified CAPILOGIN object.

Parameters:

The CAPILOGIN for the user to be examined.

Returns:

A RecArray containing a single record which will have the following fields:

ID	-	Integer	-	The user ID
OWNERID	-	Integer	-	The user ID of the user who created the group
TYPE	-	Integer	-	The user's class membership type
NAME	-	String	-	The name of the group of which the user is a member
USERDATA	-	Dynamic	-	The user's information
USERPWD	-	Dynamic	-	The user's password in encrypted format
GROUPID	-	Integer	-	The user's group ID
USERPRIVILEGES	-	Integer	-	The user's privileges
LASTNAME	-	String	-	The user's last name
MIDDLENAME	-	String	-	The user's middle name
FIRSTNAME	-	String	-	The user's first name
MAILADDRESS	-	String	-	The user's e-mail address
GROUPOWNERID	-	Integer	-	The user ID of the user who created the user's group
GROUPTYPE	-	Integer	-	The class membership type of the user's group
GROUPNAME	-	String	-	The name of the user's group
GROUPUSERDATA	-	Dynamic	-	The group information for the user's group