Element Packages

Each element type that can have instances created and stored in the repository using the CDAPI has a view and an associated PL/SQL package. Each package encapsulates:

A data record. This is a structured object containing the data part of the public interface provided by the package. It can be used to provide values and indicators required when issuing a call to create, update or otherwise manipulate an instance of the element type. When passed as a parameter in API calls, a data record is referred to as a property list.
Methods . These are PL/SQL functions and procedures for manipulating instances (and versions of each instance) of the element type in the repository. For details of the syntax and usage of these methods, see Usage of CDAPI Calls.
Exceptions. Each package defines the exceptions invalid_ref and element_locked, which are raised internally when an invalid reference is provided or when the element is currently locked for update by another session.

A summary of the PL/SQL packages is provided with the Repository API help.

For information on how to reference PL/SQL package contents, refer to the PL/SQL User's Guide and Reference.

Packages and views for all the pre-defined instantiable element types are available in the installed Repository. When new element types are created via Registration or User Extensibility, their packages are available after those processes.

The name of a package (whether it is a configured package or a registered package) is the name of the corresponding element type prefixed by ‘CIO’. For example, the name of the package for the configured ENTITY element type is cioentity; the name of a package for a registered element type called MYTYPE would be ciomytype.

The data members of the package correspond to the properties defined for the view.

PAC elements have a larger set of methods than SACs. The extra methods for PACs implement versioning operations such as check in and check out.

An important part of the CDAPI is the information that is published about the views and properties for those element types supported by the repository. Though the complete set of views is published to aid understanding of the structure of the repository, and to support extension of that structure, not all element types in the repository can be instantiated as objects. Therefore, not all views have a corresponding package defined. Only those element types that can be instantiated have a package, to enable instances of those element types (and versions of the instances) to be created, updated, deleted and otherwise manipulated in the repository. The main reason for publishing views of non-instantiable supertypes is to enable queries over all related subtypes. For example, a SQL a query on CI_RELATION_DEFINITIONS will return all TABLES, VIEWS, SNAPSHOTS and RECORDS.

The names of the columns in a view correspond to the names of the properties shown in the Element Definition page for the element type.

Package Data Records

Each element package contains a data record that can hold a property list appropriate for the element type.

Property Data Record
Usage of property lists

Property Data Record

The Property Data Record is a PL/SQL record type named data and is declared as a composite of two PL/SQL record types, as follows:

type data is record (v rm_values, i rm_indicators);

v is a the Property Value Record; i is the Property Indicator Record.

Property Value Record

In an instance of an element type, each member of v is used to hold the value for each property. For example, the Property Value Record for the element type entity, cioentity.rm_values, is declared as:

type rm_values is record
(
annual_growth_rate number(3) ,
changed_by varchar2(30) ,
created_by varchar2(30) ,
datawarehouse_type varchar2(10) ,
date_changed date ,
date_created date ,
element type_name varchar2(10) ,
id number(38) ,
initial_volume number(38) ,
instantiable_flag varchar2(1) ,
irid number(38) ,
ivid number(38) ,
maximum_volume number(38) ,
name varchar2(40) ,
number_of_times_modified number(38) ,
plural varchar2(40) ,
short_name varchar2(10) ,
supertype_reference number(38) ,
types number(38) ,
user_defined_property_0 varchar2(240),
user_defined_property_1 varchar2(240),
....
....
user_defined_property_19 varchar2(240),
volume number(38)
);

Note: The repository is case-sensitive in its treatment of the NAME property of supported elements.

Property Indicator Record

For every member in the Property Value Record there is a corresponding Boolean member declared in the Property Indicator Record (rm_indicators). For example, for the element type Entity, the Property Indicator Record (cioentity.rm_indicators) is defined as:

type rm_indicators is record
(

annual_growth_rate boolean not null default false,
changed_by boolean not null default false,
created_by boolean not null default false,
datawarehouse_type boolean not null default false,
…
…
…

.);

When an object of type cio<element type>.data is instantiated, the object contains a property data record v, and a property indicator record i.

All elements in the property data record (v) are set to NULL; all the indicators in the property indicator record (i) are set to FALSE.

Note: Some properties in some element types are system maintained and cannot be set by a caller during insert or update operations. For such properties, the legend:

System maintained...

appears against the property in the Element Type Definitions pages.

Usage Of Property Lists

For a call that passes a property data record object as a parameter, the properties in v and indicators in i must be set or interpreted as follows:

Usage of the Property Data Record (PDR).

In the case of call that retrieves data, v contains the relevant data returned from the call. v.ID always contains the unique identifier of the element version that was the target of the call.

Note: An incorrectly specified property list in a call to a CDAPI method always generates an exception which must be handled by the caller. For example, when inserting a new element, if any of the properties in the property list violates database integrity rules or repository uniqueness rules, an exception is raised by the API.

Usage of the Property Indicator Record (PIR)

The caller must set a property's corresponding indicator to specify whether a value has been explicitly provided for that property in the PDR. The indicators are for the caller to specify how the contents of the corresponding properties are to be interpreted when the call is processed. For example, consider a call to obj.upd (): if obj.v.X is set to NULL, and obj.i.X is set to TRUE, this is a specific request for the property to be updated to contain NULL, instead of leaving it untouched.

For some methods, the indicator is also used by the API to indicate to the user whether the user-provided corresponding property value was in fact used. If an indicator which was set to TRUE by the user before performing the operation has been set to FALSE by the API, this means that the property was not eligible for update. Additionally, values assigned automatically by the API have their corresponding indicators set to TRUE on return from the call.

Note: For some operations, such as sel, the indicator record is ignored by the API.

The following example creates two new entity elements, one with NAME property 'Car' and the other with NAME property 'Truck'.

declare
MyEntObj1 cioentity.data;
begin
MyEntObj1.v.name:='Car';
MyEntObj1.i.name:=TRUE;
.
.
cioentity.ins (NULL, MyEntObj1);
.
MyEntObj1.v.name:='Truck';
MyEntObj1.i.name:=TRUE;
.
.
cioentity.ins (NULL, MyEntObj2);.
.
etc.

Note:
Values assigned automatically by the API have their corresponding indicators set to TRUE on return from the call. This means that after inserting the Entity 'Car', MyEntObj.v.id is set to the value assigned to it by CDAPI. Because MyEntObj.i.id is now TRUE, CDAPI will assume that the user is trying to use this value as the ID in the next insert command, which will mean that:

Two rows would have the same value for ID
An error is raised.

The solution is: either to set all the indicators to false after the first insert, or to use MyEntObj1 and MyEntObj2.

Element Package Methods

Summary of CDAPI Element Package Methods

Method	Method name	What it does
create	ins	Adds a new object of the specified element type to the context workarea.
reference	sel	Retrieves properties of the element currently visible in the context workarea. The element to be retrieved using this method can only be specified by its IRID. To specify the element using other properties, use a query on the view. Even in cases where the IRID is known, it is usually quicker to query the view using SQL.
update	upd	Replaces indicated property values with supplied values.
delete	del	Makes the specified object invisible in the context workarea. It becomes visible in the workarea’s wastebasket.
copy	copy_pac copy sac	For PAC objects, copies an object version into the current context container. A copy of a SAC can be placed in the same PAC, or in any other PAC by updating the appropriate reference property in the copy.
lock database row	lck	Prevents the object being updated or deleted by another process.
check in	check_in	Makes a new version of an object and makes the new version available to other repository users. Of the versioning methods, only check-in/out are available in CDAPI. For more sophisticated operations, the Version service API is provided.
check out	check_out	Creates a private copy of an object version in the current context workarea. Check_out can optionally lock the original version. Of the versioning methods, only check in and out are available in CDAPI. For more sophisticated opserations, the caller typically needs to call other methods in the Version Service API.

Exceptions Posted by Element Packages

Processing of a CDAPI method call may encounter an error condition that prevents the operation from continuing. In such cases, the CDAPI posts a message on its internal message stack. Two of these cases are also accompanied by exceptions defined in each element package:

invalid_ref, raised when an invalid reference ID is passed to upd and sel operations.
element_locked, raised when an upd or del operation is attempted on an element that is currently locked by another CDAPI session.

Note: Other packages in the Repository API post a variety of messages and raise a number of exceptions that are too numerous to list. For details of how to handle exceptions generally in client code, see Handling Errors.