OCI REF Functions

Table 20-15 describes the OCI Reference (REF) functions that are described in this section.

Table 20-15 Ref Functions

Function	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 `REF`s 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()", "OCIEnvNlsCreate()", and "OCIInitialize()" (deprecated)
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() allocates memory for the target REF in the OCI object cache before the copy operation.

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()", "OCIEnvNlsCreate()", and "OCIInitialize()" (deprecated)
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 nonoperational.

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()", "OCIEnvNlsCreate()", and "OCIInitialize()" (deprecated)
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): The 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 reused.

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.

Related Functions

OCIErrorGet(), OCIRefToHex()

OCIRefHexSize()

Purpose

Returns the size of the hexadecimal 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()", "OCIEnvNlsCreate()", and "OCIInitialize()" (deprecated)
ref (IN): REF whose size in hexadecimal representation in bytes is returned.

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.

Returns

The size of the hexadecimal representation of the REF.

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()", "OCIEnvNlsCreate()", and "OCIInitialize()" (deprecated)
x (IN): REF to compare.
y (IN): REF to compare.

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.

Returns

TRUE, if the two REFs are equal.

FALSE, if the two REFs are not equal, or x is NULL, or y is NULL.

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()", "OCIEnvNlsCreate()", and "OCIInitialize()" (deprecated)
ref (IN): REF to test for NULL.

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.

Returns

Returns TRUE if the given REF is NULL; otherwise, it returns FALSE.

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()", "OCIEnvNlsCreate()", and "OCIInitialize()" (deprecated)
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 a zero hex_length value is returned.
hex (OUT): Buffer that is large enough to contain the resulting hexadecimal string; the content 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.

Returns

This function returns an error if the given buffer is not big enough to hold the resulting string.

Related Functions

OCIErrorGet(), OCIRefFromHex(), OCIRefHexSize(), OCIRefIsNull()