FairCom — FairCom DB Direct SQL Function Reference Guide

This is the function reference guide for FairCom DB SQL Direct Programmatic SDK. This SDK allows the user to work with FairCom DB SQL embedded in a C language application.

ctsqlAbort

Abort the current transaction.

Declaration

CTSQLRET ctsqlAbort(pCTSQLCONN hConn)

Description

ctsqlAbort() aborts the current transaction. A new transaction will automatically start.

hConn the connection handle.

Return

ctsqlAbort() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_NOACTIVECONN	Connection inactive.

See Also

ctsqlBegin(), ctsqlCommit()

ctsqlAddNumeric

Adds two numeric values.

Declaration

CTSQLRET ctsqlAddNumeric(NUMERIC* num1, NUMERIC* num2, NUMERIC* res)

Description

ctsqlAddNumeric() adds two numeric values.

num1 the first operand to the addition.
num2 the second operand to the addition.
res the result of the add operation.

Return

ctsqlAddNumeric() returns 0 on success, or -1 on failure.

See Also

ctsqlSubNumeric(), ctsqlMulNumeric(), ctsqlDivNumeric()

ctsqlAffectedRows

Returns the number of rows affected by command.

Declaration

INTEGER ctsqlAffectedRows(pCTSQLCMD hCmd)

Description

ctsqlAffectedRows() returns the number of rows affected by command.

hCmd the command handle.

Return

ctsqlAffectedRows() returns the number of affected rows.

ctsqlClearAutoCommit

Clears the autocommit flag.

Declaration

CTSQLRET ctsqlClearAutoCommit(pCTSQLCONN hConn)

Description

ctsqlClearAutoCommit() clears the autocommit flag.

hConn the connection handle.

Return

Returns CTSQLRET_OK on success.

See Also

ctsqlSetAutoCommit(), ctsqlGetAutoCommit()

ctsqlClearError

Clears error information.

Declaration

void ctsqlClearError(pCTSQLCONN hConn)

Description

Clears the error information returned by ctsqlGetError() and ctsqlGetErrorMessage().

Return

Void.

See Also

ctsqlGetError(), ctsqlGetErrorMessage()

ctsqlClose

Close a FairCom DB SQL cursor.

Declaration

CTSQLRET ctsqlClose(pCTSQLCMD hCmd)

Description

ctsqlClose() closes a FairCom DB SQL cursor. A cursor is created with ctsqlNewCursor().

hCmd the command handle.

Return

ctsqlClose() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_NOTOPENED	Cursor not opened

See Also

ctsqlNewCursor(), ctsqlFreeCursor()

ctsqlCommit

Commits the current transaction.

Declaration

CTSQLRET ctsqlCommit(pCTSQLCONN hConn)

Description

ctsqlCommit() commits the current transaction. A new transaction will automatically begin.

hConn the connection handle.

Return

ctsqlCommit() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_NOACTIVECONN	Connection inactive.

See Also

ctsqlBegin(), ctsqlAbort()

ctsqlCompare

Compares two data objects of a given field type.

Declaration

CTSQLRET ctsqlCompare(CTSQLTYPE dtype, void* buffer1, INTEGER length1, void* buffer2, INTEGER length2, INTEGER* result)

Description

ctsqlCompare() compares two data objects of a given field type.

dtype the data type of the two objects that are being compared
buffer1 the buffer containing the first object to be compared
length1 the length in bytes of the first data object
buffer2 the buffer containing the second object to be compared
length2 the length in bytes of the second data object
result receives the result of the comparison. A negative value indicates first object is less than second object. A positive value indicates first object is greater than second object. A zero indicates both objects are equal.

Return

ctsqlCompare() returns CTSQLRET_OK on success.

ctsqlConnect

Establishes a connection with a FairCom DB SQL database using DSQL.

Declaration

CTSQLRET ctsqlConnect(pCTSQLCONN hConn, CTSQLCHAR* dbname, CTSQLCHAR* username, CTSQLCHAR* password)

Description

ctsqlConnect() establishes a connection with a FairCom DB SQL database. If a connection is active, ctsqlConnect() will disconnect the current connection and try to obtain a new connection.

hConn the connection handle, obtained with a call to ctsqlNewConnection()
dbname the database name
username the user name to connect
password the user password

Usage

If you are remotely connecting to your server, the SQL port and DNS name need to be specified in the connection string supplied for the dbname parameter. The format is as follows:

c-treeSQLPort@DNS:DatabaseName

The defaults for FairCom DB SQL are:

c-treeSQLPort - 6597
DNS - localhost
DatabaseName - ctreeSQL

The resulting connection string would be: 6597@localhost:ctreeSQL

Return

ctsqlConnect() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_NOMEM	Memory allocation failure.

See Also

ctsqlDisconnect(), ctsqlNewConnection(), ctsqlSetSSL

ctsqlConvert

Converts data from one type representation to the desired type representation.

Declaration

CTSQLRET ctsqlConvert(CTSQLTYPE stype, void* buffer1, INTEGER length1, CTSQLCHAR* fmt, CTSQLTYPE dtype, void* buffer2, INTEGER length2)

Description

ctsqlConvert() converts data from one given representation to a new type representation.

stype The data type of the source buffer which is being converted.
buffer1 The buffer containing the source data
length1 Length in bytes of data in source buffer
fmt format string to be used for formatting the output if the desired destination data is a character string type. Currently a format string can be specified only if the input is of type TPE_DT_DATE and the output is of type TPE_DT_CHAR.
dtype The data type of the destination buffer
buffer2 The buffer to receive the converted data
length2 Length in bytes of the destination buffer

Return

ctsqlConvert() returns CTSQLRET_OK on success.

ctsqlDayOfWeek

Retrieves the day of the week from a date value.

Declaration

int ctsqlDayOfWeek(SQLDATE date)

Description

ctsqlDayOfWeek() retrieves the day of the week given a date value.

date the date value.

Return

ctsqlDayOfWeek() returns the day of the week as an integer value ranging from 0 to 6 where 0 represents Sunday, 1 represent Monday and 6 represents Saturday.

ctsqlDeployStp

Declaration

CTSQLRET ctsqlDeployStp(pCTSQLCONN hConn, pCTSQLPROCINFO hprocinfo)

Description

Deploys a stored procedure.

hConn [IN] - connection handle
hprocinfo [IN] - pointer to procedure info structure

Return Values

Value	Symbolic Constant	Explanation
0	CTSQLRET_OK	No Error

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctsqlNewProcInfo() (ctsqlNewProcInfo, ctsqlNewProcInfo) ctsqlFreeProcInfo() (ctsqlFreeProcInfo, ctsqlFreeProcInfo) ctsqlDumpStpRaw() (ctsqlDumpStpRaw, ctsqlDumpStpRaw) ctsqlDumpStp() (ctsqlDumpStp, ctsqlDumpStp) ctsqlDeployStpRaw() (ctsqlDeployStpRaw, ctsqlDeployStpRaw) ctsqlDeployStp()

ctsqlDeployStpRaw

Declaration

CTSQLRET ctsqlDeployStpRaw(pCTSQLCONN hConn, pCTSQLPROCINFO hprocinfo, void* buffer, INTEGER bufferLen)

Description

Deploys a stored procedure in Raw mode.

hConn [IN] - connection handle
hprocinfo [IN] - pointer to procedure info structure
buffer [OUT] - pointer to pointer to rawbuffer
bufferLen [OUT] - pointer to rawbuffer length

Return Values

Value	Symbolic Constant	Explanation
0	CTSQLRET_OK	No Error

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctsqlDisconnect

Disconnects from FairCom DB SQL.

Declaration

CTSQLRET ctsqlDisconnect(pCTSQLCONN hConn)

Description

ctsqlDisconnect() disconnects from FairCom DB SQL. If a connection is not active, ctsqlDisconnect() simply returns CTSQLRET_OK.

hConn the connection handle.

Return

ctsqlDisconnect() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlConnect(), ctsqlNewConnection(), ctsqlFreeConnection()

ctsqlDivNumeric

Divides two numeric values.

Declaration

CTSQLRET ctsqlDivNumeric(NUMERIC* num1, NUMERIC* num2, NUMERIC* res)

Description

ctsqlDivNumeric() divides two numeric values.

num1 the value to be divided (divisor).
num2 the value to divide (dividend).
res the result of the division operation.

Return

ctsqlDivNumeric() returns 0 on success, or -1 on failure.

See Also

ctsqlAddNumeric ctsqlSubNumeric ctsqlMulNumeric

ctsqlDumpStp

Declaration

CTSQLRET ctsqlDumpStp(pCTSQLCONN hConn, pCTSQLPROCINFO hprocinfo)

Description

Dump a stored procedure.

hConn [IN] - connection handle
hprocinfo [IN] - pointer to procedure info structure

Return Values

Value	Symbolic Constant	Explanation
0	CTSQLRET_OK	No Error

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctsqlDumpStpRaw

Declaration

CTSQLRET ctsqlDumpStpRaw(pCTSQLCONN hConn, pCTSQLPROCINFO hprocinfo, void** buffer, INTEGER* bufferLen)

Description

Dumps a stored procedure in Raw mode.

hConn [IN] - connection handle
hprocinfo [IN] - pointer to procedure info structure
buffer [OUT] - pointer to pointer to rawbuffer
bufferLen [OUT] - pointer to rawbuffer length

Return Values

Value	Symbolic Constant	Explanation
0	CTSQLRET_OK	No Error

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctsqlExecute

Executes a FairCom DB SQL command after preparing it.

Declaration

CTSQLRET ctsqlExecute(pCTSQLCMD hCmd, ppCTSQLCURSOR pCursor)

Description

ctsqlExecute() executes a FairCom DB SQL command after it has been prepared with ctsqlPrepare() or ctsqlPrepareBatch(). If executing a select query, ctsqlExecute() allocates a new cursor handle.

hCmd the command handle.
pCursor the cursor handle allocated by ctsqlExecute(), if the command being executed is a select query. If the command is not a select query, pCursor is set to NULL.

Return

ctsqlExecute() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_NOTOPENED	Cursor not opened
SQL_ERR_NOTSELECT	Open for non select statement
SQL_ERR_NOMEM	Memory allocation failure.

See Also

ctsqlPrepare(), ctsqlPrepareBatch(), ctsqlExecuteDirect()

ctsqlExecuteDirect

Executes a FairCom DB SQL command directly.

Declaration

CTSQLRET ctsqlExecuteDirect(pCTSQLCMD hCmd, CTSQLCHAR* sqlcmd)

Description

ctsqlExecuteDirect() executes aFairCom DB SQL command directly without the need to a previous preparation of the statement. It is also possible to split the command in preparation (ctsqlPrepare()) and execution (ctsqlExecute()).

hCmd the command handle.
sqlcmd the sql command string.

Return

ctsqlExecuteDirect() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_NOTOPENED	Cursor not opened
SQL_ERR_NOTSELECT	Open for non select statement
SQL_ERR_NOMEM	Memory allocation failure.

See Also

ctsqlPrepare(), ctsqlExecute()

ctsqlFirst

Retrieve the first row from cursor.

Declaration

CTSQLRET ctsqlFirst(pCTSQLCURSOR hCursor)

Description

hCursor - the cursor handle

Return Values

CTSQLRET_OK on success.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

ctsqlFreeCommand

Release resources associated with a command handle.

Declaration

void ctsqlFreeCommand(pCTSQLCMD hCmd)

Description

ctsqlFreeCommand() releases resources associated with a command handle. If a command has open cursors, it will close the cursors before releasing resources.

hCmd the command handle.

Return

None.

See Also

ctsqlNewCommand()

ctsqlFreeConnection

Releases a connection resource.

Declaration

void ctsqlFreeConnection(pCTSQLCONN hConn)

Description

ctsqlFreeConnection() releases the connection resources when a FairCom DB SQL connection is no longer needed. If the connection is active, ctsqlFreeConnection() will automatically invoke ctsqlDisconnect() before releasing the connection.

hConn the connection handle, acquired in the ctsqlNewConnection() call.

Return

None.

See Also

ctsqlDisconnect(), ctsqlNewConnection()

ctsqlFreeCursor

Release memory associated with a cursor.

Declaration

void ctsqlFreeCursor(pCTSQLCURSOR hCursor)

Description

ctsqlFreeCursor() releases memory associated with a cursor.

hCursor the cursor handle.

Return

None.

See Also

ctsqlClose(), ctsqlNewCursor()

ctsqlGetAutoCommit

Retrieve the state of the auto commit flag .

Declaration

BIT ctsqlGetAutoCommit(pCTSQLCONN hConn)

Description

ctsqlGetAutoCommit() retrieves the state of the auto commit flag.

hConn the connection handle.

Return

ctsqlGetAutoCommit() returns CTSQL_TRUE if auto commit flag is on, CTSQL_FALSE otherwise.

See Also

ctsqlSetAutoCommit(), ctsqlClearAutoCommit()

ctsqlGetBigInt

Retrieve the big int field.

Declaration

CTSQLRET ctsqlGetBigInt (pCTSQLCURSOR hCursor, INTEGER colnumber, BIGINT* buffer)

Description

ctsqlGetBigInt() retrieves the value of a big int field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetBigInt() returns CTSQLRET_OK on success.

Prior to V12, a call to this function, or similar ctsqlGet*() functions for other data types, would fail with SQL_ERR_BADARG if the column value was a SQL NULL. These functions now return CTSQL_NULLRESULT if the data value is a SQL NULL. This change does not apply to ctsqlGetBinary or ctsqlGetBlob. Note: This modification is a Compatibility Change.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetBinary

Retrieve the binary field.

Declaration

CTSQLRET ctsqlGetBinary(pCTSQLCURSOR hCursor, INTEGER colnumber, BINARY* buffer)

Description

ctsqlGetBinary() retrieves the value of a binary field, given its cursor and column. A binary field is an array of bytes.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetBinary() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBit

Retrieve the boolean field.

Declaration

CTSQLRET ctsqlGetBit(pCTSQLCURSOR hCursor, INTEGER colnumber, BIT* buffer)

Description

ctsqlGetBit() retrieves the value of a boolean field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetBit() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBlob

Retrieve the blob field.

Declaration

CTSQLRET ctsqlGetBlob(pCTSQLCURSOR hCursor, INTEGER colnumber, void* buffer, INTEGER size, INTEGER offset, INTEGER *bytesread)

Description

ctsqlGetBlob() retrieves the value of a blob field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.
size the maximum number of bytes to read.

offset the offset in bytes from the beginning of the LVARCHAR or LVARBINARY column to the portion that ctsqlGetBlob() writes to buffer.
bytesread return the number of bytes read.

Return

ctsqlGetBlob() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes

Retrieve a binary field.

Declaration

INTEGER ctsqlGetBytes(pCTSQLCURSOR hCursor, INTEGER colnumber, UTINYINT buffer[], INTEGER size)

Description

ctsqlGetBinary() retrieves the value of a binary field, given its cursor and column. A binary field is an array of bytes.

hCursor [IN] - the cursor handle.
colnumber [IN] - the number of columns.
buffer [OUT] - the buffer to receive the field data.
size [IN] - number of bytes in buffer.

Return

Return -1 on error, otherwise the number of bytes actually read or negative on error. Use ctsqlGetError to get the error code:

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBinary(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob(), ctsqlGetError

ctsqlGetChar

Retrieve character data.

Declaration

CTSQLRET ctsqlDECL ctsqlGetChar(pCTSQLCURSOR hCursor, INTEGER colnumber, char* buffer);

Description

ctsqlGetChar() retrieves character data from the given cursor and column.

hCursor the cursor handle
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetChar() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetColumnCount

Retrieve the number of columns.

Declaration

INTEGER ctsqlGetColumnCount(pCTSQLCURSOR hCursor)

Description

ctsqlGetColumnCount() retrieves the number of columns in the table.

hCursor the cursor handle.

Return

ctsqlGetColumnCount() returns the number of columns.

See Also

ctsqlGetColumnNameLen(), ctsqlGetColumnName(), ctsqlGetColumnType(), ctsqlGetColumnLength(), ctsqlGetColumnPrecision(), ctsqlGetColumnScale(), ctsqlGetColumnTitile()

ctsqlGetColumnLength

Retrieve the column length in bytes:

For character data types, the return value represents the data length in the number of bytes, including the null terminator. This field should be used for purposes of any memory allocation.
For other data types, the return value represents the number of bytes.

Declaration

INTEGER ctsqlGetColumnLength(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlGetColumnLength() retrieves the column length.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlGetColumnLength() returns the column length in bytes.

See Also

ctsqlGetColumnName(), ctsqlGetColumnNameLen(), ctsqlGetColumnCount(), ctsqlGetColumnType(), ctsqlGetColumnPrecision(), ctsqlGetColumnScale()

ctsqlGetColumnName

Retrieve the column name.

Declaration

CTSQLCHAR* ctsqlGetColumnName(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlGetColumnName() retrieves the column name, given its number.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlGetColumnName() returns the column name, or NULL if the column number is wrong or if there is any problem with the cursor handle.

See Also

ctsqlGetColumnNameLen(), ctsqlGetColumnCount(), ctsqlGetColumnType(), ctsqlGetColumnLength(), ctsqlGetColumnPrecision(), ctsqlGetColumnScale(), ctsqlGetColumnTitile()

ctsqlGetColumnNameLen

Retrieve the column name length.

Declaration

INTEGER ctsqlGetColumnNameLen(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlGetColumnNameLen() retrieves the column name length, given the column number.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlGetColumnNameLen() returns the length of the column name, or 0 in case of error (colnumber <0 or larger than the number of columns in the table).

See Also

ctsqlGetColumnCount(), ctsqlGetColumnName(), ctsqlGetColumnType(), ctsqlGetColumnLength(), ctsqlGetColumnPrecision(), ctsqlGetColumnScale(), ctsqlGetColumnTitile()

ctsqlGetColumnPrecision

Retrieve the column precision.

Declaration

SMALLINT ctsqlGetColumnPrecision(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlGetColumnPrecision() retrieves the column precision. The column precision represents the total number of digits in a BCD number represented in a column.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlGetColumnPrecision() returns the column precision.

See Also

ctsqlGetColumnName(), ctsqlGetColumnNameLen(), ctsqlGetColumnCount(), ctsqlGetColumnLength(), ctsqlGetColumnType(), ctsqlGetColumnScale(), ctsqlGetColumnTitile()

ctsqlGetColumnScale

Retrieve the column scale.

Declaration

SMALLINT ctsqlGetColumnScale(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlGetColumnScale() retrieves the column scale. The column scale represents the number of decimal digits in a column.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlGetColumnScale() returns the column scale

See Also

ctsqlGetColumnName(), ctsqlGetColumnNameLen(), ctsqlGetColumnCount(), ctsqlGetColumnLength(), ctsqlGetColumnPrecision(), ctsqlGetColumnType(), ctsqlGetColumnTitile()

ctsqlGetColumnTitle

Retrieve the column name.

Declaration

CTSQLCHAR* ctsqlGetColumnName(pCTSQLCURSOR hCursor, INTEGER colnumber)

CTSQLRET ctsqlDECL ctsqlGetColumnTitle(pCTSQLCURSOR hCursor, INTEGER colnumber, CTSQLCHAR* colname, int size);

Description

ctsqlGetColumnTitile() retrieves the column title, given its number.

hCursor the cursor handle.
colnumber the column number.
colname the column title returned.
size the length of the column title parameter.

Return

ctsqlGetColumnTitile() returns the column title, or NULL if the column number is wrong or if there is any problem with the cursor handle.

See Also

ctsqlGetColumnNameLen(), ctsqlGetColumnCount(), ctsqlGetColumnType(), ctsqlGetColumnLength(), ctsqlGetColumnName(), ctsqlGetColumnPrecision(), ctsqlGetColumnScale()

ctsqlGetColumnType

Retrieve the column type.

Declaration

CTSQLTYPE ctsqlGetColumnType(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlGetColumnType() retrieves the column type.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlGetColumnType() returns the column type.

See Also

ctsqlGetColumnName(), ctsqlGetColumnNameLen(), ctsqlGetColumnCount(), ctsqlGetColumnLength(), ctsqlGetColumnPrecision(), ctsqlGetColumnScale(), ctsqlGetColumnTitile()

ctsqlGetCommandFromCursor

Get the command associated with a cursor.

Declaration

CTSQLTYPE ctsqlGetCommandFromCursor(pCTSQLCURSOR hCursor)

Description

hCursor the cursor handle.

Return

Returns the command associated with the cursor.

ctsqlGetConnectionFromCommand

Get the connection associated with a command.

Declaration

CTSQLTYPE ctsqlGetConnectionFromCommand(pCTSQLCURSOR hCursor)

Description

hCursor the cursor handle.

Return

Returns the connection associated with the command.

ctsqlGetConnectionFromCursor

Get the connection associated with a cursor.

Declaration

CTSQLTYPE ctsqlGetConnectionFromCursor(pCTSQLCURSOR hCursor)

Description

hCursor the cursor handle.

Return

Returns the connection associated with the cursor.

ctsqlGetDatabase

Retrieve the current database name.

Declaration

CTSQLCHAR* ctsqlGetDatabase(pCTSQLCONN hConn)

Description

ctsqlGetDatabase() retrieves the current database name.

hConn the connection handle.

Return

ctsqlGetDatabase() returns a pointer to the current database name, or NULL if neither a database name is available, nor the connection handle is valid.

See Also

ctsqlConnect(), ctsqlGetUserName()

ctsqlGetDate

Retrieve the date field.

Declaration

CTSQLRET ctsqlGetDate(pCTSQLCURSOR hCursor, INTEGER colnumber, SQLDATE* buffer)

Description

ctsqlGetDate() retrieves the value of a date field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetDate() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetError

Retrieve the last error’s code.

Declaration

CTSQLRET ctsqlGetError(pCTSQLCONN hConn).

Description

ctsqlGetError() retrieves the last error’s code.

hConn the connection handle.

Return

ctsqlGetError() returns last error’s code, or CTSQLRET_OK if no previous error.

See Also

ctsqlGetErrorMessage

ctsqlGetErrorMessage

Retrieve the last error’s message text.

Declaration

CTSQLCHAR* ctsqlGetErrorMessage(pCTSQLCONN hConn)

Description

ctsqlGetErrorMessage() retrieves the last error’s message text.

hConn the connection handle.

Return

ctsqlGetErrorMessage() returns a pointer to the last error’s message text, or NULL if the connection is not active.

See Also

ctsqlGetError()

ctsqlGetFloat

Retrieve the 64 bit float field.

Declaration

CTSQLRET ctsqlGetFloat(pCTSQLCURSOR hCursor, INTEGER colnumber, FLOAT* buffer)

Description

ctsqlGetFloat() retrieves the value of a 64 bit float field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetFloat() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetInteger

Retrieve an integer field.

Declaration

CTSQLRET ctsqlGetInteger(pCTSQLCURSOR hCursor, INTEGER colnumber, INTEGER* buffer)

Description

ctsqlGetInteger() retrieves the value of an integer field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetInteger() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetIsolationLevel

Retrieve the current transaction isolation level.

Declaration

CTSQL_ISOLEVEL ctsqlGetIsolationLevel(pCTSQLCONN hConn).

Description

ctsqlGetIsolationLevel() retrieves the current transaction isolation level.

hConn the connection handle.

Return

ctsqlGetIsolationLevel() returns the current transaction isolation level.

See Also

ctsqlSetIsolationLevel()

ctsqlGetMoney

Retrieve the money field.

Declaration

CTSQLRET ctsqlGetMoney(pCTSQLCURSOR hCursor, INTEGER colnumber, NUMERIC* buffer)

Description

ctsqlGetMoney() retrieves the value of a money field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetMoney() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetNChar

Retrieve character data.

Declaration

CTSQLRET ctsqlDECL ctsqlGetNChar(pCTSQLCURSOR hCursor, INTEGER colnumber, CTSQLCHAR* buffer);

Description

ctsqlGetNChar() retrieves character data from the given cursor and column.

hCursor the cursor handle
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetNChar() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetNumeric

Retrieve the numeric field.

Declaration

CTSQLRET ctsqlGetNumeric(pCTSQLCURSOR hCursor, INTEGER colnumber, NUMERIC* buffer)

Description

ctsqlGetNumeric() retrieves the value of a numeric field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetNumeric() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetNumericAsString

Declaration

CTSQLRET ctsqlDECL ctsqlGetNumericAsString(pCTSQLCURSOR hCursor, INTEGER colnumber, CTSQLCHAR* buffer, INTEGER size)

Description

Retrieve the value of a numeric field.

Parameters

hCursor - cursor handle
colnumber - number of column
buffer [out] - buffer to receive field data
size - size of buffer

Return

Returns CTSQLRET_OK on success.

ctsqlGetNumericParameterAsString

In V11 and later, DSQL exposes a method to retrieve a numeric parameter as a string.

Function

ctsqlGetNumericParameterAsString

Retrieve the Numeric parameter as string.

Parameters

hCmd [IN] - Command handle.
index [IN] - Parameter number. Must be a number greater or equal to zero but less than parameter count.
buffer [IN] - String buffer pointer.
length [IN] - String buffer size.

Return

Return error code or 0 on success.

Example

CTSQLRET ctsqlDECL ctsqlGetNumericParameterAsString(pCTSQLCMD hCmd, INTEGER index, CTSQLCHAR* buffer, INTEGER length)

ctsqlGetParameter

Retrieve the value of a parameter.

Declaration

CTSQLRET ctsqlDECL ctsqlGetParameter(pCTSQLCMD hCmd, INTEGER index, void* buffer, INTEGER length)

Description

ctsqlGetParameter() retrieves a parameter.

hCmd the command handle.
index the parameter number. Must be a number greater or equal zero, but less than parameter count.
buffer the buffer that will contain the parameter value. The buffer can be NULL if isnull is TRUE.
length the parameter length being passed in buffer. The proper length must be passed.

Return

ctsqlGetParameter() returns the value of a parameter.

See Also

ctsqlGetParameterCount(), ctsqlGetParameterLength(), ctsqlGetParameterName(), ctsqlGetParameterNullFlag(), ctsqlGetParameterPrecision(), ctsqlGetParameterScale(), ctsqlGetParameterType()

ctsqlGetParameterAddress

Get the address of a parameter.

Declaration

TINYINT ctsqlGetParameterAddress(pCTSQLCMD hCmd, INTEGER index)

Description

hCmd - the command handle.
index - the parameter number. Must be a number greater or equal to zero but less than parameter count.

Return Values

Returns the address of a cursor variable.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

ctsqlGetParameterCount

Retrieve the number of parameters required to execute the SQL command.

Declaration

INTEGER ctsqlGetParameterCount(pCTSQLCMD hCmd)

Description

ctsqlGetParameterCount() retrieves the number of parameters required to execute the SQL command.

hCmd the command handle.

Return

ctsqlGetParameterCount() returns the number of parameters.

See Also

ctsqlGetParameterLength(), ctsqlGetParameterType(), ctsqlGetParameterPrecision(), ctsqlGetParameterScale(), ctsqlGetParameterNullFlag()

ctsqlGetParameterDirection

Get the parameter direction (IN/INOUT/OUT).

Declaration

INTEGER ctsqlGetParameterDirection(pCTSQLCMD hCmd, INTEGER index)

Description

hCmd - the command handle.
index - the parameter number. Must be a number greater or equal to zero but less than parameter count.

Stored procedure parameters can be input parameters, output parameters or input/output parameters. When calling a stored procedure, input parameters can be specified as literals. Output and input/output stored procedure parameters must be specified as SQL statement parameters otherwise the engine returns error -20127 “Bad parameter specification for the statement”.

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.
-1	SQL_INV_PARAM	Invalid parameter
1	SQL_IN_PARAM	IN parameter
2	SQL_IN_OUT_PARAM	IN and OUT parameter
4	SQL_OUT_PARAM	OUT parameter
5	SQL_SFN_SUBS_PARAM	Unexpected parameter

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

ctsqlGetParameterIndexByName

In FairCom DB V11.5 and later, ctsqlGetParameterIndexByName, provides a way to identify the parameter index number from its name when using named parameters.

ctsqlGetParameterIndexByName

Declaration

CTSQLRET ctsqlGetParameterIndexByName(pCTSQLCMD hCmd CTSQLCHAR* name)

Description

Retrieve the parameter index given its name when using named parameter :name.

hCmd - the command handle
name - parameter name (without ':').

Return

Return the parameter index or -1 if not found.

ctsqlGetParameterLength

Retrieve the parameter length.

Declaration

INTEGER ctsqlGetParameterLength(pCTSQLCMD hCmd, INTEGER index)

Description

ctsqlGetParameterLength() retrieves the parameter length.

hCmd the command handle.
index the parameter number. Must be a number greater or equal zero, but less than parameter count.

Return

ctsqlGetParameterLength() returns the parameter length.

See Also

ctsqlGetParameterCount(), ctsqlGetParameterType(), ctsqlGetParameterPrecision(), ctsqlGetParameterScale(), ctsqlGetParameterNullFlag()

ctsqlGetParameterName

Support was added in V11 to be able to retrieve the name of a parameter (which makes sense only for named parameters, i.e. ":param"). The following function was added to the FairCom DB SQL Direct SQL API (ctsqlapi.dll) to retrieve parameter names:

Function:

ctsqlGetParameterName

Description:

Retrieve the parameter name (when using named parameter ":name").

Parameters:

hCmd [IN] - Command handle
index [IN] - Parameter number. This must be a number greater or equal to zero but less than the parameter count.

Return:

Returns the parameter name.

ctsqlGetParameterNullFlag

Retrieve the parameter null flag setting.

Declaration

CTSQL_NULLABILITY ctsqlGetParameterNullFlag(pCTSQLCMD hCmd, INTEGER index)

Description

ctsqlGetParameterNullFlag() retrieves the parameter null flag setting.

hCmd the command handle.
index the parameter number. Must be a number greater or equal zero, but less than parameter count.

Return

ctsqlGetParameterNullFlag() returns the null flag value for the parameter. The possible values are: SQL_NO_NULLS, SQL_NULLABLE, SQL_NULLABLE_UNKNOWN

See Also

ctsqlIsNullable(), ctsqlIsColumnNull(), ctsqlGetParameterCount(), ctsqlGetParameterLength(), ctsqlGetParameterType(), ctsqlGetParameterPrecision(), ctsqlGetParameterScale()

ctsqlGetParameterPrecision

Retrieve the parameter precision.

Declaration

SMALLINT ctsqlGetParameterPrecision(pCTSQLCMD hCmd, INTEGER index)

Description

ctsqlGetParameterPrecision() retrieves the parameter precision. The parameter precision represents the total number of digits in a BCD number represented in a parameter.

hCmd the command handle.
index the parameter number. Must be a number greater or equal zero, but less than parameter count.

Return

ctsqlGetParameterPrecision() returns the parameter precision.

See Also

ctsqlGetParameterCount(), ctsqlGetParameterLength(), ctsqlGetParameterType(), ctsqlGetParameterScale(), ctsqlGetParameterNullFlag()

ctsqlGetParameterScale

Retrieve the parameter scale.

Declaration

SMALLINT ctsqlGetParameterScale(pCTSQLCMD hCmd, INTEGER index)

Description

ctsqlGetParameterScale() retrieves the parameter scale. The parameter scale represents the number of decimal digits in a parameter.

hCmd the command handle.
index the parameter number. Must be a number greater or equal zero, but less than parameter count.

Return

ctsqlGetParameterScale() returns the parameter scale.

See Also

ctsqlGetParameterCount(), ctsqlGetParameterLength(), ctsqlGetParameterType(), ctsqlGetParameterPrecision(), ctsqlGetParameterNullFlag()

ctsqlGetParameterType

Retrieve the parameter type.

Declaration

CTSQLTYPE ctsqlGetParameterType(pCTSQLCMD hCmd, INTEGER index)

Description

ctsqlGetParameterType() retrieves the parameter type.

hCmd the command handle.
index parameter number. Must be a number greater or equal zero, but less than parameter count.

Return

ctsqlGetParameterType() returns the type of parameter. Return 0 on error.

See Also

ctsqlGetParameterCount(), ctsqlGetParameterLength(), ctsqlGetParameterPrecision(), ctsqlGetParameterScale(), ctsqlGetParameterNullFlag()

ctsqlGetReal

Retrieve a 32 bit float field.

Declaration

CTSQLRET ctsqlGetReal(pCTSQLCURSOR hCursor, INTEGER colnumber, SMALLFLOAT* buffer)

Description

ctsqlGetReal() retrieves the value of a 32 bit float field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetSmallFloat() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetRow

Retrieve and position to the nth row of the resultset with 1 being the first row.

Declaration

CTSQLRET ctsqlGetRow(pCTSQLCURSOR hCursor, INTEGER nth)

Description

hCursor - the cursor handle
nth - the nth row retrieve relative to the current position. nth must be positive.

If the movement goes beyond the resultset first or last row, the operation returns CTSQLRET_NOTFOUND (100) and the current position is set either before (if moving backward) or after the last row (if moving forward).

Return Values

CTSQLRET_OK on success.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

ctsqlGetScrollableCursor

Retrieves the state of the scrollable cursor flag.

ctsqlSetScrollableCursor requires a valid command handle and needs to be called before the "prepare" call.

Parameters:

[hCmd] - Must point to a valid command handle.

Return:

Returns CTSQL_TRUE if scrollable cursor flag is on.

ctsqlGetSmallInt

Retrieve a small int field.

Declaration

CTSQLRET ctsqlGetSmallInt(pCTSQLCURSOR hCursor, INTEGER colnumber, SMALLINT* buffer)

Description

ctsqlGetSmallInt() retrieves the value of a small int field, given its cursor and column.

hCursor cursor handle.
colnumber column number.
buffer the buffer that will store the field data.

Return

ctsqlGetSmallInt() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetTime

Retrieve the time field.

Declaration

CTSQLRET ctsqlGetTime(pCTSQLCURSOR hCursor, INTEGER colnumber, SQLTIME* buffer)

Description

ctsqlGetTime() retrieves the value of a time field, given its cursor and column.

hCursor cursor handle.
colnumber column number.
buffer the buffer that will store the field data.

Return

ctsqlGetTime() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTimeStamp(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetTimeout

Declaration

INTEGER ctsqlDECL ctsqlGetTimeout(pCTSQLCMD hCmd);

Description

ctsqlGetTimeout() retrieves the time-out value associated with the command handle.

hCmd a valid command handle.

FairCom DB SQL supports a time-out option for executing a query. This feature can ensure that an unintended query statement does not consume excessive processing time of FairCom DB SQL.

Return Values

ctsqlGetTimeout() returns the time-out value. A return value of zero indicate that the execution will not time-out.

See Also

ctsqlSetTimeout()

ctsqlGetTimeStamp

Retrieve the time stamp field.

Declaration

CTSQLRET ctsqlGetTimeStamp(pCTSQLCURSOR hCursor, INTEGER colnumber, SQLTIMESTAMP* buffer)

Description

ctsqlGetTimeStamp() retrieves the value of a time stamp field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetTimeStamp() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTinyInt(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetTinyInt

Retrieve the tiny int field.

Declaration

CTSQLRET ctsqlGetTinyInt(pCTSQLCURSOR hCursor, INTEGER colnumber, TINYINT* buffer)

Description

ctsqlGetTinyInt() retrieves the value of a tiny int field, given its cursor and column.

hCursor the cursor handle.
colnumber the column number.
buffer the buffer that will store the field data.

Return

ctsqlGetTinyInt() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlGetBytes(), ctsqlGetNChar(), ctsqlGetNumeric(), ctsqlGetSmallInt(), ctsqlGetInteger(), ctsqlGetReal(), ctsqlGetFloat(), ctsqlGetDate(), ctsqlGetMoney(), ctsqlGetTime(), ctsqlGetTimeStamp(), ctsqlGetBinary(), ctsqlGetBit(), ctsqlGetBigInt(), ctsqlGetBlob()

ctsqlGetUsername

Retrieve the current username.

Declaration

CTSQLCHAR* ctsqlGetUsername(pCTSQLCONN hConn)

Description

ctsqlGetUsername() retrieves the current username.

hConn the connection handle.

Return

ctsqlGetUsername() returns a pointer to the current user name, or NULL if neither a user name is available, nor the connection handle is valid.

See Also

ctsqlConnect(), ctsqlGetDatabase()

ctsqlIsActiveConn

Indicate if a connection is active or not.

Declaration

BIT ctsqlIsActiveConn(pCTSQLCONN hConn)

Description

ctsqlIsActiveConn() indicates if a connection is active or not.

hConn the connection handle.

Return

ctsqlIsActiveConn() returns TRUE if a connection is active (connected) or FALSE if it is not.

See Also

ctsqlConnect(), ctsqlDisconnect()

ctsqlIsColumnNull

Indicate if a column is NULL or not.

Declaration

BIT ctsqlIsColumnNull(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlIsColumnNull() indicates if a column is NULL or not.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlIsColumnNull() returns true if the column is NULL and false otherwise.

See Also

ctsqlIsNullable(), ctsqlGetParameterNullFlag()

ctsqlIsNullable

Retrieve an indication if the column accepts null fields.

Declaration

CTSQL_NULLABILITY ctsqlIsNullable(pCTSQLCURSOR hCursor, INTEGER colnumber)

Description

ctsqlIsNullable() retrieves an indication if the column accepts null fields.

hCursor the cursor handle.
colnumber the column number.

Return

ctsqlIsNullable() returns the nullability of a column. The possible values for the nullability are:

NULLABLE Value	Value
SQL_NO_NULLS	0
SQL_NULLABLE	0
SQL_NULLABLE_UNKNOWN	0

See Also

ctsqlGetParameterNullFlag(), ctsqlIsColumnNull()

ctsqlIsParameterNull

In V11 and later, DSQL exposes a method to verify if a parameter has been set to NULL.

Function:

ctsqlIsParameterNull

Retrieve the parameter.

Parameters:

hCmd [IN] - Command handle.
index [IN] - Parameter number. Must be a number greater or equal to zero but less than parameter count.

Return:

Return CTSQL_TRUE if the parameter is set to NULL.

ctsqlJumpTo

Retrieve the nth row from cursor current position.

Declaration

CTSQLRET ctsqlJumpTo(pCTSQLCURSOR hCursor, INTEGER nth)

Description

hCursor - the cursor handle
nth - the nth item to retrieve relative to the current position

Returns the nth row from the current position. It jumps backward when nth is a negative value or forward for a positive nth value.

Return Values

CTSQLRET_OK on success.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

ctsqlJumpTo(hCursor, 1) is the same as calling ctsqlNext().

ctsqlJumpTo(hCursor, -1) is the same as calling ctsqlPrev().

ctsqlLast

Retrieve the last row from cursor.

Declaration

CTSQLRET ctsqlLast(pCTSQLCURSOR hCursor)

Description

hCursor - the cursor handle.

Return Values

CTSQLRET_OK on success.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

ctsqlMulNumeric

Multiply two numeric values.

Declaration

CTSQLRET ctsqlMulNumeric(NUMERIC* num1, NUMERIC* num2, NUMERIC* res)

Description

ctsqlMulNumeric() multiplies two numeric values.

num1 the first operand to the multiplication.
num2 the second operand to the multiplication.
res the result of the multiplication operation.

Return

ctsqlMulNumeric() returns 0 on success, or -1 on failure.

See Also

ctsqlAddNumeric(), ctsqlSubNumeric(), ctsqlDivNumeric()

ctsqlNewCommand

Allocate a new command handle.

Declaration

pCTSQLCMD ctsqlNewCommand(pCTSQLCONN hConn)

Description

ctsqlNewCommand() allocates a new command handle.

hConn the connection handle.

Notes:

This function creates a handle off the connection to perform SQL queries. Multiple command handles can be created.
- Multiple command handles do not add to the license count; only ctsqlNewConnection() will increase the connection count.
- Multiple command handles do not act separately in transactions. Transactions are on the connection.
This API is thread-safe at the connection level. If you are sharing a single ctsqlConnection (including child handles like ctsqlCommands) among multiple threads, you will need to ensure that all operations on a particular connection are serialized.
You can switch thread context using the ISAM Thread API or any other threading API.

Return

ctsqlNewCommand() returns the pointer to a command handle, or NULL on failure.

See Also

ctsqlFreeCommand()

ctsqlNewConnection

Allocates a new FairCom DB SQL connection handle.

Declaration

pCTSQLCONN ctsqlNewConnection(void)

Description

ctsqlNewConnection() allocates a new FairCom DB SQL connection handle. A connection handle must be allocated before any other FairCom DB SQL interface calls are performed. When the FairCom DB SQL connection is no longer needed, the allocated resources must be released with a call to ctsqlFreeConnection().

Return

ctsqlNewConnection() returns a new connection handle on success, or NULL on failure.

See Also

ctsqlFreeConnection()

ctsqlNewCursor

Allocate a new FairCom DB SQL cursor handle.

Declaration

pCTSQLCURSOR ctsqlNewCursor(pCTSQLCMD hCmd)

Description

ctsqlNewCursor() allocates a new FairCom DB SQL cursor handle.

hCmd the command handle.

Return

ctsqlNewCursor() returns the new allocated cursor, or NULL on failure.

See Also

ctsqlFreeCursor(), ctsqlClose()

ctsqlNewProcInfo

Declaration

pCTSQLPROCINFO ctsqlDECL ctsqlNewProcInfo(CTSQLCHAR* owner, CTSQLCHAR* name, STP_TYPE kind)

Description

Provides a new stored procedure Info structure.

owner [IN] - procedure owner
name [IN] - ocedure name
kind [IN] - object type (STP/UDF/Trigger)

Return Values

Pointer to procedure info structure.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctsqlNext

Retrieve the next row from cursor.

Declaration

CTSQLRET ctsqlNext(pCTSQLCURSOR hCursor)

Description

ctsqlNext() retrieves the next row from cursor.

hCursor the cursor handle

Return

ctsqlNext() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments.
CTSQL_NOTFOUND	No more rows exist in the result set.

ctsqlNextBatchItem

Move to the next batch item.

Declaration

INTEGER ctsqlNextBatchItem(pCTSQLCMD hCmd)

Description

ctsqlNextBatchItem() moves to the next item in a batch.

hCmd - command handle

This function must be used with ctsqlPrepareBatch(). Below is an example inserting a batch of 45 records:


int batchSize=45;
if ((eRet = ctsqlPrepareBatch(hCmd, CT_STRING_LITERAL("insert into tab250 values (?,'original')"), batchSize)) != CTSQLRET_OK)
{
Output("ctsqlPrepare (%d)\n", eRet);
goto Exit;
}
for (i = 0; i < batchSize; i++)
{
if ((eRet = ctsqlSetIntegerParameter(hCmd,0,CTSQL_INTEGER,false,i)) != CTSQLRET_OK)
{
Output("ctsqlSetIntegerParameter (%d)\n", eRet);
goto Exit;
}
if ((eRet = ctsqlNextBatchItem(hCmd)) < 0)
{
Output("Batch is full\n"t);
goto Exit;
}
}
if ((eRet = ctsqlExecute(hCmd, &hCursor)) != CTSQLRET_OK)
{
Output("ctsqlExecute  (%d)\n", eRet);
goto Exit;
}

Return

Returns batch item number (0 based). -1 if the batch buffer is full.

ctsqlNumericToString

Declaration

CTSQLRET ctsqlDECL ctsqlNumericToString(NUMERIC* num, CTSQLCHAR* str, INTEGER len);

Description

Converts a numeric value to a string value.

num Numeric value to be converted
str string value to be returned
len length of str.

Return Values

ctsqlNumericToString() returns CTSQLRET_OK on success.

See Also

ctsqlStringToNumeric()

ctsqlPrepare

Prepare a SQL statement for execution.

Declaration

CTSQLRET ctsqlPrepare(pCTSQLCMD hCmd, CTSQLCHAR* sqlcmd)

Description

ctsqlPrepare() prepares a SQL statement for execution. To execute the statement, use ctsqlExecute().

hCmd the command handle.
sqlcmd the string containing the SQL statement.

Return

ctsqlPrepare() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlExecute()

ctsqlPrepareBatch

Prepare a batch SQL statement for execution.

Declaration

CTSQLRET ctsqlDECL ctsqlPrepareBatch(pCTSQLCMD hCmd, CTSQLCHAR* sqlcmd, INTEGER max_batch)

Description

ctsqlPrepareBatch() prepares a batch SQL statement for execution. To execute the batch, use ctsqlExecute().

hCmd the command handle
sqlcmd string containing the SQL statement
max_batch integer setting the max number of rows in the batch

Return

ctsqlPrepareBatch() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlExecute()

ctsqlPrev

Retrieve the previous row from cursor.

Declaration

CTSQLRET ctsqlPrev(pCTSQLCURSOR hCursor)

Description

hCursor - the cursor handle

Return Values

CTSQLRET_OK on success.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

ctsqlRoundNumeric

Round a numeric value given a precision and scale.

Declaration

CTSQLRET ctsqlRoundNumeric(NUMERIC* num, INTEGER precision, INTEGER scale)

Description

ctsqlRoundNumeric() rounds a numeric value given a precision and scale.

num the numeric value to be rounded.
precision the rounding precision.
scale the rounding scale.

Return

ctsqlRoundNumeric() returns CTSQLRET_OK on success.

ctsqlSetAutoCommit

Set or clear the auto commit flag.

Declaration

CTSQLRET ctsqlSetAutoCommit(pCTSQLCONN hConn, BIT flag)

Description

ctsqlSetAutoCommit() sets or clears the auto commit flag.

hConn the connection handle.
flag indicates if the auto commit flag is to be turned on or off. CTSQL_TRUE indicates that the auto commit flag is to be turned on, while CTSQL_FALSE indicate that the auto commit flag is to be turned off.

Return

ctsqlSetAutoCommit() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlGetAutoCommit(), ctsqlClearAutoCommit()

ctsqlSetBigIntParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetBigIntParameter(pCTSQLCMD hCmd, INTEGER index, BIT isnull, BIGINT* buffer);

Description

Sets a BIGINT value for a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() return CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetIntegerParameter(), ctsqlSetNumericParameter(), ctsqlSetFloatParameter(), ctsqlSetDateParameter(), ctsqlSetTimeParameter(), ctsqlSetTimeStampParameter(), ctsqlSetNCharParameter(), ctsqlSetBinaryParameter()

ctsqlSetBinaryParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetBinaryParameter(pCTSQLCMD hCmd, INTEGER index, BIT isnull, void* buffer, INTEGER size);

Description

Sets the Binary value of a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.
size The size of the buffer.

Return Values

ctsqlSetParameter() return CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetIntegerParameter(), ctsqlSetBigIntParameter(), ctsqlSetNumericParameter(), ctsqlSetFloatParameter(), ctsqlSetDateParameter(), ctsqlSetTimeParameter(), ctsqlSetTimeStampParameter(), ctsqlSetNCharParameter()

ctsqlSetBlob

Set the blob field.

Declaration

CTSQLRET ctsqlSetBlob(pCTSQLCMD hCmd, INTEGER colnumber, void* buffer, INTEGER size, INTEGER offset)

Description

ctsqlSetBlob() sets the value of a blob field (types TPE_DT_LVC or TPE_DT_LVB), given its cursor and column.

hCmd the SQL command handle.
colnumber the number of the column.
buffer the buffer with data to be placed into blob.
size the size in bytes of the data in buffer.
offset the offset in field where the data is to be placed.

Example

if ((eRet = ctsqlExecuteDirect(hCmd, CT_STRING_LITERAL("create table tab265 (f0 integer, f1 clob)"))) != CTSQLRET_OK)
{
Output("FAIL ctsqlExecuteDirect (%d)\n", eRet);
goto Exit;
}
if ((eRet = ctsqlPrepare(hCmd, CT_STRING_LITERAL("insert into tab265 values (?,?)"))) != CTSQLRET_OK)
{
Output("FAIL ctsqlPrepare (%d)\n", eRet);
goto Exit;
}
if ((eRet = ctsqlSetParameter(hCmd, 0, CTSQL_INTEGER, sizeof(CTSQL_INTEGER), CTSQL_FALSE, &intval)) != CTSQLRET_OK)
{
Output("FAIL ctsqlSetParameter (%d)\n", eRet);
goto Exit;
}
if ((eRet = ctsqlExecute(hCmd, &hCursor)) != CTSQLRET_OK)
{
Output("FAIL ctsqlExecute (%d)\n", eRet);
goto Exit;
}
if ((eRet = ctsqlSetBlob(hCmd, 1, buffer, BLOB_SIZE, 0)) != CTSQLRET_OK)
{
Output("FAIL ctsqlSetBlob (%d)\n", eRet);
goto Exit;
}
ctsqlFreeCursor(hCursor);

Return

ctsqlSetBlob() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

ctsqlSetCharParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetCharParameter(pCTSQLCMD hCmd, INTEGER index, CTSQLTYPE ptype, BIT isnull, char* buffer, INTEGER len);

Description

Sets the Character value of a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
ptype the type of parameter being passed in buffer. This type must match the expected type.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetAutoCommit() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlSetCharParameter(), ctsqlSetIntegerParameter(), ctsqlSetBigIntParameter(), ctsqlSetNumericParameter(), ctsqlSetFloatParameter(), ctsqlSetDateParameter(), ctsqlSetTimeParameter(), ctsqlSetTimeStampParameter(), ctsqlSetBinaryParameter()

ctsqlSetDateParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetDateParameter(pCTSQLCMD hCmd, INTEGER index, BIT isnull, SQLDATE* buffer);

Description

Sets the Date value for a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() return CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetIntegerParameter(), ctsqlSetBigIntParameter(), ctsqlSetNumericParameter(), ctsqlSetFloatParameter(), ctsqlSetTimeParameter(), ctsqlSetTimeStampParameter(), ctsqlSetNCharParameter(), ctsqlSetBinaryParameter()

ctsqlSetFloatParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetFloatParameter(pCTSQLCMD hCmd, INTEGER index, CTSQLTYPE ptype, BIT isnull, FLOAT buffer);

Description

Sets a Float value for a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() return CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetIntegerParameter(), ctsqlSetBigIntParameter(), ctsqlSetNumericParameter(), ctsqlSetDateParameter(), ctsqlSetTimeParameter(), ctsqlSetTimeStampParameter(), ctsqlSetNCharParameter(), ctsqlSetBinaryParameter()

ctsqlSetIntegerParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetIntegerParameter(pCTSQLCMD hCmd, INTEGER index, CTSQLTYPE ptype, BIT isnull, INTEGER buffer);

Description

Sets the integer value for a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
ptype the type of parameter being passed in buffer. This type must match the expected type.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() return CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetBigIntParameter(), ctsqlSetNumericParameter(), ctsqlSetFloatParameter(), ctsqlSetDateParameter(), ctsqlSetTimeParameter(), ctsqlSetTimeStampParameter(), ctsqlSetNCharParameter(), ctsqlSetBinaryParameter()

ctsqlSetIsolationLevel

Set the transaction isolation level.

Declaration

CTSQLRET ctsqlSetIsolationLevel(pCTSQLCONN hConn, CTSQL_ISOLEVEL level).

Description

ctsqlSetIsolationLevel() sets the transaction isolation level.

hConn the connection handle.
level the new isolation level to be set.

Return

ctsqlSetIsolationLevel() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlGetIsolationLevel()

ctsqlSetKeepaliveInterval

Set the connection Keepalive Interval in seconds.

Declaration

CTSQLRET ctsqlSetKeepaliveInterval(pCTSQLCONN hConn, INTEGER value)

Parameters

hConn [IN] - the connection handle.
value [IN] - the number of seconds to keep alive.

Description

To be used before calling ctsqlConnect. if the connection is active, ctsqlSetKeepaliveInterval will fail. Default (0) indicates no keepalive. a TCP client connection requests a TCP level keepalive probe that is sent after the TCP link has been idle for the specified interval. If the host does not respond to the keepalive probe within 10 seconds, the connection will be treated as broken. This can help achieve 2 goals.1) periodic activity on the link may help prevent network hardware from identifying the connection as idle and silently terminating it. 2) this can distinguish a broken network link from a server operation that takes a long time for the server to respond.

Return

ctsqlSetKeepaliveInterval() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

ctsqlSetNCharParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetNCharParameter(pCTSQLCMD hCmd, INTEGER index, CTSQLTYPE ptype, BIT isnull, CTSQLCHAR* buffer, INTEGER len);

Description

Sets the Character value of a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
ptype the type of parameter being passed in buffer. This type must match the expected type.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() return CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetNumericParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetNumericParameter(pCTSQLCMD hCmd, INTEGER index, CTSQLTYPE ptype, BIT isnull, NUMERIC* buffer);

Description

Sets a Numeric value for a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
ptype the type of parameter being passed in buffer. This type must match the expected type.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() return CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetIntegerParameter(), ctsqlSetBigIntParameter(), ctsqlSetFloatParameter(), ctsqlSetDateParameter(), ctsqlSetTimeParameter(), ctsqlSetTimeStampParameter(), ctsqlSetNCharParameter(), ctsqlSetBinaryParameter()

ctsqlSetNumericParameterAsString

CTSQLRET ctsqlDECL ctsqlSetNumericParameterAsString(pCTSQLCMD hCmd, INTEGER index, CTSQLTYPE ptype, BIT isnull, CTSQLCHAR* buffer)

Description

Set parameter for all numeric types: CTSQL_NUMERIC and CTSQL_MONEY.

Parameters

hCmd - command handle
index - parameter number you want to set. The value must be greater or equal to zero but less than the parameter count
ptype - type of parameter being passed in buffer. This type must match one of the following types: CTSQL_NUMERIC and CTSQL_MONEY
isnull - indicate if parameter should be NULL or not
buffer - string representing the numeric data

Return

Returns CTSQLRET_OK on success.

ctsqlSetParameter

Set the value of a parameter.

Declaration

CTSQLRET ctsqlSetParameter(pCTSQLCMD hCmd, INTEGER index, CTSQLTYPE ptype, INTEGER length, BIT isnull, void* buffer)

Description

ctsqlSetParameter() sets the value of a parameter. The parameter type must match the expected type as no conversion is provided.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
ptype the type of parameter being passed in buffer. This type must match the expected type.
length the parameter length being passed in buffer. The proper length must be passed.
isnull TRUE indicate a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return

ctsqlSetParameter() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetParameterScale(), ctsqlSetParameterPrecision()

ctsqlSetParameterAsString

Set parameter for all types except BINARY.

Declaration

CTSQLRET ctsqlDECL ctsqlSetParameterAsString(pCTSQLCMD hCmd, INTEGER index, CTSQLCHAR* buffer)

Parameters:

hCmd [IN] - command handle
index [IN] - parameter number you want to set. The value must be greater or equal to zero but less than the parameter count.
buffer [IN] - null terminated char* data

Date string must be: yyyy-MM-dd

Time string must be: hh:mm:ss

Timestamp string must be: yyyy-MM-dd hh:mm:ss

Description

The Direct SQL API (ctsqlapi) requires that query parameters are set using the proper C-language type for the underlying SQL data type. This can be difficult in some languages, such as Python. In these languages, it is more convenient to use strings and let the logic determine the parameter type and perform the proper conversion.

Return

Return CTSQLRET_OK on success.

ctsqlSetParameterPrecision

Change the precision value of a parameter.

Declaration

CTSQLRET ctsqlSetParameterPrecision(pCTSQLCMD hCmd, INTEGER index, SMALLINT precision)

Description

ctsqlSetParameterPrecision() changes the parameter’s precision value. The parameter precision represents the total number of digits in a BCD number represented in a parameter.

hCmd the command handle.
index the parameter number. Must be a number greater or equal zero, but less than parameter count.
precision precision value

Return

ctsqlSetParameterPrecision() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlSetParameter(), ctsqlSetParameterScale()

ctsqlSetParameterScale

Change the parameter scale value.

Declaration

CTSQLRET ctsqlSetParameterScale(pCTSQLCMD hCmd, INTEGER index, SMALLINT scale)

Description

ctsqlSetParameterScale() changes the parameter scale value. The parameter scale represents the number of decimal digits in a parameter.

hCmd the command handle.
index the parameter number. Must be a number greater or equal zero, but less than parameter count.
scale the scale value.

Return

ctsqlSetParameterScale() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.

See Also

ctsqlSetParameter(), ctsqlSetParameterPrecision()

ctsqlSetPreserveCursor

Sets the connection Preserve Cursor option before calling ctsqlConnect. To be used before calling ctsqlConnect. If the connection is active, ctsqlSetPreserveCursor will fail.

Declaration

Preserve Cursor set to CTSQL_TRUE (1) indicates that cursors are not closed when the current transaction ends. the default is CTSQL_FALSE (0).

CTSQLRET ctsqlDECL ctsqlSetPreserveCursor (pCTSQLCONN hConn, BIT flag)

Parameters:

hConn [IN] - connection handle
flag [IN] - (1) indicates that cursors are not closed when the current transaction ends. Default: CTSQL_FALSE (0).

Return

Return CTSQLRET_OK on success.

ctsqlSetScrollableCursor

Added in FairCom DB V11.5, ctsqlSetScrollableCursor sets or clears the auto-commit flag. When the scrollable cursor flag is turned on in the command handle, the cursor returned by the Execute function will be scrollable and the number of rows properly set to the rows in the resultset. This support has been implemented to obtain the number of rows in the resultset.

Parameters:

[hCmd] - Must point to a valid command handle
flag [IN] - Indicate if the scrollable cursor flag is to be turned on or off.

CTSQL_TRUE indicates that the scrollable cursor flag is to be turned on, while CTSQL_FALSE indicates that the scrollable cursor flag is to be turned off.

Return:

Returns CTSQLRET_OK on success

ctsqlSetSSL

Set the connection's SSL options before calling ctsqlConnect.

Declaration

CTSQLRET ctsqlDECL ctsqlSetSSL(pCTSQLCONN hConn, CTSQLCHAR* certificate)

Parameters:

hConn [IN] - Connection handle.
certificate [IN] - Certificate, possible values:

NULL - No SSL.

"BASIC" - SSL without certificate checking.

"<certificate file name>" - SSL with certificate checking, certificate file as specified.

"" - SSL with certificate checking, certificate in current working directory named ctsrvr.pem.

Description

Set the connection SSL option.

Return Values

Return CTSQLRET_OK on success.

See Also

ctsqlConnect

ctsqlSetTimeout

Declaration

CTSQLRET ctsqlDECL ctsqlSetTimeout(pCTSQLCMD hCmd, INTEGER timeout);

Description

ctsqlSetTimeout() sets the timeout value associated with the command handle.

FairCom DB SQL supports a timeout option for executing a query. This feature can ensure that an unintended query statement does not consume excessive processing time of FairCom DB SQL.

hCmd a command handle.
timeout the timeout value in seconds. A value of zero clears the timeout, indicating that the execution of a FairCom DB SQL query will not timeout. To take effect, the timeout value should be set before preparing the statement by calling ctsqlPrepare(). Should you need to change the timeout value of a command handle, set the new timeout value, or set to zero to clear the timeout value, and prepare the statement again.

Negative values are not accepted and will generate a CTSQLRET_BADARG error.

Return Values

ctsqlSetTimeout() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADARG	Bad arguments

See Also

ctsqlSetTimeout()

ctsqlSetTimeParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetTimeParameter(pCTSQLCMD hCmd, INTEGER index, BIT isnull, SQLTIME* buffer);

Description

Sets the Time value of a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetIntegerParameter(), ctsqlSetBigIntParameter(), ctsqlSetNumericParameter(), ctsqlSetFloatParameter(), ctsqlSetDateParameter(), ctsqlSetTimeStampParameter(), ctsqlSetNCharParameter(), ctsqlSetBinaryParameter()

ctsqlSetTimeStampParameter

Declaration

CTSQLRET ctsqlDECL ctsqlSetTimeStampParameter(pCTSQLCMD hCmd, INTEGER index, BIT isnull, SQLTIMESTAMP* buffer);

Description

Sets the Timestamp value for a parameter.

hCmd the command handle.
index the parameter number to be set. The value must be greater or equal to zero but less than the parameter count.
isnull TRUE indicates a NULL value.
buffer buffer containing the parameter value. buffer can be NULL if isnull is TRUE.

Return Values

ctsqlSetParameter() returns CTSQLRET_OK on success.

Symbolic Constant	Explanation
SQL_ERR_BADPARAM	Bad parameter specification for the statement.
SQL_ERR_INTYPES	Inconsistent types.

See Also

ctsqlSetTLSClientAuth

Set attributes required by Direct SQL clients that want to authenticate with client certificates.

Declaration

CTSQLRET ctsqlDECL ctsqlSetTLSClientAuth(pCTSQLCONN hConn, const CTSQLCHAR * ClientCert, const CTSQLCHAR * ClientPrivateKey, const CTSQLCHAR * Password)

Description

ctsqlSetTLSClientAuth() sets attributes required for client certificate authentication. It must be called after allocating the connection handle (ctsqlNewConnection) but before connecting (ctsqlConnect).

hConn [IN] - connection handle

ClientCert [IN] - filename of certificate file

ClientPrivateKey [IN] - filename of private key file proving ownership of ClientCert. May be NULL if the private key is in the ClientCert file.

Password [IN] - password to decrypt the client private key. NULL if not encrypted.

Return

Returns CTSQLRET_OK on success.

Returns CTSQLRET_BADARG if hConn is NULL.

Returns CTSQLRET_INVENVHDL if the connection is already active.

ctsqlStringToNumeric

Declaration

CTSQLRET ctsqlDECL ctsqlStringToNumeric(CTSQLCHAR *str, INTEGER len, NUMERIC* num);

Description

Converts a String value to a numeric value.

str string value to be converted
len length of str.
num Numeric value to be returned

Return Values

ctsqlStringToNumeric() returns CTSQLRET_OK on success.

See Also

ctsqlNumericToString()

ctsqlSubNumeric

Subtract two numeric values.

Declaration

CTSQLRET ctsqlSubNumeric(NUMERIC* num1, NUMERIC* num2, NUMERIC* res)

Description

ctsqlSubNumeric() subtracts two numeric values.

num1 the first operand to the subtraction.
num2 the second operand to the subtraction.
res the result of the subtraction operation.

Return

ctsqlSubNumeric() returns 0 on success, or -1 on failure.

See Also

ctsqlAddNumeric(), ctsqlMulNumeric(), ctsqlDivNumeric()

ctsqlFreeProcInfo

Declaration

void ctsqlDECL ctsqlFreeProcInfo(pCTSQLPROCINFO hprocinfo)

Description

Frees a procedure info structure.

hprocinfo [IN] - pointer to procedure info structure

Return Values

Returns VOID

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also