Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
|
|
View PDF |
This section describes the OCI Ref functions.
Table 18-16 Ref Functions
Function/Page | Purpose |
---|---|
|
Assign one REF to another |
|
Clear or nullify a REF |
|
Convert hexadecimal string to REF |
|
Return size of hexadecimal representation of REF |
|
Compare two REFs for equality |
|
Test if a REF is |
|
Convert REF to hexadecimal string |
Purpose
Assigns one REF
to another, such that both reference the same object.
Syntax
sword OCIRefAssign ( OCIEnv *env, OCIError *err, CONST OCIRef *source, OCIRef **target );
Parameters
The OCI environment handle initialized in object mode.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Obtain diagnostic information by calling OCIErrorGet()
.
REF to copy from.
REF
to copy to.
Comments
Copies source
REF
to target REF
; both then reference the same object. If the target
REF
pointer is NULL
(*target
== NULL
), then OCIRefAssign()
will allocate memory for the target REF
in the OCI object cache prior to the copy.
Related Functions
OCIErrorGet(), OCIRefIsEqual()
Purpose
Clears or NULL
ifies a given REF.
Syntax
void OCIRefClear ( OCIEnv *env, OCIRef *ref );
Parameters
The OCI environment handle initialized in object mode.
REF to clear.
Comments
A REF
is considered to be a NULL
REF
if it no longer points to an object. Logically, a NULL
REF
is a dangling REF
.
Note that a NULL
REF
is still a valid SQL value and is not SQL NULL
. It can be used as a valid non-NULL
constant REF value for a NOT
NULL
column or attribute of a row in a table.
If a NULL
pointer value is passed as a REF
, then this function is non-operational.
Related Functions
Purpose
Converts the given hexadecimal string into a REF
.
Syntax
sword OCIRefFromHex ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, CONST OraText *hex, ub4 length, OCIRef **ref );
Parameters
The OCI environment handle initialized in object mode.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Obtain diagnostic information by calling OCIErrorGet()
.
OCI service context handle; if the resulting ref is initialized with this service context.
Hexadecimal text string, previously output by OCIRefToHex()
, to convert into a REF.
Length of the hexadecimal text string.
The REF
into which the hexadecimal string is converted. If *ref
is NULL
on input, then space for the REF
is allocated in the object cache, otherwise the memory occupied by the given REF
is re-used.
Comments
This function ensures that the resulting REF
is well formed. It does not ensure that the object pointed to by the resulting REF
exists or not.
Related Functions
Purpose
Returns the size of the hex representation of a REF
.
Syntax
ub4 OCIRefHexSize ( OCIEnv *env, CONST OCIRef *ref );
Parameters
The OCI environment handle initialized in object mode.
REF
whose size in hexadecimal representation in bytes is returned.
Returns
The size of the hexadecimal representation of the REF
.
Comments
Returns the size of the buffer in bytes required for the hexadecimal representation of the ref. A buffer of at least this size must be passed to the ref-to-hex (OCIRefToHex()
) conversion function.
Related Functions
OCIErrorGet(), OCIRefFromHex()
Purpose
Compares two REFs
to determine if they are equal.
Syntax
boolean OCIRefIsEqual ( OCIEnv *env, CONST OCIRef *x, CONST OCIRef *y );
Parameters
The OCI environment handle initialized in object mode.
REF
to compare.
REF
to compare.
Returns
TRUE
if the two REFs
are equal
FALSE
if the two REFs
are not equal, or x
is NULL
, or y
is NULL
Comments
Two REFs
are equal if and only if they are both referencing the same object, whether persistent or transient.
Note:
TwoNULL
REFs
are considered not equal by this function.Related Functions
Purpose
Tests if a REF
is NULL
.
Syntax
boolean OCIRefIsNull ( OCIEnv *env, CONST OCIRef *ref );
Parameters
The OCI environment handle initialized in object mode.
REF
to test for NULL
.
Returns
Returns TRUE
if the given REF
is NULL
; otherwise, returns FALSE
.
Comments
A REF
is NULL
if and only if:
it is supposed to be referencing a persistent object, but the object's identifier is NULL
it is supposed to be referencing a transient object, but it is currently not pointing to an object.
Note:
AREF
is a dangling REF if the object that it points to does not exist.Related Functions
Purpose
Converts a REF
to a hexadecimal string.
Syntax
sword OCIRefToHex ( OCIEnv *env, OCIError *err, CONST OCIRef *ref, OraText *hex, ub4 *hex_length );
Parameters
The OCI environment handle initialized in object mode.
The OCI error handle. If there is an error, it is recorded in err
and this function returns OCI_ERROR
. Obtain diagnostic information by calling OCIErrorGet()
.
REF
to be converted into a hexadecimal string; if ref
is a NULL
REF
(that is, OCIRefIsNull
(ref
) == TRUE
) then zero hex_length
value is returned.
Buffer that is large enough to contain the resulting hexadecimal string; the contents of the string is opaque to the caller.
On input specifies the size of the hex
buffer on output specifies the actual size of the hexadecimal string being returned in hex
.
Comments
Converts the given REF
into a hexadecimal string, and returns the length of the string. The resulting string is opaque to the caller.
This function returns an error if the given buffer is not big enough to hold the resulting string.
Related Functions
OCIErrorGet(), OCIRefFromHex(), OCIRefHexSize(), OCIRefIsNull()