Programmer's Guide to the Oracle Call Interface
Release 8.0

A54656_01

Library

Product

Contents

Index

Prev Next

B
Handle and Descriptor Attributes

This Appendix describes attributes for OCI handles and descriptors, which can be read with OCIAttrGet(), and can be modified with OCIAttrSet().

The following handle types are included:

Conventions

For each handle type, the attributes which can be read or changed are listed.

For each attribute the following information is included:

Mode

the following are the possible modes:

READ - the attribute can be read using OCIAttrGet()
WRITE - the attribute can be modified using OCIAttrSet()
READ/WRITE - the attribute can be read using OCIAttrGet(), and it can be modified using OCIAttrSet().

Description

a description of the purpose of the attribute

Attribute Datatype

The datatype of the attribute

Example

In some cases an example is included.

Environment Handle Attributes

OCI_ATTR_CACHE_MAX_SIZE

Mode

READ/WRITE

Description

Sets the maximum size (high watermark) for the client-side object cache as a percentage of the optimal size. The default value is 10%. See the section "Object Cache Parameters" on page 11-5 for more information.

Attribute Datatype

ub4 *

OCI_ATTR_CACHE_OPT_SIZE

Mode

READ/WRITE

Description

Sets the optimal size for the client-side object cache in bytes. The default value is 200k bytes. See the section "Object Cache Parameters" on page 11-5 for more information.

Attribute Datatype

ub4 *

OCI_ATTR_OBJECT

Mode

READ

Description

Returns TRUE if the environment was initialized in object mode.

Attribute Datatype

boolean *

OCI_ATTR_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value.

The OCI function codes are listed in Table 2-1.

Attribute Datatype

ub4 *

Table 2-1 OCI Function Codes
#   OCI Routine   #   OCI Routine   #   OCI Routine  

1  

OCIInitialize  

27  

OCIDefineArrayOfStruct  

53  

(NOT USED)  

2  

OCIHandleAlloc  

28  

OCIStmtFetch  

54  

OCIAttrGet  

3  

OCIHandleFree  

29  

OCIStmtGetBindInfo  

55  

OCIAttrSet  

4  

OCIDescriptorAlloc  

30  

(NOT USED)  

56  

OCIParamSet  

5  

OCIDescriptorFree  

31  

(NOT USED)  

57  

OCIParamGet  

6  

OCIEnvInit  

32  

OCIDescribeAny  

58  

OCIStmtGetPieceInfo  

7  

OCIServerAttach  

33  

OCITransStart  

59  

OCILdaToSvcCtx  

8  

OCIServerDetach  

34  

OCITransDetach  

60  

(NOT USED)  

9  

(NOT USED)  

35  

OCITransCommit  

61  

OCIStmtSetPieceInfo  

10  

OCISessionBegin  

36  

(NOT USED)  

62  

OCITransForget  

11  

OCISessionEnd  

37  

OCIErrorGet  

63  

OCITransPrepare  

12  

OCIPasswordChange  

38  

OCILobFileOpen  

64  

OCITransRollback  

13  

OCIStmtPrepare  

39  

OCILobFileClose  

65  

OCIDefineByPos  

14  

(NOT USED)  

40  

(NOT USED)  

66  

OCIBindByPos  

15  

(NOT USED)  

41  

(NOT USED)  

67  

OCIBindByName  

16  

(NOT USED)  

42  

OCILobCopy  

68  

OCILobAssign  

17  

OCIBindDynamic  

43  

OCILobAppend  

69  

OCILobIsEqual  

18  

OCIBindObject  

44  

OCILobErase  

70  

OCILobLocatorIsInit  

19  

(NOT USED)  

45  

OCILobGetLength  

71  

OCILobEnableBuffering  

20  

OCIBindArrayOfStruct  

46  

OCILobTrim  

72  

OCILobCharSetID  

21  

OCIStmtExecute  

47  

OCILobRead  

73  

OCILobCharSetForm  

22  

(NOT USED)  

48  

OCILobWrite  

74  

OCILobFileSetName  

23  

(NOT USED)  

49  

(NOT USED)  

75  

OCILobFileGetName  

24  

(NOT USED)  

50  

OCIBreak  

76  

OCILogon  

25  

OCIDefineObject  

51  

OCIServerVersion  

77  

OCILogoff  

26  

OCIDefineDynamic  

52  

(NOT USED)  

78  

OCILobDisableBuffering  

 

79  

OCILobFlushBuffer  

80  

OCILobLoadFromFile  

OCI_ATTR_PINOPTION

Mode

READ/WRITE

Description

This attribute sets the value of OCI_PIN_DEFAULT for the application associated with the environment handle.

For example, if OCI_ATTR_PINOPTION is set to OCI_PIN_RECENT, then if OCIObjectPin() is called with the pin_option parameter set to OCI_PIN_DEFAULT, then the object is pinned in OCI_PIN_RECENT mode.

Attribute Datatype

OCIPinOpt *

OCI_ATTR_ALLOC_DURATION

Mode

READ/WRITE

Description

This attribute sets the value of OCI_DURATION_DEFAULT for allocation durations for the application associated with the environment handle.

Attribute Datatype

OCIDuration *

OCI_ATTR_PIN_DURATION

Mode

READ/WRITE

Description

This attribute sets the value of OCI_DURATION_DEFAULT for pin durations for the application associated with the environment handle.

Attribute Datatype

OCIDuration *

Service Context Handle Attributes

OCI_ATTR_SQLCODE

Mode

READ

Description

Returns the code of the last SQL command processed on the service context handle. Each SQL command has a ub4 value.

The SQL command codes are listed in Table 2-2 on page B - 16.

Attribute Datatype

ub2 *

Table 2-2 SQL Command Codes
Code   SQL Function   Code   SQL Function   Code   SQL Function  

01  

CREATE TABLE  

35  

LOCK  

69  

(NOT USED)  

02  

SET ROLE  

36  

NOOP  

70  

ALTER RESOURCE COST  

03  

INSERT  

37  

RENAME  

71  

CREATE SNAPSHOT LOG  

04  

SELECT  

38  

COMMENT  

72  

ALTER SNAPSHOT LOG  

05  

UPDATE  

39  

AUDIT  

73  

DROP SNAPSHOT LOG  

06  

DROP ROLE  

40  

NO AUDIT  

74  

CREATE SNAPSHOT  

07  

DROP VIEW  

41  

ALTER INDEX  

75  

ALTER SNAPSHOT  

08  

DROP TABLE  

42  

CREATE EXTERNAL DATABASE  

76  

DROP SNAPSHOT  

09  

DELETE  

43  

DROP EXTERNAL DATABASE  

77  

CREATE TYPE  

10  

CREATE VIEW  

44  

CREATE DATABASE  

78  

DROP TYPE  

11  

DROP USER  

45  

ALTER DATABASE  

79  

ALTER ROLE  

12  

CREATE ROLE  

46  

CREATE ROLLBACK SEGMENT  

80  

ALTER TYPE  

13  

CREATE SEQUENCE  

47  

ALTER ROLLBACK SEGMENT  

81  

CREATE TYPE BODY  

14  

ALTER SEQUENCE  

48  

DROP ROLLBACK SEGMENT  

82  

ALTER TYPE BODY  

15  

(NOT USED)  

49  

CREATE TABLESPACE  

83  

DROP TYPE BODY  

16  

DROP SEQUENCE  

50  

ALTER TABLESPACE  

84  

DROP LIBRARY  

17  

CREATE SCHEMA  

51  

DROP TABLESPACE  

85  

TRUNCATE TABLE  

18  

CREATE CLUSTER  

52  

ALTER SESSION  

86  

TRUNCATE CLUSTER  

19  

CREATE USER  

53  

ALTER USER  

87  

CREATE BITMAPFILE  

20  

CREATE INDEX  

54  

COMMIT (WORK)  

88  

ALTER VIEW  

21  

DROP INDEX  

55  

ROLLBACK  

89  

DROP BITMAPFILE  

22  

DROP CLUSTER  

56  

SAVEPOINT  

90  

SET CONSTRAINTS  

23  

VALIDATE INDEX  

57  

CREATE CONTROL FILE  

91  

CREATE FUNCTION  

24  

CREATE PROCEDURE  

58  

ALTER TRACING  

92  

ALTER FUNCTION  

25  

ALTER PROCEDURE  

59  

CREATE TRIGGER  

93  

DROP FUNCTION  

26  

ALTER TABLE  

60  

ALTER TRIGGER  

94  

CREATE PACKAGE  

27  

EXPLAIN  

61  

DROP TRIGGER  

95  

ALTER PACKAGE  

28  

GRANT  

62  

ANALYZE TABLE  

96  

DROP PACKAGE  

29  

REVOKE  

63  

ANALYZE INDEX  

97  

CREATE PACKAGE BODY  

30  

CREATE SYNONYM  

64  

ANALYZE CLUSTER  

98  

ALTER PACKAGE BODY  

31  

DROP SYNONYM  

65  

CREATE PROFILE  

99  

DROP PACKAGE BODY  

32  

ALTER SYSTEM SWITCH LOG  

66  

DROP PROFILE  

157  

CREATE DIRECTORY  

33  

SET TRANSACTION  

67  

ALTER PROFILE  

158  

DROP DIRECTORY  

34  

PL/SQL EXECUTE  

68  

DROP PROCEDURE  

159  

CREATE LIBRARY  

OCI_ATTR_ENV

Mode

READ

Description

returns the environment context associated with the service context.

Attribute Datatype

OCIEnv **

OCI_ATTR_SERVER

Mode

READ/WRITE

Description

When read, returns the pointer to the server context attribute of the service context.

When changed, sets the server context attribute of the service context.

Attribute Datatype

OCIServer ** (READ) / OCIServer * (WRITE)

OCI_ATTR_SESSION

Mode

READ/WRITE

Description

When read, returns the pointer to the authentication context attribute of the service context.

When changed, sets the authentication context attribute of the service context.

Attribute Datatype

OCISession ** (READ) / OCISession * (WRITE)

OCI_ATTR_TRANS

Mode

READ/WRITE

Description

When read, returns the pointer to the transaction context attribute of the service context.

When changed, sets the transaction context attribute of the service context.

Attribute Datatype

OCITrans ** (READ) / OCITrans * (WRITE)

OCI_ATTR_IN_V8_MODE

Mode

READ

Description

Allows you to determine whether an application has switched to Oracle7 mode (e.g., through an OCISvcCtxToLda() call). A non-zero (true) return value indicates that the application is currently running in Oracle8 mode, a zero (false) return value indicates that the application is currently running in Oracle7 mode.

Attribute Datatype

ub1 *

Example

The following code sample shows how this parameter might be used:

in_v8_mode = 0; 
OCIAttrGet ((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (ub1 *)&in_v8_mode,  
                    (ub4) 0, OCI_ATTR_IN_V8_MODE, errhp); 
if (in_v8_mode) 
            fprintf (stdout, "In V8 mode\n"); 
    else 
            fprintf (stdout, "In V7 mode\n");

Server Handle Attributes

OCI_ATTR_ENV

Mode

READ

Description

Returns the environment context associated with the server context.

Attribute Datatype

OCIEnv **

OCI_ATTR_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value.

The OCI function codes are listed in Table 2-1 on page B-14.

Attribute Datatype

ub4 *

OCI_ATTR_EXTERNAL_NAME

Mode

READ/WRITE

Description

The external name is the user-friendly global name stored in sys.props$.value$ where name = `GLOBAL_DB_NAME'. It is not guaranteed to be unique unless all databases register their names with a network directory service.

Database names can be exchanged with the server in case of distributed transaction coordination. Server database names can only be accessed if the database is open at the time the OCISessionBegin call is issued.

Attribute Datatype

text ** (READ) / text * (WRITE)

OCI_ATTR_INTERNAL_NAME

Mode

READ/WRITE

Description

Sets the client database name that will be recorded when performing global transactions. The name can be used by the DBA to track transactions that may be pending in a prepared state due to failures.

Attribute Datatype

text ** (READ) / text * (WRITE)

OCI_ATTR_IN_V8_MODE

Mode

READ

Description

Allows you to determine whether an application has switched to Oracle7 mode (e.g., through an OCISvcCtxToLda() call). A non-zero (true) return value indicates that the application is currently running in Oracle8 mode, a zero (false) return value indicates that the application is currently running in Oracle7 mode.

Attribute Datatype

ub1 *

OCI_ATTR_FOCBK

Mode

READ/WRITE

Description

See "Application Failover Callbacks" on page 7-30 for more information.

Attribute Datatype

OCIFocbkStruct *

User Session Handle Attributes

OCI_ATTR_USERNAME

Mode

WRITE

Description

Specifies a username to use for authentication.

Attribute Datatype

text *

OCI_ATTR_PASSWORD

Mode

WRITE

Description

Specifies a password to use for authentication.

Attribute Datatype

text *

Transaction Handle Attributes

OCI_ATTR_TRANS_NAME

Mode

READ/WRITE

Description

Can be used to establish or read a text string which identifies a transaction. This is an alternative to using the XID to identify the transaction. The text string can be up to 64 bytes long.

Attribute Datatype

text ** (READ) / text * (WRITE)

OCI_ATTR_XID

Mode

READ/WRITE

Description

Can set or read an XID which identifies a transaction.

Attribute Datatype

XID ** (READ) / XID * (WRITE)

Statement Handle Attributes

OCI_ATTR_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value.

Attribute Datatype

ub4 *

The OCI function codes are listed in Table 2-1 on page B-14.

OCI_ATTR_ROW_COUNT

Mode

READ

Description

Returns the number of rows processed so far. The default value is 1.

Attribute Datatype

ub4 *

OCI_ATTR_SQLFNCODE

Mode

READ

Description

Returns the function code of the SQL command associated with the statement.

Attribute Datatype

ub2 *

Notes

The SQL command codes are listed in Table 2-2 on page B - 16.

OCI_ATTR_ENV

Mode

READ

Description

Returns the environment context associated with the statement.

Attribute Datatype

OCIEnv **

OCI_ATTR_STMT_TYPE

Mode

READ

Description

The type of statement associated with the handle. Possible values are:

Attribute Datatype

ub2 *

OCI_ATTR_ROWID

Mode

READ

Description

Returns the rowid of the current row inserted, updated or fetched in a character string format. If execute had been a multiple row operation then, len should contain the iteration number of the row the application is interested in. When connected to an Oracle7 server only the rowid of the last row inserted, updated, or fetched can be obtained.

Attribute Datatype

OCIRowid **

OCI_ATTR_PARAM_COUNT

Mode

READ

Description

This attribute can be used to get the number of columns in the select-list for the statement associated with the statement handle.

Attribute Datatype

ub4 *

Example

The following code sample shows how this attribute might be used:

/* Describe of a select-list */ 
text *selstmt  = "SELECT * FROM EMP"; 
ub4 parmcnt; 
OCIParam *parmdp; 

err = OCIStmtPrepare (stmhp, errhp, selstmt,
(ub4)strlen((char *)selstmt),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT); err = OCIStmtExecute (svchp, stmhp, errhp, (ub4)1, (ub4)0,
(const OCISnapshot*) 0, (OCISnapshot*)0, OCI_DESCRIBE_ONLY); /* get the number of columns in the select list */ err = OCIAttrGet ((dvoid *)stmhp, (ub4)OCI_HTYPE_STMT, (dvoid *)
&parmcnt, (ub4 *) 0, (ub4)OCI_ATTR_PARAM_COUNT, errhp); /* get describe information for each column */ for (i = 0; i < parmcnt; i++) { OCIParamGet (dvoid *)stmhp, OCI_HTYPE_STMT, errhp, &parmdp, i); /* get the attributes for each column */ }

OCI_ATTR_PREFETCH_ROWS

Mode

WRITE

Description

Sets the number of top level rows to be prefetched. The default value is 1 row.

Attribute Datatype

ub4 *

OCI_ATTR_PREFETCH_MEMORY

Mode

WRITE

Description

Sets the memory level for top level rows to be prefetched. Rows up to the specified top level row count are fetched if it occupies no more than the specified memory usage limit. The default value is 0, which means that memory size is not included in computing the number of rows to prefetch.

Attribute Datatype

ub4 *

Bind Handle Attributes

OCI_ATTR_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value. The OCI function codes are listed in Table 2-1 on page B-14.

Attribute Datatype

ub4 *

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

See "Character Count Attribute" on page 5-28.

Attribute Datatype

ub4 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

Character set ID of the bind handle.

Attribute Datatype

ub2 *

OCI_ATTR_CHARSET_FORM

Mode

READ/WRITE

Description

Character set form of the bind handle.

Attribute Datatype

ub1 *

OCI_ATTR_MAXDATA_SIZE

Mode

READ/WRITE

Description

See "OCI_ATTR_MAXDATA_SIZE Attribute" on page 5-27.

Attribute Datatype

sb4 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Sets the number of digits to the right of the decimal point for fields where the data type is SQLT_PDN.

Attribute Datatype

ub2 *

OCI_ATTR_PDFMT

Mode

WRITE

Description

Specifies a format string.

Attribute Datatype

text **

OCI_ATTR_ROWS_RETURNED

Mode

READ

Description

This attribute returns the number of rows that are going to be returned in the current iteration when we are in the OUT callback function for binding a DML statement with RETURNING clause.

Attribute Datatype

ub4 *

Define Handle Attributes

OCI_ATTR_FNCODE

Mode

READ

Description

Returns the function code of the last OCI operation on a handle. Each OCI function has a ub4 value.

The OCI function codes are listed in Table 2-1 on page B-14.

Attribute Datatype

ub4 *

OCI_ATTR_CHAR_COUNT

Mode

WRITE

Description

Sets the number of characters in a character type data. This specifies the number of characters desired in the define buffer. The define buffer length as specified in the define call must be greater than number of characters.

Attribute Datatype

ub4 *

OCI_ATTR_CHARSET_ID

Mode

READ/WRITE

Description

The character set ID of the define handle.

Attribute Datatype

ub2 *

OCI_ATTR_CHARSET_FORM

Mode

READ/WRITE

Description

The character set form of the define handle.

Attribute Datatype

ub1 *

OCI_ATTR_PDSCL

Mode

WRITE

Description

Sets the number of digits to the right of the decimal point for fields where the data type is SQLT_PDN.

Attribute Datatype

ub2 *

OCI_ATTR_PDFMT

Mode

WRITE

Description

Specifies a format string.

Attribute Datatype

text **

Describe Handle Attributes

OCI_ATTR_PARAM_COUNT

Mode

READ

Description

Returns the number of parameters in the describe handle. When the describe handle is a description of the select list, this refers to the number of columns in the select list.

Attribute Datatype

ub4 *

Parameter Descriptor Attributes

For a detailed list of parameter descriptor attributes, refer to Chapter 6, "Describing Schema Metadata".

LOB Locator Attributes

OCI_ATTR_LOBEMPTY

Mode

WRITE

Description

Sets the internal LOB locator to empty. The locator can then be used as a bind variable for an INSERT or UPDATE statement to initialize the LOB to empty. Once the LOB is empty, OCILobWrite() can be called to populate the LOB with data. This attribute is only valid for internal LOBs (i.e., BLOB, CLOB, NCLOB).

Applications should pass address of a ub4 which has a value of 0; e.g., ub4 lobEmpty = 0, then pass address &lobEmpty.

Attribute Datatype

ub4 *

Complex Object Attributes

For information about complex object retrieval, see "Complex Object Retrieval" on page 8-18.

Complex Object Retrieval Handle Attributes

OCI_ATTR_COMPLEXOBJECT_LEVEL

Mode

WRITE

Description

The depth level for complex object retrieval.

Attribute Datatype

ub4 *

OCI_ATTR_COMPLEXOBJECT_COLL_OUTOFLINE

Mode

WRITE

Description

Whether to fetch collection attributes in an object type out-of-line.

Attribute Datatype

ub1 *

Complex Object Retrieval Descriptor Attributes

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE

Mode

WRITE

Description

A type of REF to follow for complex object retrieval.

Attribute Datatype

dvoid *

OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL

Mode

WRITE

Description

The depth level for following REFs of type OCI_ATTR_COMPLEXOBJECT_COMP_TYPE.

Attribute Datatype

ub4 *




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index