kusapi.h

将对Oracle数据库读写操作的OCI进行封装。不但具有普通数据的读取操作

/*
 * $Header: kusapi.h 14-mar-97.08:14:40 pabingha Exp $
 */

/* Copyright (c) Oracle Corporation 1996, 1997. All Rights Reserved. */ 
 
/* NOTE:  See 'header_template.doc' in the 'doc' dve under the 'forms' 
      directory for the header file template that includes instructions. 
*/
 
/* 
   NAME 
     kusapi.h - Kernel Utility Statistics Application Programming Interface

   DESCRIPTION 
     Declarations of types and functions of the API used to retrieve 
     statistics from the SGA

   PUBLIC FUNCTION(S) 
     kusdb_connect - connect to a database
     kuscx_allocate - allocate continuation context
     kuscx_free - free continuation context
     kuscx_init - initialize continuation context
     kusdb_get_info - retrieve database information
     kusdb_get_memory - copy SGA contents into user-allocated memory
     kusdb_disconnect - disconnect from database
     kusdb_error_text - format message for last error
     kustv_allocate_handle - allocate a TLV handle
     kustv_dump - dump a TLV buffer
     kustv_free_handle - free a TLV handle
     kustv_get - get next entry in a TLV buffer
     kustv_offset - return offset for current entry in TLV buffer
     kussys_get_info - retrieve non-db-related info (noop for Oracle)
     kussys_error_text - format message for last error (noop for Oracle)
     kustvp1_put_one_byte - put TLV entry with 1 byte value into TLV buffer
     kustvp2_put_two_bytes - put TLV entry with 2 byte value into TLV buffer
     kustvp4_put_four_bytes - put TLV entry with 4 byte value into TLV buffer
     kustv_put - put TLV entry into TLV buffer
     kustvptg_put_tag - put TLV entry with empty value into TLV buffer
     kustv_reinit_handle - reset offset for a TLV handle
     kustv_buffer_state - return termination state for tlv buffer

   NOTES
     This interface is subject to change without notice

   MODIFIED   (MM/DD/YY)
   pabingha    03/14/97 - Add get_tagname argument
   jstenois    11/05/96 - "Make kustv_dump() header CONST"
   jstenois    11/01/96 - Use oratypes instead of sx.h
   jstenois    08/15/96 - SGAAPI public include file
   jstenois    08/15/96 - Creation

*/

 
#ifndef KUSAPI
# define KUSAPI

# ifndef ORATYPES
#  include <oratypes.h>
# endif


/*---------------------------------------------------------------------------
                     PUBLIC TYPES AND CONSTANTS
  ---------------------------------------------------------------------------*/

/* values for status code returned by API calls */

typedef enum kusst
  {

    KUSSTOK =		1,	/* Success                              */
    KUSSTEOB =		2,	/* Cursor at end of buffer.	        */
    KUSSTNWR =		3,	/* Attempt to write to TLV when no      */
				/*    length specified at init time	*/
    KUSSTILN =		4,	/* Invalid length specified when	*/
				/*    passing by value			*/
    KUSSTTRNC =		5,	/* buffer was truncated			*/
    KUSSTCONT =		6,	/* buffer is continued			*/
    KUSSTALLC =		7,	/* unable to allocate memory		*/
    KUSSTUNKC =		8,	/* unknown class tag specified		*/
    KUSSTICH =		9,	/* Invalid context handle		*/
    KUSSTIDH =		10,	/* Invalid database handle		*/
    KUSSTITH =		11,	/* Invalid TLV handle			*/
    KUSSTDIS =		12,	/* Stats collection disabled for database */
    KUSSTERR =		13,	/* Unexpected error encountered		*/
    KUSSTBINF =		14,	/* Input buffer contained a bad tag	*/
    KUSSTBDKY =         15,     /* Bad index value for class tag	*/
    KUSSTBFSML =	16,	/* Buffer is too small for data		*/
    KUSSTIBE =		17,	/* Information buffer is empty          */
    KUSSTDBDOWN =       18,     /* Database is unavaliable              */
    KUSSTFILACC =       19,     /* File cannot be accessed              */
    KUSSTINVDB =        20,     /* File is not a db root file (Rdb only)*/
    KUSSTNODB =         21,     /* Db root file doesn't exist (Rdb only)*/
    KUSSTBADVER =       22,     /* Db root file wrong version (Rdb only)*/
    KUSSTCIU =          23,     /* Context is already in use            */
    KUSSTDMPOP =        24,     /* Unable to open dump output file      */
    KUSSTDMPCL =        25      /* Unable to close dump output file     */
  } kusst;


/* values returned by kustvstate */ 

typedef enum kustvs
  {
    KUSTVS_CONT =	1,	/* tlv buffer terminated with KUSSTCONT	*/
    KUSTVS_END =	2,	/* tlv buffer terminated with KUSSTBEND	*/
    KUSTVS_TRUNC =	3,	/* tlv buffer terminated with KUSSTTRNC	*/
    KUSTVS_UNK =	4	/* handle specified has not been used	*/
                                /* to read or write a termination tag   */
  } kustvs;


/* Type Definitions for handles */

typedef dvoid *kusdb_handle;	/* handle for connected database */
typedef dvoid *kuscx_handle;	/* handle for continuation context */
typedef dvoid *kustv_handle;	/* handle for TLV context */

/* Data structure for use by kusdb_get_memory */

typedef struct kusmem
  {
    ub1 *sga_address_kusmem;    /* SGA memory address */
    ub4 length_kusmem;          /* Number of bytes to copy */
    ub1 *dest_address_kusmem;   /* User-allocated destination for SGA data */
  } kusmem;


/*---------------------------------------------------------------------------
                           PUBLIC FUNCTIONS
  ---------------------------------------------------------------------------*/


/* ---------------------------- kuscx_allocate ----------------------------- */
/*
  NAME
    kuscx_allocate -  allocate continuation context
  DESCRIPTION
    Allocate space to track information about continuation context for a 
    kusdb_get_info call.
  PARAMETERS
    context_handle - handle for the continuation context (in/out)
  RETURN VALUE
    status of call
  NOTES
    kuscx_init can be used to reinitilize a context that has been allocated 
    and is no longer used for a TLV buffer
*/

kusst kuscx_allocate (/*_ kuscx_handle *context_handle _*/);




/* ------------------------------ kuscx_free_handle ------------------------ */
/*
  NAME
    kuscx_free_handle -  free continuation context
  DESCRIPTION
    free space used to track information about continuation context for a 
    kusdb_get_info call.
  PARAMETERS
    context_handle - handle for the continuation context (in/out)
  RETURN VALUE
    status of call
  NOTES
    kuscx_init can be used to reinitilize a context that has been allocated
    and is no longer used for a TLV buffer
*/

kusst kuscx_free_handle (/*_ kuscx_handle *context_handle _*/);




/* ------------------------------ kuscx_init ------------------------------- */
/*
  NAME
    kuscx_init -  initialize continuation context
  DESCRIPTION
    Reinitialize a context handle that has been previously allocated and used.
  PARAMETERS
    context_handle - handle for the continuation context (in/out)
  RETURN VALUE
    status of call
  NOTES
    kuscx_init is the semantic equivalent of freeing a context handle and then
    allocating a new one.
*/

kusst kuscx_init (/*_ kuscx_handle *context_handle _*/);



/* ----------------------------- kusdb_allocate ---------------------------- */
/*
  NAME
    kusdb_allocate - allocate a database handle
  DESCRIPTION
    allocate resources for a database handle
  PARAMETERS
    db_handle - handle for the database context (in/out)
  RETURN VALUE
    kusst - status of attempt to allocate
*/

kusst kusdb_allocate (/*_ kusdb_handle *db_handle _*/);




/* ----------------------------- kusdb_connect ----------------------------- */
/*
  NAME
    kusdb_connect - connect to a database
  DESCRIPTION
    Connects to a database so that statistics for that database can be
    retrieved.
  PARAMETERS
    db_handle - handle for the database context (in/out)
    database_name_length - number of bytes in database_name parameter
    database name - name of database
    security_info_length - number of bytes in security_info parameter
    security_info - security information used to attach to database
  RETURN VALUE
    status of attempt to connect
  NOTES
    If the status is not successful, call kusdb_error_text to get more 
    information about the failure.
    Refer to the documentation for the format of information in the
    database_name and security_info parameters.
*/

kusst kusdb_connect (/*_
	kusdb_handle db_handle,
	ub4 database_name_length,
	char *database_name,
	ub4 security_info_length,
	char *security_info
	_*/);




/* ---------------------------- kusdb_disconnect --------------------------- */
/*
  NAME
    kusdb_disconnect - disconnect from a database
  DESCRIPTION
    Disconnect from the current database
  PARAMETERS
    db_handle - handle for the database (in/out)
  RETURN VALUE
    status of call
  NOTES
*/

kusst kusdb_disconnect (/*_ kusdb_handle db_handle _*/);




/* ------------------------------- kusdb_free ------------------------------ */
/*
  NAME
    kusdb_free - free a database handle
  DESCRIPTION
    free resources for a database handle
  PARAMETERS
    db_handle - handle for the database context (in/out)
  RETURN VALUE
    kusst - status of attempt to free the handle
*/

kusst kusdb_free (/*_ kusdb_handle *db_handle _*/);




/* ----------------------------- kusdb_get_info ---------------------------- */
/*
  NAME
    kusdb_get_info - retrieve statistics for a database
  DESCRIPTION
    Retrieve requested statistics for the current database
  PARAMETERS
    db_handle - handle for the database (in)
    context_handle - handle for the continuation context (in/out)
    info_buf - TLV buffer indicating data to be returned (in)
    info_buf_len - number of bytes in info_buffer (in)
    result_buf - allocated TLV buffer to hold data returned (in/out)
    result_buf_len - number of bytes in result_buf (in/out)
    buffer_termination_status - indicates how buffer was terminated (normally,
      truncated, or continued) (out)
  RETURN VALUE
    status of call
  NOTES
    If the status is not successful, call kusdb_error_text to get more 
    information about the failure.
    Refer to documentation for information on the format of the information
    buffer and the result buffer
*/

kusst kusdb_get_info (/*_
	kusdb_handle db_handle,
	kuscx_handle ctx_handle,
	ub1 *info_buffer,
	ub4 info_buffer_length,
	ub1 *result_buffer,
	ub4 *result_buffer_length,
	kustvs *buffer_termination_status
	_*/);



/* ----------------------------- kusdb_get_memory -------------------------- */
/*
  NAME
    kusdb_get_memory - copy SGA contents into user-allocated memory
  DESCRIPTION
    Copy SGA memory into user-allocated memory regions. User provides
    an array of kusmem structures. Each kusmem structure in the array
    describes a distinct copy to be done by this routine.
  PARAMETERS
    db_handle - handle for the database (in)
    mem_array_length - number of elements in mem_array (in)
    mem_array - address of an array of kusmem structures (in/out)
  RETURN VALUE
    status of call:
        KUSSTOK - call succeeded, all requested data copied
        KUSSTIDH - invalid database handle
        KUSSTDBDOWN - database is down
        KUSSTERR - unexpected error
  NOTES
     User should prepare each kusmem structure in array by filling in
     values for sga_address_kusmem, length_kusmem and dest_address_kusmem
     prior to making this call. 

     User is reponsible for allocating and deallocating the memory used
     by mem_array and each region that a dest_address_kusmem points to.
*/

kusst kusdb_get_memory (/*_
	kusdb_handle db_handle,
        ub4 mem_array_length,
        kusmem *mem_array
	_*/);




/* ---------------------------- kusdb_error_text --------------------------- */
/*
  NAME
    kusdb_error_text - error text
  DESCRIPTION
    Display information about status of last kusdb call
  PARAMETERS
    db_ctx - context whose errors are to be returned (in)
    text_buf - buffer to hold error message (in/out)
    text_buf_len - number of bytes in text buffer (in)
    text_len_out - number of bytes written into text_buf
  RETURN VALUE
    status of call
  NOTES
*/

kusst kusdb_error_text (/*_ kusdb_handle db_ctx, char *text_buf,
			  ub4 text_buf_len, ub4 *text_len_out _*/);




/* ------------------------ kustv_allocate_handle -------------------------- */
/*
  NAME
    kustv_allocate_handle - allocate a handle for a TLV buffer
  DESCRIPTION
    allocates and initializes information for a TLV handle
  PARAMETERS
    tlv_handle - handle of the TLV buffer (in/out)
    tlv_buffer - address of the TLV buffer for this handle (in)
    buf_size - number of bytes in tlv_buffer (in)
  RETURN VALUE
    KUSSTALL	Unable to allocate memory
  NOTES