4 OraDAV Driver API Reference

This chapter contains reference information for the methods (procedures and functions) in the ORDSYS.DAV_PUBLIC PL/SQL package. These methods are presented in alphabetical order.

Before you use the methods in this package, be sure you understand the concepts and guidelines in Chapter 3, which describes the OraDAV programming interface.

Table 4-1 lists the methods. The rest of this chapter presents detailed reference information for each method.

Table 4-1 OraDAV Methods

Procedure or Function	Description
Cversion	Function that returns the container version number (also called the physical version number).
Expose_Blob_Column	Procedure that makes objects in a column of type BLOB visible by exposing the content of each object as a file with an associated URL.
Expose_OracleMultimedia_Column	Procedure that makes objects in a column of type ORDImage, ORDAudio, ORDVideo, or ORDDoc visible by exposing the content of each object as a file with an associated URL.
Expose_Resource_By_Rowid	Procedure that makes a single object visible (associated with a specified ROWID) by exposing its content as a file with an associated URL.
Generate_Ctx	Function that returns an XML string with minimal context information for the specified container.
Unexpose_Column	Procedure that removes the visibility of objects in a column by reversing the effect of the Expose_Blob_Column or Expose_OracleMultimedia_Column procedure.
Unexpose_Resource_By_Rowid	Procedure that removes the visibility of a single object (associated with a specified ROWID) by reversing the effect of the Expose_Resource_By_Rowid procedure.
Version	Function that returns the release (version) number of the DAV_PUBLIC package.

Cversion

Format

ORDSYS.DAV_PUBLIC.Cversion() RETURN VARCHAR2;

Description

Returns the container (or physical) version number.

Parameters

None.

Usage Notes

This function returns a number describing the container (physical) version that the Oracle Multimedia OraDAV driver supports.

Contrast this function with the Version function, which returns the package version number.

Examples

The following example returns the container (physical) version number.

SELECT ORDSYS.DAV_PUBLIC.Cversion FROM DUAL;
 
  CVERSION 
---------- 
       1.5

Expose_Blob_Column

Format

ORDSYS.DAV_PUBLIC.Expose_Blob_Column( p_ctx IN VARCHAR2, p_schema_name IN VARCHAR2, p_table_name IN VARCHAR2, p_media_column_name IN VARCHAR2, p_date_column_name IN VARCHAR2, p_mime_column_name IN VARCHAR2, p_default_mimetype IN VARCHAR2, p_key_column_name IN VARCHAR2, p_key_prefix IN VARCHAR2, p_key_suffix IN VARCHAR2, p_parent_path IN VARCHAR2, p_add_triggers IN NUMBER(38), p_dupe_behavior IN NUMBER(38));

Description

Makes objects in a column of type BLOB visible by exposing the content of each object as a file with an associated URL.

Parameters

p_ctx

Context string for the container on which to operate. (See Section 3.4 for detailed information about the context.)

p_schema_name

Name of the schema containing the table with the column to be exposed.

p_table_name

Name of the table or view containing the column to be exposed. Must not be one of the container system tables or views described in Section 2.2.

p_media_column_name

Name of the BLOB column to be exposed.

p_date_column_name

Name of the column of type DATE that contains the last-modified date for the data in the BLOB column. If specified as null, SYSDATE (the current system date and time) is used.

p_mime_column_name

Name of the column in the p_table_name parameter that identifies the MIME type. If specified as null, the p_default_mimetype parameter is used.

p_default_mimetype

The MIME type to be used if the value of the p_mime_column_name parameter is null or if the data selected from the column is null.

p_key_column_name

Name of the column in the p_table_name parameter that has unique values to be used as the base file names and the final part of each URL.

p_key_prefix

Prefix to be used in the base file names and the final part of each URL. For example, if the value of the p_key_prefix parameter is emp, the value of the p_key_suffix parameter is id, and a row includes a base column value of 100, the resulting file name is emp100id.jpg (if the MIME type is image/jpeg).

p_key_suffix

Suffix to be used in the base file names and the final part of each URL. (The suffix is not a file extension such as .jpg or .wav.) For example, if the value of the p_key_prefix parameter is emp, the value of the key_suffix parameter isid, and a row includes a base column value of 100, the resulting file name is emp100id.jpg (if the MIME type is image/jpeg).

p_parent_path

Path of the folder to which the column is to be mapped. If specified as null, the default is a path in the following format:

/<p_schema_name>/<p_table_name>/<p_media_column_name>/

p_add_triggers

A value that determines whether triggers are added. If the value of this parameter is 0, no triggers are added; otherwise, if the value is 1, INSERT, UPDATE, and DELETE triggers are added to the p_table_name parameter so that the contents of the WebDAV client are automatically changed to reflect the actions on the underlying table. The default value is 0.

p_dupe_behavior

Action to be taken if a call to the procedure would result in a duplicate file being added to the collection. For more information and a list of acceptable values, see Section 3.3.

Usage Notes

Before using this procedure, be sure you understand the concepts, guidelines, and examples in Section 3.1.

The following guidelines apply to the folder parent_path:

If the path already exists, it must point to an empty folder that is not locked. For example, if you specify the path /external_data/my_blobs, and the subfolder my_blobs already exists in the folder external_data, the subfolder my_blobs must not contain any files or folders and it must not be locked.
If the path does not exist, its parent folder must exist and the parent folder must not be locked. Using the preceding example, if the subfolder my_blobs does not exist, the folder external_data must exist and it must not be locked.

For information about DAV methods that are allowed and disallowed on exposed data, see Table 3-1.

To remove the visibility of a column that had been exposed by this procedure, use the Unexpose_Column procedure.

Examples

The following example exposes all the images in the HOUSE_DOC column. This example uses the same set of assumptions as those that are used in Section 3.1.

DECLARE 
BEGIN 
ORDSYS.DAV_PUBLIC.Expose_Blob_Column( 
   ORDSYS.DAV_PUBLIC.Generate_Ctx('mywebsite'), 
   'REALTOR', 
   'HOUSES', 
   'HOUSE_DOC',
   NULL, 
   NULL, 
   'text/html',
   'HOUSE_ID', 
   NULL, 
   NULL, 
   NULL,
   0,
   ORDSYS.DAV_PUBLIC.DUPE_MODE_FAIL); 
COMMIT; 
END; 
/

Upon successful execution of the code in this example, all house descriptions in REALTOR.HOUSES can be returned by URLs that start with http://mywebserver/oradav/REALTOR/HOUSES/HOUSE_DOC/. The remainder of each URL is the value of the HOUSE_ID column for that house. For example, the following URL returns the description from REALTOR.HOUSES where the value of HOUSE_ID is 1:

http://mywebserver/oradav/REALTOR/HOUSES/HOUSE_DOC/1.htm

Expose_OracleMultimedia_Column

Format

ORDSYS.DAV_PUBLIC.Expose_OracleMultimedia_Column( p_ctx IN VARCHAR2, p_schema_name IN VARCHAR2, p_table_name IN VARCHAR2, p_media_column_name IN VARCHAR2, p_key_column_name IN VARCHAR2, p_key_prefix IN VARCHAR2, p_key_suffix IN VARCHAR2, p_parent_path IN VARCHAR2, p_add_triggers IN NUMBER(38), p_dupe_behavior IN NUMBER(38));

Description

Makes objects in a column of type ORDImage, ORDAudio, ORDVideo, or ORDDoc visible by exposing the content of each object as a file with an associated URL.

Parameters

p_ctx

Context string for the container on which to operate. (See Section 3.4 for detailed information about the context.)

p_schema_name

Name of the schema containing the table with the column to be exposed.

p_table_name

Name of the table or view containing the column to be exposed. Must not be one of the container system tables or views described in Section 2.2.

p_media_column_name

Name of the column of type ORDImage, ORDAudio, ORDVideo, or ORDDoc to be exposed.

p_key_column_name

Name of the column in the p_table_name parameter that has unique values to be used as the base file names and the final part of each URL.

p_key_prefix

p_key_suffix

Suffix to be used in the base file names and the final part of each URL. (The suffix is not a file extension such as .jpg or .wav.) For example, if the value of the p_key_prefix parameter is emp, the value of the p_key_suffix parameter is id, and a row includes a base column value of 100, the resulting file name is emp100id.jpg (if the MIME type is image/jpeg).

p_parent_path

Path of the folder to which the column is to be mapped. If specified as null, the default is a path in the following format:

/<p_schema_name>/<p_table_name>/<p_media_column_name>/

p_add_triggers

p_dupe_behavior

Action to be taken if a call to the procedure would result in a duplicate file being added to the collection. For more information and a list of acceptable values, see Section 3.3.

Usage Notes

Before using this procedure, be sure you understand the concepts, guidelines, and examples in Section 3.1.

For information about DAV methods that are allowed and disallowed on exposed data, see Table 3-1.

To remove the visibility of a column that had been exposed by this procedure, use the Unexpose_Column procedure.

Examples

The following example exposes all the images in the HOUSE_PIX column. This example uses the same set of assumptions as those that are used in Section 3.1.

DECLARE 
BEGIN 
ORDSYS.DAV_PUBLIC.expose_OracleMultimedia_column( 
   ORDSYS.DAV_PUBLIC.Generate_Ctx('mywebsite'), 
   'REALTOR', 
   'HOUSES', 
   'HOUSE_PIX', 
   'HOUSE_ID', 
   NULL, 
   NULL, 
   NULL, 
   1,  
   ORDSYS.DAV_PUBLIC.DUPE_MODE_FAIL); 
COMMIT; 
END; 
/

Upon successful execution of the code in this example, all house pictures in REALTOR.HOUSES can be returned by URLs that start with http://mywebserver/oradav/REALTOR/HOUSES/HOUSE_PIX. The remainder of each URL is the value of the HOUSE_ID column for that house. For example, the following URL returns the image from REALTOR.HOUSES where the value of HOUSE_ID is 1:

http://mywebserver/oradav/REALTOR/HOUSES/HOUSE_PIX/1.jpg

Expose_Resource_By_Rowid

Format

ORDSYS.DAV_PUBLIC.Expose_Resource_By_Rowid( p_ctx IN VARCHAR2, p_schema_name IN VARCHAR2, p_table_name IN VARCHAR2, p_value_colname IN VARCHAR2, p_value_coltype IN VARCHAR2, p_prowid IN UROWID, p_parent_path IN VARCHAR2, p_base_file_name IN VARCHAR2, p_extension IN VARCHAR2, p_mimetype IN VARCHAR2, p_content_length IN INTEGER, p_creation_date IN DATE, p_dupe_behavior IN NUMBER(38), p_docid OUT NUMBER(38));

Description

Makes a single object (associated with a specified ROWID) visible by exposing its content as a file with an associated URL.

Parameters

p_ctx

Context string for the container on which to operate. (See Section 3.4 for detailed information about the context.)

p_schema_name

Name of the schema containing the table with the object to be exposed.

p_table_name

Name of the table or view containing the object to be exposed. Must not be one of the container system tables or views described in Section 2.2.

p_value_colname

Name of the column containing the object to be exposed.

p_value_coltype

Data type of the p_value_colname parameter (for example, BLOB or ORDImage).

p_prowid

The ROWID of the row in the p_table_name parameter to be exposed.

p_parent_path

Path of the folder to which the object is to be mapped. If specified as null, the default is a path in the following format:

/< p_schema_name>/< p_table_name>/< p_media_column_name>/

p_base_file_name

Name to be used for the base file in the final part of the URL. For example, if the value of the p_base_file_name parameter is 123_main_street and the extension is .jpg, the resulting file name is 123_main_street.jpg.

p_extension

String to be used as the file extension in the final part of the URL. For example, if the value of the p_base_file_name parameter is 123_main_street and the extension is .jpg, the resulting file name is 123_main_street.jpg.

p_mimetype

MIME type of the object (for example: image/jpeg). If specified as null, the MIME type associated with the extension is used. If no MIME type is associated with the extension, application/unknown is used.

p_content_length

Length, in bytes, of the content to be exposed.

p_creation_date

Creation date of the file. If specified as null, SYSDATE (the current system date and time) is used.

p_dupe_behavior

Action to be taken if a call to the procedure would result in a duplicate file being added to the collection. For more information and a list of acceptable values, see Section 3.3.

p_docid

The internal document ID generated by OraDAV.

Usage Notes

Before using this procedure, be sure you understand the concepts, guidelines, and examples in Section 3.1.

For information about DAV methods that are allowed and disallowed on exposed data, see Table 3-1.

To remove the visibility of a resource that had been exposed by this procedure, use the Unexpose_Resource_By_Rowid procedure.

Examples

The following example exposes the object in the HOUSE_DOC column, where the value of HOUSE_ID is 1. This example uses the same set of assumptions as those that are used in Section 3.1.

DECLARE 
   ldocid INTEGER; 
   loblen INTEGER; 
   lrowid UROWID; 
BEGIN 
SELECT rowid,DBMS_LOB.GETLENGTH(HOUSE_DOC) 
           INTO lrowid, loblen 
           FROM REALTOR.HOUSES 
           WHERE HOUSE_ID = 1; 
ORDSYS.DAV_PUBLIC.expose_resource_by_rowid ( 
   ORDSYS.DAV_PUBLIC.generate_ctx('mywebsite'), 
   'REALTOR', 
   'HOUSES', 
   'HOUSE_DOC', 
   'BLOB', 
   lrowid, 
   '/external_collection', 
   'house', 
   '.html', 
   'text/html', 
   loblen, 
   SYSDATE, 
   ORDSYS.DAV_PUBLIC.DUPE_MODE_FAIL, 
   ldocid); 
COMMIT; 
END; 
/

Upon successful execution of the code in this example, the following URL returns the Web page from REATOR.HOUSES where the value of HOUSE_ID is 1:

http://mywebserver/oradav/external_collection/house.html

Generate_Ctx

Format

ORDSYS.DAV_PUBLIC.Generate_Ctx( p_container_name IN VARCHAR2, ) RETURN VARCHAR2;

Description

Returns an XML string with minimal context information for the specified container.

Parameters

p_container_name: Name of the container for which to generate minimal context information.

Usage Notes

This function can be used to generate a minimal context string for input to procedures that expose data.

For more information about container context, including examples of the XML string, see Section 3.4.

Examples

The following example returns the container context information. (In the actual output, the entire XML tag is on one line, with no space or line break.)

SELECT ORDSYS.DAV_PUBLIC.Generate_Ctx('mywebsite') FROM DUAL;
 
ORDSYS.DAV_PUBLIC.GENERATE_CTX('MYWEBSITE') 
-------------------------------------------------------------------------------- 
 
<ORADAV><DAVPARAM><ORACONTAINERNAME>mywebsite</ORACONTAINERNAME><ORAEXCEPTION>
    RAISE</ORAEXCEPTION></DAVPARAM></ORADAV>

Unexpose_Column

Format

ORDSYS.DAV_PUBLIC.Unexpose_Column( p_ctx IN VARCHAR2, p_schema_name IN VARCHAR2, p_table_name IN VARCHAR2, p_media_column_name IN VARCHAR2);

Description

Removes the visibility of objects in a column by reversing the effect of the Expose_Blob_Column or Expose_OracleMultimedia_Column procedure.

Parameters

p_ctx: Context string for the container on which to operate. (See Section 3.4 for detailed information about the context.)
p_schema_name: Name of the schema containing the table with the column to be unexposed.
p_table_name: Name of the table or view containing the column to be unexposed. Must not be one of the container system tables or views described in Section 2.2.
p_media_column_name: Name of the column containing the objects to be unexposed.

Usage Notes

Before using this procedure, be sure you understand the concepts, guidelines, and examples in Section 3.1.

Examples

The following example unexposes the images in the HOUSE_PIX column. This example uses the same set of assumptions as those that are used in Section 3.1.

DECLARE 
BEGIN 
ORDSYS.DAV_PUBLIC.Unexpose_Column( 
   ORDSYS.DAV_PUBLIC.Generate_Ctx('mywebsite'), 
   'REALTOR', 
   'HOUSES', 
   'HOUSE_PIX'); 
 
COMMIT; 
END; 
/

Upon successful execution of the code in this example, the images from REALTOR.HOUSES that were previously exposed are no longer available through the URL that was assigned.

Unexpose_Resource_By_Rowid

Format

ORDSYS.DAV_PUBLIC.Unexpose_Resource_By_Rowid( p_ctx IN VARCHAR2, p_schema_name IN VARCHAR2, p_table_name IN VARCHAR2, p_column_name IN VARCHAR2, p_rowid IN UROWID);

Description

Removes the visibility of a single object (associated with a specified ROWID) by reversing the effect of the Expose_Resource_By_Rowid procedure.

Parameters

p_ctx: Context string for the container on which to operate. (See Section 3.4 for detailed information about the context.)
p_schema_name: Name of the schema containing the table with the column to be unexposed.
p_table_name: Name of the table or view containing the object to be unexposed. Must not be one of the container system tables or views described in Section 2.2.
p_column_name: Name of the column containing the object to be unexposed.
p_rowid: The ROWID of the row in the p_table_name parameter containing the object to be unexposed.

Usage Notes

Before using this procedure, be sure you understand the concepts, guidelines, and examples in Section 3.1.

Examples

The following example unexposes the description in the HOUSE_DOC column, where the value of HOUSE_ID value is 1. This example uses the same set of assumptions as those that are used in Section 3.1.

DECLARE 
   v_rowid UROWID; 
BEGIN 
SELECT ROWID, INTO v_rowid FROM REALTOR.HOUSES
   WHERE HOUSE_ID = '1';
 
ORDSYS.DAV_PUBLIC.Unexpose_Resource_By_Rowid( 
   ORDSYS.DAV_PUBLIC.Generate_Ctx('mywebsite'), 
   'REALTOR', 
   'HOUSES', 
   'HOUSE_DOC', 
   v_rowid); 
 
COMMIT; 
END; 
/

Upon successful execution of the code in this example, the description from REALTOR.HOUSES with HOUSE_ID = '1' that was previously exposed is no longer available through the URL that was assigned.

Version

Format

ORDSYS.DAV_PUBLIC.Version() RETURN VARCHAR2;

Description

Returns the release (version) number of the DAV_PUBLIC package.

Parameters

None.

Usage Notes

Contrast this function with the Cversion function, which returns the container (physical) version number.

Examples

The following example returns the DAV_PUBLIC package version number.

SELECT ORDSYS.DAV_PUBLIC.Version FROM DUAL;
 
VERSION 
-------------------------------------------------------------------------------- 
 
1.0.3.3.0-0019