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 Content Server login objects and provides a number of convenience functions for use with any Content Server 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; ExecDirect() to directly execute a statement without parameters; 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 Content Server objects.
ContextData() sets or retrieves user-specific data associated with a CAPI-related object.
DBDateString(), GetDateStringSQL() get a Datetime string to be used to construct SQL statements.

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

Class Attributes

COMMIT

Commits database changes when passed to CAPI.EndTransaction function.

CT_HANA

Specifies SAP HANA 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.

CT_POSTGRESQL

Specifies PostgreSQL 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

Class Methods

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

Allocates a CAPI connection to the specified server and database.

AllocErr( )

Allocates a CAPIERR object.

AllocLog( String logFilePath, Integer openModeFlag )

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

Allocates a Content Server login object.

AttachLog( String loggerName, String logFilePath, Integer openModeFlag )

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 connect] )

Returns basic information about one or more CAPICONNECT objects.

ContextData( Dynamic value, [Dynamic valueIn] )

Allows user specific data to be stored and retrieved from a given CAPI related object.

DBDateString( CAPICONNECT connection )

Gets a string for retrieving the current Datetime provided by the Content Server database.

Disconnect( CAPICONNECT connection )

Disconnects the specified CAPICONNECT object from the database.

EndTransaction( Dynamic connectionOrLogin, Dynamic commitOrRollback )

Ends the current database transaction.

ErrOption( CAPIERR err, Integer flag )

Allows accumulated errors to be cleared in a CAPIErr.

Exec( CAPICONNECT connection, String statement, [Dynamic arg3-n] )

Executes a single SQL statement.

ExecDirect( CAPICONNECT connection, String statement )

Directly executes a single SQL statement.

ExecN( CAPICONNECT connection, String statement, RecArray values )

Executes a single, parameterized statement, multiple times, once for each set of parameter values in the paramValues array.

ExecSP( CAPICONNECT connection, String statement, [Dynamic arg3-n] )

Executes a single, optionally parameterized statement which will execute a stored procedure.

GetDateStringSQL( CAPICONNECT connection )

Gets a SQL statement for retrieving the current Datetime provided by the Content Server database.

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 dftValue] )

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

Checks the IsValid flag for the specified connection.

Log( CAPILOG log, String message )

Writes a message to the log file associated with the specified login.

LogError( CAPILOG log, String message )

LogInfo( CAPILOG log, String message )

LoginInfo( [CAPILOGIN login] )

Returns basic information about one or more CAPILOGIN objects.

LogWarn( CAPILOG log, String message )

Now( CAPICONNECT connect )

Returns the current time from the database.

NumErrs( CAPIERR error )

Returns the number of errors currently on the error stack.

Parent( Dynamic value )

Returns the parent object for the specified object.

RestartTransaction( Dynamic connectOrLogin, 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, [List userTypes] )

Returns a string containing the rights for the specified login, formatted for use in an SQL statement.

StartTransaction( Dynamic connectOrLogin, [Integer numberOfIds] )

Starts a new transaction.

TransactionDepth( Dynamic connectOrLogin )

Returns the current transaction depth for the database connection.

UniqueID( Dynamic connectOrLogin, 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 userId] )

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.

Class Attributes

Integer COMMIT

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

Integer CT_HANA

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

Integer CT_ODBC

Specifies ODBC as the database type when calling CAPI.AllocConnect() to create a CAPI connection. This is used for connections to Microsoft SQL Server.

Integer CT_ORACLE

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

Integer CT_POSTGRESQL

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

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.

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.

Integer LOG_APPEND

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

Integer LOG_TRUNCATE

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

Integer PROXY_NONE

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

Integer PROXY_WAPI

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

Error ROLLBACK

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

Class Methods

AllocConnect

CAPICONNECT AllocConnect( Integer type,
                          String server,
                          String database,
                          String user,
                          String password,
                          Integer log,
                           err,
                           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.

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 Content Server database.

username

The username of the Content Server user to be logged in.

password

The password for the specified Content Server 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 Content Server user that was logged in, Error otherwise.

AttachLog

CAPILOG AttachLog( String loggerName,
String logFilePath,
Integer openModeFlag )

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.

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

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:

Field	Contains
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:

Column	Contains
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.

DBDateString

String DBDateString( CAPICONNECT connection )

Gets a string for retrieving the current Datetime (without timezone) provided by the Content Server database. NOTE: The return value may not be used in the same way across all database servers. OScript programmers may have to check if an operator would be valid when applied to the string. For example, the operator '+' and '-' cannot be applied to the return value in cases of Hana AND Posgressql. However, they will work with SQL Server and Oracle.

Parameters

connection

The database connection, returned by CAPI.AllocConnect(), which points to the Content Server database.

Returns:

The string for getting the current Datetime used by the database specified by the CAPICONNECT object, if successful; Error otherwise.

Example

        CAPICONNECT cnntSqlServer = ... 
        String retVal = CAPI.DBDateString( cnntSqlServer )
        Echo( retVal) // 'GetDate()'

        CAPICONNECT cnntOracle = ... 
        String retVal = CAPI.DBDateString( cnntOracle )
        Echo( retVal) // 'SYSDATE'

        CAPICONNECT cnntPostgresql = ... 
        String retVal2 = CAPI.DBDateString( cnntPostgresql )
        Echo( retVal2) // 'now()::timestamp'

        // Add 10 days to the current date using interval.
        Integer days = 10
        String sql = Str.Format("SELECT %1 + interval '%2 day'", CAPI.DBDateString( cnntPostgresql ), days ))

        CAPICONNECT cnntHana = ... 
        String retVal2 = CAPI.DBDateString( cnntOthers )
        Echo( retVal2) // 'CURRENT_TIMESTAMP'

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 arg3-n] )

Executes a given SQL statement.

Parameterized statements where each parameter is denoted by :A 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.

Example

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 )

ExecDirect

Dynamic ExecDirect( CAPICONNECT connection,
String statement )

Directly executes a given SQL statement. The statement must not contain bind parameters.

Direct execution is best used with statements that are executed one time. In most cases, Exec() will be more efficient, because the database will cache the parsed statement and its execution plan.

Parameters

connection

The CAPICONNECT object.

statement

The SQL statement to be executed.

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.

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 affected by the SQL statement, otherwise an error.

ExecSP

Dynamic ExecSP( CAPICONNECT connection,
String statement,
[Dynamic arg3-n] )

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

Parameterized statements where each parameter is denoted by :A 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.

Example

Here is a short examples:

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

GetDateStringSQL

String GetDateStringSQL( CAPICONNECT connection )

Gets a full SQL statement for retrieving the current Datetime (without timezone) provided by the Content Server database.

Parameters

connection

The database connection, returned by CAPI.AllocConnect(), which points to the Content Server database.

Returns:

The SQL statement for getting the current Datetime used by the database specified by the CAPICONNECT object, if successful; Error otherwise.

Example

        String retVal = CAPI.GetDateStringSQL( capiCntSQLServer )
        Echo( retVal ) // "SELECT GetDate()"

        retVal = CAPI.GetDateStringSQL( capiCntOracle )
        Echo( retVal ) // "SELECT SYSDATE FROM DUAL"

        retVal = CAPI.GetDateStringSQL( capiCntPostgreSQL )
        Echo( retVal ) // "SELECT now()::timestamp"

        retVal = CAPI.GetDateStringSQL( capiCntHana )
        Echo( retVal ) // "SELECT CURRENT_TIMESTAMP FROM DUMMY"

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

Does nothing if no optional parameters are provided. If the optional keyword parameter is not passed, all values in the specified section will be deleted.

Parameters

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

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

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

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.

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:

Column	Meaning
LOGIN	The CAPILOGIN object itself
CONNECT	The CAPICONNECT that this login was allocated from.
USERNAME	The Content Server user
USERPWD	The password for the Content Server 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

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.

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:

Object	Parent type
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

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:

Field	Contains
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,
[List userTypes] )

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. Moreover, an optional parameter can be used to select rights only for the specified user types.

Parameters

The CAPILOGIN object for the specified user.

columnName

The column name to use when formatting the string.

userTypes

User types to be used in the resulting SQL statement.

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.

Example

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 Content Server ID cache. Each unique ID that is generated will be unique across the entire Content Server 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 Content Server 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

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:

Field	Type	Description
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
SPACEID	Integer	The ID of user's domain
NAME	String	The name of the group of which the user is a member
USERDATA	Dynamic	The user's information
LEADERID	Integer	The user ID of the group leader
DELETED	Integer	Indicates whether the user or group has been deleted
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
CONTACT	String	The contact data for the user or group
TITLE	String	The user's title
PWDEXPIREDATE	Date	The expiration date of the password
PWDEXPIREMODE	Integer	Verifies that the current password is valid
SETTINGSNUM	Integer	The checksum number of the user settings
FAX	String	The user's office fax number
OFFICELOCATION	String	The full address of the user's office location
TIMEZONE	Integer	The user's timezone as an offset of GMT
PHOTOID	Integer	The location of the user's personal photo
GENDER	Integer	The user's gender; male is 0, female is 1, or unspecified
BIRTHDAY	Date	The user's birthday
PERSONALEMAIL	String	The user's personal e-mail address
HOMEADDRESS1	String	The user's home address
HOMEADDRESS2	String	The user's home address
HOMEPHONE	String	The user's home phone number
HOMEFAX	String	The user's home fax number
CELLULARPHONE	String	The user's home cellular number
PAGER	String	The user's home pager number
HOMEPAGE	String	URL of the user's personal Web page
FAVORITES1	String	A user's favorite URL
FAVORITES2	String	A user's favorite URL
FAVORITES3	String	A user's favorite URL
INTERESTS	String	A list of the user's hobbies or interests
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