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

Tang Cheng

37650ea

2014-10-20 16:14:41 +0800

[diff] [blame^]

/*

NAME

ocixstream.h - OCI XStream APIs

DESCRIPTION

OCI APIs for XStream

RELATED DOCUMENTS

EXPORT FUNCTION(S)

INTERNAL FUNCTION(S)

EXAMPLES

NOTES

MODIFIED (MM/DD/YY)

fergutie 01/30/13 - Backport fergutie_bug-14496414 from main

23

thoang 02/15/12 - Backport thoang_bug-13444033 from main

24

huntran 09/02/12 - Backport huntran_bug-13471035 from

25

huntran 05/09/12 - Backport huntran_bug-13042334 from main

26

apfwkr 02/13/12 - Backport vchandar_bug-13058458 from main

27

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

28

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

29

elu 04/12/11 - xmlschema

30

elu 03/28/11 - xmlschema

31

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

32

thoang 12/04/11 - Add OCI_ROWLCR_IS_INFLIGHT_TXN

33

elu 05/25/11 - remove xml schema

34

thoang 03/10/10 - Add OCIXSTREAM_IN_ATTACH_RESTART_INBOUND mode

35

thoang 12/28/09 - Update comments

36

elu 01/07/10 - stmt lcr

37

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

38

thoang 12/09/09 - Add note to OCIXStreamInErrorGet

39

thoang 12/04/09 - Remove ProcessedLWMGet2/Set2

40

rmao 11/20/09 - add OCI_ROWLCR_SEQ_LCR

41

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

42

bpwang 10/09/09 - Add OCI_ROWLCR_HAS_ID_KEY_ONLY

43

elu 10/05/09 - add stmt LCR

44

rihuang 10/06/09 - Add OCIXSTREAM_IN_FLUSH_WAIT_FOR_COMPLETE

45

thoang 05/08/09 - Add OCILCR_NEW_ONLY_MODE

46

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

47

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

48

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

49

rihuang 01/05/09 - Add OCI_LCR_ATTR_TRACKING_LABEL

50

tianli 11/28/08 - add DDL flags

51

tianli 11/20/08 - add OCILCRAttribute methods

52

thoang 11/20/08 - Define OCI_LCR_MAX_TXID_LEN

53

tianli 11/07/08 - add edition

54

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

55

thoang 10/16/08 - remove commit position arg

56

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

57

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

58

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

59

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

60

elu 05/08/08 - add pos functions

61

thoang 04/29/08 - API changes

62

jinwu 04/28/08 - add OCILcrGetExtraAttributes

63

elu 04/14/08 - add OCI_LCR_MAX_POSITION_LEN

64

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

65

thoang 02/25/08 - Add GetNextChunk and SetNextChunk

66

rihuang 03/24/08 - Signature change for OCILcrNew

67

elu 03/05/08 - add lcr id

68

praghuna 02/26/08 - Added OCILcrGetRowStmt

69

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

70

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

71

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

72

juyuan 05/23/07 - XStream In

73

thoang 11/13/06 - Add XStream Out methods

74

thoang 11/13/06 - Add LCR getter methods

75

nshodhan 05/12/06 - xstream OCI APIs

76

nshodhan 05/12/06 - Creation

*/

#ifndef OCIXSTREAM_ORACLE

81

# define OCIXSTREAM_ORACLE

82

83

#ifndef ORATYPES

84

# include <oratypes.h>

#endif

#ifndef OCI_ORACLE

# include <oci.h>

#endif

#ifdef __cplusplus

extern "C" {

#endif

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

96

PUBLIC TYPES AND CONSTANTS

97

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

98

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

99

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

100

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

101

102

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

103

#define OCI_LCR_ROW_CMD_INSERT "INSERT"

104

#define OCI_LCR_ROW_CMD_DELETE "DELETE"

105

#define OCI_LCR_ROW_CMD_UPDATE "UPDATE"

106

#define OCI_LCR_ROW_CMD_COMMIT "COMMIT"

107

#define OCI_LCR_ROW_CMD_LOB_WRITE "LOB WRITE"

108

#define OCI_LCR_ROW_CMD_LOB_TRIM "LOB TRIM"

109

#define OCI_LCR_ROW_CMD_LOB_ERASE "LOB ERASE"

110

#define OCI_LCR_ROW_CMD_ROLLBACK "ROLLBACK"

111

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

112

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

113

114

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

115

#define OCI_LCR_ATTR_THREAD_NO "THREAD#"

116

#define OCI_LCR_ATTR_ROW_ID "ROW_ID"

117

#define OCI_LCR_ATTR_SESSION_NO "SESSION#"

118

#define OCI_LCR_ATTR_SERIAL_NO "SERIAL#"

119

#define OCI_LCR_ATTR_USERNAME "USERNAME"

120

#define OCI_LCR_ATTR_TX_NAME "TX_NAME"

121

122

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

123

#define OCI_LCR_ATTR_EDITION_NAME "EDITION_NAME"

124

#define OCI_LCR_ATTR_MESSAGE_TRACKING_LABEL "MESSAGE_TRACKING_LABEL"

125

#define OCI_LCR_ATTR_CURRENT_USER "CURRENT_USER"

126

#define OCI_LCR_ATTR_OLD_OWNER "OLD_OWNER"

127

#define OCI_LCR_ATTR_OLD_ONAME "OLD_ONAME"

128

129

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

130

#define OCI_LCR_ROW_COLVAL_OLD 0 /* OLD columns */

131

#define OCI_LCR_ROW_COLVAL_NEW 1 /* NEW columns */

132

133

/* maximum length for position

134

* NOTE: This MUST be consistent with DefaultRowLCRCache.MaxLowWaterMarkLength

135

* in DefaultRowLCRCache.java

136

*/

137

#define OCI_LCR_MAX_POSITION_LEN 64

138

139

/* maximum length for txid */

140

#define OCI_LCR_MAX_TXID_LEN 128

141

142

/* Valid column flags used in OCILCRRowColumnInfoSet, OCILCRRowColumnInfoGet,

143

* OCILCRLobInfoSet, OCILCRLobInfoGet, OCIXStreamOutChunkReceive,

144

* OCIXStreamInChunkSend calls.

145

* NOTE: last byte reserved for private OCIP_LCR flags.

146

*/

147

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

148

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

149

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

150

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

151

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

152

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

153

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

154

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

155

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

156

157

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

158

* column list of an update LCR.

159

*/

160

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

161

162

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

167

/* (0x00000002) is RESERVED */

168

/* (0x00000004) is RESERVED */

169

/* (0x00000008) is RESERVED */

170

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

171

172

/* LCR belongs to an inflight transaction, i.e., transaction was started

173

* before the outbound server's starting position.

174

*/

175

#define OCI_ROWLCR_IS_INFLIGHT_TXN (0x00000020)

176

177

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

178

* - OCIXStreamOutChunkReceive & OCIXStreamOutLCRReceive

179

* - OCIXStreamInChunkSend & OCIXStreamInLCRSend

180

*/

181

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

182

183

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

184

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

185

/* include OLD columns */

186

187

/* Valid mode flag for OCIXStreamInFlush */

188

/* Synchronous mode for OCIXStreamInFlush */

189

#define OCIXSTREAM_IN_FLUSH_WAIT_FOR_COMPLETE (0x00000001)

190

191

/* SessionSet attributes */

192

#define OCIXSTREAM_SESSION_SET_MAX_PARAM_LEN 128

193

#define OCIXSTREAM_ATTR_ATTACH_TIMEOUT "ATTACH_TIMEOUT_SECS"

194

#define OCIXSTREAM_ATTR_MAX_ATTACH_RETRIES "MAX_ATTACH_RETRIES"

195

196

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

197

PRIVATE TYPES AND CONSTANTS

198

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

199

200

201

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

202

EXPORT FUNCTIONS

203

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

204

/*

205

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

206

NAME

207

OCILCRNew - OCI LCR NEW

208

DESCRIPTION

209

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

210

PARAMETERS

211

svchp (IN) - OCI service context

212

errhp (IN) - OCI Error Handle

213

duration (IN) - allocation duration for LCR memory

214

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

215

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

216

mode (IN) - mode

217

NOTES

218

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

219

- For now, specify OCI_DEFAULT for mode

220

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

221

*/

222

sword OCILCRNew(OCISvcCtx *svchp,

223

OCIError *errhp,

224

OCIDuration duration,

ub1 lcrtype,

void **lcrp,

ub4 mode);

/*

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

231

NAME

232

OCILCRFree - OCI LCR FREE

233

DESCRIPTION

234

Free XStream LCR specified by the user

235

PARAMETERS

236

svchp (IN) - OCI service context

237

errhp (IN) - OCI Error Handle

238

lcrp (IN/OUT) - XStream LCR

239

mode (IN) - mode

240

NOTES

241

- For now, specify OCI_DEFAULT for mode

242

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

243

*/

244

sword OCILCRFree(OCISvcCtx *svchp,

OCIError *errhp,

void *lcrp,

ub4 mode);

/*

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

252

NAME

253

OCILCRHeaderSet - OCI LCR Set Header

254

DESCRIPTION

255

Initialize elements of XStream LCR's header

256

PARAMETERS

257

svchp (IN) - OCI service context

258

errhp (IN) - OCI Error Handle

259

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

260

Must be non-NULL.

261

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

262

excluding NULL terminator. Should follow Oracle

263

naming conventions and size limitations.

264

cmd_type (IN) - For ROW LCRs: OCI_LCR_ROW_CMD_XXXXXXX

265

For DDL LCRs: One of the command types

266

corresponding to OCI Reference manual

267

cmd_type_len (IN) - Length of cmd_type.

268

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

269

for COMMIT LCR.

270

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

271

NULL terminator. Should follow Oracle naming

272

conventions and size limitations.

273

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

274

COMIT LCR.

275

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

276

NULL terminator. Should follow Oracle naming

277

conventions and size limitations.

278

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

279

For example, this tag can be used to determine

280

the original source database of the DML

281

statement if apply forwarding is used.

282

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

283

bytes

284

txid (IN) - Transaction ID.

285

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

286

NULL terminator. Should not exceeed

287

OCI_LCR_MAX_TXID_LEN bytes.

288

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

289

source database.

290

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

291

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

292

flag (IN) - LCR flag.

293

lcrp (IN/OUT) - XStream LCR

294

mode (IN) - mode

295

NOTES

296

- For now, specify OCI_DEFAULT for mode

297

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

298

setting the header to the new values.

299

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

300

*/

301

sword OCILCRHeaderSet(OCISvcCtx *svchp,

302

OCIError *errhp,

303

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

/*

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

324

NAME

325

OCILCRHeaderGet - OCI LCR Get Header

326

DESCRIPTION

327

Get header information from XStream LCR

328

PARAMETERS

329

svchp (IN) - OCI service context

330

errhp (IN) - OCI Error Handle

331

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

332

Optional, if src_db_name is specified then

333

must specify src_db_name_len as well.

334

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

335

excluding NULL terminator.

336

Optional, if specified src_db_name_len then

337

must specify src_db_name as well.

338

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

339

cmd_type_len is non-null. Must be null if

340

cmd_type_len is NULL.

341

cmd_type_len (OUT) - Length of cmd_type. Optional.

342

owner (OUT) - Canonicalized table owner name.

343

Optional, if owner is specified then

344

must specify owner_len as well.

345

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

346

NULL terminator.

347

Optional, if owner_len is specified then

348

must specify owner as well.

349

oname (OUT) - Canonicalized table name.

350

Optional, if oname is specified then

351

must specify oname_len as well.

352

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

353

NULL terminator.

354

Optional, if oname_len is specified then

355

must specify oname as well.

356

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

357

For example, this tag can be used to determine

358

the original source database of the

359

DML statement if apply forwarding is used.

360

Optional, if tag is specified then

361

must specify tag_len as well.

362

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

363

Optional, if tag_len is specified then

364

must specify tag as well.

365

txid (OUT) - Transaction ID.

366

Optional, if txid is specified then

367

must specify txid_len as well.

368

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

369

the NULL terminator.

370

Optional, if txid_len is specified then

371

must specify txid as well.

372

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

373

source database. Optional.

374

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

375

Return 0 if input lcr is DDL LCR. Optional.

376

new_columns (OUT) - Number of columns present in either

377

the OLD or NEW column list.

378

Return 0 if input lcr is DDL LCR. Optional.

379

See NOTES below for the special mode supported

380

by this function.

381

position (OUT) - LCR position. Optional.

382

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

383

position is non-null. Must be null if

384

position is null.

385

flag (OUT) - LCR flag. Optional.

386

lcrp (IN) - XStream LCR

387

mode (IN) - mode (see NOTES)

388

NOTES

389

- Parameter src_time is optional. If specified the appropriate return

390

structure must be pre-allocated before calling OCILCRHeaderGet.

391

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

392

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

393

structure).

394

- Valid mode flags:

395

- OCILCR_NEW_ONLY_MODE: if this mode is specified then the new_columns

396

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

397

Otherwise, the new_columns returned is the number of distinct

398

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

399

ROW LCR.

400

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

401

*/

402

403

sword OCILCRHeaderGet(OCISvcCtx *svchp,

404

OCIError *errhp,

405

oratext **src_db_name,

406

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

/*

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

428

NAME

429

OCILCRRowColumnInfoSet - OCI LCR ROW SET COLUMN INFO

430

DESCRIPTION

431

Populates column information as specified by the user.

432

PARAMETERS

433

svchp (IN) - OCI service context

434

errhp (IN) - OCI Error Handle

435

column_value_type (IN) - ROW LCR column value type:

436

- OCI_LCR_ROW_COLVAL_OLD

437

- OCI_LCR_ROW_COLVAL_NEW

438

num_columns (IN) - Number of columns to be populated

439

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

440

names must be canonicalized. Column names should

441

follow Oracle naming conventions

442

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

443

in bytes, excluding the NULL terminator.

444

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

445

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

446

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

447

this is a pointer to an array of OCIInd values

448

(OCI_IND_NULL/OCI_IND_NOTNULL).

449

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

450

bytes.

451

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

452

the columns. The default form is SQLCS_IMPLICIT.

453

Setting this attribute will cause the database or

454

national character set to be used on the client

455

side. Set this attribute to SQLCS_NCHAR for the

456

national character set or SQLCS_IMPLICIT for the

457

database character set.

458

Pass 0 for non-character columns.

459

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

460

Possible bit values are OCI_LCR_COLUMN_* flags

461

listed above.

462

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

463

The character set id is only required for

464

XMLType column; otherwise, the csid is ignored.

465

row_lcrp (IN/OUT)- XStream Row LCR pointer

466

mode (IN) - mode

467

NOTES

468

- For now, specify OCI_DEFAULT for mode

469

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

470

*/

471

sword OCILCRRowColumnInfoSet(OCISvcCtx *svchp,

472

OCIError *errhp,

473

ub2 column_value_type,

474

ub2 num_columns,

475

oratext **column_names,

476

ub2 *column_name_lens,

477

ub2 *column_dtyp,

478

void **column_valuesp,

OCIInd *column_indp,

ub2 *column_alensp,

ub1 *column_csetfp,

oraub8 *column_flags,

ub2 *column_csid,

void *row_lcrp,

ub4 mode);

/*

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

489

NAME

490

OCILCRRowColumnInfoGet - OCI LCR ROW GET COLUMN INFO

491

DESCRIPTION

492

Returns column information as requested by the user.

493

PARAMETERS

494

svchp (IN) - OCI service context

495

errhp (IN) - OCI Error Handle

496

column_value_type (IN) - ROW LCR column value type:

497

- OCI_LCR_ROW_COLVAL_OLD

498

- OCI_LCR_ROW_COLVAL_NEW

499

(See NOTES for special mode supported by this

500

function.)

501

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

502

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

503

Optional. If specified then column_namesl must

504

be specified as well, and both arrays must be the

505

size specified by array_size parameter.

506

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

507

in bytes, excluding the NULL terminator.

508

Optional. If specified then column_names must

509

be specified as well, and both arrays must be the

510

size specified by array_size parameter.

511

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

512

Optional. If specified then this array must be

513

the size specified by array_size parameter.

514

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

515

Optional. If specified then this array must be

516

the size specified by array_size parameter.

517

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

518

this is a pointer to an array of OCIInd values

519

(OCI_IND_NULL/OCI_IND_NOTNULL).

520

Optional. If specified then this array must be

521

the size specified by array_size parameter.

522

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

523

bytes.

524

Optional. If specified then this array must be

525

the size specified by array_size parameter.

526

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

527

the columns.

528

Optional. If specified then this array must be

529

the size specified by array_size parameter.

530

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

531

the columns.

532

Optional. If specified then this array must be

533

the size specified by array_size parameter.

534

Possible bit values are OCI_LCR_COLUMN_* flags

535

listed above.

536

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

537

the columns.

538

Optional. If specified then this array must be

539

the size specified by array_size parameter.

540

The column csid is returned only for XMLType

541

column.

542

row_lcrp (IN) - XStream Row LCR pointer

543

array_size (IN) - Size of each of above arrays

544

mode (IN) - mode (see NOTES)

545

NOTES

546

- For now, specify OCI_DEFAULT for mode

547

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

548

in the requested column list then OCI_ERROR is returned. Parameter

549

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

550

- The return values for column_names and column_valuesp will be shallow

551

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

552

Client should not modify those pointers directly.

553

- Valid mode flags:

554

- OCILCR_NEW_ONLY_MODE: this mode is valid only for OCI_LCR_ROW_COLVAL_NEW

555

column_value_type; otherwise, an error is raised.

556

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

557

columns in the NEW column list.

558

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

559

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

560

NEW column list.

561

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

562

*/

563

sword OCILCRRowColumnInfoGet(OCISvcCtx *svchp,

564

OCIError *errhp,

565

ub2 column_value_type,

566

ub2 *num_columns,

567

oratext **column_names,

568

ub2 *column_name_lens,

569

ub2 *column_dtyp,

570

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

/*

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

583

NAME

584

OCILCRDDLInfoSet - OCI LCR SET DDL INFO

585

DESCRIPTION

586

populates DDL information as sepcified by the user.

587

PARAMETERS

588

svchp (IN) - OCI service context

589

errhp (IN) - OCI Error Handle

590

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

591

executed. The following are valid object types:

592

CLUSTER, FUNCTION, INDEX, LINK, OUTLINE,

593

PACKAGE, PACKAGE BODY, PROCEDURE, SEQUENCE,

594

SYNONYM, TABLE, TRIGGER, TYPE, USER, VIEW

595

LINK represents a database link.

596

NULL is also a valid object type. Specify NULL

597

for all object types not listed.

598

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

599

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

600

should be set to a non-NULL value.

601

DDL text must be in Oracle DDL format.

602

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

603

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

604

executed the DDL statement. Should follow Oracle

605

naming conventions and size limitations.

606

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

607

terminator.

608

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

609

schema is specified explicitly for the modified

610

database objects in ddl_text. If a schema is

611

specified in ddl_text that differs from the one

612

specified for current_schema, then the schema

613

specified in ddl_text will be used.

614

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

615

Should follow Oracle naming conventions and size

616

limitations.

617

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

618

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

619

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

620

DDL statement involves a table (such as creating

621

a trigger on a table), then base_table_owner

622

specifies the canonicalized owner of the table

623

involved. Otherwise, base_table_owner is NULL.

624

Should follow Oracle naming conventions and size

625

limitations.

626

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

627

terminator.

628

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

629

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

630

statement involves a table (such as creating a

631

trigger on a table), then base_table_name

632

specifies the canonicalized name of the table

633

involved. Otherwise, base_table_name is NULL.

634

Length of the above string without the NULL

635

terminator. Should follow Oracle naming

636

conventions and size limitations.

637

Should follow Oracle naming conventions and size

638

limitations.

639

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

640

terminator.

641

flag (IN) - DDL LCR flag.

642

ddl_lcrp (IN/OUT) - XStream Ddl LCR pointer

643

mode (IN) - mode

644

NOTES

645

- For now, specify OCI_DEFAULT for mode

646

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

647

*/

648

sword OCILCRDDLInfoSet(OCISvcCtx *svchp,

649

OCIError *errhp,

650

oratext *object_type,

ub2 object_type_len,

oratext *ddl_text,

ub4 ddl_text_len,

oratext *logon_user,

ub2 logon_user_len,

oratext *current_schema,

657

ub2 current_schema_len,

658

oratext *base_table_owner,

659

ub2 base_table_owner_len,

660

oratext *base_table_name,

661

ub2 base_table_name_len,

oraub8 flag,

void *ddl_lcrp,

ub4 mode);

/*

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

668

NAME

669

OCILCRDDLInfoGet - OCI LCR GET DDL INFO

670

DESCRIPTION

671

Returns DDL information from specified lcr.

672

PARAMETERS

673

svchp (IN) - OCI service context

674

errhp (IN) - OCI Error Handle

675

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

676

was executed.

677

Optional, if object_type is specified then

678

must specify object_type_len as well.

679

object_type_len (OUT) - Length of object_type without the NULL

680

terminator.

681

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

682

Optional, if ddl_text is specified then

683

must specify ddl_text_len as well.

684

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

685

terminator.

686

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

687

executed the DDL statement.

688

Optional, if logon_user is specified then

689

must specify logon_user_len as well.

690

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

691

terminator.

692

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

693

no schema is specified explicitly for the

694

modified database objects in ddl_text.

695

Optional, if current_schema is specified then

696

must specify current_schema_len as well.

697

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

698

terminator

699

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

700

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

701

the DDL statement involves a table (such as

702

creating a trigger on a table), then

703

base_table_owner specifies the canonicalized

704

owner of the table involved. Otherwise,

705

base_table_owner is NULL. Optional, if

706

base_table_owner is specified then must specify

707

base_table_owner_len as well.

708

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

709

NULL terminator.

710

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

711

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

712

the DDL statement involves a table (such as

713

creating a trigger on a table), then

714

base_table_name specifies the canonicalized name

715

of the table involved. Otherwise,

716

base_table_name is NULL. Optional, if

717

base_table_name is specified then must specify

718

base_table_name_len as well.

719

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

720

terminator.

721

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

722

NULL.

723

ddl_lcrp (IN) - XStream DDL LCR pointer

724

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

725

RETURNS

726

OCI_SUCCESS or OCI_ERROR.

727

NOTES

728

- For now, specify OCI_DEFAULT for mode

729

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

730

*/

731

sword OCILCRDDLInfoGet(OCISvcCtx *svchp,

732

OCIError *errhp,

733

oratext **object_type,

734

ub2 *object_type_len,

735

oratext **ddl_text,

736

ub4 *ddl_text_len,

737

oratext **logon_user,

738

ub2 *logon_user_len,

739

oratext **current_schema,

740

ub2 *current_schema_len,

741

oratext **base_table_owner,

742

ub2 *base_table_owner_len,

743

oratext **base_table_name,

744

ub2 *base_table_name_len,

oraub8 *flag,

void *ddl_lcrp,

ub4 mode);

/*

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

751

NAME

752

OCILCRAttributesSet - OCI LCR SET ATTRIBUTES

753

DESCRIPTION

754

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

755

non first class attributes that can not be set through

756

OCILCRHeaderSet, OCILCRDDLInfoSet, or OCILCRRowColumnInfoSet.

757

e.g. edition name

758

PARAMETERS

759

svchp (IN) - OCI service context

760

errhp (IN) - OCI Error Handle

761

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

762

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

763

names must be canonicalized and should follow

764

Oracle naming conventions

765

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

766

in bytes, excluding the NULL terminator.

767

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

768

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

769

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

770

this is a pointer to an array of OCIInd values

771

(OCI_IND_NULL/OCI_IND_NOTNULL).

772

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

773

bytes.

774

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

775

mode (IN) - mode

776

NOTES

777

- For now, specify OCI_DEFAULT for mode

778

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

779

*/

780

sword OCILCRAttributesSet(OCISvcCtx *svchp,

781

OCIError *errhp,

782

ub2 num_attrs,

783

oratext **attr_names,

ub2 *attr_name_lens,

ub2 *attr_dtyp,

void **attr_valuesp,

OCIInd *attr_indp,

ub2 *attr_alensp,

void *lcrp,

ub4 mode);

/*

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

794

NAME

795

OCILCRAttributesGet - OCI LCR GET EXTRA ATTRIBUTES

796

DESCRIPTION

797

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

798

non first class attributes that are not populated through

799

OCILCRHeaderGet, OCILCRDDLInfoGet, or OCILCRRowColumnInfoGet

800

e.g. edition name

801

PARAMETERS

802

svchp (IN) - OCI service context

803

errhp (IN) - OCI Error Handle

804

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

805

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

806

names must be canonicalized and should follow

807

Oracle naming conventions

808

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

809

in bytes, excluding the NULL terminator.

810

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

811

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

812

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

813

this is a pointer to an array of OCIInd values

814

(OCI_IND_NULL/OCI_IND_NOTNULL).

815

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

816

bytes.

817

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

818

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

819

defined by OCI_LCR_MAX_ATTRIBUTES

820

mode (IN) - mode

821

NOTES

822

- For now, specify OCI_DEFAULT for mode

823

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

824

in the requested attribute list then OCI_ERROR is returned. Parameter

825

num_attrs will return the suggested size.

826

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

827

*/

828

sword OCILCRAttributesGet(OCISvcCtx *svchp,

829

OCIError *errhp,

830

ub2 *num_attrs,

831

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

842

/*

843

NAME

844

OCILCRWhereClauseGet - OCI Get Where Clause

845

DESCRIPTION

846

Gets the Where clause statement for the given ROW LCR.

847

PARAMETERS

848

svchp (IN/OUT) - OCI service handle

849

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

850

should be reported

851

wc_stmt (OUT) - Sql Statement equivalent to the

852

LCR has applied

853

wc_stmt_len (IN/OUT) - length of wc_stmt buffer

854

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

855

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

856

Not used currently)

857

RETURNS

858

OCI_SUCCESS or OCI_ERROR.

859

NOTES

860

- For now, specify OCI_DEFAULT for mode

861

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

862

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

863

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

864

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

865

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

866

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

867

new value if it exist in the new column list

868

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

869

value will be used.

870

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

871

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

872

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

873

old column lst

874

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

875

generating the WHERE clause.

876

*/

877

878

sword OCILCRWhereClauseGet(

OCISvcCtx *svchp,

OCIError *errhp,

oratext *wc_stmt,

ub4 *wc_stmt_len,

void *row_lcrp,

ub4 mode);

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

887

/*

888

NAME

889

OCILCRRowStmtGet - OCI Get Row Statement

890

DESCRIPTION

891

Gets the SQL statement for the given ROW LCR.

892

PARAMETERS

893

svchp (IN/OUT) - OCI service handle

894

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

895

should be reported

896

row_stmt (OUT) - Sql Statement equivalent to the

897

LCR has applied

898

row_stmt_len (IN/OUT) - length of row_stmt buffer

899

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

900

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

901

Not used currently)

902

RETURNS

903

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

916

/*

917

NAME

918

OCILCRWhereClauseWithBindVarGet - OCI Get Where clause with binds

919

DESCRIPTION

920

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

921

PARAMETERS

922

svchp (IN/OUT) - OCI service handle

923

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

924

should be reported

925

wc_stmt (OUT) - Sql Stmt equivalent to the LCR

926

wc_stmt_len (IN/OUT) - length of wc_stmt buffer

927

num_bind_var (OUT) - Number of bind variables

928

bind_var_dtyp (OUT) - Array of Data types of bind

929

variables

930

bind_var_valuesp (OUT) - Array of Values of bind variables

931

bind_var_indp (OUT) - Array of null indicators of

932

bind variables

933

bind_var_alensp (OUT) - Array of lengths of bind values

934

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

935

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

936

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

937

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

938

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

939

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

940

Not used currently)

941

RETURNS

942

OCI_SUCCESS or OCI_ERROR.

943

NOTES

944

- For now, specify OCI_DEFAULT for mode

945

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

946

in the requested column list then OCI_ERROR is returned. Expected

947

array_size is returned through num_bind_var parameter.

948

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

949

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

950

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

951

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

952

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

953

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

954

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

955

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

956

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

957

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

958

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

959

old column value will be used.

960

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

961

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

962

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

963

old column lst

964

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

965

generating the WHERE clause.

966

*/

967

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,

975

OCIInd *bind_var_indp,

976

ub2 *bind_var_alensp,

977

ub2 *bind_var_csetidp,

978

ub1 *bind_var_csetfp,

979

void *row_lcrp,

980

ub2 array_size,

981

oratext *bind_var_syntax,

982

ub4 mode);

983

984

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

985

/*

986

NAME

987

OCILCRRowStmtWithBindVarGet - OCI Get Row Statement

988

DESCRIPTION

989

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

990

PARAMETERS

991

svchp (IN/OUT) - OCI service handle

992

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

993

should be reported

994

row_stmt (OUT) - Sql Stmt equivalent to the LCR

995

row_stmt_len (IN/OUT) - length of row_stmt buffer

996

num_bind_var (OUT) - Number of bind variables

997

bind_var_dtyp (OUT) - Array of Data types of bind

998

variables

999

bind_var_valuesp (OUT) - Array of Values of bind variables

1000

bind_var_indp (OUT) - Array of null indicators of

1001

bind variables

1002

bind_var_alensp (OUT) - Array of lengths od bind values

1003

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

1004

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

1005

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

1006

chunk_column_names (OUT) - Array of chunked column names in

1007

lcr

1008

chunk_column_namesl (OUT) - Length of chunk_column_names

1009

chunk_column_flags (OUT) - flags of chunked columns in lcr

1010

Possible bit values are

1011

OCI_LCR_COLUMN_* flags listed

1012

above.

1013

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

1014

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

1015

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

1016

Not used currently)

1017

RETURNS

1018

OCI_SUCCESS or OCI_ERROR.

1019

NOTES

1020

- For now, specify OCI_DEFAULT for mode

1021

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

1022

in the requested column list then OCI_ERROR is returned. Expected

1023

array_size is returned through num_bind_var parameter.

1024

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

1025

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

1026

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

1027

*/

1028

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,

1036

OCIInd *bind_var_indp,

1037

ub2 *bind_var_alensp,

1038

ub2 *bind_var_csetidp,

1039

ub1 *bind_var_csetfp,

1040

void *row_lcrp,

1041

oratext **chunk_column_names,

1042

ub2 *chunk_column_namesl,

1043

oraub8 *chunk_column_flags,

1044

ub2 array_size,

1045

oratext *bind_var_syntax,

ub4 mode);

/*

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

1050

NAME

1051

OCILCRSCNsFromPosition - Get SCNs From Position

1052

1053

DESCRIPTION

1054

Returns the SCN and commit SCN from the given position.

1055

PARAMETERS

1056

svchp (IN) - OCI service context

1057

errhp (IN) - OCI Error Handle

1058

position (IN) - LCR position

1059

position_len (IN) - length of position

1060

scn (OUT) - the SCN stored in position

1061

commit_scn (OUT) - the commit SCN stored in position

1062

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

1063

currently)

1064

RETURN

1065

OCI_SUCCESS if the conversion succeeds, OCI_ERROR otherwise.

1066

NOTE

1067

The user must allocate memory for the return numbers.

1068

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

1069

server.

1070

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

1071

*/

1072

sword OCILCRSCNsFromPosition(OCISvcCtx *svchp,

OCIError *errhp,

ub1 *position,

ub2 position_len,

OCINumber *scn,

OCINumber *commit_scn,

ub4 mode);

/*

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

1082

NAME

1083

OCILCRSCNToPosition - Converts SCN To Position

1084

1085

DESCRIPTION

1086

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

1087

last_position to OCIXStreamOutAttach function to filter the LCRs

1088

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

1089

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

1090

- a commit LCR at the given SCN, or

1091

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

1092

than or equal to the given SCN.

1093

PARAMETERS

1094

svchp (IN) - OCI service context

1095

errhp (IN) - OCI Error Handle

1096

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

1097

OCI_LCR_MAX_POSITION_LEN bytes.

1098

position_len (OUT) - Length of position

1099

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

1100

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

1101

RETURN

1102

OCI_SUCCESS if the conversion succeeds, OCI_ERROR otherwise.

1103

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

1104

*/

1105

sword OCILCRSCNToPosition(OCISvcCtx *svchp,

OCIError *errhp,

ub1 *position,

ub2 *position_len,

OCINumber *scn,

ub4 mode);

/*

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

1114

NAME

1115

OCILCRLobInfoGet - OCI LCR GET LOB INFO

1116

DESCRIPTION

1117

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

1118

PARAMETERS

1119

svchp (IN) - OCI service context

1120

errhp (IN) - OCI Error Handle

1121

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

1122

Optional. If specified then column_name_len must

1123

be specified as well.

1124

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

1125

terminator.

1126

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

1127

SQLT_BIN (for BLOB).

1128

column_flag (OUT) - LOB column flag.

1129

Possible bit values are OCI_LCR_COLUMN_* flags

1130

listed above.

1131

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

1132

for LOB_TRIM and LOB_WRITE operations; otherwise,

1133

a zero is returned.

1134

This is the same as the 'soffset' parameter for

1135

OCILobErase or the 'offset' parameter in

1136

OCILobWrite functions.

1137

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

1138

for LOB_TRIM and LOB_ERASE operations; otherwise,

1139

a zero is returned.

1140

This is the same as the 'new_length' parameter in

1141

OCILobTrim or the 'amtp' parameter in OCILobErase

1142

functions.

1143

row_lcrp (IN) - XStream Row LCR pointer

1144

mode (IN) - mode

1145

NOTES

1146

- For now, specify OCI_DEFAULT for mode

1147

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

1148

*/

1149

sword OCILCRLobInfoGet(OCISvcCtx *svchp,

1150

OCIError *errhp,

1151

oratext **column_name,

1152

ub2 *column_name_len,

ub2 *column_dty,

oraub8 *column_flag,

ub4 *offset,

ub4 *size,

void *row_lcrp,

ub4 mode);

/*

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

1163

NAME

1164

OCILCRLobInfoSet - OCI LCR SET LOB INFO

1165

DESCRIPTION

1166

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

1167

PARAMETERS

1168

svchp (IN) - OCI service context

1169

errhp (IN) - OCI Error Handle

1170

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

1171

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

1172

terminator.

1173

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

1174

SQLT_BIN (for BLOB).

1175

column_flag (IN) - LOB column flag.

1176

Possible bit values are OCI_LCR_COLUMN_* flags

1177

listed above.

1178

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

1179

for LOB_TRIM and LOB_WRITE operations; otherwise,

1180

a zero is returned.

1181

This is the same as the 'soffset' parameter for

1182

OCILobErase or the 'offset' parameter in

1183

OCILobWrite functions.

1184

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

1185

for LOB_TRIM and LOB_ERASE operations; otherwise,

1186

a zero is returned.

1187

This is the same as the 'new_length' parameter in

1188

OCILobTrim or the 'amtp' parameter in OCILobErase

1189

functions.

1190

row_lcrp (IN/OUT)- XStream Row LCR pointer

1191

mode (IN) - mode

1192

NOTES

1193

- For now, specify OCI_DEFAULT for mode

1194

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

1195

*/

1196

sword OCILCRLobInfoSet(OCISvcCtx *svchp,

1197

OCIError *errhp,

1198

oratext *column_name,

ub2 column_name_len,

ub2 column_dty,

oraub8 column_flag,

ub4 offset,

ub4 size,

void *row_lcrp,

ub4 mode);

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

1208

XSTREAM OUT FUNCTIONS

1209

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

1210

1211

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

1212

/*

1213

NAME

1214

OCIXStreamOutAttach - OCI Attach to XStream Out

1215

DESCRIPTION

1216

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

1217

PARAMETERS

1218

svchp (IN/OUT) - OCI service handle

1219

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

1220

server_name (IN) - Server name.

1221

server_name_len (IN) - Length of server name.

1222

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

1223

last_position_len (IN) - Length of last_position.

1224

mode (IN) - Mode flags (see below)

1225

RETURNS

1226

OCI_SUCCESS or OCI_ERROR.

1227

NOTES

1228

Specify OCI_DEFAULT for the mode parameter.

1229

1230

The name of the outbound server must be provided because multiple

1231

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

1232

returns OCI_ERROR if it encounters any error while attaching to the

1233

outbound server.

1234

1235

The last_position parameter is used to establish the starting point

1236

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

1237

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

1238

otherwise, LCRs with position greater than last_position will be

1239

sent to the user.

1240

1241

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

1242

low-watermark maintained in the server.

1243

*/

1244

1245

sword OCIXStreamOutAttach (OCISvcCtx *svchp, OCIError *errhp,

1246

oratext *server_name, ub2 server_name_len,

1247

ub1 *last_position,

1248

ub2 last_position_len,

1249

ub4 mode);

1250

1251

/* Valid modes for OCIXStreamOutAttach call */

1252

#define OCIXSTREAM_OUT_ATTACH_RESERVED_1 (0x00000001)

1253

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

1254

#define OCIXSTREAM_OUT_ATTACH_APP_FREE_LCR (0x00000002)

1255

1256

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

1257

/*

1258

NAME

1259

OCIXStreamOutProcessedLWMSet - Set Processed Low-Watermark

1260

DESCRIPTION

1261

Sets the processed low-watermark maintained at the client.

1262

PARAMETERS

1263

svchp (IN/OUT) - OCI service handle

1264

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

1265

processed_low_position (IN) - processed low position.

1266

processed_low_position_len (IN) - processed low position length.

1267

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

1268

currently).

1269

RETURNS

1270

OCI_SUCCESS or OCI_ERROR.

1271

1272

NOTES

1273

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

1274

have been processed. After successfully attaching to an XStream

1275

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

1276

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

1277

server so that archived logs containing already processed transactions

1278

can be purged.

1279

1280

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

1281

low-watermark. It can be called anytime between OCIXStreamOutAttach

1282

and OCIXStreamOutDetach calls. Clients, using the callback mechanism

1283

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

1284

in the callback functions.

1285

*/

1286

1287

sword OCIXStreamOutProcessedLWMSet (OCISvcCtx *svchp, OCIError *errhp,

1288

ub1 *processed_low_position,

1289

ub2 processed_low_position_len,

ub4 mode);

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

1294

/*

1295

NAME

1296

OCICallbackXStreamOutLCRProcess - Callback to process each LCR received

1297

DESCRIPTION

1298

This callback is invoked during OCIXStreamOutLCRCallbackReceive

1299

to process each LCR received from the outbound server.

1300

PARAMETERS

1301

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

1302

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

1303

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

1304

flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1305

this means the current LCR has more

1306

chunk data.

1307

RETURNS

1308

This callback function must return OCI_CONTINUE to continue processing

1309

OCIXStreamOutLCRCallbackReceive call. Any return code other than

1310

OCI_CONTINUE signals that the client wants to terminate

1311

OCIXStreamOutLCRCallbackReceive immediately.

1312

*/

1313

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

1314

ub1 lcrtyp, oraub8 flag);

1315

1316

1317

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

1318

/*

1319

NAME

1320

OCICallbackXStreamOutChunkProcess - Callback to process each chunk

1321

DESCRIPTION

1322

This callback is invoked during OCIXStreamOutLCRCallbackReceive

1323

to process each chunk in an LCR.

1324

PARAMETERS

1325

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

1326

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

1327

column_name_len (IN) - Length of column name.

1328

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

1329

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

1330

OCI_LCR_COLUMN_* flags listed above.

1331

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

1332

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

1333

column_flag has OCI_LCR_COLUMN_XML_DATA bit set).

1334

chunk_bytes (IN) - Chunk data length in bytes.

1335

chunk_data (IN) - Chunk data buffer.

1336

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

1337

the current LCR has more chunks.

1338

RETURNS

1339

This callback function must return OCI_CONTINUE to continue processing

1340

OCIXStreamOutLCRCallbackReceive call. Any return code other than

1341

OCI_CONTINUE signals that the client wants to terminate

1342

OCIXStreamOutLCRCallbackReceive immediately.

1343

*/

1344

typedef sb4 (*OCICallbackXStreamOutChunkProcess)

1345

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

1346

ub2 column_dty, oraub8 column_flag, ub2 column_csid,

1347

ub4 chunk_bytes, ub1 *chunk_data, oraub8 flag);

1348

1349

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

1350

/*

1351

NAME

1352

OCIXStreamOutLCRCallbackReceive - OCI Receive LCR stream using Callbacks

1353

DESCRIPTION

1354

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

1355

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

1356

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

1357

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

1358

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

1359

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

1360

process each chunk data.

1361

1362

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

1363

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

1364

current LCR contains additional chunks then the processchunk_cb function

1365

is invoked for each chunk belonging to that LCR.

1366

1367

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

1368

OCI_ATTR_XSTREAM_IDLE_TIMEOUT), this call returns a null LCR with

1369

OCI_SUCCESS code.

1370

PARAMETERS

1371

svchp (IN/OUT) - OCI service handle

1372

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

1373

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

1374

processchunk_cb (IN) - Client callback function for each

1375

chunk.

1376

usrctxp (IN) - Client context. (Optional)

1377

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

1378

fetch_low_position_len (OUT)- Fetch low watermark length.

1379

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

1380

currently).

1381

RETURNS

1382

OCI_SUCCESS or OCI_ERROR.

1383

NOTES

1384

- The fetch low watermark is used to indicate all transactions

1385

with commit position below this have been received by the XStream

1386

outbound server.

1387

1388

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

1389

limited to the processlcr_cb function. If the LCR contains some

1390

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

1391

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

1392

processchunk_cb function does not have OCI_XSTREAM_MORE_ROW_DATA flag

1393

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

1394

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

1395

or free the LCR passing to the callback.

1396

1397

If the OCIXSTREAM_OUT_ATTACH_APP_FREE_LCR mode is passed to

1398

OCIXStreamOutAttach call then the application is in charge of calling

1399

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

1400

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

1401

immediately after each OCIXStreamOutChunkReceive call.

1402

1403

- The given usrctxp is passed to both callbacks.

1404

1405

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

1406

server receives the processed LWM or the inbound server sends

1407

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

1408

value can be changed by setting the OCI_ATTR_XSTREAM_ACK_INTERVAL

1409

attribute using OCIAttrSet API. This attribute is checked only

1410

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

1411

1412

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

1413

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

1414

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

1415

OCI_ATTR_XSTREAM_IDLE_TIMEOUT attribute using OCIAttrSet API. This

1416

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

1417

set before invoking this API.

1418

1419

- The outbound server ends each call at the transaction boundary

1420

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

1421

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

1422

low watermark at the end of each call.

1423

*/

1424

sword OCIXStreamOutLCRCallbackReceive(

1425

OCISvcCtx *svchp, OCIError *errhp,

1426

OCICallbackXStreamOutLCRProcess processlcr_cb,

1427

OCICallbackXStreamOutChunkProcess processchunk_cb, void *usrctxp,

1428

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

1429

1430

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

1431

/*

1432

NAME

1433

OCIXStreamOutLCRReceive - Receive LCR without using callback

1434

DESCRIPTION

1435

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

1436

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

1437

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

1438

null LCR after the idle timeout (see OCI_ATTR_XSTREAM_IDLE_TIMEOUT)

1439

has expired.

1440

1441

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

1442

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

1443

If the OCIXSTREAM_OUT_ATTACH_APP_FREE_LCR mode is passed to

1444

OCIXStreamOutAttach call then the application is in charge of calling

1445

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

1446

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

1447

immediately after each OCIXStreamOutChunkReceive call.

1448

1449

To avoid network round trip for every OCIXStreamOutLCRReceive call,

1450

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

1451

the network buffer with LCRs so subsequent calls can quickly receive

1452

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

1453

transaction boundary after an ACK interval has elapsed since the start

1454

of the call or when the idle timeout expires. See

1455

OCI_ATTR_XSTREAM_ACK_INTERVAL & OCI_ATTR_XSTREAM_IDLE_TIMEOUT

1456

attributes.

1457

PARAMETERS

1458

svchp (IN/OUT) - OCI service handle

1459

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

1460

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

1461

stream.

1462

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

1463

flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1464

it means the current LCR has more

1465

chunk data.

1466

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

1467

fetch_low_position_len (OUT)- Fetch low watermark length.

1468

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

1469

currently).

1470

RETURNS

1471

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

1472

connection associated with the specified service context handle is

1473

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

1474

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

1475

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

1476

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

1477

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

1478

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

1479

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

1480

- OCI_ERROR means the current call encounters some errors. Use

1481

OCIErrorGet to obtain information about the error.

1482

1483

NOTES

1484

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

1485

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

1486

server has received all transactions with commit position lower than or

1487

equal to this value.

1488

1489

The fetch low watermark is used to indicate all transactions

1490

with commit position below this have been received by the XStream

outbound server.

*/

sword OCIXStreamOutLCRReceive(

1495

OCISvcCtx *svchp, OCIError *errhp,

void **lcrp,

ub1 *lcrtype,

oraub8 *flag,

ub1 *fetch_low_position,

1500

ub2 *fetch_low_position_len,

1501

ub4 mode);

1502

1503

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

1504

/*

1505

NAME

1506

OCIXStreamOutChunkReceive - Receive Chunk data

1507

DESCRIPTION

1508

Receives next chunk of LCR data from XStream Outbound server.

1509

This API can only be called while OCIXStreamOutLCRReceive call is

1510

in progress.

1511

PARAMETERS

1512

svchp (IN/OUT) - OCI service handle

1513

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

1514

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

1515

column_name_len (OUT) - Length of column name.

1516

column_dty (OUT) - LCR column data type.

1517

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

1518

OCI_LCR_COLUMN_LOB_DATA

1519

OCI_LCR_COLUMN_LONG_DATA

1520

OCI_LCR_COLUMN_EMPTY_LOB

1521

OCI_LCR_COLUMN_LAST_CHUNK

1522

OCI_LCR_COLUMN_AL16UTF16

1523

OCI_LCR_COLUMN_ENCRYPTED

1524

OCI_LCR_COLUMN_NCLOB

1525

OCI_LCR_COLUMN_XML_DATA

1526

OCI_LCR_COLUMN_XML_DIFF

1527

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

1528

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

1529

column_flag has OCI_LCR_COLUMN_XML_DATA bit

1530

set).

1531

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

1532

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

1533

Client must not de-allocate this pointer.

1534

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

1535

the current LCR has more data coming.

1536

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

1537

RETURNS

1538

OCI_SUCCESS - Check colname_len and chunk_bytes to determine the

1539

data just read.

1540

OCI_ERROR - Error encountered. Execute OCIErrorGet to get information

1541

about the error.

1542

NOTES

1543

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

1544

determine the # of bytes read and check column_name to determine

1545

which LCR column the data associated with.

1546

1547

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

1548

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

1549

returned.

1550

1551

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

1552

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

1553

The column_flag will have OCI_LCR_COLUMN_LAST_CHUNK bit set when this

1554

function returns the last chunk of each column.

1555

1556

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

1557

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

1558

1559

- If OCIXStreamOutLCRReceive call returns OCI_XSTREAM_MORE_ROW_DATA flag

1560

then the user must iteratively call OCIXStreamOutChunkReceive to

1561

retrieve all the chunks belonging to the current row change before

1562

calling the next OCIXStreamOutLCRReceive.

1563

1564

*/

1565

sword OCIXStreamOutChunkReceive(OCISvcCtx *svchp, OCIError *errhp,

1566

oratext **column_name, ub2 *column_name_len,

1567

ub2 *column_dty, oraub8 *column_flag,

1568

ub2 *column_csid, ub4 *chunk_bytes,

1569

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

1570

1571

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

1572

/*

1573

NAME

1574

OCIXStreamOutDetach - OCI Detach from XStream Out

1575

DESCRIPTION

1576

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

1577

current local processed low-watermark to the server before detaching

1578

from the outbound server. The outbound server automatically restarts

1579

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

1580

ReceiveLCR call is in progress.

1581

PARAMETERS

1582

svchp (IN/OUT) - OCI service handle

1583

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

1584

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

1585

RETURNS

1586

OCI_SUCCESS or OCI_ERROR.

1587

NOTES

1588

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

1589

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

1590

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

1591

*/

1592

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

1593

1594

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

1595

XSTREAM IN FUNCTIONS

1596

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

1597

1598

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

1599

/*

1600

NAME

1601

OCIXStreamInAttach - OCI XStream In Attach

1602

DESCRIPTION

1603

Attaches to the specified XStream inbound server.

1604

PARAMETERS

1605

svchp (IN/OUT) - OCI service handle

1606

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

1607

should be reported

1608

server_name (IN) - XStream inbound server name.

1609

server_name_len (IN) - Length of server name.

1610

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

1611

source_name_len (IN) - Length of source name.

1612

last_position (OUT) - Last position received by inbound

1613

server. Optional. If specified must

1614

pre-allocate OCI_LCR_MAX_POSITION_LEN

1615

bytes for return value.

1616

last_position_len (OUT) - Length of last_position. Must be

1617

non-NULL if last_position is non-NULL.

1618

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

1619

(Not used currently)

1620

RETURNS

1621

OCI_SUCCESS or OCI_ERROR.

1622

NOTES

1623

The last_position parameter is returned to establish the starting point

1624

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

1625

positions greater than the last_position since the inbound server will

1626

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

1627

*/

1628

1629

sword OCIXStreamInAttach(

1630

OCISvcCtx *svchp,

1631

OCIError *errhp,

1632

oratext *server_name,

1633

ub2 server_name_len,

1634

oratext *source_name,

1635

ub2 source_name_len,

1636

ub1 *last_position,

1637

ub2 *last_position_len,

1638

ub4 mode);

1639

1640

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

1641

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

1642

#define OCIXSTREAM_IN_ATTACH_RESTART_INBOUND (0x00000001)

1643

1644

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

1645

/*

1646

NAME

1647

OCICallbackXStreamInLCRCreate - Callback to create an LCR

1648

DESCRIPTION

1649

This callback is invoked during OCIXStreamInLCRCallbackSend

1650

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

1651

PARAMETERS

1652

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

1653

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

1654

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

1655

flag (OUT) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1656

this means the current LCR has more

1657

chunk data.

1658

RETURNS

1659

This callback function must return OCI_CONTINUE to continue processing

1660

OCIXStreamInLCRCallbackSend call. Any return code other than

1661

OCI_CONTINUE signals that the client wants to terminate

1662

OCIXStreamInLCRCallbackSend immediately.

1663

*/

1664

typedef sb4 (*OCICallbackXStreamInLCRCreate)(

void *usrctxp,

void **lcrp,

ub1 *lcrtyp,

oraub8 *flag);

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

1671

/*

1672

NAME

1673

OCICallbackXStreamInChunkCreate - Callback to create each chunk

1674

DESCRIPTION

1675

This callback is invoked during OCIXStreamInLCRCallbackSend

1676

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

1677

PARAMETERS

1678

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

1679

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

1680

column_name_len (OUT) - Length of column name.

1681

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

1682

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

1683

OCI_LCR_COLUMN_* flags listed above.

1684

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

1685

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

1686

column_flag has OCI_LCR_COLUMN_XML_DATA bit

1687

set).

1688

chunk_bytes (OUT) - Chunk data length in bytes.

1689

chunk_data (OUT) - Chunk data buffer.

1690

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

1691

the current LCR has more chunks.

1692

RETURNS

1693

This callback function must return OCI_CONTINUE to continue processing

1694

OCIXStreamInLCRCallbackSend call. Any return code other than

1695

OCI_CONTINUE signals that the client wants to terminate

1696

OCIXStreamInLCRCallbackSend immediately.

1697

*/

1698

typedef sb4 (*OCICallbackXStreamInChunkCreate)(

1699

void *usrctxp,

1700

oratext **column_name,

1701

ub2 *column_name_len,

ub2 *column_dty,

oraub8 *column_flag,

ub2 *column_csid,

ub4 *chunk_bytes,

ub1 **chunk_data,

oraub8 *flag);

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

1710

/*

1711

NAME

1712

OCIXStreamInLCRCallbackSend - OCI XStream In Send LCR to Inbound Server

1713

DESCRIPTION

1714

Sends LCR stream to XStream inbound server using callbacks.

1715

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

1716

server. If the return flag from the createlcr_cb function has

1717

OCI_XSTREAM_MORE_ROW_DATA bit set, then it invokes createchunk_cb

1718

procedure to obtain each chunk. It repeatedly calls createchunk_cb

1719

function while the flag returned from this callback has

1720

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

1721

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

1722

This cycle is repeated until the createlcr_cb function returns a null

1723

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

1724

See OCI_ATTR_XSTREAM_ACK_INTERVAL attribute.

1725

PARAMETERS

1726

svchp (IN/OUT) - OCI service handle

1727

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

1728

should be reported

1729

createlcr_cb (IN) - Callback function to be invoked

1730

to generate an LCR for streaming.

1731

Cannot be null.

1732

createchunk_cb (IN) - Callback function to be invoked to

1733

create each chunk. Can be null if the

1734

user does not need to send any LCR with

1735

LOB/LONG/XMLType columns. OCI_ERROR

1736

will be returned if this argument is

1737

null and the user attempts to send an

1738

LCR with additional chunk data.

1739

usrctxp (IN) - Client context to pass to both

1740

callback functions.

1741

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

1742

Not used currently)

1743

RETURNS

1744

OCI_SUCCESS or OCI_ERROR.

NOTES

None

*/

sword OCIXStreamInLCRCallbackSend(

1750

OCISvcCtx *svchp,

1751

OCIError *errhp,

1752

OCICallbackXStreamInLCRCreate createlcr_cb,

1753

OCICallbackXStreamInChunkCreate createchunk_cb,

void *userctxp,

ub4 mode);

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

1758

/*

1759

NAME

1760

OCIXStreamInLCRSend - OCI XStream In Send LCR to Inbound Server

1761

DESCRIPTION

1762

Sends LCR stream to XStream inbound server without using callbacks.

1763

To avoid a network round trip for every OCIXStreamInLCRSend call,

1764

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

1765

specified by the OCI_ATTR_XSTREAM_ACK_INTERVAL attribute.

1766

PARAMETERS

1767

svchp (IN/OUT) - OCI service handle

1768

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

1769

should be reported

1770

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

1771

be null.

1772

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

1773

flag (IN) - If OCI_XSTREAM_MORE_ROW_DATA is set,

1774

it means the current LCR has more

1775

chunk data.

1776

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

1777

Not used currently)

1778

RETURNS

1779

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

1780

connection associated with the specified service context handle is

1781

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

1782

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

1783

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

1784

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

1785

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

1786

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

1787

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

1788

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

1789

obtain information about the error.

1790

*/

1791

sword OCIXStreamInLCRSend(

OCISvcCtx *svchp,

OCIError *errhp,

void *lcrp,

ub1 lcrtype,

oraub8 flag,

ub4 mode);

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

1800

/*

1801

NAME

1802

OCIXStreamInChunkSend - Send Chunk

1803

DESCRIPTION

1804

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

1805

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

1806

most recent OCIXStreamInLCRSend call prior to this call.

1807

PARAMETERS

1808

svchp (IN/OUT) - OCI service handle

1809

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

1810

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

1811

Column names must be canonicalized and must

1812

follow Oracle naming conventions.

1813

column_name_len (IN) - Length of column name.

1814

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

1815

SQLT_BIN).

1816

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

1817

OCI_LCR_COLUMN_LOB_DATA

1818

OCI_LCR_COLUMN_LONG_DATA

1819

OCI_LCR_COLUMN_EMPTY_LOB

1820

OCI_LCR_COLUMN_LAST_CHUNK

1821

OCI_LCR_COLUMN_AL16UTF16

1822

OCI_LCR_COLUMN_ENCRYPTED

1823

OCI_LCR_COLUMN_NCLOB

1824

OCI_LCR_COLUMN_XML_DATA

1825

OCI_LCR_COLUMN_XML_DIFF

1826

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

1827

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

1828

column_flag has OCI_LCR_COLUMN_XML_DATA bit set).

1829

chunk_bytes (IN) - Chunk data length in bytes.

1830

chunk_data (IN) - Chunk data buffer.

1831

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

1832

the current LCR has more data coming.

1833

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

1834

RETURNS

1835

OCI_SUCCESS - Successful call.

1836

OCI_ERROR - Error encountered. Execute OCIErrorGet to get information

1837

about the error.

1838

NOTES

1839

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

1840

1841

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

1842

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

1843

same LCR.

1844

1845

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

1846

1847

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

1848

column contains multiple chunks, this procedure must be called

1849

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

1850

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

1851

irrelevant.

1852

1853

- The OCI_LCR_COLUMN_LAST_CHUNK must be specified for the last chunk of

1854

each column.

1855

1856

- Only one column can be specified for LOB_WRITE operation.

1857

1858

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

1859

AL16UTF16 format.

1860

1861

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

1862

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

1863

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

1864

null and must have OCI_LCR_COLUMN_EMPTY_LOB flag defined.

1865

1866

*/

1867

sword OCIXStreamInChunkSend (OCISvcCtx *svchp, OCIError *errhp,

1868

oratext *column_name, ub2 column_name_len,

1869

ub2 column_dty, oraub8 column_flag,

1870

ub2 column_csid, ub4 chunk_bytes,

1871

ub1 *chunk_data, oraub8 flag, ub4 mode);

1872

1873

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

1874

/*

1875

NAME

1876

OCIXStreamInDetach - OCI XStream In Detach from Inbound Server

1877

DESCRIPTION

1878

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

1879

processed low-watermark.

1880

PARAMETERS

1881

svchp (IN/OUT) - OCI service handle

1882

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

1883

should be reported

1884

processed_low_position (OUT) - Inbound server's processed low

1885

position. Must pre-allocate

1886

OCI_LCR_MAX_POSITION_LEN bytes for

1887

output buffer.

1888

processed_low_position_len(OUT)- Processed_low_position length.

1889

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

1890

Not used currently)

1891

RETURNS

1892

OCI_SUCCESS or OCI_ERROR.

NOTES

None

*/

sword OCIXStreamInDetach(

1897

OCISvcCtx *svchp,

1898

OCIError *errhp,

1899

ub1 *processed_low_position,

1900

ub2 *processed_low_position_len,

1901

ub4 mode);

1902

1903

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

1904

/* Restart inbound server when calling detach. */

1905

#define OCIXSTREAM_IN_DETACH_RESTART_INBOUND (0x00000001)

1906

1907

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

1908

/*

1909

NAME

1910

OCIXStreamInProcessedLWMGet - OCI XStream In Get LowWatermark

1911

DESCRIPTION

1912

Returns XStream inbound server's processed low watermark

1913

cached at the client.

1914

PARAMETERS

1915

svchp (IN/OUT) - OCI service handle

1916

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

1917

should be reported

1918

processed_low_position (OUT) - Inbound server's cached processed

1919

low position. Must pre-

1920

allocate OCI_LCR_MAX_POSITION_LEN

1921

bytes for output buffer.

1922

processed_low_position_len (OUT) - Processed_low_position length.

1923

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

1924

Not used currently)

1925

RETURNS

1926

OCI_SUCCESS or OCI_ERROR.

NOTES

None

*/

sword OCIXStreamInProcessedLWMGet(

1931

OCISvcCtx *svchp,

1932

OCIError *errhp,

1933

ub1 *processed_low_position,

1934

ub2 *processed_low_position_len,

1935

ub4 mode);

1936

1937

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

1938

/*

1939

NAME

1940

OCIXStreamInFlush - OCI XStream In Flush network

1941

DESCRIPTION

1942

Flushes network and terminates any in-progress OCIXStreamInLCRSend or

1943

OCIXStreamInLCRCallbackSend call associated with the given service handle.

1944

PARAMETERS

1945

svchp (IN/OUT) - OCI service handle

1946

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

1947

should be reported

1948

mode (IN) - Mode flags (see below)

1949

RETURNS

1950

OCI_SUCCESS or OCI_ERROR.

1951

NOTES

1952

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

1953

low-watermark, which the user can retrieve afterward using

1954

OCIXStreamInProcessedLWMGet API. This API should be called only when

1955

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

1956

progress of the attached inbound server.

1957

1958

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

1959

of OCIXStreamInLCRCallbackSend API.

1960

1961

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

1966

complete and rollback transactions sent to the inbound server to complete

1967

before returning control to the client.

1968

1969

*/

1970

sword OCIXStreamInFlush(

OCISvcCtx *svchp,

OCIError *errhp,

ub4 mode);

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

1977

/*

1978

NAME

1979

OCIXStreamInCommit - OCI XStream In Commit

1980

DESCRIPTION

1981

Commits current transaction

1982

PARAMETERS

1983

svchp (IN/OUT) - OCI service handle

1984

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

1985

should be reported

1986

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

1987

be a commit LCR.

1988

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

1989

Not used currently)

1990

RETURNS

1991

OCI_SUCCESS or OCI_ERROR.

1992

NOTES

1993

The position of the input LCR must be higher than

1994

DBA_XSTREAM_INBOUND_PROGRESS.APPLIED_HIGH_POSITION and the LCR's source

1995

database must match DBA_APPLY_PROGRESS.SOURCE_DATABASE of the attached

1996

inbound server.

1997

1998

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

1999

unapplied complete or rollback transaction remaining. If none is found

2000

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

2001

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

2002

2003

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

2004

this commit LCR is executed.

2005

*/

2006

sword OCIXStreamInCommit(

OCISvcCtx *svchp,

OCIError *errhp,

void *lcrp,

ub4 mode);

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

2013

/*

2014

NAME

2015

OCIXStreamInErrorGet - OCI XStream In Get Error Info

2016

DESCRIPTION

2017

Returns the first error encountered by the inbound server since the

2018

Attach call.

2019

PARAMETERS

2020

svchp (IN/OUT) - OCI service handle

2021

errhp (IN/OUT) - Error Handle

2022

errcodep (OUT) - Error code

2023

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

2024

msg_bufsize (IN) - Message buffer size

2025

msg_len (OUT) - Length of returned error message

2026

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

2027

txn_id_bufsize (IN) - Txn_id buffer size

2028

txn_id_len (OUT) - Length of returned txn id

2029

RETURNS

2030

OCI_SUCCESS or OCI_ERROR.

2031

NOTES

2032

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

2033

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

2034

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

2035

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

2036

truncated.

2037

*/

2038

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

/*

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

2051

NAME

2052

OCIXStreamOutSessionSet - OCI XStream Out Session Set attribute

2053

DESCRIPTION

2054

Sets session attributes for XStream Out

2055

PARAMETERS

2056

svchp (IN) - OCI service context

2057

errhp (IN) - OCI Error Handle

2058

attribute_name (IN) - Attribute name

2059

attribute_name_len (IN) - Attribute name length

2060

attribute_value (IN) - Attribute value

2061

attribute_value_len (IN) - Attribute value length

2062

attribute_dty (IN) - Attribute dty

2063

mode (IN) - mode

2064

RETURNS

2065

OCI_SUCCESS if successful, OCI_ERROR otherwise

2066

NOTES

2067

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

2068

*/

2069

sword OCIXStreamOutSessionSet(OCISvcCtx *svchp,

2070

OCIError *errhp,

2071

oratext *attribute_name,

2072

ub2 attribute_name_len,

2073

void *attribute_value,

2074

ub2 attribute_value_len,

ub2 attribute_dty,

ub4 mode);

/*

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

2080

NAME

2081

OCIXStreamInSessionSet - OCI XStream In Session Set attribute

2082

DESCRIPTION

2083

Sets session attributes for XStream In

2084

PARAMETERS

2085

svchp (IN) - OCI service context

2086

errhp (IN) - OCI Error Handle

2087

attribute_name (IN) - Attribute name

2088

attribute_name_len (IN) - Attribute name length

2089

attribute_value (IN) - Attribute value

2090

attribute_value_len (IN) - Attribute value length

2091

attribute_dty (IN) - Attribute dty

2092

mode (IN) - mode

2093

RETURNS

2094

OCI_SUCCESS if successful, OCI_ERROR otherwise

2095

NOTES

2096

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

2097

*/

2098

sword OCIXStreamInSessionSet(OCISvcCtx *svchp,

2099

OCIError *errhp,

2100

oratext *attribute_name,

2101

ub2 attribute_name_len,

2102

void *attribute_value,

2103

ub2 attribute_value_len,

ub2 attribute_dty,

ub4 mode);

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

2108

INTERNAL FUNCTIONS

2109

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

#ifdef __cplusplus

}

#endif /* __cplusplus */

2115

2116

#endif /* OCIXSTREAM_ORACLE */