This section describes the OCI 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 |
Assigns one REF
to another, such that both reference the same object.
sword OCIRefAssign ( OCIEnv *env, OCIError *err, CONST OCIRef *source, OCIRef **target );
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.
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.
OCIErrorGet(), OCIRefIsEqual()
Clears or NULL
ifies a given REF.
void OCIRefClear ( OCIEnv *env, OCIRef *ref );
The OCI environment handle initialized in object mode.
REF to clear.
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.
Converts the given hexadecimal string into a REF
.
sword OCIRefFromHex ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, CONST OraText *hex, ub4 length, OCIRef **ref );
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.
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.
Returns the size of the hex representation of a REF
.
ub4 OCIRefHexSize ( OCIEnv *env, CONST OCIRef *ref );
The OCI environment handle initialized in object mode.
REF
whose size in hexadecimal representation in bytes is returned.
The size of the hexadecimal representation of the REF
.
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.
OCIErrorGet(), OCIRefFromHex()
Compares two REFs
to determine if they are equal.
boolean OCIRefIsEqual ( OCIEnv *env, CONST OCIRef *x, CONST OCIRef *y );
The OCI environment handle initialized in object mode.
REF
to compare.
REF
to compare.
TRUE
if the two REFs
are equal
FALSE
if the two REFs
are not equal, or x
is NULL
, or y
is NULL
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.Tests if a REF
is NULL
.
boolean OCIRefIsNull ( OCIEnv *env, CONST OCIRef *ref );
The OCI environment handle initialized in object mode.
REF
to test for NULL
.
Returns TRUE
if the given REF
is NULL
; otherwise, returns FALSE
.
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.Converts a REF
to a hexadecimal string.
sword OCIRefToHex ( OCIEnv *env, OCIError *err, CONST OCIRef *ref, OraText *hex, ub4 *hex_length );
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
.
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.
OCIErrorGet(), OCIRefFromHex(), OCIRefHexSize(), OCIRefIsNull()