OCI Table Functions

29.8 OCI Table Functions

Lists and describes the OCI table functions.

Table 29-17 describes the OCI table functions that are described in this section.

Table 29-17 Table Functions

Function	Purpose
OCITableDelete()	Delete element
OCITableExists()	Test whether element exists
OCITableFirst()	Return first index of table
OCITableLast()	Return last index of table
OCITableNext()	Return next available index of table
OCITablePrev()	Return previous available index of table
OCITableSize()	Return current size of table

29.8.1 OCITableDelete()

Deletes the element at the specified index.

Purpose

Deletes the element at the specified index.

Syntax

sword OCITableDelete ( OCIEnv          *env, 
                       OCIError        *err, 
                       sb4              index, 
                       OCITable        *tbl );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
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().
index (IN): Index of the element that must be deleted.
tbl (IN): Table whose element is deleted.

Comments

This function returns an error if the element at the given index has already been deleted or if the given index is not valid for the given table.

Note:

The position ordinals of the remaining elements of the table are not changed by OCITableDelete(). The delete operation creates holes in the table.

Returns

An error is also returned if any input parameter is NULL.

Related Topics

29.8.2 OCITableKeyDelete()

Deletes a key and the associated element from an associative array collection using a string key.

Purpose

Deletes a key and the associated element from an associative array collection using a string key. An error is returned if the element does not exist.

Syntax

sword OCITableKeyDelete ( OCIEnv         *env, 
   OCIError       *err, 			
   CONST void     *key, 
   ub4             keylen,
   OCIKeyType      keytype,
   CONST OCITable *coll);

Parameters

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

err (IN/OUT): The OCI error handle.

key (IN): The non-null key value of the element in the associative array collection.

keylen (IN): If the keytype is OCI_KEYTYPE_STRING, then the length of the key value is in bytes.

keytype (IN): The type of the key.

coll (IN): The pointer to the associative array collection.

29.8.3 OCITableExists()

Tests whether an element exists at the given index.

Purpose

Tests whether an element exists at the given index.

Syntax

sword OCITableExists ( OCIEnv              *env,
                       OCIError            *err, 
                       const OCITable      *tbl,
                       sb4                 index, 
                       boolean             *exists );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
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().
tbl (IN): Table in which the given index is checked.
index (IN): Index of the element that is checked for existence.
exists (OUT): Set to TRUE if the element at the given index exists; otherwise, it is set to FALSE.

Returns

This function returns an error if any input parameter is NULL.

Related Topics

29.8.4 OCITableKeyExists()

Tests whether an element exists in an associative array collection using a string key.

Purpose

Tests whether an element exists in an associative array collection using a string key.

Syntax

sword OCITableKeyExists ( OCIEnv         *env, 
   OCIError       *err, 			
   CONST void     *key, 
   ub4             keylen,
   OCIKeyType      keytype,
   CONST OCITable *coll,
   boolean        *exists);

Parameters

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

err (IN/OUT): The OCI error handle.

key (IN): The non-null key value of the element in the associative array collection.

keylen (IN): If the keytype is OCI_KEYTYPE_STRING, then the length of the key value is in bytes.

keytype (IN): The type of the key.

coll (IN): Pointer to the associative array collection.

exists (OUT): Set to value TRUE if the element with the given key value exists; otherwise, it is set to value FALSE.

29.8.5 OCITableFirst()

Returns the index of the first existing element in a given table.

Purpose

Returns the index of the first existing element in a given table.

Syntax

sword OCITableFirst ( OCIEnv             *env, 
                      OCIError           *err,
                      const OCITable     *tbl, 
                      sb4                *index  );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
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().
tbl (IN): Table to scan.
index (OUT): First index of the element that exists in the given table that is returned.

Comments

If OCITableDelete() deletes the first five elements of a table, OCITableFirst() returns the value 6.

29.8.6 OCITableKeyFirst()

Returns a reference pointer to the first key value in the associative array.

Purpose

Returns a reference pointer to the first key value in the associative array, based on the sorting order.

Syntax

sword OCITableKeyFirst ( OCIEnv         *env, 
  OCIError       *err, 			
  CONST void    **key,
  ub4            *keylen,
  OCIKeyType     *keytype,
  CONST OCITable *coll);

Parameters

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

err (IN/OUT): The OCI error handle.

key (OUT): Reference to the key of the current element, the reference must not be modified.

keylen (OUT): The size of the referenced key string.

keytype (OUT): The type of the first key.

coll (IN): The pointer to the associative array collection.

29.8.7 OCITableLast()

Returns the index of the last existing element of a table.

Purpose

Returns the index of the last existing element of a table.

Syntax

sword OCITableLast ( OCIEnv              *env, 
                     OCIError            *err, 
                     const OCITable      *tbl, 
                     sb4                 *index );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
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().
tbl (IN): Table to scan.
index (OUT): Index of the last existing element in the table.

Comments

OCITableLast() returns the largest index numbered element in the index by integer collection.

Returns

This function returns an error if the table is empty.

Related Topics

29.8.8 OCITableKeyLast()

Returns a pointer reference to the last key value in the associative array.

Purpose

Returns a reference pointer to the last key value in the associative array, based on the sorting order.

Syntax

sword OCITableKeyLast ( OCIEnv         *env, 
 OCIError       *err, 			
 void          **key,
 ub4            *keylen,
 OCIKeyType     *keytype,
 CONST OCITable *coll);

Parameters

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

err (IN/OUT): The OCI error handle.

key (OUT): Reference to the key of the current element, the reference must not be modified.

keylen (OUT): Size of the referenced key string.

keytype (OUT): The type of the last key.

coll (IN): The pointer to the associative array collection.

29.8.9 OCITableNext()

Returns the index of the next existing element of a table.

Purpose

Returns the index of the next existing element of a table.

Syntax

sword OCITableNext ( OCIEnv             *env, 
                     OCIError           *err, 
                     sb4                 index, 
                     const OCITable     *tbl, 
                     sb4                *next_index
                     boolean            *exists );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
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().
index (IN): Index for the starting point of the scan.
tbl (IN): Table to scan.
next_index (OUT): Index of the next existing element after tbl(index).
exists (OUT): FALSE if no next index is available; otherwise, TRUE.

Returns

Returns the smallest position j, greater than index, such that exists(j) is TRUE.

Related Topics

29.8.10 OCITableKeyNext ()

Returns a reference pointer to the next existing key in an associative array collection.

Purpose

Returns a reference pointer to the next existing key in an associative array collection, based on the sorting order.

Syntax

sword OCITableKeyNext ( OCIEnv         *env, 
 OCIError       *err, 			
 CONST void     *key, 
 ub4             keylen,
 OCIKeyType      keytype,
 CONST OCITable *coll,
 void          **next_key,
 ub4            *next_keylen,
 OCIKeyType      next_keytype,
 boolean        *exists);

Parameters

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

err (IN/OUT): The OCI error handle.

key (IN): The non-null starting key value. The next key following this key is returned.

keylen (IN): The length of the starting key value.

keytype (IN): The type of the key.

coll (IN): The pointer to the associative array collection.

next_key (OUT): Reference to the key of the current element, the reference must not be modified.

next_keylen (OUT): Size of the next_key reference string.

next_keytype (OUT): The type of the next key.

exists (IN): The value is FALSE if no next key value is available, else the value is set to TRUE.

29.8.11 OCITablePrev()

Returns the index of the previous existing element of a table.

Purpose

Returns the index of the previous existing element of a table.

Syntax

sword OCITablePrev ( OCIEnv             *env, 
                     OCIError           *err, 
                     sb4                 index,
                     const OCITable     *tbl,
                     sb4                *prev_index
                     boolean            *exists );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
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().
index (IN): Index for the starting point of the scan.
tbl (IN): Table to scan.
prev_index (OUT): Index of the previous existing element before tbl(index).
exists (OUT): FALSE if no previous index is available; otherwise, TRUE.

Returns

Returns the largest position j, less than index, such that exists (j) is TRUE.

Related Topics

29.8.12 OCITableSize()

Returns the size of the given table, not including any holes created by deleted elements.

Purpose

Returns the size of the given table, not including any holes created by deleted elements.

Syntax

sword OCITableSize ( OCIEnv             *env,
                     OCIError           *err,
                     const OCITable     *tbl
                     sb4                *size );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate(), OCIEnvNlsCreate(), and OCIInitialize() (deprecated) for more information.
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().
tbl (IN): Nested table whose number of elements is returned.
size (OUT): Current number of elements in the nested table. The count does not include deleted elements.

Comments

The count is decremented when elements are deleted from the nested table. So this count does not include any holes created by deleting elements. To get the count including the holes created by the deleted elements, use OCICollSize().

The following code example shows a code fragment where an element is deleted from a nested table.

Deleting an Element from a Nested table

OCITableSize(...); 
// assume 'size' returned is equal to 5
OCITableDelete(...); // delete one element
OCITableSize(...);
// 'size' returned is equal to 4

To get the count plus the count of deleted elements, use OCICollSize(), as shown in the following code example. Continuing the previous code example.

Getting a Count of All Elements Including Deleted Elements from a Nested Table

OCICollSize(...)
// 'size' returned is still equal to 5

Returns

This function returns an error if an error occurs during the loading of the nested table into the object cache, or if any of the input parameters is NULL.

Related Topics