/* Copyright (c) 2006, 2009, Oracle and/or its affiliates. All rights reserved. */ /* NAME ocixstreams.h - OCI X-Stream APIs DESCRIPTION OCI APIs for X-Stream RELATED DOCUMENTS EXPORT FUNCTION(S) INTERNAL FUNCTION(S) EXAMPLES NOTES MODIFIED (MM/DD/YY) thoang 05/08/09 - Add OCILCR_NEW_ONLY_MODE praghuna 05/11/09 - removed 'TODO' comments thoang 02/15/09 - Change lob_column_* to chunk_column_* thoang 01/27/09 - 8216105 - add OLD/NEW column parms to OCILCRHeaderGet rihuang 01/05/09 - Add OCI_LCR_ATTR_TRACKING_LABEL tianli 11/28/08 - add DDL flags tianli 11/20/08 - add OCILCRAttribute methods thoang 11/20/08 - Define OCI_LCR_MAX_TXID_LEN tianli 11/07/08 - add edition thoang 11/10/08 - change return type to sword for consistency thoang 10/16/08 - remove commit position arg tianli 08/26/08 - rename client_name in XStreamIn attach call thoang 06/30/08 - Support XStream APIs using two callbacks. praghuna 05/14/08 - charset id is ub2, OCILcrGetRowStmtWithBindVar thoang 06/02/08 - Define reserved attach mode for internal clients elu 05/08/08 - add pos functions thoang 04/29/08 - API changes jinwu 04/28/08 - add OCILcrGetExtraAttributes elu 04/14/08 - add OCI_LCR_MAX_POSITION_LEN juyuan 03/27/08 - add flag for Set/GetHeader and Set/GetColumnInfo thoang 02/25/08 - Add GetNextChunk and SetNextChunk rihuang 03/24/08 - Signature change for OCILcrNew elu 03/05/08 - add lcr id praghuna 02/26/08 - Added OCILcrGetRowStmt thoang 01/25/08 - Add wm_time parameter to XApply APIs thoang 12/28/07 - Add mode parameter to XApplyDetach thoang 11/07/07 - Change extapp apis to return ub1[] watermark juyuan 05/23/07 - XStream In thoang 11/13/06 - Add XStream Out methods thoang 11/13/06 - Add LCR getter methods nshodhan 05/12/06 - streams OCI APIs nshodhan 05/12/06 - Creation */ #ifndef OCIXSTREAM_ORACLE # define OCIXSTREAM_ORACLE #ifndef ORATYPES # include #endif #ifndef OCI_ORACLE # include #endif #ifdef __cplusplus extern "C" { #endif /*--------------------------------------------------------------------------- PUBLIC TYPES AND CONSTANTS ---------------------------------------------------------------------------*/ /* LCR Types -- must match with values defined in kngo.h */ #define OCI_LCR_XROW (3) /* External Row LCR */ #define OCI_LCR_XDDL (4) /* External DDL LCR */ /* DML Command Types -- must match with values defined in kngl.h */ #define OCI_LCR_ROW_CMD_INSERT "INSERT" #define OCI_LCR_ROW_CMD_DELETE "DELETE" #define OCI_LCR_ROW_CMD_UPDATE "UPDATE" #define OCI_LCR_ROW_CMD_COMMIT "COMMIT" #define OCI_LCR_ROW_CMD_LOB_WRITE "LOB WRITE" #define OCI_LCR_ROW_CMD_LOB_TRIM "LOB TRIM" #define OCI_LCR_ROW_CMD_LOB_ERASE "LOB ERASE" /* LCR Extra Attribute Name -- must match with values defined in knll.h */ #define OCI_LCR_ATTR_THREAD_NO "THREAD#" #define OCI_LCR_ATTR_ROW_ID "ROW_ID" #define OCI_LCR_ATTR_SESSION_NO "SESSION#" #define OCI_LCR_ATTR_SERIAL_NO "SERIAL#" #define OCI_LCR_ATTR_USERNAME "USERNAME" #define OCI_LCR_ATTR_TX_NAME "TX_NAME" /* below are non first class LCR field specific */ #define OCI_LCR_ATTR_EDITION_NAME "EDITION_NAME" #define OCI_LCR_ATTR_MESSAGE_TRACKING_LABEL "MESSAGE_TRACKING_LABEL" /* the maximum total number of attributes, total of extra attributes * plus non first class LCR field. */ #define OCI_LCR_MAX_ATTRIBUTES 8 /* Row LCR column value types used in OCILCRRowColumnInfoGet/Set functions. */ #define OCI_LCR_ROW_COLVAL_OLD 0 /* OLD columns */ #define OCI_LCR_ROW_COLVAL_NEW 1 /* NEW columns */ /* maximum length for position */ #define OCI_LCR_MAX_POSITION_LEN 64 /* maximum length for txid */ #define OCI_LCR_MAX_TXID_LEN 128 /* Valid column flags used in OCILCRRowColumnInfoSet, OCILCRRowColumnInfoGet, * OCILCRLobInfoSet, OCILCRLobInfoGet, OCIXStreamOutChunkReceive, * OCIXStreamInChunkSend calls. */ #define OCI_LCR_COLUMN_LOB_DATA (0x00000001) /* col contains lob data */ #define OCI_LCR_COLUMN_LONG_DATA (0x00000002) /* col contains long data*/ #define OCI_LCR_COLUMN_EMPTY_LOB (0x00000004) /* col has an empty lob */ #define OCI_LCR_COLUMN_LAST_CHUNK (0x00000008) /* last chunk of current col*/ #define OCI_LCR_COLUMN_AL16UTF16 (0x00000010) /* col is in AL16UTF16 fmt */ #define OCI_LCR_COLUMN_NCLOB (0x00000020) /* col has NCLOB data */ #define OCI_LCR_COLUMN_XML_DATA (0x00000040) /* col contains xml data */ #define OCI_LCR_COLUMN_XML_DIFF (0x00000080)/* col contains xmldiff data */ #define OCI_LCR_COLUMN_ENCRYPTED (0x00000100) /* col is encrypted */ /* OCI_LCR_COLUMN_UPDATED is set only for the modified columns in the NEW * column list of an update LCR. */ #define OCI_LCR_COLUMN_UPDATED (0x00000200) /* col is updated */ /* Valid bit values for flag parameter in the following APIs: * - OCIXStreamOutChunkReceive & OCIXStreamOutLCRReceive * - OCIXStreamInChunkSend & OCIXStreamInLCRSend */ #define OCI_XSTREAM_MORE_ROW_DATA (0x00000001) /* LCR contains more data */ /* Valid mode flag for OCILCRHeaderGet and OCILCRRowColumnInfoGet functions */ #define OCILCR_NEW_ONLY_MODE (0x0001) /* NEW columns only -- dont */ /* include OLD columns */ /*--------------------------------------------------------------------------- PRIVATE TYPES AND CONSTANTS ---------------------------------------------------------------------------*/ /*--------------------------------------------------------------------------- EXPORT FUNCTIONS ---------------------------------------------------------------------------*/ /* ------------------------------------------------------------------------------= NAME OCILCRNew - OCI LCR NEW DESCRIPTION Create a new Streams LCR for the user specified duration and type PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle duration (IN) - allocation duration for LCR memory lcrtype (IN) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL) lcrp (IN/OUT) - Streams LCR. (*lcrp must be initialized to null.) mode (IN) - mode NOTES - memory will be based on the duration specified by the user - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRNew(OCISvcCtx *svchp, OCIError *errhp, OCIDuration duration, ub1 lcrtype, void **lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRFree - OCI LCR FREE DESCRIPTION Free Streams LCR specified by the user PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle lcrp (IN/OUT) - Streams LCR mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRFree(OCISvcCtx *svchp, OCIError *errhp, void *lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRHeaderSet - OCI LCR Set Header DESCRIPTION Initialize elements of Streams LCR's header PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle src_db_name (IN) - Pointer to Canonicalized source database name. Must be non-NULL. src_db_name_len (IN) - Length of source database name in bytes excluding NULL terminator. Should follow Oracle naming conventions and size limitations. cmd_type (IN) - For ROW LCRs: OCI_LCR_ROW_CMD_XXXXXXX For DDL LCRs: One of the command types corresponding to OCI Reference manual cmd_type_len (IN) - Length of cmd_type. owner (IN) - Canonicalized table owner name. Not required for COMMIT LCR. owner_len (IN) - Length of owner name in bytes excluding the NULL terminator. Should follow Oracle naming conventions and size limitations. oname (IN) - Canonicalized table name. Not required for COMIT LCR. oname_len (IN) - Length of table name in bytes excluding the NULL terminator. Should follow Oracle naming conventions and size limitations. tag (IN) - A binary tag that enables tracking of the LCR. For example, this tag can be used to determine the original source database of the DML statement if apply forwarding is used. tag_len (IN) - Number of bytes in the tag. Cannot exceed 2000 bytes txid (IN) - Transaction ID. txid_len (IN) - Length of transaction id in bytes excluding the NULL terminator. Should not exceeed OCI_LCR_MAX_TXID_LEN bytes. src_time (IN) - The time when the change was generated at the source database. position (IN) - position for LCR. Must be byte-comparable. position_len (IN) - Length of position. Must be non-zero. flag (IN) - LCR flag. lcrp (IN/OUT) - Streams LCR mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode - This function clears the current contents of the input LCR before setting the header to the new values. ------------------------------------------------------------------------------= */ sword OCILCRHeaderSet(OCISvcCtx *svchp, OCIError *errhp, oratext *src_db_name, ub2 src_db_name_len, oratext *cmd_type, ub2 cmd_type_len, oratext *owner, ub2 owner_len, oratext *oname, ub2 oname_len, ub1 *tag, ub2 tag_len, oratext *txid, ub2 txid_len, OCIDate *src_time, ub1 *position, ub2 position_len, oraub8 flag, void *lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRHeaderGet - OCI LCR Get Header DESCRIPTION Get header information from Streams LCR PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle src_db_name (OUT) - Pointer to Canonicalized source database name. Optional, if src_db_name is specified then must specify src_db_name_len as well. src_db_name_len (OUT) - Length of source database name in bytes excluding NULL terminator. Optional, if specified src_db_name_len then must specify src_db_name as well. cmd_type (OUT) - Command type. Must be non-null if cmd_type_len is non-null. Must be null if cmd_type_len is NULL. cmd_type_len (OUT) - Length of cmd_type. Optional. owner (OUT) - Canonicalized table owner name. Optional, if owner is specified then must specify owner_len as well. owner_len (OUT) - Length of owner name in bytes excluding the NULL terminator. Optional, if owner_len is specified then must specify owner as well. oname (OUT) - Canonicalized table name. Optional, if oname is specified then must specify oname_len as well. oname_len (OUT) - Length of table name in bytes excluding the NULL terminator. Optional, if oname_len is specified then must specify oname as well. tag (OUT) - A binary tag that enables tracking of the LCR. For example, this tag can be used to determine the original source database of the DML statement if apply forwarding is used. Optional, if tag is specified then must specify tag_len as well. tag_len (OUT) - Number of bytes in the tag. Optional, if tag_len is specified then must specify tag as well. txid (OUT) - Transaction ID. Optional, if txid is specified then must specify txid_len as well. txid_len (OUT) - Length of transaction id in bytes excluding the NULL terminator. Optional, if txid_len is specified then must specify txid as well. src_time (OUT) - The time when the change was generated at the source database. Optional. old_columns (OUT) - Number of columns in the OLD column list. Return 0 if input lcr is DDL LCR. Optional. new_columns (OUT) - Number of columns present in either the OLD or NEW column list. Return 0 if input lcr is DDL LCR. Optional. See NOTES below for the special mode supported by this function. position (OUT) - LCR position. Optional. position_len (OUT) - Length of position. Must be non-null if position is non-null. Must be null if position is null. flag (OUT) - LCR flag. Optional. lcrp (IN) - Streams LCR mode (IN) - mode (see NOTES) NOTES - Parameter src_time is optional. If specified the appropriate return structure must be pre-allocated before calling OCILCRHeaderGet. - The return values for src_db_name, cmd_type, owner, oname, tag, txid and position are shallow-copied (i.e., they point directly into the LCR structure). - Valid mode flags: - OCILCR_NEW_ONLY_MODE: if this mode is specified then the new_columns returned is the count of the columns in the NEW column list only. Otherwise, the new_columns returned is the number of distinct columns present in either the NEW or the OLD column list of the given ROW LCR. ------------------------------------------------------------------------------= */ sword OCILCRHeaderGet(OCISvcCtx *svchp, OCIError *errhp, oratext **src_db_name, ub2 *src_db_name_len, oratext **cmd_type, ub2 *cmd_type_len, oratext **owner, ub2 *owner_len, oratext **oname, ub2 *oname_len, ub1 **tag, ub2 *tag_len, oratext **txid, ub2 *txid_len, OCIDate *src_time, ub2 *old_columns, ub2 *new_columns, ub1 **position, ub2 *position_len, oraub8 *flag, void *lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRRowColumnInfoSet - OCI LCR ROW SET COLUMN INFO DESCRIPTION Populates column information as specified by the user. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle column_value_type (IN) - ROW LCR column value type: - OCI_LCR_ROW_COLVAL_OLD - OCI_LCR_ROW_COLVAL_NEW num_columns (IN) - Number of columns to be populated column_names (IN) - Pointer to an array of column names. Column names must be canonicalized. Column names should follow Oracle naming conventions column_name_lens (IN) - Pointer to an array of column name lengths in bytes, excluding the NULL terminator. column_dtyp (IN) - Pointer to an array of column datatypes. column_valuesp (IN) - Pointer to an array of column data values. column_indp (IN) - Pointer to an indicator array. For all datatypes, this is a pointer to an array of OCIInd values (OCI_IND_NULL/OCI_IND_NOTNULL). column_alensp (IN) - Pointer to an array of actual column lengths in bytes. column_csetfp (IN) - Pointer to an array of character set forms for the columns. The default form is SQLCS_IMPLICIT. Setting this attribute will cause the database or national character set to be used on the client side. Set this attribute to SQLCS_NCHAR for the national character set or SQLCS_IMPLICIT for the database character set. Pass 0 for non-character columns. column_flags (IN) - Pointer to an array of column flags. Possible bit values are OCI_LCR_COLUMN_* flags listed above. column_csid (IN) - Pointer to an array of column character set id. The character set id is only required for XMLType column; otherwise, the csid is ignored. row_lcrp (IN/OUT)- Streams Row LCR pointer mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRRowColumnInfoSet(OCISvcCtx *svchp, OCIError *errhp, ub2 column_value_type, ub2 num_columns, oratext **column_names, ub2 *column_name_lens, ub2 *column_dtyp, void **column_valuesp, OCIInd *column_indp, ub2 *column_alensp, ub1 *column_csetfp, oraub8 *column_flags, ub2 *column_csid, void *row_lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRRowColumnInfoGet - OCI LCR ROW GET COLUMN INFO DESCRIPTION Returns column information as requested by the user. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle column_value_type (IN) - ROW LCR column value type: - OCI_LCR_ROW_COLVAL_OLD - OCI_LCR_ROW_COLVAL_NEW (See NOTES for special mode supported by this function.) num_columns (OUT) - Number of columns in requested column list column_names (IN/OUT)- Pointer to an array of column names. Optional. If specified then column_namesl must be specified as well, and both arrays must be the size specified by array_size parameter. column_name_lens (IN/OUT)- Pointer to an array of column name lengths in bytes, excluding the NULL terminator. Optional. If specified then column_names must be specified as well, and both arrays must be the size specified by array_size parameter. column_dtyp (IN/OUT)- Pointer to an array of column datatypes. Optional. If specified then this array must be the size specified by array_size parameter. column_valuesp (IN/OUT)- Pointer to an array of column data values. Optional. If specified then this array must be the size specified by array_size parameter. column_indp (IN/OUT)- Pointer to an indicator array. For all datatypes, this is a pointer to an array of OCIInd values (OCI_IND_NULL/OCI_IND_NOTNULL). Optional. If specified then this array must be the size specified by array_size parameter. column_alensp (IN/OUT)- Pointer to an array of actual column lengths in bytes. Optional. If specified then this array must be the size specified by array_size parameter. column_csetfp (IN/OUT)- Pointer to an array of character set forms for the columns. Optional. If specified then this array must be the size specified by array_size parameter. column_flags (IN/OUT)- Pointer to an array of column flags for the columns. Optional. If specified then this array must be the size specified by array_size parameter. Possible bit values are OCI_LCR_COLUMN_* flags listed above. column_csid (IN/OUT)- Pointer to an array of column character set id for the columns. Optional. If specified then this array must be the size specified by array_size parameter. The column csid is returned only for XMLType column. row_lcrp (IN) - Streams Row LCR pointer array_size (IN) - Size of each of above arrays mode (IN) - mode (see NOTES) NOTES - For now, specify OCI_DEFAULT for mode - If array_size is not large enough to accommodate the number of columns in the requested column list then OCI_ERROR is returned. Parameter num_columns will have the number of columns in the requested column list. - The return values for column_names and column_valuesp will be shallow copied (i.e., they reference directly into the LCR structure). Client should not modify those pointers directly. - Valid mode flags: - OCILCR_NEW_ONLY_MODE: this mode is valid only for OCI_LCR_ROW_COLVAL_NEW column_value_type; otherwise, an error is raised. If this mode is specified then the columns returned include only the columns in the NEW column list. If this mode is not specified then the columns returned is the union of the NEW columns plus the OLD columns that are not present in the NEW column list. ------------------------------------------------------------------------------= */ sword OCILCRRowColumnInfoGet(OCISvcCtx *svchp, OCIError *errhp, ub2 column_value_type, ub2 *num_columns, oratext **column_names, ub2 *column_name_lens, ub2 *column_dtyp, void **column_valuesp, OCIInd *column_indp, ub2 *column_alensp, ub1 *column_csetfp, oraub8 *column_flags, ub2 *column_csid, void *row_lcrp, ub2 array_size, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRDDLInfoSet - OCI LCR SET DDL INFO DESCRIPTION populates DDL information as sepcified by the user. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle object_type (IN) - The type of object on which the DDL statement was executed. The following are valid object types: CLUSTER, FUNCTION, INDEX, LINK, OUTLINE, PACKAGE, PACKAGE BODY, PROCEDURE, SEQUENCE, SYNONYM, TABLE, TRIGGER, TYPE, USER, VIEW LINK represents a database link. NULL is also a valid object type. Specify NULL for all object types not listed. object_type_len (IN) - Length of object_type without the NULL terminator. ddl_text (IN) - The text of the DDL statement. This parameter should be set to a non-NULL value. DDL text must be in Oracle DDL format. ddl_text_len (IN) - DDL text length in bytes without NULL terminator. logon_user (IN) - Canonicalized name of the user whose session executed the DDL statement. Should follow Oracle naming conventions and size limitations. logon_user_len (IN) - logon user name length in bytes without NULL terminator. current_schema (IN) - The canonicalized schema name that is used if no schema is specified explicitly for the modified database objects in ddl_text. If a schema is specified in ddl_text that differs from the one specified for current_schema, then the schema specified in ddl_text will be used. This parameter should be set to a non-NULL value. Should follow Oracle naming conventions and size limitations. current_schema_len (IN) - schema name length in bytes without NULL terminator base_table_owner (IN) - If the DDL statement is a table related DDL (such as CREATE TABLE and ALTER TABLE), or if the DDL statement involves a table (such as creating a trigger on a table), then base_table_owner specifies the canonicalized owner of the table involved. Otherwise, base_table_owner is NULL. Should follow Oracle naming conventions and size limitations. base_table_owner_len (IN)- base table owner name length in bytes without NULL terminator. base_table_name (IN) - If the DDL statement is a table related DDL (such as CREATE TABLE and ALTER TABLE), or if the DDL statement involves a table (such as creating a trigger on a table), then base_table_name specifies the canonicalized name of the table involved. Otherwise, base_table_name is NULL. Length of the above string without the NULL terminator. Should follow Oracle naming conventions and size limitations. Should follow Oracle naming conventions and size limitations. base_table_name_len (IN)- base table name length in bytes without NULL terminator. flag (IN) - DDL LCR flag. ddl_lcrp (IN/OUT) - Streams Ddl LCR pointer mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRDDLInfoSet(OCISvcCtx *svchp, OCIError *errhp, oratext *object_type, ub2 object_type_len, oratext *ddl_text, ub4 ddl_text_len, oratext *logon_user, ub2 logon_user_len, oratext *current_schema, ub2 current_schema_len, oratext *base_table_owner, ub2 base_table_owner_len, oratext *base_table_name, ub2 base_table_name_len, oraub8 flag, void *ddl_lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRDDLInfoGet - OCI LCR GET DDL INFO DESCRIPTION Returns DDL information from specified lcr. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle object_type (OUT) - The type of object on which the DDL statement was executed. Optional, if object_type is specified then must specify object_type_len as well. object_type_len (OUT) - Length of object_type without the NULL terminator. ddl_text (OUT) - The text of the DDL statement. Optional, if ddl_text is specified then must specify ddl_text_len as well. ddl_text_len (OUT) - DDL text length in bytes without NULL terminator. logon_user (OUT) - Canonicalized name of the user whose session executed the DDL statement. Optional, if logon_user is specified then must specify logon_user_len as well. logon_user_len (OUT) - logon user name length in bytes without NULL terminator. current_schema (OUT) - The canonicalized schema name that is used if no schema is specified explicitly for the modified database objects in ddl_text. Optional, if current_schema is specified then must specify current_schema_len as well. current_schema_len (OUT)- schema name length in bytes without NULL terminator base_table_owner (OUT) - If the DDL statement is a table related DDL (such as CREATE TABLE and ALTER TABLE), or if the DDL statement involves a table (such as creating a trigger on a table), then base_table_owner specifies the canonicalized owner of the table involved. Otherwise, base_table_owner is NULL. Optional, if base_table_owner is specified then must specify base_table_owner_len as well. base_table_owner_len (OUT) - base table owner name length in bytes without NULL terminator. base_table_name (OUT) - If the DDL statement is a table related DDL (such as CREATE TABLE and ALTER TABLE), or if the DDL statement involves a table (such as creating a trigger on a table), then base_table_name specifies the canonicalized name of the table involved. Otherwise, base_table_name is NULL. Optional, if base_table_name is specified then must specify base_table_name_len as well. base_table_name_len (OUT) - base table name length in bytes without NULL terminator. flag (OUT) - DDL LCR flag. Optional, data not returned if NULL. ddl_lcrp (IN) - Streams DDL LCR pointer mode (IN) - mode (for future extention - not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRDDLInfoGet(OCISvcCtx *svchp, OCIError *errhp, oratext **object_type, ub2 *object_type_len, oratext **ddl_text, ub4 *ddl_text_len, oratext **logon_user, ub2 *logon_user_len, oratext **current_schema, ub2 *current_schema_len, oratext **base_table_owner, ub2 *base_table_owner_len, oratext **base_table_name, ub2 *base_table_name_len, oraub8 *flag, void *ddl_lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRAttributesSet - OCI LCR SET ATTRIBUTES DESCRIPTION populates extra attribute information in ROW/DDL LCR, as well as any non first class attributes that can not be set through OCILCRHeaderSet, OCILCRDDLInfoSet, or OCILCRRowColumnInfoSet. e.g. edition name PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle num_attrs (IN) - Number of extra attributes to be populated attr_names (IN) - Pointer to an array of attribute names. Attribute names must be canonicalized and should follow Oracle naming conventions attr_names_lens (IN) - Pointer to an array of attribute name lengths in bytes, excluding the NULL terminator. attr_dtyp (IN) - Pointer to an array of attribute datatypes. attr_valuesp (IN) - Pointer to an array of attribute data values. attr_indp (IN) - Pointer to an indicator array. For all datatypes, this is a pointer to an array of OCIInd values (OCI_IND_NULL/OCI_IND_NOTNULL). attr_alensp (IN) - Pointer to an array of actual attribute lengths in bytes. lcrp (IN/OUT)- Streams (Row/DDL) LCR pointer mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRAttributesSet(OCISvcCtx *svchp, OCIError *errhp, ub2 num_attrs, oratext **attr_names, ub2 *attr_name_lens, ub2 *attr_dtyp, void **attr_valuesp, OCIInd *attr_indp, ub2 *attr_alensp, void *lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRAttributesGet - OCI LCR GET EXTRA ATTRIBUTES DESCRIPTION Gets extra attribute information in (ROW/DDL) LCR, as well as any non first class attributes that are not populated through OCILCRHeaderGet, OCILCRDDLInfoGet, or OCILCRRowColumnInfoGet e.g. edition name PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle num_attrs (OUT) - Number of extra attributes to be populated attr_names (IN/OUT)- Pointer to an array of attribute names. Attribute names must be canonicalized and should follow Oracle naming conventions attr_namesl (IN/OUT)- Pointer to an array of attribute name lengths in bytes, excluding the NULL terminator. attr_dtyp (IN/OUT)- Pointer to an array of attribute datatypes. attr_valuesp (IN/OUT)- Pointer to an array of attribute data values. attr_indp (IN/OUT)- Pointer to an indicator array. For all datatypes, this is a pointer to an array of OCIInd values (OCI_IND_NULL/OCI_IND_NOTNULL). attr_alensp (IN/OUT)- Pointer to an array of actual attribute lengths in bytes. lcrp (IN) - Streams (Row/DDL) LCR pointer array_size (IN) - Size of each of above arrays, use at least the size defined by OCI_LCR_MAX_ATTRIBUTES mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode - If array_size is not large enough to accommodate the number of attributes in the requested attribute list then OCI_ERROR is returned. Parameter num_attrs will return the suggested size. ------------------------------------------------------------------------------= */ sword OCILCRAttributesGet(OCISvcCtx *svchp, OCIError *errhp, ub2 *num_attrs, oratext **attr_names, ub2 *attr_namesl, ub2 *attr_dtyp, void **attr_valuesp, OCIInd *attr_indp, ub2 *attr_alensp, void *lcrp, ub2 array_size, ub4 mode); /*--------------------- OCILCRWhereClauseGet ----------------------------*/ /* NAME OCILCRWhereClauseGet - OCI Get Where Clause DESCRIPTION Gets the Where clause statement for the given ROW LCR. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported wc_stmt (OUT) - Sql Statement equivalent to the LCR has applied wc_stmt_len (IN/OUT) - length of wc_stmt buffer row_lcrp (IN) - row LCR to be converted to SQL mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES - For now, specify OCI_DEFAULT for mode - WHERE clause generated for INSERT lcr will have all the columns that are being inserted. This WHERE clause could be used to identify the inserted row after inserting. (like "returning ROWID"). INSERT INTO TAB(COL1) VALUES (10) -> WHERE COL1=10 - WHERE clause generated for UPDATE will have all the columns in the old column list. However the values of the columns will be that of new value if it exist in the new column list of the UPDATE. If the column doesnt have new value then the old column value will be used. UPDATE TAB SET COL1 = 10 WHERE COL1 = 20 -> WHERE COL1 = 10 UPDATE TAB SET COL2 = 20 WHERE COL1 = 20 -> WHERE COL1 = 20 - WHERE clause for DELETE will use the columns and values from old column lst - LOB piecewise operations would use the new columns and values for generating the WHERE clause. */ sword OCILCRWhereClauseGet( OCISvcCtx *svchp, OCIError *errhp, oratext *wc_stmt, ub4 *wc_stmt_len, void *row_lcrp, ub4 mode); /*--------------------- OCILCRRowStmtGet ----------------------------*/ /* NAME OCILCRRowStmtGet - OCI Get Row Statement DESCRIPTION Gets the SQL statement for the given ROW LCR. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported row_stmt (OUT) - Sql Statement equivalent to the LCR has applied row_stmt_len (IN/OUT) - length of row_stmt buffer row_lcrp (IN) - row LCR to be converted to SQL mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES None */ sword OCILCRRowStmtGet( OCISvcCtx *svchp, OCIError *errhp, oratext *row_stmt, ub4 *row_stmt_len, void *row_lcrp, ub4 mode); /*--------------------- OCILCRWhereClauseWithBindVarGet ----------------------*/ /* NAME OCILCRWhereClauseWithBindVarGet - OCI Get Where clause with binds DESCRIPTION Gets the where clause statement with bind variables for the given ROW LCR. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported wc_stmt (OUT) - Sql Stmt equivalent to the LCR wc_stmt_len (IN/OUT) - length of wc_stmt buffer num_bind_var (OUT) - Number of bind variables bind_var_dtyp (OUT) - Array of Data types of bind variables bind_var_valuesp (OUT) - Array of Values of bind variables bind_var_indp (OUT) - Array of null indicators of bind variables bind_var_alensp (OUT) - Array of lengths of bind values bind_var_csetidp (OUT) - Array of char set id of binds bind_var_csetfp (OUT) - Array of char set form of binds row_lcrp (IN) - row LCR to be converted to SQL array_size (IN) - Size of the array of bind values bind_var_syntax (IN) - Native syntax to be used for binds mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES - For now, specify OCI_DEFAULT for mode - If array_size is not large enough to accommodate the number of columns in the requested column list then OCI_ERROR is returned. Expected array_size is returned through num_bind_var parameter. - bind_var_syntax for oracle should contain ":". This will generate positional binds such as :1, :2, :3 etc. For other non-oracle databases they can give the string that needs to be used for binds. - WHERE clause generated for INSERT lcr will have all the columns that are being inserted. This WHERE clause could be used to identify the inserted row after inserting. (like "returning ROWID"). INSERT INTO TAB(COL1) VALUES (10) -> WHERE COL1=10 - WHERE clause generated for UPDATE will have all the columns in the old column list. However the values of the columns will be that of new column value of the column if it exist in the new values of the UPDATE. If the column appears only in the old column then old column value will be used. UPDATE TAB SET COL1 = 10 WHERE COL1 = 20 -> WHERE COL1 = 10 UPDATE TAB SET COL2 = 20 WHERE COL1 = 20 -> WHERE COL1 = 20 - WHERE clause for DELETE will use the columns and values from old column lst - LOB piecewise operations would use the new columns and values for generating the WHERE clause. */ sword OCILCRWhereClauseWithBindVarGet( OCISvcCtx *svchp, OCIError *errhp, oratext *wc_stmt, ub4 *wc_stmt_len, ub2 *num_bind_var, ub2 *bind_var_dtyp, void **bind_var_valuesp, OCIInd *bind_var_indp, ub2 *bind_var_alensp, ub2 *bind_var_csetidp, ub1 *bind_var_csetfp, void *row_lcrp, ub2 array_size, oratext *bind_var_syntax, ub4 mode); /*--------------------- OCILCRRowStmtWithBindVarGet ----------------------*/ /* NAME OCILCRRowStmtWithBindVarGet - OCI Get Row Statement DESCRIPTION Gets the SQL statement with bind variables for the given ROW LCR. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported row_stmt (OUT) - Sql Stmt equivalent to the LCR row_stmt_len (IN/OUT) - length of row_stmt buffer num_bind_var (OUT) - Number of bind variables bind_var_dtyp (OUT) - Array of Data types of bind variables bind_var_valuesp (OUT) - Array of Values of bind variables bind_var_indp (OUT) - Array of null indicators of bind variables bind_var_alensp (OUT) - Array of lengths od bind values bind_var_csetidp (OUT) - Array of char set id of binds bind_var_csetfp (OUT) - Array of char set form of binds row_lcrp (IN) - row LCR to be converted to SQL chunk_column_names (OUT) - Array of chunked column names in lcr chunk_column_namesl (OUT) - Length of chunk_column_names chunk_column_flags (OUT) - flags of chunked columns in lcr Possible bit values are OCI_LCR_COLUMN_* flags listed above. array_size (IN) - Size of the array of bind values bind_var_syntax (IN) - Native syntax to be used for binds mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES - For now, specify OCI_DEFAULT for mode - If array_size is not large enough to accommodate the number of columns in the requested column list then OCI_ERROR is returned. Expected array_size is returned through num_bind_var parameter. - bind_var_syntax for oracle should contain ":". This will generate positional binds such as :1, :2, :3 etc. For other non-oracle databases they can give the string that needs to be used for binds. */ sword OCILCRRowStmtWithBindVarGet( OCISvcCtx *svchp, OCIError *errhp, oratext *row_stmt, ub4 *row_stmt_len, ub2 *num_bind_var, ub2 *bind_var_dtyp, void **bind_var_valuesp, OCIInd *bind_var_indp, ub2 *bind_var_alensp, ub2 *bind_var_csetidp, ub1 *bind_var_csetfp, void *row_lcrp, oratext **chunk_column_names, ub2 *chunk_column_namesl, oraub8 *chunk_column_flags, ub2 array_size, oratext *bind_var_syntax, ub4 mode); /* ------------------------------------------------------------------------------- NAME OCILCRSCNsFromPosition - Get SCNs From Position DESCRIPTION Returns the SCN and commit SCN from the given position. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle position (IN) - LCR position position_len (IN) - length of position scn (OUT) - the SCN stored in position commit_scn (OUT) - the commit SCN stored in position mode (IN) - Mode flags (For future extension. Not used currently) RETURN OCI_SUCCESS if the conversion succeeds, OCI_ERROR otherwise. NOTE The user must allocate memory for the return numbers. The input position must conform to the format generated by an XStream server. ------------------------------------------------------------------------------- */ sword OCILCRSCNsFromPosition(OCISvcCtx *svchp, OCIError *errhp, ub1 *position, ub2 position_len, OCINumber *scn, OCINumber *commit_scn, ub4 mode); /* ------------------------------------------------------------------------------- NAME OCILCRSCNToPosition - Converts SCN To Position DESCRIPTION Converts an SCN to a position. The generated position can be passed as the last_position to OCIXStreamOutAttach function to filter the LCRs with commit SCN less than the given SCN and the LCR's SCN less than the given SCN. This means the first LCR sent by the Outbound server is either - a commit LCR at the given SCN, or - the first LCR of the subsequent transaction with commit SCN greater than or equal to the given SCN. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle position (OUT) - Result position. Must pre-allocate OCI_LCR_MAX_POSITION_LEN bytes. position_len (OUT) - Length of position scn (IN) - The SCN to be stored in position mode (IN) - Mode flags (for future extension) RETURN OCI_SUCCESS if the conversion succeeds, OCI_ERROR otherwise. ------------------------------------------------------------------------------- */ sword OCILCRSCNToPosition(OCISvcCtx *svchp, OCIError *errhp, ub1 *position, ub2 *position_len, OCINumber *scn, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRLobInfoGet - OCI LCR GET LOB INFO DESCRIPTION Returns the LOB information for a given piece-wise LOB LCR. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle column_name (OUT) - Pointer to the LOB column name. Optional. If specified then column_name_len must be specified as well. column_name_len(OUT) - Length of LOB column name without the NULL terminator. column_dty (OUT) - LOB column dty - either SQLT_CHR (for CLOB) or SQLT_BIN (for BLOB). column_flag (OUT) - LOB column flag. Possible bit values are OCI_LCR_COLUMN_* flags listed above. offset (OUT) - LOB operation offset in code points. Returned only for LOB_TRIM and LOB_WRITE operations; otherwise, a zero is returned. This is the same as the 'soffset' parameter for OCILobErase or the 'offset' parameter in OCILobWrite functions. size (OUT) - LOB operation size in code points. Returned only for LOB_TRIM and LOB_ERASE operations; otherwise, a zero is returned. This is the same as the 'new_length' parameter in OCILobTrim or the 'amtp' parameter in OCILobErase functions. row_lcrp (IN) - Streams Row LCR pointer mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRLobInfoGet(OCISvcCtx *svchp, OCIError *errhp, oratext **column_name, ub2 *column_name_len, ub2 *column_dty, oraub8 *column_flag, ub4 *offset, ub4 *size, void *row_lcrp, ub4 mode); /* ------------------------------------------------------------------------------= NAME OCILCRLobInfoSet - OCI LCR SET LOB INFO DESCRIPTION Sets the LOB information for a given piece-wise LOB LCR. PARAMETERS svchp (IN) - OCI service context errhp (IN) - OCI Error Handle column_name (IN) - Pointer to the LOB column name. column_name_len(IN) - Length of LOB column name without the NULL terminator. column_dty (IN) - LOB column dty - either SQLT_CHR (for CLOB) or SQLT_BIN (for BLOB). column_flag (IN) - LOB column flag. Possible bit values are OCI_LCR_COLUMN_* flags listed above. offset (IN) - LOB operation offset in code points. Returned only for LOB_TRIM and LOB_WRITE operations; otherwise, a zero is returned. This is the same as the 'soffset' parameter for OCILobErase or the 'offset' parameter in OCILobWrite functions. size (IN) - LOB operation size in code points. Returned only for LOB_TRIM and LOB_ERASE operations; otherwise, a zero is returned. This is the same as the 'new_length' parameter in OCILobTrim or the 'amtp' parameter in OCILobErase functions. row_lcrp (IN/OUT)- Streams Row LCR pointer mode (IN) - mode NOTES - For now, specify OCI_DEFAULT for mode ------------------------------------------------------------------------------= */ sword OCILCRLobInfoSet(OCISvcCtx *svchp, OCIError *errhp, oratext *column_name, ub2 column_name_len, ub2 column_dty, oraub8 column_flag, ub4 offset, ub4 size, void *row_lcrp, ub4 mode); /*--------------------------------------------------------------------------- STREAMS XSTREAM OUT FUNCTIONS ---------------------------------------------------------------------------*/ /*------------------------- OCIXStreamOutAttach -----------------------------*/ /* NAME OCIXStreamOutAttach - OCI Attach to XStreams Out DESCRIPTION Given the name of the server process, attach to the outbound server. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle for error reporting server_name (IN) - Server name. server_name_len (IN) - Length of server name. last_position (IN) - last rcv position. (Optional) last_position_len (IN) - Length of last_position. mode (IN) - Mode flags (future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES Specify OCI_DEFAULT for the mode parameter. The name of the outbound server must be provided because multiple outbound servers can be configured in one Oracle instance. This call returns OCI_ERROR if it encounters any error while attaching to the outbound server. The last_position parameter is used to establish the starting point of the stream. This call returns OCI_ERROR if the specified position is non-null and less than the server's processed low-watermark; otherwise, LCRs with position greater than last_position will be sent to the user. If last_position is null then the stream will start from the processed low-watermark maintained in the server. */ sword OCIXStreamOutAttach (OCISvcCtx *svchp, OCIError *errhp, oratext *server_name, ub2 server_name_len, ub1 *last_position, ub2 last_position_len, ub4 mode); #define OCIXSTREAM_OUT_ATTACH_RESERVED_1 (0x00000001) /*---------------------- OCIXStreamOutProcessedLWMSet ----------------------*/ /* NAME OCIXStreamOutProcessedLWMSet - Set Processed Low-Watermark DESCRIPTION Sets the processed low-watermark maintained at the client. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle for error reporting processed_low_position (IN) - processed low position. processed_low_position_len (IN) - processed low position length. mode (IN) - mode for future extension. (Not used currently). RETURNS OCI_SUCCESS or OCI_ERROR. NOTES The processed low-watermark denotes all LCRs at or below this position have been processed. After successfully attaching to an XStream outbound server, a local copy of the processed low-watermark is maintained at the client. Periodically, this watermark is sent to the server so that archived logs containing already processed transactions can be purged. The following API is used to update the local copy of the processed low-watermark. It can be called anytime between OCIXStreamOutAttach and OCIXStreamOutDetach calls. Clients, using the callback mechanism to stream LCRs from the server, can invoke this API while in the callback functions. */ sword OCIXStreamOutProcessedLWMSet (OCISvcCtx *svchp, OCIError *errhp, ub1 *processed_low_position, ub2 processed_low_position_len, ub4 mode); /*-------------------- OCICallbackXStreamOutLCRProcess ----------------------*/ /* NAME OCICallbackXStreamOutLCRProcess - Callback to process each LCR received DESCRIPTION This callback is invoked during OCIXStreamOutLCRCallbackReceive to process each LCR received from the outbound server. PARAMETERS usrctxp (IN/OUT) - Ptr to the user context. lcrp (IN) - Pointer to the LCR just received. lcrtyp (IN) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL) flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set, this means the current LCR has more chunk data. RETURNS This callback function must return OCI_CONTINUE to continue processing OCIXStreamOutLCRCallbackReceive call. Any return code other than OCI_CONTINUE signals that the client wants to terminate OCIXStreamOutLCRCallbackReceive immediately. */ typedef sb4 (*OCICallbackXStreamOutLCRProcess) (void *usrctxp, void *lcrp, ub1 lcrtyp, oraub8 flag); /*-------------------- OCICallbackXStreamOutChunkProcess --------------------*/ /* NAME OCICallbackXStreamOutChunkProcess - Callback to process each chunk DESCRIPTION This callback is invoked during OCIXStreamOutLCRCallbackReceive to process each chunk in an LCR. PARAMETERS usrctxp (IN/OUT) - Ptr to the user context. column_name (IN) - Column name for the current chunk. column_name_len (IN) - Length of column name. column_dty (IN) - Chunk data type (SQLT_CHR or SQLT_BIN). column_flag (IN) - LCR column flags. Possible bit values are OCI_LCR_COLUMN_* flags listed above. column_csid (IN) - Column character set id. Relevant only if the column is an XMLType column (i.e., column_flag has OCI_LCR_COLUMN_XML_DATA bit set). chunk_bytes (IN) - Chunk data length in bytes. chunk_data (IN) - Chunk data buffer. flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set, this means the current LCR has more chunks. RETURNS This callback function must return OCI_CONTINUE to continue processing OCIXStreamOutLCRCallbackReceive call. Any return code other than OCI_CONTINUE signals that the client wants to terminate OCIXStreamOutLCRCallbackReceive immediately. */ typedef sb4 (*OCICallbackXStreamOutChunkProcess) (void *usrctxp, oratext *column_name, ub2 column_name_len, ub2 column_dty, oraub8 column_flag, ub2 column_csid, ub4 chunk_bytes, ub1 *chunk_data, oraub8 flag); /*-------------------- OCIXStreamOutLCRCallbackReceive ----------------------*/ /* NAME OCIXStreamOutLCRCallbackReceive - OCI Receive LCR stream using Callbacks DESCRIPTION This API is used to get the LCR stream from the outbound server using callbacks to gain better performance. The user must supply a callback function to be invoked for each LCR received. If some row changes in the stream may contain LOB/LONG/XMLType columns then the data for those columns are returned to the user in chunks. To receive those row changes, the user must provide a second callback to be invoked to process each chunk data. If there is an LCR available in the stream, the processlcr_cb function is invoked immediately. After the processlcr_cb function exits, if the current LCR contains additional chunks then the processchunk_cb function is invoked for each chunk belonging to that LCR. If there is no LCR in the stream when the idle timeout expires (see OCI_ATTR_XSTREAM_IDLE_TIMEOUT), this call returns a null LCR with OCI_SUCCESS code. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle for error reporting processlcr_cb (IN) - Client callback function for each LCR. processchunk_cb (IN) - Client callback function for each chunk. usrctxp (IN) - Client context. (Optional) fetch_low_position (OUT)- Fetch low watermark. (Optional) fetch_low_position_len (OUT)- Fetch low watermark length. mode (IN) - mode for future extension. (Not used currently). RETURNS OCI_SUCCESS or OCI_ERROR. NOTES - The fetch low watermark is used to indicate all transactions with commit position below this have been received by the XStream outbound server. - If the LCR contains non-chunked column(s), the duration of that LCR is limited to the processlcr_cb function. If the LCR contains some chunk data then the duration of the LCR is extended until all the chunks have been processed (that is, when the flag passing to processchunk_cb function does not have OCI_XSTREAM_MORE_ROW_DATA flag set). If the user wants to access the LCR data at a later time, a copy of the LCR must be made. The client callback should not modify or free the LCR passing to the callback. - The given usrctxp is passed to both callbacks. - An ACK interval is the interval in seconds which the outbound server receives the processed LWM or the inbound server sends the processed LWM. The default ACK interval is 30 seconds. This value can be changed by setting the OCI_ATTR_XSTREAM_ACK_INTERVAL attribute using OCIAttrSet API. This attribute is checked only during the Attach call; thus, it must be set before invoking this API. - The idle timeout is the interval in seconds after which the current call will terminate if there is no LCR in the stream. The default idle timeout is one second. This value can be changed by setting the OCI_ATTR_XSTREAM_IDLE_TIMEOUT attribute using OCIAttrSet API. This attribute is checked only during the Attach call; thus, it must be set before invoking this API. - The outbound server ends each call at the transaction boundary after an ACK interval has elapsed from the start of the call or when the idle timeout expires. This API returns the fetch low watermark at the end of each call. */ sword OCIXStreamOutLCRCallbackReceive( OCISvcCtx *svchp, OCIError *errhp, OCICallbackXStreamOutLCRProcess processlcr_cb, OCICallbackXStreamOutChunkProcess processchunk_cb, void *usrctxp, ub1 *fetch_low_position, ub2 *fetch_low_position_len, ub4 mode); /*---------------------- OCIXStreamOutLCRReceive -------------------------*/ /* NAME OCIXStreamOutLCRReceive - Receive LCR without using callback DESCRIPTION This API is used to receive an LCR from an outbound stream. If there is an LCR available, this API immediately returns that LCR. The duration of each LCR is limited to the processlcr_cb function. When there is no LCR available in the stream, this call returns a null LCR after the idle timeout (see OCI_ATTR_XSTREAM_IDLE_TIMEOUT) has expired. To avoid network round trip for every OCIXStreamOutLCRReceive call, the connection is tied to this call to let the server fill up the network buffer with LCRs so subsequent calls can quickly receive the LCRs from the network. The server ends each call at the transaction boundary after an ACK interval has elapsed since the start of the call or when the idle timeout expires. See OCI_ATTR_XSTREAM_ACK_INTERVAL & OCI_ATTR_XSTREAM_IDLE_TIMEOUT attributes. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle for error reporting lcrp (OUT) - Pointer to the LCR received from the stream. lcrtype (OUT) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL) flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set, it means the current LCR has more chunk data. fetch_low_position (OUT)- Fetch low watermark. (Optional) fetch_low_position_len (OUT)- Fetch low watermark length. mode (IN) - mode for future extension. (Not used currently). RETURNS - OCI_STILL_EXECUTING means the current call is still in progress. The connection associated with the specified service context handle is still tied to this call for streaming the LCRs from the server. An error is returned if the user attempts to use the same connection to execute any OCI calls that require database round trip, for example, OCIStmtExecute, OCIStmtFetch, OCILobRead, etc. OCILcr* calls are local calls; thus, they are valid while the stream is in progress. - OCI_SUCCESS means the current call is completed. User is free to execute OCIStmt*, OCILob*, etc. from the same service context. - OCI_ERROR means the current call encounters some errors. Use OCIErrorGet to obtain information about the error. NOTES This call always returns a null LCR when the return code is OCI_SUCCESS. In addition, it returns the fetch low position to denote the outbound server has received all transactions with commit position lower than or equal to this value. */ sword OCIXStreamOutLCRReceive( OCISvcCtx *svchp, OCIError *errhp, void **lcrp, ub1 *lcrtype, oraub8 *flag, ub1 *fetch_low_position, ub2 *fetch_low_position_len, ub4 mode); /*-------------------------- OCIXStreamOutChunkReceive ---------------------*/ /* NAME OCIXStreamOutChunkReceive - Receive Chunk data DESCRIPTION Receives next chunk of LCR data from XStream Outbound server. This API can only be called while OCIXStreamOutLCRReceive call is in progress. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported column_name (OUT) - Name of column for which data is retrieved. column_name_len (OUT) - Length of column name. column_dty (OUT) - LCR column data type. column_flag (OUT) - LCR column flag. Possible bit values are OCI_LCR_COLUMN_LOB_DATA OCI_LCR_COLUMN_LONG_DATA OCI_LCR_COLUMN_EMPTY_LOB OCI_LCR_COLUMN_LAST_CHUNK OCI_LCR_COLUMN_AL16UTF16 OCI_LCR_COLUMN_ENCRYPTED OCI_LCR_COLUMN_NCLOB OCI_LCR_COLUMN_XML_DATA OCI_LCR_COLUMN_XML_DIFF column_csid (OUT) - Column character set id. This is returned only if the column is an XMLType column (i.e., column_flag has OCI_LCR_COLUMN_XML_DATA bit set). chunk_bytes (OUT) - Number of bytes in output buffer. chunk_data (OUT) - Pointer to the chunk data in the LCR. Client must not de-allocate this pointer. flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set, it means the current LCR has more data coming. mode (IN) - mode for future extension. (Not used currently). RETURNS OCI_SUCCESS - Check colname_len and chunk_bytes to determine the data just read. OCI_ERROR - Error encountered. Execute OCIErrorGet to get information about the error. NOTES - If the return code is OCI_SUCCESS, client should check chunk_bytes to determine the # of bytes read and check column_name to determine which LCR column the data associated with. - All the chunks from one LOB/LONG/XMLType column are returned entirely before the chunk value for the next LOB/LONG/XMLType column is returned. - The is no fixed ordering on how the LOB/LONG/XMLType columns is returned. Users must check the column name to determine which column. The column_flag will have OCI_LCR_COLUMN_LAST_CHUNK bit set when this function returns the last chunk of each column. - This call returns a null column name and null chunk data if it's invoked when the current LCR contains only non-chunked columns. - If OCIXStreamOutLCRReceive call returns OCI_XSTREAM_MORE_ROW_DATA flag then the user must iteratively call OCIXStreamOutChunkReceive to retrieve all the chunks belonging to the current row change before calling the next OCIXStreamOutLCRReceive. */ sword OCIXStreamOutChunkReceive(OCISvcCtx *svchp, OCIError *errhp, oratext **column_name, ub2 *column_name_len, ub2 *column_dty, oraub8 *column_flag, ub2 *column_csid, ub4 *chunk_bytes, ub1 **chunk_data, oraub8 *flag, ub4 mode); /*------------------------- OCIXStreamOutDetach -----------------------------*/ /* NAME OCIXStreamOutDetach - OCI Detach from XStream Out DESCRIPTION Detaches from the attached XStream outbound server. This call sends the current local processed low-watermark to the server before detaching from the outbound server. The outbound server automatically restarts after this call. This API returns OCI_ERROR if it is invoked while a ReceiveLCR call is in progress. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported mode (IN) - mode for future extension. (Not used currently). RETURNS OCI_SUCCESS or OCI_ERROR. NOTES - The processed_low_position is passed to the server so it can update its copy. This value if provided must be greater than or equal to the value maintained in the server; otherwise, an error is returned. */ sword OCIXStreamOutDetach (OCISvcCtx *svchp, OCIError *errhp, ub4 mode); /*--------------------------------------------------------------------------- STREAMS XSTREAM IN FUNCTIONS ---------------------------------------------------------------------------*/ /*------------------------ OCIXStreamInAttach -------------------------------*/ /* NAME OCIXStreamInAttach - OCI XStream In Attach DESCRIPTION Attaches to the specified XStream inbound server. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported server_name (IN) - XStream inbound server name. server_name_len (IN) - Length of server name. source_name (IN) - source name to identify the data src. source_name_len (IN) - Length of source name. last_position (OUT) - Last position received by inbound server. Optional. If specified must pre-allocate OCI_LCR_MAX_POSITION_LEN bytes for return value. last_position_len (OUT) - Length of last_position. Must be non-NULL if last_position is non-NULL. mode (IN) - Mode flags (For future extension. (Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES The last_position parameter is returned to establish the starting point to resume the inbound stream. The client should start sending LCRs with positions greater than the last_position since the inbound server will ignore all LCRs with positions less than or equal to this value. */ sword OCIXStreamInAttach( OCISvcCtx *svchp, OCIError *errhp, oratext *server_name, ub2 server_name_len, oratext *source_name, ub2 source_name_len, ub1 *last_position, ub2 *last_position_len, ub4 mode); /*-------------------- OCICallbackXStreamInLCRCreate ------------------------*/ /* NAME OCICallbackXStreamInLCRCreate - Callback to create an LCR DESCRIPTION This callback is invoked during OCIXStreamInLCRCallbackSend to create each LCR to be sent to the inbound server. PARAMETERS usrctxp (IN/OUT) - Ptr to the user context lcrp (OUT) - Pointer to the LCR to be sent lcrtyp (OUT) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL) flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set, this means the current LCR has more chunk data. RETURNS This callback function must return OCI_CONTINUE to continue processing OCIXStreamInLCRCallbackSend call. Any return code other than OCI_CONTINUE signals that the client wants to terminate OCIXStreamInLCRCallbackSend immediately. */ typedef sb4 (*OCICallbackXStreamInLCRCreate)( void *usrctxp, void **lcrp, ub1 *lcrtyp, oraub8 *flag); /*-------------------- OCICallbackXStreamInChunkCreate --------------------*/ /* NAME OCICallbackXStreamInChunkCreate - Callback to create each chunk DESCRIPTION This callback is invoked during OCIXStreamInLCRCallbackSend to create each chunk to be sent to the inbound server. PARAMETERS usrctxp (IN/OUT) - Ptr to the user context. column_name (OUT) - Column name for the current chunk. column_name_len (OUT) - Length of column name. column_dty (OUT) - Chunk data type (SQLT_CHR or SQLT_BIN). column_flag (OUT) - LCR column flags. Possible bit values are OCI_LCR_COLUMN_* flags listed above. column_csid (OUT) - Column character set id. Relevant only if the column is an XMLType column (i.e., column_flag has OCI_LCR_COLUMN_XML_DATA bit set). chunk_bytes (OUT) - Chunk data length in bytes. chunk_data (OUT) - Chunk data buffer. flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set, this means the current LCR has more chunks. RETURNS This callback function must return OCI_CONTINUE to continue processing OCIXStreamInLCRCallbackSend call. Any return code other than OCI_CONTINUE signals that the client wants to terminate OCIXStreamInLCRCallbackSend immediately. */ typedef sb4 (*OCICallbackXStreamInChunkCreate)( void *usrctxp, oratext **column_name, ub2 *column_name_len, ub2 *column_dty, oraub8 *column_flag, ub2 *column_csid, ub4 *chunk_bytes, ub1 **chunk_data, oraub8 *flag); /*--------------------- OCIXStreamInLCRCallbackSend ------------------------*/ /* NAME OCIXStreamInLCRCallbackSend - OCI XStream In Send LCR to Inbound Server DESCRIPTION Sends LCR stream to XStream inbound server using callbacks. The API invokes createlcr_cb function to obtain each LCR to send to the server. If the return flag from the createlcr_cb function has OCI_XSTREAM_MORE_ROW_DATA bit set, then it invokes createchunk_cb procedure to obtain each chunk. It repeatedly calls createchunk_cb function while the flag returned from this callback has OCI_XSTREAM_MORE_ROW_DATA bit set. When this bit is not set, this API cycles back to invoke createlcr_cb function to get the next LCR. This cycle is repeated until the createlcr_cb function returns a null LCR or when an ACK interval has elapsed since the start of the call. See OCI_ATTR_XSTREAM_ACK_INTERVAL attribute. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported createlcr_cb (IN) - Callback function to be invoked to generate an LCR for streaming. Cannot be null. createchunk_cb (IN) - Callback function to be invoked to create each chunk. Can be null if the user does not need to send any LCR with LOB/LONG/XMLType columns. OCI_ERROR will be returned if this argument is null and the user attempts to send an LCR with additional chunk data. usrctxp (IN) - Client context to pass to both callback functions. mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES None */ sword OCIXStreamInLCRCallbackSend( OCISvcCtx *svchp, OCIError *errhp, OCICallbackXStreamInLCRCreate createlcr_cb, OCICallbackXStreamInChunkCreate createchunk_cb, void *userctxp, ub4 mode); /*---------------------------- OCIXStreamInLCRSend --------------------------*/ /* NAME OCIXStreamInLCRSend - OCI XStream In Send LCR to Inbound Server DESCRIPTION Sends LCR stream to XStream inbound server without using callbacks. To avoid a network round trip for every OCIXStreamInLCRSend call, the connection is tied to this call for at least the duration specified by the OCI_ATTR_XSTREAM_ACK_INTERVAL attribute. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported lcrp (IN) - Pointer to the LCR to send. Cannot be null. lcrtype (IN) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL) flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set, it means the current LCR has more chunk data. mode (IN) - Mode flags (For future extension. Not used currently) RETURNS - OCI_STILL_EXECUTING means the current call is still in progress. The connection associated with the specified service context handle is still tied to this call for streaming the LCRs to the server. An error is returned if the user attempts to use the same connection to execute any OCI calls that require database round trip, for example, OCIStmtExecute, OCIStmtFetch, OCILobRead, etc. OCILcr* calls are local calls; thus, they are valid while this call is in progress. - OCI_SUCCESS means the current call is completed. User is free to execute OCIStmt*, OCILob*, etc. from the same service context. - OCI_ERROR means this call encounters some errors. Use OCIErrorGet to obtain information about the error. */ sword OCIXStreamInLCRSend( OCISvcCtx *svchp, OCIError *errhp, void *lcrp, ub1 lcrtype, oraub8 flag, ub4 mode); /*----------------------------- OCIXStreamInChunkSend -----------------------*/ /* NAME OCIXStreamInChunkSend - Send Chunk DESCRIPTION Sends the given chunk of column data to XStream Inbound server. This chunk is associated with the LCR that is sent by the most recent OCIXStreamInLCRSend call prior to this call. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported column_name (IN) - Name of column for which data is sent. Column names must be canonicalized and must follow Oracle naming conventions. column_name_len (IN) - Length of column name. column_dty (IN) - LCR column data type (must be SQLT_CHR or SQLT_BIN). column_flag (IN) - LCR column flags. Possible bit values are OCI_LCR_COLUMN_LOB_DATA OCI_LCR_COLUMN_LONG_DATA OCI_LCR_COLUMN_EMPTY_LOB OCI_LCR_COLUMN_LAST_CHUNK OCI_LCR_COLUMN_AL16UTF16 OCI_LCR_COLUMN_ENCRYPTED OCI_LCR_COLUMN_NCLOB OCI_LCR_COLUMN_XML_DATA OCI_LCR_COLUMN_XML_DIFF column_csid (IN) - Column character set id. This is required only if the column is an XMLType column (i.e., column_flag has OCI_LCR_COLUMN_XML_DATA bit set). chunk_bytes (IN) - Chunk data length in bytes. chunk_data (IN) - Chunk data buffer. flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set, it means the current LCR has more data coming. mode (IN) - mode for future extension. (Not used currently). RETURNS OCI_SUCCESS - Successful call. OCI_ERROR - Error encountered. Execute OCIErrorGet to get information about the error. NOTES - This function must be called while OCIXStreamInLCRSend is in progress. - This function is valid only if the associated LCR's cmd type is INSERT, UPDATE or LOB_WRITE. It can be invoked multiple times for the same LCR. - This API is not valid for LOB_ERASE and LOB_TRIM LCRs. - The chunk values for different columns can not be interleaved. If a column contains multiple chunks, this procedure must be called consecutively using the same column name before proceeding to a new column. The ordering in which the LOB/LONG/XMLType column values are set is irrelevant. - The OCI_LCR_COLUMN_LAST_CHUNK must be specified for the last chunk of each column. - Only one column can be specified for LOB_WRITE operation. - For NCLOB or varying width CLOB, the input buffer must be in AL16UTF16 format. - For INSERT operation, each LOB/LONG/XMLType column, with value set using OCIXStreamInChunkSend, must be included in the current LCR's NEW column list. The value of that LOB/LONG/XMLType column must be set to null and must have OCI_LCR_COLUMN_EMPTY_LOB flag defined. */ sword OCIXStreamInChunkSend (OCISvcCtx *svchp, OCIError *errhp, oratext *column_name, ub2 column_name_len, ub2 column_dty, oraub8 column_flag, ub2 column_csid, ub4 chunk_bytes, ub1 *chunk_data, oraub8 flag, ub4 mode); /*--------------------- OCIXStreamInDetach ----------------------------*/ /* NAME OCIXStreamInDetach - OCI XStream In Detach from Inbound Server DESCRIPTION Detaches from XStream inbound server and returns the inbound server's processed low-watermark. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported processed_low_position (OUT) - Inbound server's processed low position. Must pre-allocate OCI_LCR_MAX_POSITION_LEN bytes for output buffer. processed_low_position_len(OUT)- Processed_low_position length. mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES None */ sword OCIXStreamInDetach( OCISvcCtx *svchp, OCIError *errhp, ub1 *processed_low_position, ub2 *processed_low_position_len, ub4 mode); /*--------------------- OCIXStreamInProcessedLWMGet -------------------------*/ /* NAME OCIXStreamInProcessedLWMGet - OCI XStream In Get LowWatermark DESCRIPTION Returns XStream inbound server's processed low watermark cached at the client. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported processed_low_position (OUT) - Inbound server's cached processed low position. Must pre- allocate OCI_LCR_MAX_POSITION_LEN bytes for output buffer. processed_low_position_len (OUT) - Processed_low_position length. mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES None */ sword OCIXStreamInProcessedLWMGet( OCISvcCtx *svchp, OCIError *errhp, ub1 *processed_low_position, ub2 *processed_low_position_len, ub4 mode); /*-------------------------- OCIXStreamInFlush ------------------------------*/ /* NAME OCIXStreamInFlush - OCI XStream In Flush network DESCRIPTION Flushes network and terminates any in-progress OCIXStreamInLCRSend or OCIXStreamInLCRCallbackSend call associated with the given service handle. PARAMETERS svchp (IN/OUT) - OCI service handle errhp (IN/OUT) - Error Handle to which errors should be reported mode (IN) - Mode flags (For future extension. Not used currently) RETURNS OCI_SUCCESS or OCI_ERROR. NOTES Each call will incur a database round trip to get the server's processed low-watermark, which the user can retrieve afterward using OCIXStreamInProcessedLWMGet API. This API should be called only when there is no LCR to send to the server and the client wants to know the progress of the attached inbound server. This call returns OCI_ERROR if it is invoked from the callback functions of OCIXStreamInLCRCallbackSend API. Client must have attached to an XStream inbound server prior to calling this API. */ sword OCIXStreamInFlush( OCISvcCtx *svchp, OCIError *errhp, ub4 mode); /*--------------------------------------------------------------------------- INTERNAL FUNCTIONS ---------------------------------------------------------------------------*/ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* OCIXSTREAM_ORACLE */