sqlora.h

一个很好用的Linux/Unix下Oracle OCI开发接口封装库

/** @} */

/**
 * @defgroup easy The easy interface
 * Functions in this group use basically bind variables passed as strings in
 * an argv. The query results are also converted to strings.
 *
 * @{ */

/**
 * Tests if a value exists in a table.
 *
 * Tests if a record exists in a table where field = value [AND where].
 *
 * @param dbh     I - A database handle
 * @param table   I - A table name
 * @param colname I - A column name
 * @param colval  I - A column value
 * @param where   I - More conditions (optional)
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_NO_DATA
 * <li> < 0 on error.
 * </ul>
 * @par Example:
 * @include ex1.c
 */
int sqlo_exists __P(( sqlo_db_handle_t dbh, 
                      CONST char * table, 
                      CONST char * colname,
                      CONST char * colval, 
                      CONST char * where ));
/**
 * Counts the number of items in the table.
 *
 * Counts the number of items where field = value [AND where]
 *
 * @param dbh     I - A database handle
 * @param table   I - A table name
 * @param colname I - A column name
 * @param colval  I - A column value
 * @param where   I - More conditions (optional)
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_NO_DATA 
 * <li> < 0 on error
 * </ul>
 * @par Example:
 * @include ex2.c
 */
int sqlo_count __P((sqlo_db_handle_t dbh,
                    CONST char * table,
                    CONST char * colname,
                    CONST char * colval,
                    CONST char * where ));

/**
 * Run a simple sql statements with parameters
 *
 * Like @ref sqlo_exec, but with bind parameters. 
 * This is basically the same as calling @ref sqlo_open followed by @ref sqlo_fetch and 
 * @ref sqlo_close.
 *
 * @param dbh   I - A database handle
 * @param stmt  I - A sql statement (non-query).
 * @param argc  I - Number of arguments in argv.
 * @param argv  I - The arguments
 *
 * @return <ul>
 * <li>The number of processed rows.
 * <li>SQLO_STILL_EXECUTING in non-blocking mode.
 * <li> < 0 on error.
 * </ul>
 * @par Example:
 * @include ex3.c
 */
int sqlo_run __P(( sqlo_db_handle_t dbh, CONST char * stmt, int argc, CONST char ** argv));


/**
 * Open a new cursor 
 *
 * This function opens a new cursor for a query statement.
 *
 * If the stmt is a SELECT statement, the function sets the attribute 
 * OCI_ATTR_PREFETCH rows to the max arraysize parameter of the library.
 * This is a kind of internal array fetch Oracle provides to speed up the fetching.
 *
 * @deprecated  For new developments please use @ref sqlo_open2
 * @param dbh  I - A database handle
 * @param stmt I - A sql statement
 * @param argc I - Number of arguments in argv
 * @param argv I - Arguments
 *
 * @return <ul>
 * <li>A statement handle
 * <li> < 0 on error
 * </ul>
 * @par Example:
 * @include ex4.c
 *
 * @see sqlo_open2, sqlo_fetch, sqlo_values, sqlo_close
 */
sqlo_stmt_handle_t sqlo_open __P((sqlo_db_handle_t dbh, 
                                  CONST char * stmt, 
                                  int argc, 
                                  CONST char ** argv));

/**
 * Open a new cursor 
 * 
 * This function opens a new cursor for a query statement.
 * Use this function if your bind variables are all strings.
 * If you need native datatype support, use @ref sqlo_prepare
 *
 * If the stmt is a SELECT statement, the function sets the attribute 
 * OCI_ATTR_PREFETCH rows to the max arraysize parameter of the library.
 * This is a kind of internal array fetch Oracle provides to speed up the fetching.
 *
 * @attention You have to init the passed statement handle with SQLO_STH_INIT.
 * This is required escpecially in non-blocking mode. 
 *
 * @param sthp I/O - Returns the new sth in *sthp.
 * @param dbh  I - A database handle
 * @param stmt I - A sql statement
 * @param argc I - Number of arguments in argv
 * @param argv I - Arguments
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_STILL_EXECUTING in non-blocking mode
 * <li> < 0 on error
 * </ul>
 * @par Example:
 * @include ex5.c
 *
 * @see sqlo_fetch, sqlo_values, sqlo_close
 * @since Version 2.2
 */
int sqlo_open2 __P((sqlo_stmt_handle_t * sthp, 
                    sqlo_db_handle_t dbh, 
                    CONST char * stmt, 
                    int argc, 
                    CONST char ** argv));

/**
 * Reopens a already used cursor
 * 
 * This function reopens an already used cursor with new bind variables.
 * Reopening cursors improve the speed, because no new parse is necessary.
 *
 * @param sth  I - The sth you want to rebind.
 * @param argc I - Number of arguments in argv
 * @param argv I - Arguments
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_STILL_EXECUTING in non-blocking mode
 * <li> < 0 on error
 * </ul>
 *
 * @par Example:
 * @anchor ex6
 * @include ex6.c
 *
 * @see sqlo_open2, sqlo_fetch, sqlo_values, sqlo_close
 */
int sqlo_reopen __P((sqlo_stmt_handle_t sth, 
                     int argc, 
                     CONST char ** argv));

/**
 * Fetches the data from an open cursor.
 *
 * This functions fetches data from an open cursor, if the sql was a query.
 * For non-queries, the statement is executed. Use @ref sqlo_values to get the
 * data.
 * @attention nrows must be 1 for cursors opened with @ref sqlo_open or @sqlo_open2.
 * For cursors where the output variables were defined manually with @sqlo_define_by_pos,
 * this can be for example the size of the array in which you are fetching. 
 * 
 * @param sth   I - A statement handle
 * @param nrows I - The number of rows to fetch. 
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>SQLO_NO_DATA
 * <li>< 0 on error
 * </ul>
 *
 * @see sqlo_open2, sqlo_values, sqlo_close
 */
int sqlo_fetch __P((sqlo_stmt_handle_t sth, unsigned int nrows));

/**
 * Get one dataset
 * 
 * Returns the data for one set of data fetched via @ref sqlo_fetch.
 *
 * @param sth I - A statement handle
 * @param num O - A destination where the function could write the size of the 
 *                returned array (optional)
 * @param dostrip I - A flag indicating whether trailing blanks should be stripped 
 *                    off (leading blanks in case of numbers).
 *
 * @return A pointer to an array of strings containing the data values
 *
 * @par Example:
 * @anchor ex7
 * @include ex7.c
 *
 * @see sqlo_fetch, sqlo_value_lens, sqlo_open, sqlo_close.
 */
CONST char **sqlo_values __P(( sqlo_stmt_handle_t sth, int * num, int dostrip ));

/**
 * Get the length of the returned values
 * 
 * Returns the length in number of characters (bytes for non-unicode chars)
 * for a dataset fetched by sqlo_fetch.
 * 
 * @param sth I - A statement handle
 * @param num O - A destination where the function can write the size of the returned
 * array (optional).
 *
 * @return A pointer to an array of unsigned shorts containing the lengths
 *
 * @see sqlo_fetch, sqlo_values, sqlo_open2, sqlo_close.
 */
CONST unsigned short * sqlo_value_lens __P(( sqlo_stmt_handle_t sth, int * num));

/**
 * Get the select list columns
 * 
 * Use this function to get the select list column names. 
 * Most usefull for dynamic sql, where you don't know the sql statement at all.
 * 
 * @param sth I - A statement handle
 * @param num O - A destination where the function can write the size of the returned
 * array (optional).
 *
 * @return A pointer to an array of strings containing the column names
 *
 * @see sqlo_fetch, sqlo_values, sqlo_open2, sqlo_close, sqlo_ocol_name_lens.
 */
CONST char **sqlo_ocol_names __P(( sqlo_stmt_handle_t sth, int * num));


/**
 * Get the select list columns name lengths
 * 
 * Use this function to get the length of each select list column. 
 * Call this when you need the length of the column, for formatting purposes etc.
 *
 * @param sth I - A statement handle
 * @param num O - A destination where the function can write the size of the returned
 * array.
 *
 * @return A pointer to an array of integers containing the lengths
 *
 * @see sqlo_ocol_names, sqlo_fetch, sqlo_open2, sqlo_close.
 */
CONST int *sqlo_ocol_name_lens __P(( sqlo_stmt_handle_t sth, int * num));

/**
 * Get the number of bind/select-list variables
 * 
 * @param sth I - A statement handle
 * @param in  I - 1 returns the number of bind variables, 0 returns the number of
 *                select list columns.
 *
 * @return <ul>
 * <li>The number of columns
 * <li>SQLO_INVALID_STMT_HANDLE
 * </ul>
 */
int sqlo_ncols __P((sqlo_stmt_handle_t sth, int in));

/**
 * Return the sql command
 *
 * @return The active sql statement of the sth.
 *
 * @param sth I - A statement handle
 */
CONST char *sqlo_command __P(( sqlo_stmt_handle_t sth ));

/**
 * Close the cursor
 *
 * Closes the cursor and releases the Oracle statement handle.
 * 
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li>< 0 on error
 * </ul>
 *
 * @see sqlo_open.
 *
 */
int sqlo_close __P(( sqlo_stmt_handle_t sth ));

/**
 * Execute a simple sql statement
 * 
 * Use this to execute non-qeuery statements without bind variables.
 *
 * @param dbh A database handle
 * @param stmt A sql statement 
 *
 * @return The number of processed rows (DML statements), 0 (non DML statements) 
 *         or < 0 on error.
 *
 * @par Example: 
 * @include ex8.c
 * 
 * @see sqlo_run
 */
int sqlo_exec __P(( sqlo_db_handle_t dbh, CONST char * stmt ));



/**
 * Test if a cursor is open
 *
 * @param sth  I - A statement handle.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS  if the cursor is open
 * <li>1 if not (unused sth)
 * <li>SQLO_INVALID_STMT_HANDLE.
 * </ul>
 * @see sqlo_open2
 */
int sqlo_isopen __P((sqlo_stmt_handle_t sth));

/**
 * Return the number of processed rows by this statement
 *
 * @param sth I - A statement handle
 *
 * @return <ul>
 * <li>Number of processed rows
 * <li> 0 if it is not a dml statement
 * <li> < 0 on error
 * </ul>
 *
 */
int sqlo_prows __P(( sqlo_stmt_handle_t sth ));

/** @} */


/**
 * @defgroup loginout Functions to do login/logout to/from a database
 * @{
 */

/**
 * Connect to a database
 *
 * This is the short form of @ref sqlo_server_attach followed by @ref sqlo_session_begin
 *
 * @param dbhp        O - The database handle
 * @param cstr        I - A Oracle connect string.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @par Example:
 * @include examples.c
 * @see sqlo_finish, sqlo_server_attach, sqlo_session_begin
 */
int sqlo_connect __P(( sqlo_db_handle_t * dbhp, CONST char * cstr ));


/**
 * Finish the session
 *
 * Finish the session with implicit commit.
 * This is the short form of @ref sqlo_session_end followed by @ref sqlo_server_detach.
 *
 * @param dbh I - A database handle
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_connect, sqlo_session_end, sqlo_server_detach, sqlo_server_attach
 */
int sqlo_finish __P((sqlo_db_handle_t dbh ));

/**
 * Split an Oracle connect string
 * 
 * Splits an Oracle connect string of the form uid[[/pwd]@tnsname] into its
 * components. If no tnsname is found in the cstr, we copy the value of the
 * env. variable ORACLE_SID into tnsname.
 *
 * @param cstr     I - A connect string to split
 * @param uid      O - The returned uid part.
 * @param pwd      O - The returned pwd part.
 * @param tnsname  O - The returned tnsname.
 * @param bufsize  I - The capacity of the output buffers.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS 
 * <li> SQLO_ERROR (buffer too small)
 * </ul>
 * @since Version 2.2
 */
int sqlo_split_cstring __P((CONST char * cstr, 
                            char * uid, 
                            char * pwd, 
                            char * tnsname, 
                            unsigned int bufsize));

/**
 * Attach to a database server
 *
 * Attaches to a database without creating a session.
 * tnsname can be a database name or a connect string. The function extracts
 * the database name. If no database name is supplied, the function attaches
 * to the database given in the env. variable ORACLE_SID.
 *
 * @param dbhp    O - The database handle
 * @param tnsname O - The tnsname or the complete Oracle connect string.
 *
 * @return <ul>
 * <li>SQLO_SUCCESS
 * <li> < 0 on error
 * </ul>
 *
 * @see sqlo_session_begin, sqlo_server_detach
 * @since Version 2.2
 */
int sqlo_server_attach __P((sqlo_db_handle_t * dbhp, CONST char * tnsname));

/** 
 * Begin a session
 *
 * Do the login to an attached server.
 * You can either pass username and password seperatly, or pass the complete
 * connect string in username.