oajava.sql
Interface sqlip

public interface sqlip

A connection (session) with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

Field Summary

static java.lang.String	DB_CONNECT_STRING_TOKEN_SEPARATOR Constant to indicate the character separating tokens in the connect string
static int	SQLDRV_BUFFER_FULL Constant to indicate results in current buffer are completely returned.
static int	SQLDRV_EOS Constant to indicate that all results are returned.
static int	SQLDRV_ERROR Constant to indicate Failure from IP routine.
static int	SQLDRV_INFO_NEXT_RESULT_SET_AVAILABLE Constant to check and see if more result sets are available.
static int	SQLDRV_INFO_OUTPUT_RESULT_SET_AVAILABLE Constant to indicate for the current statement report whether it had a return code and/or output parameters.
static int	SQLDRV_NOT_AVAILABLE Constant to indicates that Driver functionality is not available
static int	SQLDRV_SUCCESS Constant to indicate Success from IP routine
static int	SQLIP_ERROR Constant to Indicate IP Routine had an Error
static int	SQLIP_FAILURE Constant to Indicate IP Routine had an Error
static int	SQLIP_SUCCESS Constant to Indicate IP Routine was succesful
static int	UL_TM_ERRORS Constant to indicate message type as "General Errors" in either the protocol or application.
static int	UL_TM_F_TRACE Constant to indicate message type as function call trace.
static int	UL_TM_FATAL Constant to indicate message type as "FATAL" error
static int	UL_TM_INFO Constant to indicate message type as general info to give details about the events.
static int	UL_TM_MAJOR_EV Constant to indicate message type as major protocol or application events to give the big picture.
static int	UL_TM_MINOR_EV Constant to indicate message type as minor or secondary protocol or application events to give more detail.
static int	UL_TM_PARM Constant to indicate message type as "Bad or missing Parameter" passed.
static int	UL_TM_SNO Constant to indicate message type as "Should not occur" error, usually caused by programmer or spec error
static int	UL_TM_TRIVIA Constant to indicate message type as trivial info of value only to the implementor.

Method Summary

int	sqlipCommit() Commit any active transactions on the specified connection.
int	sqlipConnect(java.lang.String psDbResourceName, java.lang.String psDbName, java.lang.String psUid, java.lang.String psPwd, int iAccessMode, java.lang.String sUsrConnStr, java.lang.String pSqlSecData) Connect to the specified database using the specified user name and password.
int	sqlipDisconnect() Disconnect from the database and abort any open transactions.
int	sqlipError(java.lang.StringBuffer sSqlState, xo_int piNativeError, java.lang.StringBuffer sErrorText) Return the error during the last operation on this object.
int	sqlipGetInfo(int iInfoType, java.lang.StringBuffer sInfoValue) Called by the OpenAccess layer to request information from the IP.
int	sqlipPrepareToCommit(java.lang.String pCmdArgs, xo_int piReadOnly) Used to support distributed transactions.
int	sqlipRollback() Roll back all uncommitted transactions on this connection.
int	sqlipSetInfo(java.lang.String pCmdArgs) Called by the OpenAccess layer to inform the IP of various connection and statement level options like the maximum number of rows to return, transaction commit mode, query timeout, etc.
int	sqlipStartTransaction(int iExplicitFlag, java.lang.String pCmdArgs) Start a new transaction on the specified connection in response to a request for an explicit start transaction by the client.

Field Detail

SQLDRV_SUCCESS

public static final int SQLDRV_SUCCESS

Constant to indicate Success from IP routine

SQLDRV_EOS

public static final int SQLDRV_EOS

Constant to indicate that all results are returned. End of Data.

SQLDRV_BUFFER_FULL

public static final int SQLDRV_BUFFER_FULL

Constant to indicate results in current buffer are completely returned.

SQLDRV_ERROR

public static final int SQLDRV_ERROR

Constant to indicate Failure from IP routine.

SQLDRV_NOT_AVAILABLE

public static final int SQLDRV_NOT_AVAILABLE

Constant to indicates that Driver functionality is not available

SQLIP_SUCCESS

public static final int SQLIP_SUCCESS

Constant to Indicate IP Routine was succesful

SQLIP_FAILURE

public static final int SQLIP_FAILURE

Constant to Indicate IP Routine had an Error

SQLIP_ERROR

public static final int SQLIP_ERROR

Constant to Indicate IP Routine had an Error

UL_TM_FATAL

public static final int UL_TM_FATAL

Constant to indicate message type as "FATAL" error

UL_TM_SNO

public static final int UL_TM_SNO

Constant to indicate message type as "Should not occur" error, usually caused by programmer or spec error

UL_TM_PARM

public static final int UL_TM_PARM

Constant to indicate message type as "Bad or missing Parameter" passed.

UL_TM_ERRORS

public static final int UL_TM_ERRORS

Constant to indicate message type as "General Errors" in either the protocol or application.

UL_TM_MAJOR_EV

public static final int UL_TM_MAJOR_EV

Constant to indicate message type as major protocol or application events to give the big picture.

UL_TM_MINOR_EV

public static final int UL_TM_MINOR_EV

Constant to indicate message type as minor or secondary protocol or application events to give more detail.

UL_TM_INFO

public static final int UL_TM_INFO

Constant to indicate message type as general info to give details about the events.

UL_TM_F_TRACE

public static final int UL_TM_F_TRACE

Constant to indicate message type as function call trace.

UL_TM_TRIVIA

public static final int UL_TM_TRIVIA

Constant to indicate message type as trivial info of value only to the implementor.

SQLDRV_INFO_NEXT_RESULT_SET_AVAILABLE

public static final int SQLDRV_INFO_NEXT_RESULT_SET_AVAILABLE

Constant to check and see if more result sets are available.

SQLDRV_INFO_OUTPUT_RESULT_SET_AVAILABLE

public static final int SQLDRV_INFO_OUTPUT_RESULT_SET_AVAILABLE

Constant to indicate for the current statement report whether it had a return code and/or output parameters.

DB_CONNECT_STRING_TOKEN_SEPARATOR

public static final java.lang.String DB_CONNECT_STRING_TOKEN_SEPARATOR

Constant to indicate the character separating tokens in the connect string

Method Detail

sqlipConnect

public int sqlipConnect(java.lang.String psDbResourceName,
                        java.lang.String psDbName,
                        java.lang.String psUid,
                        java.lang.String psPwd,
                        int iAccessMode,
                        java.lang.String sUsrConnStr,
                        java.lang.String pSqlSecData)

Connect to the specified database using the specified user name and password. In multi-threaded mode, each connection is on a new thread created by the server. This is the first method called on a new instance of the class you have registered for the oajva.sql.sqlip interface.

Parameters:

psDbResourceName - The logical name of the database the user has specified when connecting.

psDbName - The string specified as the CONNECT_STRING for the database resource identified by the psDbResourceName.

psUid - User ID

psPwd - Password

iAccessMode - Whether the client needs read only or read/write access to this database.

sUsrConnStr - Complete connection string as received from the client. This can be parsed to retrieve any custom connection level options.

pSqlSecData - Windows token. Should be used only when Windows authentication is enabled.

Returns:

• SQLDRV_SUCCESS - connected to the database
• SQLDRV_ERROR - error occurred during connection. Specific error should be returned when sqlipError is called.

sqlipDisconnect

public int sqlipDisconnect()

Disconnect from the database and abort any open transactions. After returning from this function the thread or the process that was created for this connection is destroyed. This is the last method called on this object.

Returns:

• SQLDRV_SUCCESS - Disconnected from the database
• SQLDRV_ERROR - error disconnection from the database.

sqlipError

public int sqlipError(java.lang.StringBuffer sSqlState,
                      xo_int piNativeError,
                      java.lang.StringBuffer sErrorText)

Return the error during the last operation on this object. Once the error is returned, delete the error from the list of errors on the specified statement or connection. This function will be will called until it returns SQLDRV_EOS to indicate no more errors are present.

Parameters:

sSqlState - Return a 5 character SQL sate string if the sSqlState is not NULL.

piNativeError - Return an integer value indicating a native error. This code will be made available to the client application. Provide this if piNativeError in not NULL.

sErrorText - Return error message of length SQLDRV_MAX_MESSAGE_LENGTH or less if sErrorText is not NULL.

Returns:

• SQLDRV_SUCCESS - return the error
• SQLDRV_EOS - no errors available
• SQLDRV_ERROR - error in returning the error

sqlipGetInfo

public int sqlipGetInfo(int iInfoType,
                        java.lang.StringBuffer sInfoValue)

Called by the OpenAccess layer to request information from the IP.

Parameters:

iInfoType -

• SQLDRV_INFO_NEXT_RESULT_SET_AVAILABLE (1) - For the current statement check and see if more result sets are available. Return a value of 1 if more result sets are available, otherwise return 0. Returning a 1 will result in the open_next_cursor method being called.
• For the current statement report whether it had a return code and/or output parameters. Return a value of 1 if yes, otherwise return 0. Returning a 1 will result in the open_output_cursor being called.

sInfoValue - Buffer to return the data into.

Returns:

• SQLDRV_SUCCESS - if the requested option is supported.
• SQLDRV_ERROR - error occurred in obtaining the requested information.

sqlipSetInfo

public int sqlipSetInfo(java.lang.String pCmdArgs)

Called by the OpenAccess layer to inform the IP of various connection and statement level options like the maximum number of rows to return, transaction commit mode, query timeout, etc. The IP can optionally use this information in its processing.

Parameters:

pCmdArgs - Option string - STMT_OPTIONS The options string contains settings for maximum number of rows, query timeout, and extended column attributes. These settings are passed in using keywords mrows, qt, and op. An example options string is: 'mrows=0;qt=0;op=0'

• mrows - the number of rows to limit the results to. A value of zero indicates no limit and is the default.
• qt - query timeout in seconds. A value of 0 indicates to limit and is the default.
• op - additional bit type of options.

Returns:

• SQLDRV_SUCCESS - if you are able to successfuly apply the option or if you want to ignore the options.
• SQLDRV_ERROR - if error in handling the requested option for which you do have support.

sqlipCommit

public int sqlipCommit()

Commit any active transactions on the specified connection. This should cause any operations that were performed since the last COMMIT or ROLLBACK to be saved. This function is called when the client application explicitly commits or, when in auto commit mode, after the execution of every statement that does not return any columns.

Returns:

• SQLDRV_SUCCESS - commits the transactions
• SQLDRV_ERROR - error commiting the transactions

sqlipRollback

public int sqlipRollback()

Roll back all uncommitted transactions on this connection. This should cause any operations that were done on this connection since the last COMMIT or ROLLBACK to be rolled back as if they were never performed. If you are not supporting transactions then always return SQLDRV_SUCCESS.

Returns:

• SQLDRV_SUCCESS - transactions rolled back
• SQLDRV_ERROR - error rolling back

sqlipStartTransaction

public int sqlipStartTransaction(int iExplicitFlag,
                                 java.lang.String pCmdArgs)

Start a new transaction on the specified connection in response to a request for an explicit start transaction by the client. This function is not called for an implied transaction that is always open on a connection after a connection is opened or after a commit on a top-level transaction. The IP must insure that a transaction is always active on a connection. If nested transactions are supported, then this function will be called when the client has made a start transaction API call. If you don't want to support nested transactions then return a SQLDRV_ERROR when this function is called. When commit is called you must commit on the current nested level and set the current transaction to the previous level. If a commit is called for the top level transaction, then you must commit and then start a new high-level transaction because a call to sqlip_start_transaction will not be made. If you do not want to support transactions then always return SQLDRV_SUCCESS.

Parameters:

iExplicitFlag - For future use - always set to 1 in this version.

pCmdArgs - Isolation level for this transaction - '%d' where d is an integer value corresponding to the isolation level as defined in the ipdef.h file.

Returns:

• SQLDRV_SUCCESS
• SQLDRV_ERROR

sqlipPrepareToCommit

public int sqlipPrepareToCommit(java.lang.String pCmdArgs,
                                xo_int piReadOnly)

Used to support distributed transactions. If the data source is not going to support distributed transactions then always return SQLDRV_ERROR.

Parameters:

pCmdArgs - Transaction ID and other details

piReadOnly -

• 1 - If the commands on this transaction have been just reads
• 0 - If data has been modified by the transaction

Returns:

• SQLDRV_SUCCESS - transaction is ready
• SQLDRV_ERROR - error in preparing the transaction to commit