The CDAPI

See also:

CDAPI Activities
PL/SQL Example

CDAPI's element packages provide the following methods for managing objects in the repository:

check_in
check_out
copy_pac
copy_sac
del
ins
lck
sel
upd

Access Requirements

• Access to a PAC element is determined by access rights on its owning container. Access to a SAC element is determined by access rights on its parent PAC element.
  
  
• For the ins method, the caller must have the INS access right on the context container.
  
  
• For the del, sel, and upd methods, the caller must have the DEL, SEL, and UPD access rights, respectively, on the owning container of the element.
  
  
• For the lck method, the caller must have the SEL access right on the owning container of the element.
  
  
• For the copy_pac method, the caller must have the SEL access right on the owning container of the source object, and the INS access right on the target container. This also applies to the share_pac method.
  
  
• For the copy_sac method, the caller must have the SEL access right on the owning container of the source PAC, and the INS access right on the container of the target PAC.
  
  
• The requirements for the check_in and check_out methods are as described for the corresponding methods in the Version Service API.

For details of the various access rights and system privileges, see The Privileges and Access Rights API.

Notes:

1. In the following descriptions, element type is the name of the element type as defined in the Oracle Designer Model, and shown in the Element Type Name section on the Element Type Definitions page for the element type. For example, for application modules, this is 'application_module'.
   
   
2. The information about the ins, upd, and del methods should be read in conjunction with the information in the 'Secondary Processing' and 'Deletion Rules' sections in the API Spec for the element type. The API Spec for an element type can be reached via the Element Type Definitions page for the element type.
   
   
3. It is recommended that calls to all methods be made within a CDAPI activity, except for check_in and check_out, which do not use the activity model for error handling.
   
   
4. For all CDAPI methods, a context workarea must be set.
   
   
5. The ins method is the only method which generally requires a context container to be set. However, calling ins with no context container set is allowed when creating a container; the result in that case is a new root container.
   
   
6. Where a method takes a property list as a parameter, the property list always contains the current values of the data on return from the call.
   
   
7. A PLSQL_MODULE is usually treated as a  PAC element.  However, when its ORACLE_OBJECT_TYPE_REFERENCE property is set, it behaves as if it were a SAC element.  Therefore, some methods (those that work with PAC elements only) cannot be used with a PLSQL_MODULE element that has this property set.
   
   
8. Only the check_in method affects the version history of the repository.

PROCEDURE cio<element type>.check_in (i_irid NUMBER
                                    , i_ivid NUMBER
                                    , i_notes VARCHAR2 default NULL
                                    , i_vlabel VARCHAR2 default NULL
                                    , o_ivid OUT NUMBER);

Where:

i_irid is the IRID of the object to be checked in.

i_ivid is IVID of the particular version of the element. This can be left NULL.

i_notes is an optional checkin note.

i_vlabel is an optional version label for the new version created by the checkin operation. If NULL

o_ivid is the IVID assigned to the new version created by the check in.

Description

IRID must be the identifier for a PAC object or container element, which must either be new or have a currently checked out version.

The checkin operation updates the version history of the object identified by IRID. 

This procedure is a wrapper for JR_VERSION.check_in .  The object is checked in at the tip of the current branch.  Methods on the JR_VERSION package provide for more flexible checkin operations .

Applies to PACs and container element types only.

For a checkin operation, a context workarea must be set.  The operation fails if the object has already been branched to the default branch and the checked out version is on a different branch. The operation also fails if it will result in a check-in at tip on a branch that has been locked by another user.

Does not check whether the version being checked in is different to the current tip node; so a new version will be added to the branch, even if no changes have been made.

After an object version has been checked in, it is not available for update or delete, though it is otherwise available in the workarea.

This method can be called outside any CDAPI activity.

Note: When an object is checked in for the first time, its owning container must also be explicitly checked in, otherwise the new object is not visible to other repository users.

Errors are passed out on the built in PLSQL error stack, and are generated if:

• The JR_VERSION.is_merge_needed method returns TRUE.
  
  
• Any errors result from the underlying call to JR_VERSION.check_in .

See also

jr_version.check_in
API Methods List

PROCEDURE cio<element type>.check_out (i_irid NUMBER
                                     , i_ivid NUMBER
                                     , i_lock VARCHAR2 default 'Y'
                                     , i_notes VARCHAR2 default NULL
                                     , i_vlabel VARCHAR2 default NULL
                                     , o_ivid OUT NUMBER
                                     , copy_deps_policy in VARCHAR2); 

Where:

i_irid is the IRID of element to be checked out.

i_ivid is the IVID of the object version to be checked out.

i_lock, i_notes, i_vlabel, o_ivid, are as described for JR_VERSION.check_out. (Note, however, that with JR_VERSION.check_out, the i_lock parameter is a boolean).

copy_deps_policy specifies whether dependency information should be copied when the new version of the object is created: 'Y' = copy dependency information. 'N' = do not copy dependency information.

Description

This procedure is a wrapper for JR_VERSION.check_out.   The object is checked out from the tip of the current branch.  Methods on the JR_VERSION package provide for more flexible checkout operations .

The object identified by IRID must be currently checked in.  A checkout operation does not contribute to the version history of the object.

This procedure is available in packages for PAC element types and container element types only.

Can be called outside a CDAPI activity.

Any errors from JR_VERSION.check_out are passed out on the built in PL/SQL error stack.

See also

API Methods List

PROCEDURE cio<element type>.copy_pac (i_irid in number
                                    , container_reference in number
                                    , pl in out cio<element type>.data
                                    , ensure_unique in VARCHAR2 default 'Y'
                                    , deep in VARCHAR2 default 'Y'
                                    , copy_deps_policy in VARCHAR2 default 'Y');

Where:

i_irid is the IRID of element to be copied.

container_reference is the IRID of the container into which the copy is to be placed. If NULL, the context container is assumed.

pl is a property list (of type cio<element type>.data) containing modifications to be made in the copy that differentiate it from the original.

ensure_unique specifies that the API should adjust the definition of the copy to meet uniqueness requirements of the repository.

deep is the single-character depth specifier: 'Y' = deep copy - copy child elements too (default). 'N' = shallow copy - only copy the element.

copy_deps_policy specifies whether dependency information should be copied when the new version of the object is created: 'Y' = copy dependency information. 'N' = do not copy dependency information.

Description

Copies the currently visible version of the element specified by irid. The copy is modified as specified by the contents of the property list pl. Any property (except for system properties) can be set in the property list. However, if the property values in the copy break uniqueness rules, errors are generated. Copy_pac creates a new non-versioned object in the workarea.

The container specified by container_reference owns the copy; ownership of the original remains unchanged.

In cases where the caller must specify the IRID and IVID of the copy, the caller must set these values in the property list. However, specifying an IRID and an IVID is not recommended; this should be left to the API, which returns these values in the property list.

All API checks are performed on the new element, so in general at least one property in the element's unique identifier (IRID and IVID) must be modified, or ensure that the copy is placed in a different container than the original.

If ensure_unique is set to 'Y' (the default), the set of properties required to be unique in the repository are adjusted by the API. Typically, this involves appending to the Name property a single digit in the range 1 through 9, starting with 1 and checking each time that the resulting Name is unique. If this fails, the call is deemed to have failed. For some element types, properties in addition to the Name property are treated in this way.

The deep parameter can be one of:

• 'Y' (the default) - A copy of the element and a copy of each of its children are made (for example, Table, Column, Constraints, Key Components).

  When a container element is copied using this procedure, elements contained in the original are not copied; only the original and pointers to its contained elements (FOLDER_MEMBER elements) are copied. The effect is that the new container shares contents with the original container.

  Also, note that only contents at the first level are affected by the copy operation on a container element; that is, the copy is not recursive all the way down any containership hierarchy.

• 'N' - only a copy of the specified element is made.

The following conditions cause errors to be passed on the CDAPI error stack:

• element_irid does not refer to a PAC element in the context workarea
  
  
• API constraints are broken by the creation of the new element.
  
  
• The element referred to by i_irid is checked in.

See also

API Methods List
Uniqueness Requirements

PROCEDURE cio<element type>.copy_sac (i_irid IN NUMBER
                                    , pl IN OUT cio<element type>.data
                                    , ensure_unique IN VARCHAR2 DEFAULT 'Y'
                                    , deep IN VARCHAR2 DEFAULT 'Y'
                                    , copy_deps_policy IN VARCHAR2 DEFAULT 'Y'); 

Where:

i_irid is the IRID of element to be copied.

pl is a property list (of type cio<element type>.data) containing modifications to be made in the copy that differentiate it from the original.

ensure_unique specifies that the API should adjust the definition of the copy to meet uniqueness requirements of the repository.

deep is the single-character depth specifier: 'Y' = deep copy - copy child elements too (default). 'N' = shallow copy - only copy the element.

copy_deps_policy specifies whether dependency information should be copied when the new version of the object is created: 'Y' = copy dependency information. 'N' = do not copy dependency information.

Description

Copies the currently visible version of the element specified by irid. This method is for copying SAC element types (that is, all element types that are not PACs or are not Containers).

Any property (except for system properties) can be set in the property list pl, so a copy of a column say, may be placed in a different table by setting pl.V.TABLE_REFERENCE. The appropriate reference property must be set in pl to specify the target PAC into which the SAC is to be copied.

If ensure_unique is set to 'Y' (the default), the set of properties required to be unique in the repository are adjusted by the API. Typically, this involves appending to the Name property a single digit in the range 1 through 9, starting with 1 and checking each time that the resulting Name is unique. If this fails, the call is deemed to have failed. For some element types, properties in addition to the Name property are treated in this way.

The deep parameter is be one of:

• 'Y' (the default) - A copy of the element and (if it is a PAC) all its children is made (for example, Column).
• 'N' - only a copy of the specified element is made.

See also

API Methods List

 PROCEDURE cio<element type>.del (irid NUMBER); 

Where:

irid is the IRID of the object to be deleted.

Description

Removes the currently checked out version of the object specified by irid from the context workarea, after validating against referential integrity constraints in force for the element type.  The object version is made invisible in the context workarea, and visible in the associated wastebasket.

Calls JR_WASTEBASKET.delete .

The result of a delete operation depends on checkin status of object version:

• If it is checked in, delete removes the folder membership so the object version no longer appears in the currently visible versions of containers that used to share or own it (use 'connected to'). Nothing is placed in the wastebasket as a result.
  
  
• If it is checked out or not yet versioned, delete removes the checked out object version of the object from containers and from the workarea, and places it in the wastebasket.

To remove a checked-in object version, use jr_wastebasket.purge (which requires the PURGE system privilege).

Each element type in the repository has its own delete constraints, described in the 'API Specs' section of its Element Type Definition page..

Notes:

1. This procedure fails if the object being deleted is a container and it contains other objects.
   
   
2. The owning container of the element to be deleted must be checked out.
   
   
3. When an element is deleted, all its child elements (if it has any) are deleted.
   
   
4. Some repository elements cannot be deleted if they have dependents. Also, elements cannot be deleted if it is shared into multiple containers; it must first be unshared.

   The JR_WASTEBASKET.force_delete method overrules these restrictions, causing cascade deletes.

5. When there are references to an object to be deleted, each reference is handled as described for the element type in the Other Links: Deletion Rules section of the Element Type Definition page.
   
   
6. Deleting a mapped file in the repository does not cause the corresponding mapped file in the file system to be deleted (the file may re-appear in the repository as a result of a subsequent synchronize or upload operation). The reverse is also true: deleting a mapped file in the file system does not cause the corresponding mapped file in the repository to be deleted (the file may re-appear in the file system as a result of a subsequent synchronize or download operation).
   
   
7. Where cascade deletes are required, any failure to cascade delete a referenced or referencing object causes the delete request to fail.

See also

wastebasket concepts.
Purge and delete methods on the JR_WASTEBASKET package.
API Methods List

PROCEDURE cio<element type>.ins (irid IN NUMBER
                               , pl IN OUT cio<element type>.data); 

Where:

irid is the application-supplied IRID of the new element

pl is the property list (of type cio<element type>.data) containing property values for the new object.

Description

Creates the base version of a new element of type element type in the context workarea.

Any context container becomes the owning container of the new element.

The owning container is not automatically versioned when a new object is added.

If no context container is set and the element is a container element, this creates a root container (a container that has no owning container). In that case the ROOT_FLAG property of the container is set to 'Y'.

Note: ROOT_FLAG is a system-maintained property of container element types.

An error is generated if no context container is set and the element is not a container element. 

The newly created element is not under version control.

See also

API Methods List
Uniqueness Requirements

 PROCEDURE cio<element type>.lck (irid IN NUMBER); 

Where:

irid is the IRID of the object version whose row in the repository database is to be locked.

Description

Locks the database row for the object specified by irid, thus preventing other users from updating or deleting it.  The target can be a new object, or a currently checked out object version.  The version locked is the one visible in the context workarea. The lock is automatically released when the outermost activity ends.

On return, irid is unchanged.

Note: Locking a PAC does not prevent its SACs from being deleted or updated.

See also

API Methods List

PROCEDURE cio<element type>.sel (IRID NUMBER
                               , pl cio<element type>.data); 

Where:

IRID is the element to be queried.

pl is a property (of type cio<element type>.data) list to hold the results of the query.

Description

Retrieves property values for the currently visible version of the element identified by IRID.  On return, property values are in pl.

Note: It is generally quicker to issue a SQL query on the element's view (CI_<element type_pluralname>) to select data.

See also

API Methods List

PROCEDURE cio<element type>.upd (irid NUMBER
                               , pl cio<element type>.data); 

Where:

IRID identifies the element to be updated.

pl is a property list (of type cio<element type>.data) containing the new property values.

Description

Updates the currently visible version of the element identified by irid, using property values and indicator settings supplied in the property list pl.

The target must be either a currently checked out object version or an object that is not under version control.

The updated object version remains checked out and available for further update.

Notes:

1. The IRID and IVID properties of object versions are 'system-maintained properties', and cannot be updated via the API. The 'Notes' column in the description of a property in the Element Type Definition pages specifies whether a property is system-maintained.
   
   
2. Updating a container element (and subsequently checking it back in) affects the version history of that element only, not those of its individual children, nor that of its containers (if it has any).

See also

API Methods List
Uniqueness Requirements

The CILOK Package

FUNCTION idgen RETURN number;

Description

Returns a single unique sequence number that can be used as an identifier (IRID) for a new element.

PROCEDURE idgen (current_array in out NumberArray, num_seq number) 

Where:

current_array is the array to be populated

num_seq the number of elements to return in the array.

Description

Populates a supplied array with a number of unique sequence numbers that can be used as identifiers (IRIDs) for new elements.

See also

API Methods List

Uniqueness Requirements For Insert, Update, and Copy

Every element type has a set of uniqueness rules (described in its API specification or the Element Type Definition).

In addition, the NAME property of a PAC object must be unique for its type within its owning container and in any container into which it is shared. This is validated when an element is created (inserted) or when any of the properties in its uniqueness rules is updated.

The API does not check for uniqueness of name outside the context workarea.

Note: Because a structured variable such as a property list always contains the current values of the data on return from a call, re-using such a variable immediately after a call can cause problems unless steps are taken to set the members of the variable appropriately. For example:

1. pl.v.name:='xxxxx';
2. cioentity.ins (NULL, pl);
3. pl.v.name:='yyyyy';
4. cioentity.ins (NULL, pl);

The second call to ins fails because pl.v.irid has been set by the first call.