Blame - sdk/include/ocixstream.h - common/oracle_instantclient

Tang Cheng

31b9525

2014-10-23 09:22:35 +0800

[diff] [blame^]

/*

NAME

ocixstream.h - OCI X-Stream APIs

7

8

DESCRIPTION

9

OCI APIs for X-Stream

RELATED DOCUMENTS

EXPORT FUNCTION(S)

INTERNAL FUNCTION(S)

EXAMPLES

NOTES

MODIFIED (MM/DD/YY)

elu 06/06/11 - Backport elu_bug-12592488 from main

23

bpwang 04/14/11 - Backport bpwang_bug-11815316 from main

24

elu 04/12/11 - xmlschema

25

elu 03/28/11 - xmlschema

26

tianli 03/21/11 - Backport tianli_bug-11875662 from main

27

elu 05/25/11 - remove xml schema

28

thoang 03/10/10 - Add OCIXSTREAM_IN_ATTACH_RESTART_INBOUND mode

29

thoang 12/28/09 - Update comments

30

elu 01/07/10 - stmt lcr

31

thoang 12/15/09 - Remove non-oracle src mode

32

thoang 12/09/09 - Add note to OCIXStreamInErrorGet

33

thoang 12/04/09 - Remove ProcessedLWMGet2/Set2

34

rmao 11/20/09 - add OCI_ROWLCR_SEQ_LCR

35

thoang 10/20/09 - Add rollback and start_tx cmd.

36

bpwang 10/09/09 - Add OCI_ROWLCR_HAS_ID_KEY_ONLY

37

elu 10/05/09 - add stmt LCR

38

rihuang 10/06/09 - Add OCIXSTREAM_IN_FLUSH_WAIT_FOR_COMPLETE

39

thoang 05/08/09 - Add OCILCR_NEW_ONLY_MODE

40

praghuna 05/11/09 - removed 'TODO' comments

41

thoang 02/15/09 - Change lob_column_* to chunk_column_*

42

thoang 01/27/09 - 8216105 - add OLD/NEW column parms to OCILCRHeaderGet

43

rihuang 01/05/09 - Add OCI_LCR_ATTR_TRACKING_LABEL

44

tianli 11/28/08 - add DDL flags

45

tianli 11/20/08 - add OCILCRAttribute methods

46

thoang 11/20/08 - Define OCI_LCR_MAX_TXID_LEN

47

tianli 11/07/08 - add edition

48

thoang 11/10/08 - change return type to sword for consistency

49

thoang 10/16/08 - remove commit position arg

50

tianli 08/26/08 - rename client_name in XStreamIn attach call

51

thoang 06/30/08 - Support XStream APIs using two callbacks.

52

praghuna 05/14/08 - charset id is ub2, OCILcrGetRowStmtWithBindVar

53

thoang 06/02/08 - Define reserved attach mode for internal clients

54

elu 05/08/08 - add pos functions

55

thoang 04/29/08 - API changes

56

jinwu 04/28/08 - add OCILcrGetExtraAttributes

57

elu 04/14/08 - add OCI_LCR_MAX_POSITION_LEN

58

juyuan 03/27/08 - add flag for Set/GetHeader and Set/GetColumnInfo

59

thoang 02/25/08 - Add GetNextChunk and SetNextChunk

60

rihuang 03/24/08 - Signature change for OCILcrNew

61

elu 03/05/08 - add lcr id

62

praghuna 02/26/08 - Added OCILcrGetRowStmt

63

thoang 01/25/08 - Add wm_time parameter to XApply APIs

64

thoang 12/28/07 - Add mode parameter to XApplyDetach

65

thoang 11/07/07 - Change extapp apis to return ub1[] watermark

66

juyuan 05/23/07 - XStream In

67

thoang 11/13/06 - Add XStream Out methods

68

thoang 11/13/06 - Add LCR getter methods

69

nshodhan 05/12/06 - streams OCI APIs

70

nshodhan 05/12/06 - Creation

*/

#ifndef OCIXSTREAM_ORACLE

75

# define OCIXSTREAM_ORACLE

76

77

#ifndef ORATYPES

78

# include <oratypes.h>

#endif

#ifndef OCI_ORACLE

# include <oci.h>

#endif

#ifdef __cplusplus

extern "C" {

#endif

/*---------------------------------------------------------------------------

90

PUBLIC TYPES AND CONSTANTS

91

---------------------------------------------------------------------------*/

92

/* LCR Types -- must match with values defined in kngo.h */

93

#define OCI_LCR_XROW (3) /* External Row LCR */

94

#define OCI_LCR_XDDL (4) /* External DDL LCR */

95

96

/* DML Command Types -- must match with values defined in kngl.h */

97

#define OCI_LCR_ROW_CMD_INSERT "INSERT"

98

#define OCI_LCR_ROW_CMD_DELETE "DELETE"

99

#define OCI_LCR_ROW_CMD_UPDATE "UPDATE"

100

#define OCI_LCR_ROW_CMD_COMMIT "COMMIT"

101

#define OCI_LCR_ROW_CMD_LOB_WRITE "LOB WRITE"

102

#define OCI_LCR_ROW_CMD_LOB_TRIM "LOB TRIM"

103

#define OCI_LCR_ROW_CMD_LOB_ERASE "LOB ERASE"

104

#define OCI_LCR_ROW_CMD_ROLLBACK "ROLLBACK"

105

#define OCI_LCR_ROW_CMD_START_TX "START_TX" /* start transaction */

106

#define OCI_LCR_ROW_CMD_CTRL_INFO "CONTROL INFO" /* contorl lcr */

107

108

/* LCR Extra Attribute Name -- must match with values defined in knll.h */

109

#define OCI_LCR_ATTR_THREAD_NO "THREAD#"

110

#define OCI_LCR_ATTR_ROW_ID "ROW_ID"

111

#define OCI_LCR_ATTR_SESSION_NO "SESSION#"

112

#define OCI_LCR_ATTR_SERIAL_NO "SERIAL#"

113

#define OCI_LCR_ATTR_USERNAME "USERNAME"

114

#define OCI_LCR_ATTR_TX_NAME "TX_NAME"

115

116

/* below are non first class LCR field specific */

117

#define OCI_LCR_ATTR_EDITION_NAME "EDITION_NAME"

118

#define OCI_LCR_ATTR_MESSAGE_TRACKING_LABEL "MESSAGE_TRACKING_LABEL"

119

#define OCI_LCR_ATTR_CURRENT_USER "CURRENT_USER"

120

121

/* the maximum total number of attributes, total of extra attributes

122

* plus non first class LCR field.

123

* NOTE: This MUST be consistent with DefaultRowLCRCache.MaxAttritubeNumber

124

* in DefaultRowLCRCache.java

125

*/

126

#define OCI_LCR_MAX_ATTRIBUTES 9

127

128

/* Row LCR column value types used in OCILCRRowColumnInfoGet/Set functions. */

129

#define OCI_LCR_ROW_COLVAL_OLD 0 /* OLD columns */

130

#define OCI_LCR_ROW_COLVAL_NEW 1 /* NEW columns */

131

132

/* maximum length for position

133

* NOTE: This MUST be consistent with DefaultRowLCRCache.MaxLowWaterMarkLength

134

* in DefaultRowLCRCache.java

135

*/

136

#define OCI_LCR_MAX_POSITION_LEN 64

137

138

/* maximum length for txid */

139

#define OCI_LCR_MAX_TXID_LEN 128

140

141

/* Valid column flags used in OCILCRRowColumnInfoSet, OCILCRRowColumnInfoGet,

142

* OCILCRLobInfoSet, OCILCRLobInfoGet, OCIXStreamOutChunkReceive,

143

* OCIXStreamInChunkSend calls.

144

*/

145

#define OCI_LCR_COLUMN_LOB_DATA (0x00000001) /* col contains lob data */

146

#define OCI_LCR_COLUMN_LONG_DATA (0x00000002) /* col contains long data*/

147

#define OCI_LCR_COLUMN_EMPTY_LOB (0x00000004) /* col has an empty lob */

148

#define OCI_LCR_COLUMN_LAST_CHUNK (0x00000008) /* last chunk of current col*/

149

#define OCI_LCR_COLUMN_AL16UTF16 (0x00000010) /* col is in AL16UTF16 fmt */

150

#define OCI_LCR_COLUMN_NCLOB (0x00000020) /* col has NCLOB data */

151

#define OCI_LCR_COLUMN_XML_DATA (0x00000040) /* col contains xml data */

152

#define OCI_LCR_COLUMN_XML_DIFF (0x00000080)/* col contains xmldiff data */

153

#define OCI_LCR_COLUMN_ENCRYPTED (0x00000100) /* col is encrypted */

154

155

/* OCI_LCR_COLUMN_UPDATED is set only for the modified columns in the NEW

156

* column list of an update LCR.

157

*/

158

#define OCI_LCR_COLUMN_UPDATED (0x00000200) /* col is updated */

159

160

/* Valid bit values for the flag parameter in the following APIS:

* - OCILCRHeaderGet

* - OCILCRHeaderSet

*/

#define OCI_ROWLCR_HAS_ID_KEY_ONLY (0x00000001) /* only has ID key cols */

165

/* (0x00000002) is RESERVED */

166

/* (0x00000004) is RESERVED */

167

/* (0x00000008) is RESERVED */

168

#define OCI_ROWLCR_SEQ_LCR (0x00000010) /* sequence lcr */

169

170

/* Valid bit values for flag parameter in the following APIs:

171

* - OCIXStreamOutChunkReceive & OCIXStreamOutLCRReceive

172

* - OCIXStreamInChunkSend & OCIXStreamInLCRSend

173

*/

174

#define OCI_XSTREAM_MORE_ROW_DATA (0x00000001) /* LCR contains more data */

175

176

/* Valid mode flag for OCILCRHeaderGet and OCILCRRowColumnInfoGet functions */

177

#define OCILCR_NEW_ONLY_MODE (0x0001) /* NEW columns only -- dont */

178

/* include OLD columns */

179

180

/* Valid mode flag for OCIXStreamInFlush */

181

/* Synchronous mode for OCIXStreamInFlush */

182

#define OCIXSTREAM_IN_FLUSH_WAIT_FOR_COMPLETE (0x00000001)

183

184

/*---------------------------------------------------------------------------

185

PRIVATE TYPES AND CONSTANTS

186

---------------------------------------------------------------------------*/

187

188

189

/*---------------------------------------------------------------------------

190

EXPORT FUNCTIONS

191

---------------------------------------------------------------------------*/

192

/*

193

------------------------------------------------------------------------------=

194

NAME

195

OCILCRNew - OCI LCR NEW

196

DESCRIPTION

197

Create a new Streams LCR for the user specified duration and type

198

PARAMETERS

199

svchp (IN) - OCI service context

200

errhp (IN) - OCI Error Handle

201

duration (IN) - allocation duration for LCR memory

202

lcrtype (IN) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL)

203

lcrp (IN/OUT) - Streams LCR. (*lcrp must be initialized to null.)

204

mode (IN) - mode

205

NOTES

206

- memory will be based on the duration specified by the user

207

- For now, specify OCI_DEFAULT for mode

208

------------------------------------------------------------------------------=

209

*/

210

sword OCILCRNew(OCISvcCtx *svchp,

211

OCIError *errhp,

212

OCIDuration duration,

ub1 lcrtype,

void **lcrp,

ub4 mode);

/*

------------------------------------------------------------------------------=

219

NAME

220

OCILCRFree - OCI LCR FREE

221

DESCRIPTION

222

Free Streams LCR specified by the user

223

PARAMETERS

224

svchp (IN) - OCI service context

225

errhp (IN) - OCI Error Handle

226

lcrp (IN/OUT) - Streams LCR

227

mode (IN) - mode

228

NOTES

229

- For now, specify OCI_DEFAULT for mode

230

------------------------------------------------------------------------------=

231

*/

232

sword OCILCRFree(OCISvcCtx *svchp,

OCIError *errhp,

void *lcrp,

ub4 mode);

/*

------------------------------------------------------------------------------=

240

NAME

241

OCILCRHeaderSet - OCI LCR Set Header

242

DESCRIPTION

243

Initialize elements of Streams LCR's header

244

PARAMETERS

245

svchp (IN) - OCI service context

246

errhp (IN) - OCI Error Handle

247

src_db_name (IN) - Pointer to Canonicalized source database name.

248

Must be non-NULL.

249

src_db_name_len (IN) - Length of source database name in bytes

250

excluding NULL terminator. Should follow Oracle

251

naming conventions and size limitations.

252

cmd_type (IN) - For ROW LCRs: OCI_LCR_ROW_CMD_XXXXXXX

253

For DDL LCRs: One of the command types

254

corresponding to OCI Reference manual

255

cmd_type_len (IN) - Length of cmd_type.

256

owner (IN) - Canonicalized table owner name. Not required

257

for COMMIT LCR.

258

owner_len (IN) - Length of owner name in bytes excluding the

259

NULL terminator. Should follow Oracle naming

260

conventions and size limitations.

261

oname (IN) - Canonicalized table name. Not required for

262

COMIT LCR.

263

oname_len (IN) - Length of table name in bytes excluding the

264

NULL terminator. Should follow Oracle naming

265

conventions and size limitations.

266

tag (IN) - A binary tag that enables tracking of the LCR.

267

For example, this tag can be used to determine

268

the original source database of the DML

269

statement if apply forwarding is used.

270

tag_len (IN) - Number of bytes in the tag. Cannot exceed 2000

271

bytes

272

txid (IN) - Transaction ID.

273

txid_len (IN) - Length of transaction id in bytes excluding the

274

NULL terminator. Should not exceeed

275

OCI_LCR_MAX_TXID_LEN bytes.

276

src_time (IN) - The time when the change was generated at the

277

source database.

278

position (IN) - position for LCR. Must be byte-comparable.

279

position_len (IN) - Length of position. Must be non-zero.

280

flag (IN) - LCR flag.

281

lcrp (IN/OUT) - Streams LCR

282

mode (IN) - mode

283

NOTES

284

- For now, specify OCI_DEFAULT for mode

285

- This function clears the current contents of the input LCR before

286

setting the header to the new values.

287

------------------------------------------------------------------------------=

288

*/

289

sword OCILCRHeaderSet(OCISvcCtx *svchp,

290

OCIError *errhp,

291

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);

/*

------------------------------------------------------------------------------=

312

NAME

313

OCILCRHeaderGet - OCI LCR Get Header

314

DESCRIPTION

315

Get header information from Streams LCR

316

PARAMETERS

317

svchp (IN) - OCI service context

318

errhp (IN) - OCI Error Handle

319

src_db_name (OUT) - Pointer to Canonicalized source database name.

320

Optional, if src_db_name is specified then

321

must specify src_db_name_len as well.

322

src_db_name_len (OUT) - Length of source database name in bytes

323

excluding NULL terminator.

324

Optional, if specified src_db_name_len then

325

must specify src_db_name as well.

326

cmd_type (OUT) - Command type. Must be non-null if

327

cmd_type_len is non-null. Must be null if

328

cmd_type_len is NULL.

329

cmd_type_len (OUT) - Length of cmd_type. Optional.

330

owner (OUT) - Canonicalized table owner name.

331

Optional, if owner is specified then

332

must specify owner_len as well.

333

owner_len (OUT) - Length of owner name in bytes excluding the

334

NULL terminator.

335

Optional, if owner_len is specified then

336

must specify owner as well.

337

oname (OUT) - Canonicalized table name.

338

Optional, if oname is specified then

339

must specify oname_len as well.

340

oname_len (OUT) - Length of table name in bytes excluding the

341

NULL terminator.

342

Optional, if oname_len is specified then

343

must specify oname as well.

344

tag (OUT) - A binary tag that enables tracking of the LCR.

345

For example, this tag can be used to determine

346

the original source database of the

347

DML statement if apply forwarding is used.

348

Optional, if tag is specified then

349

must specify tag_len as well.

350

tag_len (OUT) - Number of bytes in the tag.

351

Optional, if tag_len is specified then

352

must specify tag as well.

353

txid (OUT) - Transaction ID.

354

Optional, if txid is specified then

355

must specify txid_len as well.

356

txid_len (OUT) - Length of transaction id in bytes excluding

357

the NULL terminator.

358

Optional, if txid_len is specified then

359

must specify txid as well.

360

src_time (OUT) - The time when the change was generated at the

361

source database. Optional.

362

old_columns (OUT) - Number of columns in the OLD column list.

363

Return 0 if input lcr is DDL LCR. Optional.

364

new_columns (OUT) - Number of columns present in either

365

the OLD or NEW column list.

366

Return 0 if input lcr is DDL LCR. Optional.

367

See NOTES below for the special mode supported

368

by this function.

369

position (OUT) - LCR position. Optional.

370

position_len (OUT) - Length of position. Must be non-null if

371

position is non-null. Must be null if

372

position is null.

373

flag (OUT) - LCR flag. Optional.

374

lcrp (IN) - Streams LCR

375

mode (IN) - mode (see NOTES)

376

NOTES

377

- Parameter src_time is optional. If specified the appropriate return

378

structure must be pre-allocated before calling OCILCRHeaderGet.

379

- The return values for src_db_name, cmd_type, owner, oname, tag, txid and

380

position are shallow-copied (i.e., they point directly into the LCR

381

structure).

382

- Valid mode flags:

383

- OCILCR_NEW_ONLY_MODE: if this mode is specified then the new_columns

384

returned is the count of the columns in the NEW column list only.

385

Otherwise, the new_columns returned is the number of distinct

386

columns present in either the NEW or the OLD column list of the given

387

ROW LCR.

388

------------------------------------------------------------------------------=

389

*/

390

391

sword OCILCRHeaderGet(OCISvcCtx *svchp,

392

OCIError *errhp,

393

oratext **src_db_name,

394

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);

/*

------------------------------------------------------------------------------=

416

NAME

417

OCILCRRowColumnInfoSet - OCI LCR ROW SET COLUMN INFO

418

DESCRIPTION

419

Populates column information as specified by the user.

420

PARAMETERS

421

svchp (IN) - OCI service context

422

errhp (IN) - OCI Error Handle

423

column_value_type (IN) - ROW LCR column value type:

424

- OCI_LCR_ROW_COLVAL_OLD

425

- OCI_LCR_ROW_COLVAL_NEW

426

num_columns (IN) - Number of columns to be populated

427

column_names (IN) - Pointer to an array of column names. Column

428

names must be canonicalized. Column names should

429

follow Oracle naming conventions

430

column_name_lens (IN) - Pointer to an array of column name lengths

431

in bytes, excluding the NULL terminator.

432

column_dtyp (IN) - Pointer to an array of column datatypes.

433

column_valuesp (IN) - Pointer to an array of column data values.

434

column_indp (IN) - Pointer to an indicator array. For all datatypes,

435

this is a pointer to an array of OCIInd values

436

(OCI_IND_NULL/OCI_IND_NOTNULL).

437

column_alensp (IN) - Pointer to an array of actual column lengths in

438

bytes.

439

column_csetfp (IN) - Pointer to an array of character set forms for

440

the columns. The default form is SQLCS_IMPLICIT.

441

Setting this attribute will cause the database or

442

national character set to be used on the client

443

side. Set this attribute to SQLCS_NCHAR for the

444

national character set or SQLCS_IMPLICIT for the

445

database character set.

446

Pass 0 for non-character columns.

447

column_flags (IN) - Pointer to an array of column flags.

448

Possible bit values are OCI_LCR_COLUMN_* flags

449

listed above.

450

column_csid (IN) - Pointer to an array of column character set id.

451

The character set id is only required for

452

XMLType column; otherwise, the csid is ignored.

453

row_lcrp (IN/OUT)- Streams Row LCR pointer

454

mode (IN) - mode

455

NOTES

456

- For now, specify OCI_DEFAULT for mode

457

------------------------------------------------------------------------------=

458

*/

459

sword OCILCRRowColumnInfoSet(OCISvcCtx *svchp,

460

OCIError *errhp,

461

ub2 column_value_type,

462

ub2 num_columns,

463

oratext **column_names,

464

ub2 *column_name_lens,

465

ub2 *column_dtyp,

466

void **column_valuesp,

OCIInd *column_indp,

ub2 *column_alensp,

ub1 *column_csetfp,

oraub8 *column_flags,

ub2 *column_csid,

void *row_lcrp,

ub4 mode);

/*

------------------------------------------------------------------------------=

477

NAME

478

OCILCRRowColumnInfoGet - OCI LCR ROW GET COLUMN INFO

479

DESCRIPTION

480

Returns column information as requested by the user.

481

PARAMETERS

482

svchp (IN) - OCI service context

483

errhp (IN) - OCI Error Handle

484

column_value_type (IN) - ROW LCR column value type:

485

- OCI_LCR_ROW_COLVAL_OLD

486

- OCI_LCR_ROW_COLVAL_NEW

487

(See NOTES for special mode supported by this

488

function.)

489

num_columns (OUT) - Number of columns in requested column list

490

column_names (IN/OUT)- Pointer to an array of column names.

491

Optional. If specified then column_namesl must

492

be specified as well, and both arrays must be the

493

size specified by array_size parameter.

494

column_name_lens (IN/OUT)- Pointer to an array of column name lengths

495

in bytes, excluding the NULL terminator.

496

Optional. If specified then column_names must

497

be specified as well, and both arrays must be the

498

size specified by array_size parameter.

499

column_dtyp (IN/OUT)- Pointer to an array of column datatypes.

500

Optional. If specified then this array must be

501

the size specified by array_size parameter.

502

column_valuesp (IN/OUT)- Pointer to an array of column data values.

503

Optional. If specified then this array must be

504

the size specified by array_size parameter.

505

column_indp (IN/OUT)- Pointer to an indicator array. For all datatypes,

506

this is a pointer to an array of OCIInd values

507

(OCI_IND_NULL/OCI_IND_NOTNULL).

508

Optional. If specified then this array must be

509

the size specified by array_size parameter.

510

column_alensp (IN/OUT)- Pointer to an array of actual column lengths in

511

bytes.

512

Optional. If specified then this array must be

513

the size specified by array_size parameter.

514

column_csetfp (IN/OUT)- Pointer to an array of character set forms for

515

the columns.

516

Optional. If specified then this array must be

517

the size specified by array_size parameter.

518

column_flags (IN/OUT)- Pointer to an array of column flags for

519

the columns.

520

Optional. If specified then this array must be

521

the size specified by array_size parameter.

522

Possible bit values are OCI_LCR_COLUMN_* flags

523

listed above.

524

column_csid (IN/OUT)- Pointer to an array of column character set id for

525

the columns.

526

Optional. If specified then this array must be

527

the size specified by array_size parameter.

528

The column csid is returned only for XMLType

529

column.

530

row_lcrp (IN) - Streams Row LCR pointer

531

array_size (IN) - Size of each of above arrays

532

mode (IN) - mode (see NOTES)

533

NOTES

534

- For now, specify OCI_DEFAULT for mode

535

- If array_size is not large enough to accommodate the number of columns

536

in the requested column list then OCI_ERROR is returned. Parameter

537

num_columns will have the number of columns in the requested column list.

538

- The return values for column_names and column_valuesp will be shallow

539

copied (i.e., they reference directly into the LCR structure).

540

Client should not modify those pointers directly.

541

- Valid mode flags:

542

- OCILCR_NEW_ONLY_MODE: this mode is valid only for OCI_LCR_ROW_COLVAL_NEW

543

column_value_type; otherwise, an error is raised.

544

If this mode is specified then the columns returned include only the

545

columns in the NEW column list.

546

If this mode is not specified then the columns returned is the union

547

of the NEW columns plus the OLD columns that are not present in the

548

NEW column list.

549

------------------------------------------------------------------------------=

550

*/

551

sword OCILCRRowColumnInfoGet(OCISvcCtx *svchp,

552

OCIError *errhp,

553

ub2 column_value_type,

554

ub2 *num_columns,

555

oratext **column_names,

556

ub2 *column_name_lens,

557

ub2 *column_dtyp,

558

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);

/*

------------------------------------------------------------------------------=

571

NAME

572

OCILCRDDLInfoSet - OCI LCR SET DDL INFO

573

DESCRIPTION

574

populates DDL information as sepcified by the user.

575

PARAMETERS

576

svchp (IN) - OCI service context

577

errhp (IN) - OCI Error Handle

578

object_type (IN) - The type of object on which the DDL statement was

579

executed. The following are valid object types:

580

CLUSTER, FUNCTION, INDEX, LINK, OUTLINE,

581

PACKAGE, PACKAGE BODY, PROCEDURE, SEQUENCE,

582

SYNONYM, TABLE, TRIGGER, TYPE, USER, VIEW

583

LINK represents a database link.

584

NULL is also a valid object type. Specify NULL

585

for all object types not listed.

586

object_type_len (IN) - Length of object_type without the NULL terminator.

587

ddl_text (IN) - The text of the DDL statement. This parameter

588

should be set to a non-NULL value.

589

DDL text must be in Oracle DDL format.

590

ddl_text_len (IN) - DDL text length in bytes without NULL terminator.

591

logon_user (IN) - Canonicalized name of the user whose session

592

executed the DDL statement. Should follow Oracle

593

naming conventions and size limitations.

594

logon_user_len (IN) - logon user name length in bytes without NULL

595

terminator.

596

current_schema (IN) - The canonicalized schema name that is used if no

597

schema is specified explicitly for the modified

598

database objects in ddl_text. If a schema is

599

specified in ddl_text that differs from the one

600

specified for current_schema, then the schema

601

specified in ddl_text will be used.

602

This parameter should be set to a non-NULL value.

603

Should follow Oracle naming conventions and size

604

limitations.

605

current_schema_len (IN) - schema name length in bytes without NULL terminator

606

base_table_owner (IN) - If the DDL statement is a table related DDL

607

(such as CREATE TABLE and ALTER TABLE), or if the

608

DDL statement involves a table (such as creating

609

a trigger on a table), then base_table_owner

610

specifies the canonicalized owner of the table

611

involved. Otherwise, base_table_owner is NULL.

612

Should follow Oracle naming conventions and size

613

limitations.

614

base_table_owner_len (IN)- base table owner name length in bytes without NULL

615

terminator.

616

base_table_name (IN) - If the DDL statement is a table related DDL (such

617

as CREATE TABLE and ALTER TABLE), or if the DDL

618

statement involves a table (such as creating a

619

trigger on a table), then base_table_name

620

specifies the canonicalized name of the table

621

involved. Otherwise, base_table_name is NULL.

622

Length of the above string without the NULL

623

terminator. Should follow Oracle naming

624

conventions and size limitations.

625

Should follow Oracle naming conventions and size

626

limitations.

627

base_table_name_len (IN)- base table name length in bytes without NULL

628

terminator.

629

flag (IN) - DDL LCR flag.

630

ddl_lcrp (IN/OUT) - Streams Ddl LCR pointer

631

mode (IN) - mode

632

NOTES

633

- For now, specify OCI_DEFAULT for mode

634

------------------------------------------------------------------------------=

635

*/

636

sword OCILCRDDLInfoSet(OCISvcCtx *svchp,

637

OCIError *errhp,

638

oratext *object_type,

ub2 object_type_len,

oratext *ddl_text,

ub4 ddl_text_len,

oratext *logon_user,

ub2 logon_user_len,

oratext *current_schema,

645

ub2 current_schema_len,

646

oratext *base_table_owner,

647

ub2 base_table_owner_len,

648

oratext *base_table_name,

649

ub2 base_table_name_len,

oraub8 flag,

void *ddl_lcrp,

ub4 mode);

/*

------------------------------------------------------------------------------=

656

NAME

657

OCILCRDDLInfoGet - OCI LCR GET DDL INFO

658

DESCRIPTION

659

Returns DDL information from specified lcr.

660

PARAMETERS

661

svchp (IN) - OCI service context

662

errhp (IN) - OCI Error Handle

663

object_type (OUT) - The type of object on which the DDL statement

664

was executed.

665

Optional, if object_type is specified then

666

must specify object_type_len as well.

667

object_type_len (OUT) - Length of object_type without the NULL

668

terminator.

669

ddl_text (OUT) - The text of the DDL statement.

670

Optional, if ddl_text is specified then

671

must specify ddl_text_len as well.

672

ddl_text_len (OUT) - DDL text length in bytes without NULL

673

terminator.

674

logon_user (OUT) - Canonicalized name of the user whose session

675

executed the DDL statement.

676

Optional, if logon_user is specified then

677

must specify logon_user_len as well.

678

logon_user_len (OUT) - logon user name length in bytes without NULL

679

terminator.

680

current_schema (OUT) - The canonicalized schema name that is used if

681

no schema is specified explicitly for the

682

modified database objects in ddl_text.

683

Optional, if current_schema is specified then

684

must specify current_schema_len as well.

685

current_schema_len (OUT)- schema name length in bytes without NULL

686

terminator

687

base_table_owner (OUT) - If the DDL statement is a table related DDL

688

(such as CREATE TABLE and ALTER TABLE), or if

689

the DDL statement involves a table (such as

690

creating a trigger on a table), then

691

base_table_owner specifies the canonicalized

692

owner of the table involved. Otherwise,

693

base_table_owner is NULL. Optional, if

694

base_table_owner is specified then must specify

695

base_table_owner_len as well.

696

base_table_owner_len (OUT) - base table owner name length in bytes without

697

NULL terminator.

698

base_table_name (OUT) - If the DDL statement is a table related DDL

699

(such as CREATE TABLE and ALTER TABLE), or if

700

the DDL statement involves a table (such as

701

creating a trigger on a table), then

702

base_table_name specifies the canonicalized name

703

of the table involved. Otherwise,

704

base_table_name is NULL. Optional, if

705

base_table_name is specified then must specify

706

base_table_name_len as well.

707

base_table_name_len (OUT) - base table name length in bytes without NULL

708

terminator.

709

flag (OUT) - DDL LCR flag. Optional, data not returned if

710

NULL.

711

ddl_lcrp (IN) - Streams DDL LCR pointer

712

mode (IN) - mode (for future extention - not used currently)

713

RETURNS

714

OCI_SUCCESS or OCI_ERROR.

715

NOTES

716

- For now, specify OCI_DEFAULT for mode

717

------------------------------------------------------------------------------=

718

*/

719

sword OCILCRDDLInfoGet(OCISvcCtx *svchp,

720

OCIError *errhp,

721

oratext **object_type,

722

ub2 *object_type_len,

723

oratext **ddl_text,

724

ub4 *ddl_text_len,

725

oratext **logon_user,

726

ub2 *logon_user_len,

727

oratext **current_schema,

728

ub2 *current_schema_len,

729

oratext **base_table_owner,

730

ub2 *base_table_owner_len,

731

oratext **base_table_name,

732

ub2 *base_table_name_len,

oraub8 *flag,

void *ddl_lcrp,

ub4 mode);

/*

------------------------------------------------------------------------------=

739

NAME

740

OCILCRAttributesSet - OCI LCR SET ATTRIBUTES

741

DESCRIPTION

742

populates extra attribute information in ROW/DDL LCR, as well as any

743

non first class attributes that can not be set through

744

OCILCRHeaderSet, OCILCRDDLInfoSet, or OCILCRRowColumnInfoSet.

745

e.g. edition name

746

PARAMETERS

747

svchp (IN) - OCI service context

748

errhp (IN) - OCI Error Handle

749

num_attrs (IN) - Number of extra attributes to be populated

750

attr_names (IN) - Pointer to an array of attribute names. Attribute

751

names must be canonicalized and should follow

752

Oracle naming conventions

753

attr_names_lens (IN) - Pointer to an array of attribute name lengths

754

in bytes, excluding the NULL terminator.

755

attr_dtyp (IN) - Pointer to an array of attribute datatypes.

756

attr_valuesp (IN) - Pointer to an array of attribute data values.

757

attr_indp (IN) - Pointer to an indicator array. For all datatypes,

758

this is a pointer to an array of OCIInd values

759

(OCI_IND_NULL/OCI_IND_NOTNULL).

760

attr_alensp (IN) - Pointer to an array of actual attribute lengths in

761

bytes.

762

lcrp (IN/OUT)- Streams (Row/DDL) LCR pointer

763

mode (IN) - mode

764

NOTES

765

- For now, specify OCI_DEFAULT for mode

766

------------------------------------------------------------------------------=

767

*/

768

sword OCILCRAttributesSet(OCISvcCtx *svchp,

769

OCIError *errhp,

770

ub2 num_attrs,

771

oratext **attr_names,

ub2 *attr_name_lens,

ub2 *attr_dtyp,

void **attr_valuesp,

OCIInd *attr_indp,

ub2 *attr_alensp,

void *lcrp,

ub4 mode);

/*

------------------------------------------------------------------------------=

782

NAME

783

OCILCRAttributesGet - OCI LCR GET EXTRA ATTRIBUTES

784

DESCRIPTION

785

Gets extra attribute information in (ROW/DDL) LCR, as well as any

786

non first class attributes that are not populated through

787

OCILCRHeaderGet, OCILCRDDLInfoGet, or OCILCRRowColumnInfoGet

788

e.g. edition name

789

PARAMETERS

790

svchp (IN) - OCI service context

791

errhp (IN) - OCI Error Handle

792

num_attrs (OUT) - Number of extra attributes to be populated

793

attr_names (IN/OUT)- Pointer to an array of attribute names. Attribute

794

names must be canonicalized and should follow

795

Oracle naming conventions

796

attr_namesl (IN/OUT)- Pointer to an array of attribute name lengths

797

in bytes, excluding the NULL terminator.

798

attr_dtyp (IN/OUT)- Pointer to an array of attribute datatypes.

799

attr_valuesp (IN/OUT)- Pointer to an array of attribute data values.

800

attr_indp (IN/OUT)- Pointer to an indicator array. For all datatypes,

801

this is a pointer to an array of OCIInd values

802

(OCI_IND_NULL/OCI_IND_NOTNULL).

803

attr_alensp (IN/OUT)- Pointer to an array of actual attribute lengths in

804

bytes.

805

lcrp (IN) - Streams (Row/DDL) LCR pointer

806

array_size (IN) - Size of each of above arrays, use at least the size

807

defined by OCI_LCR_MAX_ATTRIBUTES

808

mode (IN) - mode

809

NOTES

810

- For now, specify OCI_DEFAULT for mode

811

- If array_size is not large enough to accommodate the number of attributes

812

in the requested attribute list then OCI_ERROR is returned. Parameter

813

num_attrs will return the suggested size.

814

------------------------------------------------------------------------------=

815

*/

816

sword OCILCRAttributesGet(OCISvcCtx *svchp,

817

OCIError *errhp,

818

ub2 *num_attrs,

819

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 ----------------------------*/

830

/*

831

NAME

832

OCILCRWhereClauseGet - OCI Get Where Clause

833

DESCRIPTION

834

Gets the Where clause statement for the given ROW LCR.

835

PARAMETERS

836

svchp (IN/OUT) - OCI service handle

837

errhp (IN/OUT) - Error Handle to which errors

838

should be reported

839

wc_stmt (OUT) - Sql Statement equivalent to the

840

LCR has applied

841

wc_stmt_len (IN/OUT) - length of wc_stmt buffer

842

row_lcrp (IN) - row LCR to be converted to SQL

843

mode (IN) - Mode flags (For future extension.

844

Not used currently)

845

RETURNS

846

OCI_SUCCESS or OCI_ERROR.

847

NOTES

848

- For now, specify OCI_DEFAULT for mode

849

- WHERE clause generated for INSERT lcr will have all the columns that

850

are being inserted. This WHERE clause could be used to identify the

851

inserted row after inserting. (like "returning ROWID").

852

INSERT INTO TAB(COL1) VALUES (10) -> WHERE COL1=10

853

- WHERE clause generated for UPDATE will have all the columns in the

854

old column list. However the values of the columns will be that of

855

new value if it exist in the new column list

856

of the UPDATE. If the column doesnt have new value then the old column

857

value will be used.

858

UPDATE TAB SET COL1 = 10 WHERE COL1 = 20 -> WHERE COL1 = 10

859

UPDATE TAB SET COL2 = 20 WHERE COL1 = 20 -> WHERE COL1 = 20

860

- WHERE clause for DELETE will use the columns and values from

861

old column lst

862

- LOB piecewise operations would use the new columns and values for

863

generating the WHERE clause.

864

*/

865

866

sword OCILCRWhereClauseGet(

OCISvcCtx *svchp,

OCIError *errhp,

oratext *wc_stmt,

ub4 *wc_stmt_len,

void *row_lcrp,

ub4 mode);

/*--------------------- OCILCRRowStmtGet ----------------------------*/

875

/*

876

NAME

877

OCILCRRowStmtGet - OCI Get Row Statement

878

DESCRIPTION

879

Gets the SQL statement for the given ROW LCR.

880

PARAMETERS

881

svchp (IN/OUT) - OCI service handle

882

errhp (IN/OUT) - Error Handle to which errors

883

should be reported

884

row_stmt (OUT) - Sql Statement equivalent to the

885

LCR has applied

886

row_stmt_len (IN/OUT) - length of row_stmt buffer

887

row_lcrp (IN) - row LCR to be converted to SQL

888

mode (IN) - Mode flags (For future extension.

889

Not used currently)

890

RETURNS

891

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 ----------------------*/

904

/*

905

NAME

906

OCILCRWhereClauseWithBindVarGet - OCI Get Where clause with binds

907

DESCRIPTION

908

Gets the where clause statement with bind variables for the given ROW LCR.

909

PARAMETERS

910

svchp (IN/OUT) - OCI service handle

911

errhp (IN/OUT) - Error Handle to which errors

912

should be reported

913

wc_stmt (OUT) - Sql Stmt equivalent to the LCR

914

wc_stmt_len (IN/OUT) - length of wc_stmt buffer

915

num_bind_var (OUT) - Number of bind variables

916

bind_var_dtyp (OUT) - Array of Data types of bind

917

variables

918

bind_var_valuesp (OUT) - Array of Values of bind variables

919

bind_var_indp (OUT) - Array of null indicators of

920

bind variables

921

bind_var_alensp (OUT) - Array of lengths of bind values

922

bind_var_csetidp (OUT) - Array of char set id of binds

923

bind_var_csetfp (OUT) - Array of char set form of binds

924

row_lcrp (IN) - row LCR to be converted to SQL

925

array_size (IN) - Size of the array of bind values

926

bind_var_syntax (IN) - Native syntax to be used for binds

927

mode (IN) - Mode flags (For future extension.

928

Not used currently)

929

RETURNS

930

OCI_SUCCESS or OCI_ERROR.

931

NOTES

932

- For now, specify OCI_DEFAULT for mode

933

- If array_size is not large enough to accommodate the number of columns

934

in the requested column list then OCI_ERROR is returned. Expected

935

array_size is returned through num_bind_var parameter.

936

- bind_var_syntax for oracle should contain ":". This will generate

937

positional binds such as :1, :2, :3 etc. For other non-oracle databases

938

they can give the string that needs to be used for binds.

939

- WHERE clause generated for INSERT lcr will have all the columns that

940

are being inserted. This WHERE clause could be used to identify the

941

inserted row after inserting. (like "returning ROWID").

942

INSERT INTO TAB(COL1) VALUES (10) -> WHERE COL1=10

943

- WHERE clause generated for UPDATE will have all the columns in the

944

old column list. However the values of the columns will be that of

945

new column value of the column if it exist in the new values

946

of the UPDATE. If the column appears only in the old column then

947

old column value will be used.

948

UPDATE TAB SET COL1 = 10 WHERE COL1 = 20 -> WHERE COL1 = 10

949

UPDATE TAB SET COL2 = 20 WHERE COL1 = 20 -> WHERE COL1 = 20

950

- WHERE clause for DELETE will use the columns and values from

951

old column lst

952

- LOB piecewise operations would use the new columns and values for

953

generating the WHERE clause.

954

*/

955

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,

963

OCIInd *bind_var_indp,

964

ub2 *bind_var_alensp,

965

ub2 *bind_var_csetidp,

966

ub1 *bind_var_csetfp,

967

void *row_lcrp,

968

ub2 array_size,

969

oratext *bind_var_syntax,

970

ub4 mode);

971

972

/*--------------------- OCILCRRowStmtWithBindVarGet ----------------------*/

973

/*

974

NAME

975

OCILCRRowStmtWithBindVarGet - OCI Get Row Statement

976

DESCRIPTION

977

Gets the SQL statement with bind variables for the given ROW LCR.

978

PARAMETERS

979

svchp (IN/OUT) - OCI service handle

980

errhp (IN/OUT) - Error Handle to which errors

981

should be reported

982

row_stmt (OUT) - Sql Stmt equivalent to the LCR

983

row_stmt_len (IN/OUT) - length of row_stmt buffer

984

num_bind_var (OUT) - Number of bind variables

985

bind_var_dtyp (OUT) - Array of Data types of bind

986

variables

987

bind_var_valuesp (OUT) - Array of Values of bind variables

988

bind_var_indp (OUT) - Array of null indicators of

989

bind variables

990

bind_var_alensp (OUT) - Array of lengths od bind values

991

bind_var_csetidp (OUT) - Array of char set id of binds

992

bind_var_csetfp (OUT) - Array of char set form of binds

993

row_lcrp (IN) - row LCR to be converted to SQL

994

chunk_column_names (OUT) - Array of chunked column names in

995

lcr

996

chunk_column_namesl (OUT) - Length of chunk_column_names

997

chunk_column_flags (OUT) - flags of chunked columns in lcr

998

Possible bit values are

999

OCI_LCR_COLUMN_* flags listed

1000

above.

1001

array_size (IN) - Size of the array of bind values

1002

bind_var_syntax (IN) - Native syntax to be used for binds

1003

mode (IN) - Mode flags (For future extension.

1004

Not used currently)

1005

RETURNS

1006

OCI_SUCCESS or OCI_ERROR.

1007

NOTES

1008

- For now, specify OCI_DEFAULT for mode

1009

- If array_size is not large enough to accommodate the number of columns

1010

in the requested column list then OCI_ERROR is returned. Expected

1011

array_size is returned through num_bind_var parameter.

1012

- bind_var_syntax for oracle should contain ":". This will generate

1013

positional binds such as :1, :2, :3 etc. For other non-oracle databases

1014

they can give the string that needs to be used for binds.

1015

*/

1016

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,

1024

OCIInd *bind_var_indp,

1025

ub2 *bind_var_alensp,

1026

ub2 *bind_var_csetidp,

1027

ub1 *bind_var_csetfp,

1028

void *row_lcrp,

1029

oratext **chunk_column_names,

1030

ub2 *chunk_column_namesl,

1031

oraub8 *chunk_column_flags,

1032

ub2 array_size,

1033

oratext *bind_var_syntax,

ub4 mode);

/*

-------------------------------------------------------------------------------

1038

NAME

1039

OCILCRSCNsFromPosition - Get SCNs From Position

1040

1041

DESCRIPTION

1042

Returns the SCN and commit SCN from the given position.

1043

PARAMETERS

1044

svchp (IN) - OCI service context

1045

errhp (IN) - OCI Error Handle

1046

position (IN) - LCR position

1047

position_len (IN) - length of position

1048

scn (OUT) - the SCN stored in position

1049

commit_scn (OUT) - the commit SCN stored in position

1050

mode (IN) - Mode flags (For future extension. Not used

1051

currently)

1052

RETURN

1053

OCI_SUCCESS if the conversion succeeds, OCI_ERROR otherwise.

1054

NOTE

1055

The user must allocate memory for the return numbers.

1056

The input position must conform to the format generated by an XStream

1057

server.

1058

-------------------------------------------------------------------------------

1059

*/

1060

sword OCILCRSCNsFromPosition(OCISvcCtx *svchp,

OCIError *errhp,

ub1 *position,

ub2 position_len,

OCINumber *scn,

OCINumber *commit_scn,

ub4 mode);

/*

-------------------------------------------------------------------------------

1070

NAME

1071

OCILCRSCNToPosition - Converts SCN To Position

1072

1073

DESCRIPTION

1074

Converts an SCN to a position. The generated position can be passed as the

1075

last_position to OCIXStreamOutAttach function to filter the LCRs

1076

with commit SCN less than the given SCN and the LCR's SCN less than the

1077

given SCN. This means the first LCR sent by the Outbound server is either

1078

- a commit LCR at the given SCN, or

1079

- the first LCR of the subsequent transaction with commit SCN greater

1080

than or equal to the given SCN.

1081

PARAMETERS

1082

svchp (IN) - OCI service context

1083

errhp (IN) - OCI Error Handle

1084

position (OUT) - Result position. Must pre-allocate

1085

OCI_LCR_MAX_POSITION_LEN bytes.

1086

position_len (OUT) - Length of position

1087

scn (IN) - The SCN to be stored in position

1088

mode (IN) - Mode flags (for future extension)

1089

RETURN

1090

OCI_SUCCESS if the conversion succeeds, OCI_ERROR otherwise.

1091

-------------------------------------------------------------------------------

1092

*/

1093

sword OCILCRSCNToPosition(OCISvcCtx *svchp,

OCIError *errhp,

ub1 *position,

ub2 *position_len,

OCINumber *scn,

ub4 mode);

/*

------------------------------------------------------------------------------=

1102

NAME

1103

OCILCRLobInfoGet - OCI LCR GET LOB INFO

1104

DESCRIPTION

1105

Returns the LOB information for a given piece-wise LOB LCR.

1106

PARAMETERS

1107

svchp (IN) - OCI service context

1108

errhp (IN) - OCI Error Handle

1109

column_name (OUT) - Pointer to the LOB column name.

1110

Optional. If specified then column_name_len must

1111

be specified as well.

1112

column_name_len(OUT) - Length of LOB column name without the NULL

1113

terminator.

1114

column_dty (OUT) - LOB column dty - either SQLT_CHR (for CLOB) or

1115

SQLT_BIN (for BLOB).

1116

column_flag (OUT) - LOB column flag.

1117

Possible bit values are OCI_LCR_COLUMN_* flags

1118

listed above.

1119

offset (OUT) - LOB operation offset in code points. Returned only

1120

for LOB_TRIM and LOB_WRITE operations; otherwise,

1121

a zero is returned.

1122

This is the same as the 'soffset' parameter for

1123

OCILobErase or the 'offset' parameter in

1124

OCILobWrite functions.

1125

size (OUT) - LOB operation size in code points. Returned only

1126

for LOB_TRIM and LOB_ERASE operations; otherwise,

1127

a zero is returned.

1128

This is the same as the 'new_length' parameter in

1129

OCILobTrim or the 'amtp' parameter in OCILobErase

1130

functions.

1131

row_lcrp (IN) - Streams Row LCR pointer

1132

mode (IN) - mode

1133

NOTES

1134

- For now, specify OCI_DEFAULT for mode

1135

------------------------------------------------------------------------------=

1136

*/

1137

sword OCILCRLobInfoGet(OCISvcCtx *svchp,

1138

OCIError *errhp,

1139

oratext **column_name,

1140

ub2 *column_name_len,

ub2 *column_dty,

oraub8 *column_flag,

ub4 *offset,

ub4 *size,

void *row_lcrp,

ub4 mode);

/*

------------------------------------------------------------------------------=

1151

NAME

1152

OCILCRLobInfoSet - OCI LCR SET LOB INFO

1153

DESCRIPTION

1154

Sets the LOB information for a given piece-wise LOB LCR.

1155

PARAMETERS

1156

svchp (IN) - OCI service context

1157

errhp (IN) - OCI Error Handle

1158

column_name (IN) - Pointer to the LOB column name.

1159

column_name_len(IN) - Length of LOB column name without the NULL

1160

terminator.

1161

column_dty (IN) - LOB column dty - either SQLT_CHR (for CLOB) or

1162

SQLT_BIN (for BLOB).

1163

column_flag (IN) - LOB column flag.

1164

Possible bit values are OCI_LCR_COLUMN_* flags

1165

listed above.

1166

offset (IN) - LOB operation offset in code points. Returned only

1167

for LOB_TRIM and LOB_WRITE operations; otherwise,

1168

a zero is returned.

1169

This is the same as the 'soffset' parameter for

1170

OCILobErase or the 'offset' parameter in

1171

OCILobWrite functions.

1172

size (IN) - LOB operation size in code points. Returned only

1173

for LOB_TRIM and LOB_ERASE operations; otherwise,

1174

a zero is returned.

1175

This is the same as the 'new_length' parameter in

1176

OCILobTrim or the 'amtp' parameter in OCILobErase

1177

functions.

1178

row_lcrp (IN/OUT)- Streams Row LCR pointer

1179

mode (IN) - mode

1180

NOTES

1181

- For now, specify OCI_DEFAULT for mode

1182

------------------------------------------------------------------------------=

1183

*/

1184

sword OCILCRLobInfoSet(OCISvcCtx *svchp,

1185

OCIError *errhp,

1186

oratext *column_name,

ub2 column_name_len,

ub2 column_dty,

oraub8 column_flag,

ub4 offset,

ub4 size,

void *row_lcrp,

ub4 mode);

/*---------------------------------------------------------------------------

1196

STREAMS XSTREAM OUT FUNCTIONS

1197

---------------------------------------------------------------------------*/

1198

1199

/*------------------------- OCIXStreamOutAttach -----------------------------*/

1200

/*

1201

NAME

1202

OCIXStreamOutAttach - OCI Attach to XStreams Out

1203

DESCRIPTION

1204

Given the name of the server process, attach to the outbound server.

1205

PARAMETERS

1206

svchp (IN/OUT) - OCI service handle

1207

errhp (IN/OUT) - Error Handle for error reporting

1208

server_name (IN) - Server name.

1209

server_name_len (IN) - Length of server name.

1210

last_position (IN) - last rcv position. (Optional)

1211

last_position_len (IN) - Length of last_position.

1212

mode (IN) - Mode flags (see below)

1213

RETURNS

1214

OCI_SUCCESS or OCI_ERROR.

1215

NOTES

1216

Specify OCI_DEFAULT for the mode parameter.

1217

1218

The name of the outbound server must be provided because multiple

1219

outbound servers can be configured in one Oracle instance. This call

1220

returns OCI_ERROR if it encounters any error while attaching to the

1221

outbound server.

1222

1223

The last_position parameter is used to establish the starting point

1224

of the stream. This call returns OCI_ERROR if the specified position

1225

is non-null and less than the server's processed low-watermark;

1226

otherwise, LCRs with position greater than last_position will be

1227

sent to the user.

1228

1229

If last_position is null then the stream will start from the processed

1230

low-watermark maintained in the server.

1231

*/

1232

1233

sword OCIXStreamOutAttach (OCISvcCtx *svchp, OCIError *errhp,

1234

oratext *server_name, ub2 server_name_len,

1235

ub1 *last_position,

1236

ub2 last_position_len,

1237

ub4 mode);

1238

1239

/* Valid modes for OCIXStreamOutAttach call */

1240

#define OCIXSTREAM_OUT_ATTACH_RESERVED_1 (0x00000001)

1241

/* Application is in charge of freeing the LCRs from the outbound server */

1242

#define OCIXSTREAM_OUT_ATTACH_APP_FREE_LCR (0x00000002)

1243

1244

/*---------------------- OCIXStreamOutProcessedLWMSet ----------------------*/

1245

/*

1246

NAME

1247

OCIXStreamOutProcessedLWMSet - Set Processed Low-Watermark

1248

DESCRIPTION

1249

Sets the processed low-watermark maintained at the client.

1250

PARAMETERS

1251

svchp (IN/OUT) - OCI service handle

1252

errhp (IN/OUT) - Error Handle for error reporting

1253

processed_low_position (IN) - processed low position.

1254

processed_low_position_len (IN) - processed low position length.

1255

mode (IN) - mode for future extension. (Not used

1256

currently).

1257

RETURNS

1258

OCI_SUCCESS or OCI_ERROR.

1259

1260

NOTES

1261

The processed low-watermark denotes all LCRs at or below this position

1262

have been processed. After successfully attaching to an XStream

1263

outbound server, a local copy of the processed low-watermark is

1264

maintained at the client. Periodically, this watermark is sent to the

1265

server so that archived logs containing already processed transactions

1266

can be purged.

1267

1268

The following API is used to update the local copy of the processed

1269

low-watermark. It can be called anytime between OCIXStreamOutAttach

1270

and OCIXStreamOutDetach calls. Clients, using the callback mechanism

1271

to stream LCRs from the server, can invoke this API while

1272

in the callback functions.

1273

*/

1274

1275

sword OCIXStreamOutProcessedLWMSet (OCISvcCtx *svchp, OCIError *errhp,

1276

ub1 *processed_low_position,

1277

ub2 processed_low_position_len,

ub4 mode);

/*-------------------- OCICallbackXStreamOutLCRProcess ----------------------*/

1282

/*

1283

NAME

1284

OCICallbackXStreamOutLCRProcess - Callback to process each LCR received

1285

DESCRIPTION

1286

This callback is invoked during OCIXStreamOutLCRCallbackReceive

1287

to process each LCR received from the outbound server.

1288

PARAMETERS

1289

usrctxp (IN/OUT) - Ptr to the user context.

1290

lcrp (IN) - Pointer to the LCR just received.

1291

lcrtyp (IN) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL)

1292

flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1293

this means the current LCR has more

1294

chunk data.

1295

RETURNS

1296

This callback function must return OCI_CONTINUE to continue processing

1297

OCIXStreamOutLCRCallbackReceive call. Any return code other than

1298

OCI_CONTINUE signals that the client wants to terminate

1299

OCIXStreamOutLCRCallbackReceive immediately.

1300

*/

1301

typedef sb4 (*OCICallbackXStreamOutLCRProcess) (void *usrctxp, void *lcrp,

1302

ub1 lcrtyp, oraub8 flag);

1303

1304

1305

/*-------------------- OCICallbackXStreamOutChunkProcess --------------------*/

1306

/*

1307

NAME

1308

OCICallbackXStreamOutChunkProcess - Callback to process each chunk

1309

DESCRIPTION

1310

This callback is invoked during OCIXStreamOutLCRCallbackReceive

1311

to process each chunk in an LCR.

1312

PARAMETERS

1313

usrctxp (IN/OUT) - Ptr to the user context.

1314

column_name (IN) - Column name for the current chunk.

1315

column_name_len (IN) - Length of column name.

1316

column_dty (IN) - Chunk data type (SQLT_CHR or SQLT_BIN).

1317

column_flag (IN) - LCR column flags. Possible bit values are

1318

OCI_LCR_COLUMN_* flags listed above.

1319

column_csid (IN) - Column character set id. Relevant only if

1320

the column is an XMLType column (i.e.,

1321

column_flag has OCI_LCR_COLUMN_XML_DATA bit set).

1322

chunk_bytes (IN) - Chunk data length in bytes.

1323

chunk_data (IN) - Chunk data buffer.

1324

flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set, this means

1325

the current LCR has more chunks.

1326

RETURNS

1327

This callback function must return OCI_CONTINUE to continue processing

1328

OCIXStreamOutLCRCallbackReceive call. Any return code other than

1329

OCI_CONTINUE signals that the client wants to terminate

1330

OCIXStreamOutLCRCallbackReceive immediately.

1331

*/

1332

typedef sb4 (*OCICallbackXStreamOutChunkProcess)

1333

(void *usrctxp, oratext *column_name, ub2 column_name_len,

1334

ub2 column_dty, oraub8 column_flag, ub2 column_csid,

1335

ub4 chunk_bytes, ub1 *chunk_data, oraub8 flag);

1336

1337

/*-------------------- OCIXStreamOutLCRCallbackReceive ----------------------*/

1338

/*

1339

NAME

1340

OCIXStreamOutLCRCallbackReceive - OCI Receive LCR stream using Callbacks

1341

DESCRIPTION

1342

This API is used to get the LCR stream from the outbound server using

1343

callbacks to gain better performance. The user must supply a callback

1344

function to be invoked for each LCR received. If some row changes

1345

in the stream may contain LOB/LONG/XMLType columns then the data for

1346

those columns are returned to the user in chunks. To receive those row

1347

changes, the user must provide a second callback to be invoked to

1348

process each chunk data.

1349

1350

If there is an LCR available in the stream, the processlcr_cb function

1351

is invoked immediately. After the processlcr_cb function exits, if the

1352

current LCR contains additional chunks then the processchunk_cb function

1353

is invoked for each chunk belonging to that LCR.

1354

1355

If there is no LCR in the stream when the idle timeout expires (see

1356

OCI_ATTR_XSTREAM_IDLE_TIMEOUT), this call returns a null LCR with

1357

OCI_SUCCESS code.

1358

PARAMETERS

1359

svchp (IN/OUT) - OCI service handle

1360

errhp (IN/OUT) - Error Handle for error reporting

1361

processlcr_cb (IN) - Client callback function for each LCR.

1362

processchunk_cb (IN) - Client callback function for each

1363

chunk.

1364

usrctxp (IN) - Client context. (Optional)

1365

fetch_low_position (OUT)- Fetch low watermark. (Optional)

1366

fetch_low_position_len (OUT)- Fetch low watermark length.

1367

mode (IN) - mode for future extension. (Not used

1368

currently).

1369

RETURNS

1370

OCI_SUCCESS or OCI_ERROR.

1371

NOTES

1372

- The fetch low watermark is used to indicate all transactions

1373

with commit position below this have been received by the XStream

1374

outbound server.

1375

1376

- If the LCR contains non-chunked column(s), the duration of that LCR is

1377

limited to the processlcr_cb function. If the LCR contains some

1378

chunk data then the duration of the LCR is extended until all the

1379

chunks have been processed (that is, when the flag passing to

1380

processchunk_cb function does not have OCI_XSTREAM_MORE_ROW_DATA flag

1381

set). If the user wants to access the LCR data at a later time, a

1382

copy of the LCR must be made. The client callback should not modify

1383

or free the LCR passing to the callback.

1384

1385

If the OCIXSTREAM_OUT_ATTACH_APP_FREE_LCR mode is passed to

1386

OCIXStreamOutAttach call then the application is in charge of calling

1387

OCILCRFree to free each LCR. Note, this mode does not apply to the

1388

chunk data associated with each LCR. Each chunk data is freed

1389

immediately after each OCIXStreamOutChunkReceive call.

1390

1391

- The given usrctxp is passed to both callbacks.

1392

1393

- An ACK interval is the interval in seconds which the outbound

1394

server receives the processed LWM or the inbound server sends

1395

the processed LWM. The default ACK interval is 30 seconds. This

1396

value can be changed by setting the OCI_ATTR_XSTREAM_ACK_INTERVAL

1397

attribute using OCIAttrSet API. This attribute is checked only

1398

during the Attach call; thus, it must be set before invoking this API.

1399

1400

- The idle timeout is the interval in seconds after which the current

1401

call will terminate if there is no LCR in the stream. The default

1402

idle timeout is one second. This value can be changed by setting the

1403

OCI_ATTR_XSTREAM_IDLE_TIMEOUT attribute using OCIAttrSet API. This

1404

attribute is checked only during the Attach call; thus, it must be

1405

set before invoking this API.

1406

1407

- The outbound server ends each call at the transaction boundary

1408

after an ACK interval has elapsed since the start of the call

1409

or when the idle timeout expires. This API returns the fetch

1410

low watermark at the end of each call.

1411

*/

1412

sword OCIXStreamOutLCRCallbackReceive(

1413

OCISvcCtx *svchp, OCIError *errhp,

1414

OCICallbackXStreamOutLCRProcess processlcr_cb,

1415

OCICallbackXStreamOutChunkProcess processchunk_cb, void *usrctxp,

1416

ub1 *fetch_low_position, ub2 *fetch_low_position_len, ub4 mode);

1417

1418

/*---------------------- OCIXStreamOutLCRReceive -------------------------*/

1419

/*

1420

NAME

1421

OCIXStreamOutLCRReceive - Receive LCR without using callback

1422

DESCRIPTION

1423

This API is used to receive an LCR from an outbound stream. If there

1424

is an LCR available, this API immediately returns that LCR.

1425

When there is no LCR available in the stream, this call returns a

1426

null LCR after the idle timeout (see OCI_ATTR_XSTREAM_IDLE_TIMEOUT)

1427

has expired.

1428

1429

The client must not modify the LCR received from the outbound server.

1430

The duration of each LCR is until the next OCIXStreamOutLCRReceive call.

1431

If the OCIXSTREAM_OUT_ATTACH_APP_FREE_LCR mode is passed to

1432

OCIXStreamOutAttach call then the application is in charge of calling

1433

OCILCRFree to free each LCR. Note, this mode does not apply to the

1434

chunk data associated with each LCR. Each chunk data is freed

1435

immediately after each OCIXStreamOutChunkReceive call.

1436

1437

To avoid network round trip for every OCIXStreamOutLCRReceive call,

1438

the connection is tied to this call to let the server fill up

1439

the network buffer with LCRs so subsequent calls can quickly receive

1440

the LCRs from the network. The server ends each call at the

1441

transaction boundary after an ACK interval has elapsed since the start

1442

of the call or when the idle timeout expires. See

1443

OCI_ATTR_XSTREAM_ACK_INTERVAL & OCI_ATTR_XSTREAM_IDLE_TIMEOUT

1444

attributes.

1445

PARAMETERS

1446

svchp (IN/OUT) - OCI service handle

1447

errhp (IN/OUT) - Error Handle for error reporting

1448

lcrp (OUT) - Pointer to the LCR received from the

1449

stream.

1450

lcrtype (OUT) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL)

1451

flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1452

it means the current LCR has more

1453

chunk data.

1454

fetch_low_position (OUT)- Fetch low watermark. (Optional)

1455

fetch_low_position_len (OUT)- Fetch low watermark length.

1456

mode (IN) - mode for future extension. (Not used

1457

currently).

1458

RETURNS

1459

- OCI_STILL_EXECUTING means the current call is still in progress. The

1460

connection associated with the specified service context handle is

1461

still tied to this call for streaming the LCRs from the server. An

1462

error is returned if the user attempts to use the same connection to

1463

execute any OCI calls that require database round trip, for example,

1464

OCIStmtExecute, OCIStmtFetch, OCILobRead, etc. OCILcr* calls are

1465

local calls; thus, they are valid while the stream is in progress.

1466

- OCI_SUCCESS means the current call is completed. User is free to

1467

execute OCIStmt*, OCILob*, etc. from the same service context.

1468

- OCI_ERROR means the current call encounters some errors. Use

1469

OCIErrorGet to obtain information about the error.

1470

1471

NOTES

1472

This call always returns a null LCR when the return code is OCI_SUCCESS.

1473

In addition, it returns the fetch low position to denote the outbound

1474

server has received all transactions with commit position lower than or

1475

equal to this value.

1476

1477

The fetch low watermark is used to indicate all transactions

1478

with commit position below this have been received by the XStream

outbound server.

*/

sword OCIXStreamOutLCRReceive(

1483

OCISvcCtx *svchp, OCIError *errhp,

void **lcrp,

ub1 *lcrtype,

oraub8 *flag,

ub1 *fetch_low_position,

1488

ub2 *fetch_low_position_len,

1489

ub4 mode);

1490

1491

/*-------------------------- OCIXStreamOutChunkReceive ---------------------*/

1492

/*

1493

NAME

1494

OCIXStreamOutChunkReceive - Receive Chunk data

1495

DESCRIPTION

1496

Receives next chunk of LCR data from XStream Outbound server.

1497

This API can only be called while OCIXStreamOutLCRReceive call is

1498

in progress.

1499

PARAMETERS

1500

svchp (IN/OUT) - OCI service handle

1501

errhp (IN/OUT) - Error Handle to which errors should be reported

1502

column_name (OUT) - Name of column for which data is retrieved.

1503

column_name_len (OUT) - Length of column name.

1504

column_dty (OUT) - LCR column data type.

1505

column_flag (OUT) - LCR column flag. Possible bit values are

1506

OCI_LCR_COLUMN_LOB_DATA

1507

OCI_LCR_COLUMN_LONG_DATA

1508

OCI_LCR_COLUMN_EMPTY_LOB

1509

OCI_LCR_COLUMN_LAST_CHUNK

1510

OCI_LCR_COLUMN_AL16UTF16

1511

OCI_LCR_COLUMN_ENCRYPTED

1512

OCI_LCR_COLUMN_NCLOB

1513

OCI_LCR_COLUMN_XML_DATA

1514

OCI_LCR_COLUMN_XML_DIFF

1515

column_csid (OUT) - Column character set id. This is returned only

1516

if the column is an XMLType column (i.e.,

1517

column_flag has OCI_LCR_COLUMN_XML_DATA bit

1518

set).

1519

chunk_bytes (OUT) - Number of bytes in output buffer.

1520

chunk_data (OUT) - Pointer to the chunk data in the LCR.

1521

Client must not de-allocate this pointer.

1522

flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set, it means

1523

the current LCR has more data coming.

1524

mode (IN) - mode for future extension. (Not used currently).

1525

RETURNS

1526

OCI_SUCCESS - Check colname_len and chunk_bytes to determine the

1527

data just read.

1528

OCI_ERROR - Error encountered. Execute OCIErrorGet to get information

1529

about the error.

1530

NOTES

1531

- If the return code is OCI_SUCCESS, client should check chunk_bytes to

1532

determine the # of bytes read and check column_name to determine

1533

which LCR column the data associated with.

1534

1535

- All the chunks from one LOB/LONG/XMLType column are returned entirely

1536

before the chunk value for the next LOB/LONG/XMLType column is

1537

returned.

1538

1539

- The is no fixed ordering on how the LOB/LONG/XMLType columns is

1540

returned. Users must check the column name to determine which column.

1541

The column_flag will have OCI_LCR_COLUMN_LAST_CHUNK bit set when this

1542

function returns the last chunk of each column.

1543

1544

- This call returns a null column name and null chunk data if it's

1545

invoked when the current LCR contains only non-chunked columns.

1546

1547

- If OCIXStreamOutLCRReceive call returns OCI_XSTREAM_MORE_ROW_DATA flag

1548

then the user must iteratively call OCIXStreamOutChunkReceive to

1549

retrieve all the chunks belonging to the current row change before

1550

calling the next OCIXStreamOutLCRReceive.

1551

1552

*/

1553

sword OCIXStreamOutChunkReceive(OCISvcCtx *svchp, OCIError *errhp,

1554

oratext **column_name, ub2 *column_name_len,

1555

ub2 *column_dty, oraub8 *column_flag,

1556

ub2 *column_csid, ub4 *chunk_bytes,

1557

ub1 **chunk_data, oraub8 *flag, ub4 mode);

1558

1559

/*------------------------- OCIXStreamOutDetach -----------------------------*/

1560

/*

1561

NAME

1562

OCIXStreamOutDetach - OCI Detach from XStream Out

1563

DESCRIPTION

1564

Detaches from the attached XStream outbound server. This call sends the

1565

current local processed low-watermark to the server before detaching

1566

from the outbound server. The outbound server automatically restarts

1567

after this call. This API returns OCI_ERROR if it is invoked while a

1568

ReceiveLCR call is in progress.

1569

PARAMETERS

1570

svchp (IN/OUT) - OCI service handle

1571

errhp (IN/OUT) - Error Handle to which errors should be reported

1572

mode (IN) - mode for future extension. (Not used currently).

1573

RETURNS

1574

OCI_SUCCESS or OCI_ERROR.

1575

NOTES

1576

- The processed_low_position is passed to the server so it can update its

1577

copy. This value if provided must be greater than or equal to the

1578

value maintained in the server; otherwise, an error is returned.

1579

*/

1580

sword OCIXStreamOutDetach (OCISvcCtx *svchp, OCIError *errhp, ub4 mode);

1581

1582

/*---------------------------------------------------------------------------

1583

STREAMS XSTREAM IN FUNCTIONS

1584

---------------------------------------------------------------------------*/

1585

1586

/*------------------------ OCIXStreamInAttach -------------------------------*/

1587

/*

1588

NAME

1589

OCIXStreamInAttach - OCI XStream In Attach

1590

DESCRIPTION

1591

Attaches to the specified XStream inbound server.

1592

PARAMETERS

1593

svchp (IN/OUT) - OCI service handle

1594

errhp (IN/OUT) - Error Handle to which errors

1595

should be reported

1596

server_name (IN) - XStream inbound server name.

1597

server_name_len (IN) - Length of server name.

1598

source_name (IN) - source name to identify the data src.

1599

source_name_len (IN) - Length of source name.

1600

last_position (OUT) - Last position received by inbound

1601

server. Optional. If specified must

1602

pre-allocate OCI_LCR_MAX_POSITION_LEN

1603

bytes for return value.

1604

last_position_len (OUT) - Length of last_position. Must be

1605

non-NULL if last_position is non-NULL.

1606

mode (IN) - Mode flags (For future extension.

1607

(Not used currently)

1608

RETURNS

1609

OCI_SUCCESS or OCI_ERROR.

1610

NOTES

1611

The last_position parameter is returned to establish the starting point

1612

to resume the inbound stream. The client should start sending LCRs with

1613

positions greater than the last_position since the inbound server will

1614

ignore all LCRs with positions less than or equal to this value.

1615

*/

1616

1617

sword OCIXStreamInAttach(

1618

OCISvcCtx *svchp,

1619

OCIError *errhp,

1620

oratext *server_name,

1621

ub2 server_name_len,

1622

oratext *source_name,

1623

ub2 source_name_len,

1624

ub1 *last_position,

1625

ub2 *last_position_len,

1626

ub4 mode);

1627

1628

/*--------- Valid modes for OCIXStreamInAttach -------------*/

1629

/* Restart inbound server regardless if it's in DISABLED or ABORTED state. */

1630

#define OCIXSTREAM_IN_ATTACH_RESTART_INBOUND (0x00000001)

1631

1632

/*-------------------- OCICallbackXStreamInLCRCreate ------------------------*/

1633

/*

1634

NAME

1635

OCICallbackXStreamInLCRCreate - Callback to create an LCR

1636

DESCRIPTION

1637

This callback is invoked during OCIXStreamInLCRCallbackSend

1638

to create each LCR to be sent to the inbound server.

1639

PARAMETERS

1640

usrctxp (IN/OUT) - Ptr to the user context

1641

lcrp (OUT) - Pointer to the LCR to be sent

1642

lcrtyp (OUT) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL)

1643

flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1644

this means the current LCR has more

1645

chunk data.

1646

RETURNS

1647

This callback function must return OCI_CONTINUE to continue processing

1648

OCIXStreamInLCRCallbackSend call. Any return code other than

1649

OCI_CONTINUE signals that the client wants to terminate

1650

OCIXStreamInLCRCallbackSend immediately.

1651

*/

1652

typedef sb4 (*OCICallbackXStreamInLCRCreate)(

void *usrctxp,

void **lcrp,

ub1 *lcrtyp,

oraub8 *flag);

/*-------------------- OCICallbackXStreamInChunkCreate --------------------*/

1659

/*

1660

NAME

1661

OCICallbackXStreamInChunkCreate - Callback to create each chunk

1662

DESCRIPTION

1663

This callback is invoked during OCIXStreamInLCRCallbackSend

1664

to create each chunk to be sent to the inbound server.

1665

PARAMETERS

1666

usrctxp (IN/OUT) - Ptr to the user context.

1667

column_name (OUT) - Column name for the current chunk.

1668

column_name_len (OUT) - Length of column name.

1669

column_dty (OUT) - Chunk data type (SQLT_CHR or SQLT_BIN).

1670

column_flag (OUT) - LCR column flags. Possible bit values are

1671

OCI_LCR_COLUMN_* flags listed above.

1672

column_csid (OUT) - Column character set id. Relevant only if

1673

the column is an XMLType column (i.e.,

1674

column_flag has OCI_LCR_COLUMN_XML_DATA bit

1675

set).

1676

chunk_bytes (OUT) - Chunk data length in bytes.

1677

chunk_data (OUT) - Chunk data buffer.

1678

flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set, this means

1679

the current LCR has more chunks.

1680

RETURNS

1681

This callback function must return OCI_CONTINUE to continue processing

1682

OCIXStreamInLCRCallbackSend call. Any return code other than

1683

OCI_CONTINUE signals that the client wants to terminate

1684

OCIXStreamInLCRCallbackSend immediately.

1685

*/

1686

typedef sb4 (*OCICallbackXStreamInChunkCreate)(

1687

void *usrctxp,

1688

oratext **column_name,

1689

ub2 *column_name_len,

ub2 *column_dty,

oraub8 *column_flag,

ub2 *column_csid,

ub4 *chunk_bytes,

ub1 **chunk_data,

oraub8 *flag);

/*--------------------- OCIXStreamInLCRCallbackSend ------------------------*/

1698

/*

1699

NAME

1700

OCIXStreamInLCRCallbackSend - OCI XStream In Send LCR to Inbound Server

1701

DESCRIPTION

1702

Sends LCR stream to XStream inbound server using callbacks.

1703

The API invokes createlcr_cb function to obtain each LCR to send to the

1704

server. If the return flag from the createlcr_cb function has

1705

OCI_XSTREAM_MORE_ROW_DATA bit set, then it invokes createchunk_cb

1706

procedure to obtain each chunk. It repeatedly calls createchunk_cb

1707

function while the flag returned from this callback has

1708

OCI_XSTREAM_MORE_ROW_DATA bit set. When this bit is not set, this API

1709

cycles back to invoke createlcr_cb function to get the next LCR.

1710

This cycle is repeated until the createlcr_cb function returns a null

1711

LCR or when an ACK interval has elapsed since the start of the call.

1712

See OCI_ATTR_XSTREAM_ACK_INTERVAL attribute.

1713

PARAMETERS

1714

svchp (IN/OUT) - OCI service handle

1715

errhp (IN/OUT) - Error Handle to which errors

1716

should be reported

1717

createlcr_cb (IN) - Callback function to be invoked

1718

to generate an LCR for streaming.

1719

Cannot be null.

1720

createchunk_cb (IN) - Callback function to be invoked to

1721

create each chunk. Can be null if the

1722

user does not need to send any LCR with

1723

LOB/LONG/XMLType columns. OCI_ERROR

1724

will be returned if this argument is

1725

null and the user attempts to send an

1726

LCR with additional chunk data.

1727

usrctxp (IN) - Client context to pass to both

1728

callback functions.

1729

mode (IN) - Mode flags (For future extension.

1730

Not used currently)

1731

RETURNS

1732

OCI_SUCCESS or OCI_ERROR.

NOTES

None

*/

sword OCIXStreamInLCRCallbackSend(

1738

OCISvcCtx *svchp,

1739

OCIError *errhp,

1740

OCICallbackXStreamInLCRCreate createlcr_cb,

1741

OCICallbackXStreamInChunkCreate createchunk_cb,

void *userctxp,

ub4 mode);

/*---------------------------- OCIXStreamInLCRSend --------------------------*/

1746

/*

1747

NAME

1748

OCIXStreamInLCRSend - OCI XStream In Send LCR to Inbound Server

1749

DESCRIPTION

1750

Sends LCR stream to XStream inbound server without using callbacks.

1751

To avoid a network round trip for every OCIXStreamInLCRSend call,

1752

the connection is tied to this call for at least the duration

1753

specified by the OCI_ATTR_XSTREAM_ACK_INTERVAL attribute.

1754

PARAMETERS

1755

svchp (IN/OUT) - OCI service handle

1756

errhp (IN/OUT) - Error Handle to which errors

1757

should be reported

1758

lcrp (IN) - Pointer to the LCR to send. Cannot

1759

be null.

1760

lcrtype (IN) - LCR type (OCI_LCR_XROW / OCI_LCR_XDDL)

1761

flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1762

it means the current LCR has more

1763

chunk data.

1764

mode (IN) - Mode flags (For future extension.

1765

Not used currently)

1766

RETURNS

1767

- OCI_STILL_EXECUTING means the current call is still in progress. The

1768

connection associated with the specified service context handle is

1769

still tied to this call for streaming the LCRs to the server. An error

1770

is returned if the user attempts to use the same connection to

1771

execute any OCI calls that require database round trip, for example,

1772

OCIStmtExecute, OCIStmtFetch, OCILobRead, etc. OCILcr* calls are

1773

local calls; thus, they are valid while this call is in progress.

1774

- OCI_SUCCESS means the current call is completed. User is free to

1775

execute OCIStmt*, OCILob*, etc. from the same service context.

1776

- OCI_ERROR means this call encounters some errors. Use OCIErrorGet to

1777

obtain information about the error.

1778

*/

1779

sword OCIXStreamInLCRSend(

OCISvcCtx *svchp,

OCIError *errhp,

void *lcrp,

ub1 lcrtype,

oraub8 flag,

ub4 mode);

/*----------------------------- OCIXStreamInChunkSend -----------------------*/

1788

/*

1789

NAME

1790

OCIXStreamInChunkSend - Send Chunk

1791

DESCRIPTION

1792

Sends the given chunk of column data to XStream Inbound server.

1793

This chunk is associated with the LCR that is sent by the

1794

most recent OCIXStreamInLCRSend call prior to this call.

1795

PARAMETERS

1796

svchp (IN/OUT) - OCI service handle

1797

errhp (IN/OUT) - Error Handle to which errors should be reported

1798

column_name (IN) - Name of column for which data is sent.

1799

Column names must be canonicalized and must

1800

follow Oracle naming conventions.

1801

column_name_len (IN) - Length of column name.

1802

column_dty (IN) - LCR column data type (must be SQLT_CHR or

1803

SQLT_BIN).

1804

column_flag (IN) - LCR column flags. Possible bit values are

1805

OCI_LCR_COLUMN_LOB_DATA

1806

OCI_LCR_COLUMN_LONG_DATA

1807

OCI_LCR_COLUMN_EMPTY_LOB

1808

OCI_LCR_COLUMN_LAST_CHUNK

1809

OCI_LCR_COLUMN_AL16UTF16

1810

OCI_LCR_COLUMN_ENCRYPTED

1811

OCI_LCR_COLUMN_NCLOB

1812

OCI_LCR_COLUMN_XML_DATA

1813

OCI_LCR_COLUMN_XML_DIFF

1814

column_csid (IN) - Column character set id. This is required only

1815

if the column is an XMLType column (i.e.,

1816

column_flag has OCI_LCR_COLUMN_XML_DATA bit set).

1817

chunk_bytes (IN) - Chunk data length in bytes.

1818

chunk_data (IN) - Chunk data buffer.

1819

flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set, it means

1820

the current LCR has more data coming.

1821

mode (IN) - mode for future extension. (Not used currently).

1822

RETURNS

1823

OCI_SUCCESS - Successful call.

1824

OCI_ERROR - Error encountered. Execute OCIErrorGet to get information

1825

about the error.

1826

NOTES

1827

- This function must be called while OCIXStreamInLCRSend is in progress.

1828

1829

- This function is valid only if the associated LCR's cmd type is

1830

INSERT, UPDATE or LOB_WRITE. It can be invoked multiple times for the

1831

same LCR.

1832

1833

- This API is not valid for LOB_ERASE and LOB_TRIM LCRs.

1834

1835

- The chunk values for different columns can not be interleaved. If a

1836

column contains multiple chunks, this procedure must be called

1837

consecutively using the same column name before proceeding to a new column.

1838

The ordering in which the LOB/LONG/XMLType column values are set is

1839

irrelevant.

1840

1841

- The OCI_LCR_COLUMN_LAST_CHUNK must be specified for the last chunk of

1842

each column.

1843

1844

- Only one column can be specified for LOB_WRITE operation.

1845

1846

- For NCLOB or varying width CLOB, the input buffer must be in

1847

AL16UTF16 format.

1848

1849

- For INSERT operation, each LOB/LONG/XMLType column, with value set using

1850

OCIXStreamInChunkSend, must be included in the current LCR's NEW

1851

column list. The value of that LOB/LONG/XMLType column must be set to

1852

null and must have OCI_LCR_COLUMN_EMPTY_LOB flag defined.

1853

1854

*/

1855

sword OCIXStreamInChunkSend (OCISvcCtx *svchp, OCIError *errhp,

1856

oratext *column_name, ub2 column_name_len,

1857

ub2 column_dty, oraub8 column_flag,

1858

ub2 column_csid, ub4 chunk_bytes,

1859

ub1 *chunk_data, oraub8 flag, ub4 mode);

1860

1861

/*--------------------- OCIXStreamInDetach ----------------------------*/

1862

/*

1863

NAME

1864

OCIXStreamInDetach - OCI XStream In Detach from Inbound Server

1865

DESCRIPTION

1866

Detaches from XStream inbound server and returns the inbound server's

1867

processed low-watermark.

1868

PARAMETERS

1869

svchp (IN/OUT) - OCI service handle

1870

errhp (IN/OUT) - Error Handle to which errors

1871

should be reported

1872

processed_low_position (OUT) - Inbound server's processed low

1873

position. Must pre-allocate

1874

OCI_LCR_MAX_POSITION_LEN bytes for

1875

output buffer.

1876

processed_low_position_len(OUT)- Processed_low_position length.

1877

mode (IN) - Mode flags (For future extension.

1878

Not used currently)

1879

RETURNS

1880

OCI_SUCCESS or OCI_ERROR.

NOTES

None

*/

sword OCIXStreamInDetach(

1885

OCISvcCtx *svchp,

1886

OCIError *errhp,

1887

ub1 *processed_low_position,

1888

ub2 *processed_low_position_len,

1889

ub4 mode);

1890

1891

/*--------- Valid modes for OCIXStreamInDetach -------------*/

1892

/* Restart inbound server when calling detach. */

1893

#define OCIXSTREAM_IN_DETACH_RESTART_INBOUND (0x00000001)

1894

1895

/*--------------------- OCIXStreamInProcessedLWMGet -------------------------*/

1896

/*

1897

NAME

1898

OCIXStreamInProcessedLWMGet - OCI XStream In Get LowWatermark

1899

DESCRIPTION

1900

Returns XStream inbound server's processed low watermark

1901

cached at the client.

1902

PARAMETERS

1903

svchp (IN/OUT) - OCI service handle

1904

errhp (IN/OUT) - Error Handle to which errors

1905

should be reported

1906

processed_low_position (OUT) - Inbound server's cached processed

1907

low position. Must pre-

1908

allocate OCI_LCR_MAX_POSITION_LEN

1909

bytes for output buffer.

1910

processed_low_position_len (OUT) - Processed_low_position length.

1911

mode (IN) - Mode flags (For future extension.

1912

Not used currently)

1913

RETURNS

1914

OCI_SUCCESS or OCI_ERROR.

NOTES

None

*/

sword OCIXStreamInProcessedLWMGet(

1919

OCISvcCtx *svchp,

1920

OCIError *errhp,

1921

ub1 *processed_low_position,

1922

ub2 *processed_low_position_len,

1923

ub4 mode);

1924

1925

/*-------------------------- OCIXStreamInFlush ------------------------------*/

1926

/*

1927

NAME

1928

OCIXStreamInFlush - OCI XStream In Flush network

1929

DESCRIPTION

1930

Flushes network and terminates any in-progress OCIXStreamInLCRSend or

1931

OCIXStreamInLCRCallbackSend call associated with the given service handle.

1932

PARAMETERS

1933

svchp (IN/OUT) - OCI service handle

1934

errhp (IN/OUT) - Error Handle to which errors

1935

should be reported

1936

mode (IN) - Mode flags (see below)

1937

RETURNS

1938

OCI_SUCCESS or OCI_ERROR.

1939

NOTES

1940

Each call will incur a database round trip to get the server's processed

1941

low-watermark, which the user can retrieve afterward using

1942

OCIXStreamInProcessedLWMGet API. This API should be called only when

1943

there is no LCR to send to the server and the client wants to know the

1944

progress of the attached inbound server.

1945

1946

This call returns OCI_ERROR if it is invoked from the callback functions

1947

of OCIXStreamInLCRCallbackSend API.

1948

1949

Client must have attached to an XStream inbound server prior to calling

this API.

Valid Mode flags:

- OCIXSTREAM_IN_FLUSH_WAIT_FOR_COMPLETE : flush network and wait for all

1954

complete and rollback transactions sent to the inbound server to complete

1955

before returning control to the client.

1956

1957

*/

1958

sword OCIXStreamInFlush(

OCISvcCtx *svchp,

OCIError *errhp,

ub4 mode);

/*-------------------------- OCIXStreamInCommit -----------------------------*/

1965

/*

1966

NAME

1967

OCIXStreamInCommit - OCI XStream In Commit

1968

DESCRIPTION

1969

Commits current transaction

1970

PARAMETERS

1971

svchp (IN/OUT) - OCI service handle

1972

errhp (IN/OUT) - Error Handle to which errors

1973

should be reported

1974

lcrp (IN) - Pointer to the LCR to send. Must

1975

be a commit LCR.

1976

mode (IN) - Mode flags (For future extension.

1977

Not used currently)

1978

RETURNS

1979

OCI_SUCCESS or OCI_ERROR.

1980

NOTES

1981

The position of the input LCR must be higher than

1982

DBA_XSTREAM_INBOUND_PROGRESS.APPLIED_HIGH_POSITION and the LCR's source

1983

database must match DBA_APPLY_PROGRESS.SOURCE_DATABASE of the attached

1984

inbound server.

1985

1986

Upon receiving this LCR, the inbound server will check if there is any

1987

unapplied complete or rollback transaction remaining. If none is found

1988

it inserts a row to the apply progress table based on the input LCR and

1989

commit the current transaction; otherwise, it returns an error.

1990

1991

If there is any pre-commit handler defined, it will be executed when

1992

this commit LCR is executed.

1993

*/

1994

sword OCIXStreamInCommit(

OCISvcCtx *svchp,

OCIError *errhp,

void *lcrp,

ub4 mode);

/*-------------------------- OCIXStreamInErrorGet ---------------------------*/

2001

/*

2002

NAME

2003

OCIXStreamInErrorGet - OCI XStream In Get Error Info

2004

DESCRIPTION

2005

Returns the first error encountered by the inbound server since the

2006

Attach call.

2007

PARAMETERS

2008

svchp (IN/OUT) - OCI service handle

2009

errhp (IN/OUT) - Error Handle

2010

errcodep (OUT) - Error code

2011

msgbuf (IN/OUT) - Pre-allocated message buffer

2012

msg_bufsize (IN) - Message buffer size

2013

msg_len (OUT) - Length of returned error message

2014

txn_id (IN/OUT) - Pre-allocated txn id buffer

2015

txn_id_bufsize (IN) - Txn_id buffer size

2016

txn_id_len (OUT) - Length of returned txn id

2017

RETURNS

2018

OCI_SUCCESS or OCI_ERROR.

2019

NOTES

2020

The maximum size for the returned txn id is OCI_LCR_MAX_TXID_LEN. If the

2021

allocated buffer for txn_id is too small, this routine returns ORA-29258.

2022

The maximum size for the returned error msg is OCI_ERROR_MAXMSG_SIZE. If

2023

the allocated size for msgbuf is too small, the returned message will be

2024

truncated.

2025

*/

2026

sword OCIXStreamInErrorGet(

OCISvcCtx *svchp,

OCIError *errhp,

sb4 *errcodep,

oratext *msgbuf,

ub2 msg_bufsize,

ub2 *msg_len,

oratext *txn_id,

ub2 txn_id_bufsize,

ub2 *txn_id_len);

/*---------------------------------------------------------------------------

2038

INTERNAL FUNCTIONS

2039

---------------------------------------------------------------------------*/

#ifdef __cplusplus

}

#endif /* __cplusplus */

2045

2046

#endif /* OCIXSTREAM_ORACLE */