17 Objects

Object Types

An object type is a user-defined datatype that has attributes, the variables that form the datatype defined by a CREATE TYPE SQL statement, and methods, functions and procedures that are the set of allowed behaviors of the object type. We consider object types with only attributes in this guide.

For example:

--Defining an object type...
CREATE TYPE employee_type AS OBJECT(
    name    VARCHAR2(20),
    id      NUMBER,
    MEMBER FUNCTION get_id(name VARCHAR2) RETURN NUMBER);
/
--
--Creating an object table...
CREATE TABLE employees OF employee_type;
--Instantiating an object, using a constructor...
INSERT INTO employees VALUES (
        employee_type('JONES', 10042));

LONG, LONG RAW, NCLOB, NCHAR and NCHAR Varying are not allowed as datatypes in attributes of objects.

REFs to Object Types

REF (short for "reference") was also new in Oracle8. It is a reference to an object stored in a database table, instead of the object itself. REF types can occur in relational columns and also as datatypes of an object type. For example, a table employee_tab can have a column that is a REF to an object type employee_t itself:

CREATE TYPE employee_t AS OBJECT(
   empname         CHAR(20),
   empno           INTEGER,
   manager         REF employee_t);
/
CREATE TABLE employee_tab OF employee_t;

Type Inheritance

Oracle9i supports type inheritance of objects. This enables sharing of attributes and methods between similar object types, as well as extending the characteristics of an object type.

Pro*C/C++ supports type inheritance of object types with the following SQL operators:

• IS OF type

• TREAT

The IS OF type operator is used to test an object instance for specific type information.

The following code example returns the references to all p objects where p is of type Employee_t and Student_t.

SELECT REF(p)
   FROM person_tab p
   WHERE VALUE(p) IS OF (Employee_t, Student_t);

The following code example returns all rows where p is of type Student_t only.

SELECT VALUE(p)
   FROM person_tab p
   WHERE VALUE(p) IS OF (ONLY Student_t);

The TREAT operator is used to modify the declared type of an expression.

The following code example returns all rows where p is of type Student_t. For all instances of p that are not of type Student_t, null is returned.

SELECT TREAT(VALUE(p) AS Student_t)
   FROM person_tab p;

The following code example returns the references to all p objects of type Student_t and any objects of subtype PartTimeStudent_t.

SELECT TREAT(REP(p) AS REF Student_t) 
   FROM person_tab p
   WHERE VALUE(p) IS OF (Student_t);

NULL Indicators

C structures representing the NULL status of object types are generated by the Object Type Translator. You must use these generated structure types in declaring indicator variables for object types.

Other Oracle types do not require special treatment for NULL indicators.

Because object types have internal structure, NULL indicators for object types also have internal structure. A NULL indicator structure for a non-collection object type provides atomic (single) NULL status for the object type as a whole, as well as the NULL status of every attribute. OTT generates a C structure to represent the NULL indicator structure for the object type. The name of the NULL indicator structure is Object_typename_ind where Object_typename is the name of the C structure for the user-defined type in the database.

Persistent Versus Transient Copies of Objects

Objects that you allocated in the cache with EXEC SQL ALLOCATE statements in Pro*C/C++ are transient copies of persistent objects in the Oracle database. As such, you can update these copies in the cache after they are fetched in, but in order to make these changes persistent in the database, you must use explicit SQL commands. This "transient copy" or "value-based" object caching model is an extension of the relational model, in which scalar columns of relational tables can be fetched into host variables, updated in place, and the updates communicated to the server.

When to Use the Associative Interface

Use in these cases:

• To access large collections of objects where explicit joins between tables are not expensive.

• To access objects that are not referenceable; they do not have object identity. For example, an object type in a relational column.

• When an operation such as UPDATE or INSERT is applied to a set of objects. For example, add a bonus of $1000 to all employees in a department.

ALLOCATE

You allocate space in the object cache with this statement. The syntax is:

EXEC SQL [AT [:]database] ALLOCATE :host_ptr [[INDICATOR]:ind_ptr] ;

Variables entered are:

database (IN)

a zero-terminated string containing the name of the database connection, as established previously through the statement:

EXEC SQL CONNECT :user [AT [:]database];

If the AT clause AT is omitted, or if database is an empty string, the default database connection is assumed.

host_ptr (IN)

a pointer to a host structure generated by OTT for object types, collection object types, or REFs, or a pointer to one of the new C datatypes: OCIDate, OCINumber, OCIRaw, or OCIString.

ind_ptr (IN)

The indicator variable, ind_ptr, is optional, as is the keyword INDICATOR. Only pointers to struct-typed indicators can be used in the ALLOCATE and FREE statements.

host_ptr and ind_ptr can be host arrays.

The duration of allocation is the session. Any instances will be freed when the session (connection) is terminated, even if not explicitly freed by a FREE statement.

For more details, see "ALLOCATE (Executable Embedded SQL Extension)" and "FREE (Executable Embedded SQL Extension)".

FREE

EXEC SQL [AT[:]database] [OBJECT] FREE :host_ptr [[INDICATOR]:ind_ptr];

You de-allocate the space for an object that is placed in the object cache using the FREE statement. Variables used are the same as in the ALLOCATE statement.

CACHE FREE ALL

EXEC SQL [AT [:]database] [OBJECT] CACHE FREE ALL;

Use the earlier statement to free all object cache memory for the specified database connection.

Accessing Objects Using the Associative Interface

When accessing objects using SQL, Pro*C/C++ applications manipulate transient copies of the persistent objects. This is a direct extension of the relational access interface, which uses SELECT, UPDATE and DELETE statements.

In Figure 17-1, you allocate memory in the cache for a transient copy of the persistent object with the ALLOCATE statement. The allocated object does not contain data, but it has the form of the struct generated by the OTT.

person *per_p;
...
EXEC SQL ALLOCATE :per_p;

You can execute a SELECT statement to populate the cache. Or, use a FETCH statement or a C assignment to populate the cache with data.

EXEC SQL SELECT ... INTO :per_p FROM person_tab WHERE ...

Make changes to the server objects with INSERT, UPDATE or DELETE statements, as shown in the illustration. You can insert the data is into the table by the INSERT statement:

EXEC SQL INSERT INTO person_tab VALUES(:per_p);

Finally, free memory associated with the copy of the object with the FREE statement:

EXEC SQL FREE :per_p;

Figure 17-1 Accessing Objects Using SQL

Description of the illustration lnpcc069.gif

When to Use the Navigational Interface

Use the navigational interface:

• To access a single or small set of objects where explicit joins between tables are expensive. When you use dereferencing to navigate between objects, you perform implicit joins which are less expensive than an explicit join across two entire tables.

• To make many small changes to many different objects. It is more convenient to fetch all objects to the client, make changes, mark them as updated, and flush all the changes back to the server.

Rules Used in the Navigational Statements

Embedded SQL OBJECT statements are described later with these assumptions:

• If an AT clause is absent, the default (unnamed) connection is assumed.

• Host variables can be arrays, except where specifically noted.

• Use the FOR clause to explicitly specify the array dimension. If absent, the minimum dimension of the pertinent host variables is used.

• After execution of the statement, if the SQLCA is provided as a status variable, the number of elements processed is returned in sqlca.sqlerrd[2].

• Parameters have IN or OUT (or both) specified to signify input or output.

  
  

  See Also: Appendix F, " Embedded SQL Statements and Directives" for SQL OBJECT statements and syntax diagrams

  
  

OBJECT CREATE

EXEC SQL [AT [:]database] [FOR [:]count] OBJECT CREATE :obj [INDICATOR]:
obj_ind [TABLE tab] [RETURNING REF INTO :ref] ;

where tab is:

{:hv | [schema.]table}

Use this statement to create a referenceable object in the object cache. The type of the object corresponds to the host variable obj. When optional type host variables (:obj_ind,:ref,:ref_ind) are supplied, they must all correspond to the same type.

The referenceable object can be either persistent (TABLE clause is supplied) or transient (TABLE clause is absent). Persistent objects are implicitly pinned and marked as updated. Transient objects are implicitly pinned.

The host variables are:

obj (OUT)

The object instance host variable, obj, must be a pointer to a structure generated by OTT. This variable is used to determine the referenceable object that is created in the object cache. After a successful execution, obj will point to the newly created object.

obj_ind (OUT)

This variable points to an OTT-generated indicator structure. Its type must match that of the object instance host variable. After a successful execution, obj_ind will be a pointer to the parallel indicator structure for the referenceable object.

tab (IN)

Use the table clause to create persistent objects. The table name can be specified as a host variable, hv, or as an undeclared SQL identifier. It can be qualified with a schema name. Do not use trailing spaces in host variables containing the table name.

hv (IN)

A host variable specifying a table. If a host variable is used, it must not be an array. It must not be blank-padded. It is case-sensitive. When an array of persistent objects is created, they are all associated with the same table.

table (IN)

An undeclared SQL identifier which is case-sensitive.

ref (OUT)

The reference host variable must be a pointer to the OTT-generated reference type. The type of ref must match that of the object instance host variable. After execution, ref contains a pointer to the ref for the newly created object.

Attributes are initially set to null. Creating new objects for object views is not currently supported.

Creating new objects for object views is not currently supported.

OBJECT DEREF

EXEC SQL [AT [:]database] [FOR [:]count] OBJECT DEREF :ref INTO :obj [[INDICATOR]:obj_ind
] [FOR UPDATE [NOWAIT]] ;

Given an object reference, ref, the OBJECT DEREF statement pins the corresponding object or array of objects in the object cache. Pointers to these objects are returned in the variables obj and obj_ind.

The host variables are:

ref (IN)

This is the object reference variable, which must be a pointer to the OTT-generated reference type. This variable (or array of variables) is dereferenced, returning a pointer to the corresponding object in the cache.

obj (OUT)

The object instance host variable, obj, must be a pointer to an OTT-generated structure. Its type must match that of the object reference host variable. After successful execution, obj contains a pointer to the pinned object in the object cache.

obj_ind (OUT)

The object instance indicator variable, obj_ind, must be a pointer to an OTT-generated indicator structure. Its type must match that of the object reference indicator variable. After successful execution, obj_ind contains a pointer to the parallel indicator structure for the referenceable object.

FOR UPDATE

If this clause is present, an exclusive lock is obtained for the corresponding object in the server.

NOWAIT

If this optional keyword is present, an error is immediately returned if another user has already locked the object.

OBJECT RELEASE

EXEC SQL [AT [:]database] [FOR [:]count] OBJECT RELEASE :obj ;

This statement unpins the object in the object cache. When an object is not pinned and not updated, it is eligible for implicit freeing.

If an object has been dereferenced n times, it must be released n times to be eligible for implicit freeing from the object cache. Oracle advises releasing all objects that are no longer needed.

OBJECT DELETE

EXEC SQL [AT [:]database] [FOR [:]count] OBJECT DELETE :obj ;

For persistent objects, this statement marks an object or array of objects as deleted in the object cache. The object is deleted in the server when the object is flushed or when the cache is flushed. The memory reserved in the object cache is not freed.

For transient objects, the object is marked as deleted. The memory for the object is not freed.

OBJECT UPDATE

EXEC SQL [AT [:]database] [FOR [:]count] OBJECT UPDATE :obj ;

For persistent objects, this statement marks them as updated in the object cache. The changes are written to the server when the object is flushed or when the cache is flushed.

For transient objects, this statement is a no-op.

OBJECT FLUSH

EXEC SQL [AT [:]database] [FOR [:]count] OBJECT FLUSH :obj ;

This statement flushes persistent objects that have been marked as updated, deleted, or created, to the server.

Navigational Access to Objects

See Figure 17-2 for an illustration of the navigational interface.

Use the ALLOCATE statement to allocate memory in the object cache for a copy of the REF to the person object. The allocated REF does not contain data.

person *per_p;
person_ref *per_ref_p;
...
EXEC SQL ALLOCATE :per_p;

Populate the allocated memory by using a SELECT statement to retrieve the REF of the person object (exact format depends on the application):

EXEC SQL SELECT ... INTO :per_ref_p;

The DEREF statement is then used to pin the object in the cache, so that changes can be made in the object. The DEREF statement takes the pointer per_ref_p and creates an instance of the person object in the client-side cache. The pointer per_p to the person object is returned.

EXEC SQL OBJECT DEREF :per_ref_p INTO :per_p;

Figure 17-2 Navigational Access

Description of the illustration lnpcc070.gif

Make changes to the object in the cache by using C assignment statements, or by using data conversions with the OBJECT SET statement.

Then you must mark the object as updated. See Figure 17-3. To mark the object in the cache as updated, and eligible to be flushed to the server:

EXEC SQL OBJECT UPDATE :per_p;

You send changes to the server by the FLUSH statement:

EXEC SQL OBJECT FLUSH :per_p;

You release the object:

EXEC SQL OBJECT RELEASE :per_p;

Figure 17-3 Navigational Access (continued)

Description of the illustration lnpcc071.gif

The statements in the next section are used to make the conversions between object attributes and C types.

OBJECT SET

EXEC SQL [AT [:]database] 
  OBJECT SET  [ {'*' | {attr[, attr]} } OF] 
    :obj [[INDICATOR]:obj_ind] 
       TO {:hv [[INDICATOR]:hv_ind] 
          [, :hv [INDICATOR]:hv_ind]]} ;

Use this statement with objects created by both the associative and the navigational interfaces. This statement updates the attributes of the object. For persistent objects, the changes will be written to the server when the object is updated and flushed. Flushing the cache writes all changes made to updated objects to the server.

The OF clause is optional. If absent, all the attributes of obj are set. The same result is achieved by writing:

... OBJECT SET * OF ...

The host variable list can include structures that are exploded to provide values for the attributes. However, the number of attributes in obj must match the number of elements in the exploded variable list.

Host variables and attributes are:

attr

The attributes are not host variables, but rather simple identifiers that specify which attributes of the object will be updated. The first attribute in the list is paired with the first expression in the list, and so on. The attribute must be one of either OCIString, OCINumber, OCIDate, or OCIRef.

obj (IN/OUT)

obj specifies the object to be updated. The bind variable obj must not be an array. It must be a pointer to an OTT-generated structure.

obj_ind (IN/OUT)

The parallel indicator structure that will be updated. It must be a pointer to an OTT-generated indicator structure.

hv (IN)

This is the bind variable used as input to the OBJECT SET statement. hv must be an int, float, OCIRef *, a one-dimensional char array, or a structure of these types.

hv_ind (IN)

This is the associated indicator that is used as input to the OBJECT SET statement. hv_ind must be a 2-byte integer scalar or a structure of 2-byte integer scalars.

Using Indicator Variables:

If a host variable indicator is present, then an object indicator must also be present.

If hv_ind is set to -1, the associated field in the obj_ind is set to -1.

The following implicit conversions are permitted:

• [OCIString | STRING | VARCHAR | CHARZ] to OCIString

• OCIRef to OCIRef

• [OCINumber | int | float | double] to OCINumber

• [OCIDate | STRING | VARCHAR | CHARZ ] to OCIDate

  
  

  Note: Nested structures are not allowed. This statement cannot be used to set a referenceable object to be atomically NULL. Set the appropriate field of the NULL indicator instead. Conversions between the OCIDateTime or OCIInterval datatypes and OCIString are not supported.

  
  

OBJECT GET

EXEC SQL [AT [:]database] 
   OBJECT GET [ { '*' | {attr[, attr]} } FROM]
     :obj [[INDICATOR]:obj_ind] 
        INTO {:hv [[INDICATOR]:hv_ind]
          [, :hv [[INDICATOR]:hv_ind]]} ;

This statement converts the attributes of an object into native C types.

The FROM clause is optional. If absent, all the attributes of obj are converted. The same result is achieved by writing:

... OBJECT GET * FROM ...

The host variable list may include structures that are exploded to receive the values of the attributes. However, the number of attributes in obj must match the number of elements in the exploded host variable list.

Host variables and attributes:

attr

The attributes are not host variables, but simple identifiers that specify which attributes of the object will be retrieved. The first attribute in the list is paired with the first host variable in the list, and so on. The attribute must represent a base type. It must be OCIString, OCINumber, OCIRef, or OCIDate.

obj (IN)

This specifies the object that serves as the source for the attribute retrieval. The bind variable obj must not be an array.

hv (OUT)

This is the bind variable used to hold output from the OBJECT GET statement. It can be an int, float, double, a one-dimensional char array, or a structure containing those types. The statement returns the converted attribute value in this host variable.

hv_ind (OUT)

This is the associated indicator variable for the attribute value. It is a 2-byte integer scalar or a structure of 2-byte integer scalars.

Using Indicator Variables:

If no object indicator is specified, it is assumed that the attribute is valid. It is a program error to convert object attributes to C types if the object is atomically NULL or if the requested attribute is NULL and no object indicator variable is supplied. It may not be possible to raise an Oracle error in this situation.

If the object variable is atomically NULL or the requested attribute is NULL, and a host variable indicator (hv_ind) is supplied, then it is set to -1.

If the object is atomically NULL or the requested attribute is NULL, and no host variable indicator is supplied, then an error is raised.

The following implicit conversions are permitted:

• OCIString to [STRING | VARCHAR | CHARZ | OCIString]

• OCINumber to [int | float | double | OCINumber]

• OCIRef to OCIRef

• OCIDate to [STRING | VARCHAR | CHARZ | OCIDate]

  
  

  Note: Nested structures are not allowed Conversions between the OCIDateTime or OCIInterval datatypes and OCIString are not supported

  
  

CONTEXT OBJECT OPTION SET

EXEC SQL CONTEXT OBJECT OPTION SET {option[, option]} TO {:hv[, :hv]} ;

where the variables are:

:hv(IN) ...

The input bind variables hv ..., are of type STRING, VARCHAR, or CHARZ.

option ...

Simple identifiers that specify which option of the runtime context to update. The first option is paired with the first input bind variable, and so on. Here are the values supported at this time:

An example is:

char *new_format = "DD-MM-YYYY";
char *new_lang = "French";
char *new_date = "14-07-1789";
/* One of the attributes of the license type is dateofbirth */
license *aLicense; 
...
/* Declaration and allocation of context ... */
EXEC SQL CONTEXT OBJECT OPTION SET DATEFORMAT, DATELANG TO :new_format,   :new_lang;
/* Navigational object obtained  */
...
EXEC SQL OBJECT SET dateofbirth OF :aLicense TO :new_date;
...

CONTEXT OBJECT OPTION GET

The context affected is understood to be the context in use at the time. To determine the values of these options, use this directive:

EXEC SQL CONTEXT OBJECT OPTION GET {option[, option]} INTO {:hv[, :hv]} ;

Where the values of option are found in Table 17-1, "Valid Choices for CONTEXT OBJECT OPTION Values".

The bind variables, hv ... are used as output, and are of type STRING, VARCHAR, or CHARZ. The context affected is understood to be the context in use at the time.

VERSION

This option determines which version of the object is returned by the EXEC SQL OBJECT DEREF statement. This gives you varying levels of consistency between cache objects and server objects.

Use the EXEC ORACLE OPTION statement to set it inline. Permitted values are:

RECENT (default)

If the object has been selected into the object cache in the current transaction, then return that object. If the object has not been selected, it is retrieved from the server. For transactions that are running in serializable mode, this option has the same behavior as VERSION=LATEST without incurring as many network round trips. This value can be safely used with most Pro*C/C++ applications.

LATEST

If the object does not reside in the object cache, it is retrieved from the database. If it does reside in the object cache, it is refreshed from the server. Use this value with caution because it will incur the greatest number of network round trips. Use it only when it is imperative that the object cache be kept as coherent as possible with the server-side buffer.

ANY

If the object already resides in the object cache, then return that object. If the object does not reside in the object cache, retrieve it from the server. This value will incur the fewest number of network round trips. Use in applications that access read-only objects or when a user will have exclusive access to the objects.

DURATION

Use this precompiler option to set the pin duration used by subsequent EXEC SQL OBJECT CREATE and EXEC SQL OBJECT DEREF statements. Objects in the cache are implicitly unpinned at the end of the duration.

Use with navigational interface only.

You can set this option in the EXEC ORACLE OPTION statement. Permitted values are:

TRANSACTION (default)

Objects are implicitly unpinned when the transaction completes.

SESSION

Objects are implicitly unpinned when the connection is terminated.

OBJECTS

This precompiler option provides the ability to use the object cache.

The OBJECTS default value, for DBMS=NATIVE | V8, is YES. The default size of the object cache is the same as the OCI default cache size, 8 Mbytes.

INTYPE

If your program uses any object types, collection object types, or REFs, you must give the INTYPE files in this command-line option.

Specify the INTYPE option using the syntax:

INTYPE=filename1 INTYPE=filename2 ...

where filename1, and so on., is the name of the typefiles generated by OTT. These files are meant to be a read-only input to Pro*C/C++. The information in it, though in plain-text form, might be encoded, and might not necessarily be interpretable by you, the user.

You can provide more than one INTYPE file as input to a single Pro*C/C++ precompilation unit.

This option cannot be used inline in EXEC ORACLE statements.

OTT generates C structure declarations for object types created in the database, and writes type names and version information to a file called the typefile.

An object type may not necessarily have the same name as the C structure type or C++ class type that represents it. This could arise for the following reasons:

• The name of the object type specified in the server includes characters not legal in a C or C++ identifier

• The user asked OTT to use a different name for the structure or class

• The user asked OTT to change the case of names

Under these circumstances, it is impossible to infer from the structure or class declaration which object type it matches. This information, which is required by Pro*C/C++, is generated by OTT in the type file.

ERRTYPE

ERRTYPE=filename

Writes errors to the file specified, as well as to the screen. If omitted, errors are directed to the screen only. Only one ERRTYPE is allowed. As is usual with other single-valued command-line options, if you enter multiple values for ERRTYPE on the command line, the last one supersedes the earlier values.

This option cannot be used inline in EXEC ORACLE statements.

SQLCHECK Support for Objects

Object types and their attributes are represented in a C program according to the C binding of Oracle types. If the precompiler command-line option SQLCHECK is set to SEMANTICS or FULL, Pro*C/C++ verifies during precompilation that host variable types conform to the mandated C bindings for the types in the database schema. In addition, runtime checks are always performed to verify that Oracle types are mapped correctly during program execution. See also "SQLCHECK".

Relational datatypes are checked in the usual manner.

A relational SQL datatype is compatible with a host variable type if the two types are the same, or if a conversion is permitted between the two. Object types, on the other hand, are compatible only if they are the same type. They must

• Have the same name

• Be in the same schema (if a schema is explicitly specified)

When you specify the option SQLCHECK=SEMANTICS or FULL, during precompilation Pro*C/C++ logs onto the database using the specified userid and password, and verifies that the object type from which a structure declaration was generated is identical to the object type used in the embedded SQL statement.

Type Checking at Runtime

Pro*C/C++ gathers the type name, version, and possibly schema information for Object, collection Object, and REF host variables, for a type from the input INTYPE file, and stores this information in the code that it generates. This enables access to the type information for Object and REF bind variables at runtime. Appropriate errors are returned for type mismatches.

Associative Access

Consider the case of how to change a lastname value from "Smith" to "Smythe", using Pro*C/C++.

Run the OTT to generate C structures which map to person. In your Pro*C/C++ program you must include the header file generated by OTT.

In your application, declare a pointer, person_p, to the persistent memory in the client-side cache. Then allocate memory and use the returned pointer:

char *new_name = "Smythe";
person *person_p;
...
EXEC SQL ALLOCATE :person_p;

Memory is now allocated for a copy of the persistent object. The allocated object does not yet contain data.

Populate data in the cache either by C assignment statements or by using SELECT or FETCH to retrieve an existing object:

EXEC SQL SELECT VALUE(p) INTO :person_p FROM person_tab p WHERE lastname = 'Smith';

Changes made to the copy in the cache are transmitted to the server database by use of INSERT, UPDATE, and DELETE statements:

EXEC SQL OBJECT SET lastname OF :person_p TO :new_name;
EXEC SQL INSERT INTO person_tab VALUES(:person_p);

Free cache memory in this way:

EXEC SQL FREE :person_p;

Navigational Access

Allocate memory in the object cache for a copy of the REF to the object person. The ALLOCATE statement returns a pointer to the REF:

person *person_p;
person_ref *per_ref_p;
...
EXEC SQL ALLOCATE :per_ref_p;

The allocated REF contains no data. To populate it with data, retrieve the REF of the object:

EXEC SQL SELECT ... INTO :per_ref_p;

Then dereference the REF to put an instance of object in the client-side cache. The dereference command takes the per_ref_p and creates an instance of the corresponding object in the cache:

EXEC SQL OBJECT DEREF :per_ref_p INTO :person_p;

Make changes to data in the cache by using C assignments, or by using OBJECT GET statements:

/* lname is a C variable to hold the result */
EXEC SQL OBJECT GET lastname FROM :person_p INTO :lname;
...
EXEC SQL OBJECT SET lastname OF :person_p TO :new_name;
/* Mark the changed object as changed with OBJECT UPDATE command */;
EXEC SQL OBJECT UPDATE :person_p;
EXEC SQL FREE :per_ref_p;

To make the changes permanent in the database, use FLUSH:

EXEC SQL OBJECT FLUSH :person_p;

Changes have been made to the server; the object can now be released. Objects that are released are not necessarily freed from the object cache memory immediately. They are placed on a least-recently used stack. When the cache is full, the objects are swapped out of memory.

Only the object is released; the REF to the object remains in the cache. To release the REF, use the RELEASE statement. for the REF. To release the object pointed to by person_p:

EXEC SQL OBJECT RELEASE :person_p;

Or, issue a transaction commit and all objects in the cache are released, provided the pin duration has been set appropriately.

Generating a C Structure for a REF

The C representation for a REF to an object type is generated by OTT during type translation. For example, a reference to a user-defined PERSON type in the database may be represented in C as the type "Person_ref". The exact type name is determined by the OTT options in effect during type translation. The OTT-generated typefile must be specified in the INTYPE option to Pro*C/C++ and the OTT-generated header #included in the Pro*C/C++ program. This scheme ensures that the proper type-checking for the REF can be performed by Pro*C/C++ during precompilation.

A REF type does not require a special indicator structure to be generated by OTT; a scalar signed 2-byte indicator is used instead.

Declaring REFs

A host variable representing a REF in Pro*C/C++ must be declared as a pointer to the appropriate OTT-generated type.

Unlike object types, the indicator variable for a REF is declared as the signed 2-byte scalar type OCIInd. As always, the indicator variable is optional, but it is a good programming practice to use one for each host variable declared.

Using REFs in Embedded SQL

REFs reside in the object cache. However, indicators for REFs are scalars and cannot be allocated in the cache. They generally reside in the user stack.

Prior to using the host structure for a REF in embedded SQL, allocate space for it in the object cache by using the EXEC SQL ALLOCATE command. After use, free using the EXEC SQL FREE or EXEC SQL CACHE FREE ALL commands.

Memory for scalar indicator variables is not allocated in the object cache, and hence indicators are not permitted to appear in the ALLOCATE and FREE commands for REF types. Scalar indicators declared as OCIInd reside on the program stack. At runtime, the ALLOCATE statement causes space to be allocated in the object cache for the specified host variable. For the navigational interface, use EXEC SQL GET and EXEC SQL SET, not C assignments.

Pro*C/C++ supports REF host variables in associative SQL statements and in embedded PL/SQL blocks.

Declaring OCIDate, OCIString, OCINumber, OCIRaw

The OCI* types appear as object type attributes in OTT-generated structures, and you use them as part of object types in Pro*C/C++ programs. Other than their use in object types, Oracle recommends that the beginner-level C and Pro*C/C++ user avoid declaring individual host variables of these types. An experienced Pro*C/C++ user may wish to declare C host variables of these types to take advantage of the advanced functionality these types provide. The host variables must be declared as pointers to these types, for example, OCIString *s. The associated (optional) indicators are scalar signed 2-byte quantities, declared, for example, OCIInd s_ind.

Use of the OCI Types in Embedded SQL

Space for host variables of these types may be allocated in the object cache using EXEC SQL ALLOCATE. Scalar indicator variables are not permitted to appear in the ALLOCATE and FREE commands for these types. You allocate such indicators statically on the stack, or dynamically on the heap. De-allocation of space can be done using the statement EXEC SQL FREE, EXEC SQL CACHE FREE ALL, or automatically at the end of the session.

Manipulating the OCI Types

Except for OCIDate, which is a structure type with individual fields for various date components: year, month, day, hour and so on., the other OCI types are encapsulated, and are meant to be opaque to an external user. In contrast to the way existing C types like VARCHAR are currently handled in Pro*C/C++, you include the OCI header file oci.h and employ its functions to perform DATE arithmetic, and to convert these types to and from native C types such as int, char, and so on.