32
Oracle XML DB Versioning API for PL/SQL

Oracle XML DB Versioning APIs are found in the DBMS_XDB_VERSION Package.

This chapter contains the following sections:

• Description of DBMS_XDB_VERSION
• Functions and Procedures of DBMS_XDB_VERSION

  See Also: Oracle9i XML Database Developer's Guide - Oracle XML DB Oracle9i Supplied PL/SQL Packages and Types Reference

---

DBMS_XDB_VERSION Package

---

Description of DBMS_XDB_VERSION

Functions and procedures of DBMS_XDB_VERSION help to create a VCR and manage the versions in the version history.

---

Functions and Procedures of DBMS_XDB_VERSION

Table 32-1 Summary of Functions and Procedures of DBMS_XDB_VERSION  

Function/Procedure	Description
MakeVersioned()	Turns a regular resource whose path name is given into a version-controlled resource.
Checkout()	Checks out a VCR before updating or deleting it.
Checkin()	Checks in a checked-out VCR and returns the resource id of the newly-created version.
Uncheckout()	Checks in a checked-out resource and returns the resource id of the version before the resource is checked out.
GetPredecessors()	Retrieves the list of predecessors by path name.
GetPredsByResId()	Retrieves the list of predecessors by resource id.
GetResourceByResId()	Obtains the resource as an XMLType, given the resource objectID.
GetSuccessors()	Retrieves the list of successors by path name.
GetSuccsByResId()	Retrieves the list of successors by resource id.

MakeVersioned()

Description

Turns a regular resource whose path name is given into a version-controlled resource. If two or more path names are bound with the same resource, a copy of the resource will be created, and the given path name will be bound with the newly-created copy. This new resource is then put under version control. All other path names continue to refer to the original resource. This function returns the resource ID of the first version, or root, of the VCR. This is not an auto-commit SQL operation.

• It is legal to call MakeVersioned() for VCR, and neither exception nor warning is raised.
• It is illegal to call MakeVersioned() for folder, version history, version resource, and ACL.
• No support for Schema-based resources is provided.

An exception is raised if the resource doesn't exist.

Syntax

FUNCTION MakeVersioned( pathname VARCHAR2) RETURN dbms_xdb.resid_type;

Parameter	Description
pathname	The path name of the resource to be put under version control.

Checkout()

Description

Checks out a VCR before updating or deleting it. This is not an auto-commit SQL operation. Two users of the same workspace cannot Checkout() the same VCR at the same time. If this happens, one user must rollback. As a result, it is good practice to commit the Checkout() operation before updating a resource and avoid loss of the update if the transaction is rolled back. An exception is raised if the given resource is not a VCR, if the VCR is already checked out, if the resource doesn't exist.

Syntax

PROCEDURE Checkout(  pathname VARCHAR2);

Parameter	Description
pathname	The path name of the VCR to be checked out.

Checkin()

Description

Checks in a checked-out VCR and returns the resource id of the newly-created version. This is not an auto-commit SQL operation. Checkin() doesn't have to take the same path name that was passed to Checkout() operation. However, the Checkin() path name and the Checkout() path name must be of the same resource for the operations to function correctly. If the resource has been renamed, the new name must be used to Checkin() because the old name is either invalid or is currently bound with a different resource. Exception is raised if the path name doesn't exist. If the path name has been changed, the new path name must be used to Checkin() the resource.

Syntax

FUNCTION Checkin( pathname VARCHAR2) RETURN dbms_xdb.resid_type;

Parameter	Description
pathname	The path name of the checked-out resource.

Uncheckout()

Description

Checks in a checked-out resource and returns the resource id of the version before the resource is checked out. This is not an auto-commit SQL operation. Uncheckout() doesn't have to take the same path name that was passed to Checkout() operation. However, the Uncheckout() path name and the Checkout() path name must be of the same resource for the operations to function correctly. If the resource has been renamed, the new name must be used to uncheckout because the old name is either invalid or is currently bound with a different resource. An exception is raised if the path name doesn't exist. If the path name has been changed, the new path name must be used to Checkin() the resource.

Syntax

FUNCTION Uncheckout( pathname VARCHAR2) RETURN dbms_xdb.resid_type;

Parameter	Description
pathname	The path name of the checked-out resource.

GetPredecessors()

Description

Retrieves the list of predecessors by path name. An exception is raised if the pathname is illegal.

Syntax

FUNCTION GetPredecessors( pathname VARCHAR2) RETURN resid_list_type;

Parameter	Description
pathname	The path name of the resource.

GetPredsByResId()

Description

Retrieves the list of predecessors by resource id. Getting predecessors by resid is more efficient than by path name. An exception is raised if the resid is illegal.

Syntax

FUNCTION GetPredsByResId( resid resid_type) RETURN resid_list_type;

Parameter	Description
resid	The resource id.

GetResourceByResId()

Description

Obtains the resource as an XMLType, given the resource objectID. Because the system will not create a path name for versions, this function is useful for retrieving the resource using its resource id.

Syntax

FUNCTION GetResourceByResId( resid resid_type) RETURN XMLType;

Parameter	Description
resid	The resource id.

GetSuccessors()

Description

Given a version resource or a VCR, retrieves the list of the successors of the resource by path name. Getting successors by resid is more efficient than by pathname. An exception is raised if the pathname is illegal.

Syntax

FUNCTION GetSuccessors( pathname VARCHAR2) RETURN resid_list_type;

Parameter	Description
pathname	The path name of the resource

GetSuccsByResId()

Description

Given a version resource or a VCR, retrieves the list of the successors of the resource by resource id. Getting successors by resid is more efficient than by path name. An exception is raised if the resid is illegal.

Syntax

FUNCTION GetSuccsByResId( resid resid_type) RETURN resid_list_type;

Parameter	Description
resid	The resource id.