OCI Ref Functions

This section describes the OCI Ref functions.

Table 18-16 Ref Functions

Function/Page	Purpose
OCIRefAssign()	Assign one REF to another
OCIRefClear()	Clear or nullify a REF
OCIRefFromHex()	Convert hexadecimal string to REF
OCIRefHexSize()	Return size of hexadecimal representation of REF
OCIRefIsEqual()	Compare two REFs for equality
OCIRefIsNull()	Test if a REF is `NULL`
OCIRefToHex()	Convert REF to hexadecimal string

OCIRefAssign()

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

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
OCIEnvCreate() and OCIInitialize()
err (IN/OUT): 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().
source (IN): REF to copy from.
target (IN/OUT): 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()

OCIRefClear()

Purpose

Clears or NULLifies a given REF.

Syntax

void OCIRefClear ( OCIEnv        *env,
                   OCIRef        *ref );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
OCIEnvCreate() and OCIInitialize()
ref (IN/OUT): 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

OCIErrorGet(), OCIRefIsNull()

OCIRefFromHex()

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

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
OCIEnvCreate() and OCIInitialize()
err (IN/OUT): 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().
svc (IN): OCI service context handle; if the resulting ref is initialized with this service context.
hex (IN): Hexadecimal text string, previously output by OCIRefToHex(), to convert into a REF.
length (IN): Length of the hexadecimal text string.
ref (IN/OUT): 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

OCIErrorGet(), OCIRefToHex()

OCIRefHexSize()

Purpose

Returns the size of the hex representation of a REF.

Syntax

ub4 OCIRefHexSize ( OCIEnv            *env,
                    CONST OCIRef      *ref );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
OCIEnvCreate() and OCIInitialize()
ref (IN): 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()

OCIRefIsEqual()

Purpose

Compares two REFs to determine if they are equal.

Syntax

boolean OCIRefIsEqual ( OCIEnv              *env,
                        CONST OCIRef        *x,
                        CONST OCIRef        *y );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
OCIEnvCreate() and OCIInitialize()
x (IN): REF to compare.
y (IN): 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:

Two NULL REFs are considered not equal by this function.

Related Functions

OCIErrorGet(), OCIRefAssign()

OCIRefIsNull()

Purpose

Tests if a REF is NULL.

Syntax

boolean OCIRefIsNull ( OCIEnv           *env,
                       CONST OCIRef     *ref );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
OCIEnvCreate() and OCIInitialize()
ref (IN): 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:
A REF is a dangling REF if the object that it points to does not exist.

Related Functions

OCIErrorGet(), OCIRefClear()

OCIRefToHex()

Purpose

Converts a REF to a hexadecimal string.

Syntax

sword OCIRefToHex ( OCIEnv            *env,
                    OCIError          *err, 
                    CONST OCIRef      *ref, 
                    OraText           *hex, 
                    ub4               *hex_length );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
OCIEnvCreate() and OCIInitialize()
err (IN/OUT): 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 (IN): 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.
hex (OUT): Buffer that is large enough to contain the resulting hexadecimal string; the contents of the string is opaque to the caller.
hex_length (IN/OUT): 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()