Skip Headers

Oracle® Data Cartridge Developer's Guide
10g Release 1 (10.1)

Part Number B10800-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page

Go to previous page
Go to next page
View PDF

2 Roadmap to Building a Data Cartridge

This chapter recommends a process for developing data cartridges, including relationships and dependencies among parts of the process.

This chapter contains these topics:

Data Cartridge Development Process

Questions that are simple to state are often difficult to answer. For example, newspaper reporters are often reminded to answer the basic questions Who, What, When, Where, and How. In a sense, this chapter concentrates on the when and where of how. It begins by viewing the project as a whole.


What do you need? The first step in developing a data cartridge is to establish the domain-specific value you intend to provide. Define clearly what new capabilities the cartridge will provide. Specify the objects the cartridge will expose to users who need these capabilities.


Who are the intended users of this cartridge? If they are software developers, the extensibility of the cartridge is of crucial importance. If they are end- users. the cartridge must be highly attuned to the domain in question. As with any serious project, building a cartridge should be founded in a business model that clearly distinguishes who the users are.

Who will develop and maintain the cartridge? Regardless of its size, the development team must understand the object-relational database management system well enough to apply its facilities to the problems of the cartridge's domain.

When and Where

How much time is scheduled for the project, and what resources are available? What is to be delivered? A well-defined software development process, clearly defined expectations, and reasonable milestones make the project more likely to succeed.


Choose and design objects so that their names and semantics are familiar in the developer's and users' domain. Given the complexity of the project, you should consider using one of the standard object-oriented design methodologies.

In defining a collection of objects, give care to the interface between the SQL side of object methods and the 3GL code that incorporates your value-added technology. Keep this interface as simple as possible by limiting the number of methods that call out to library routines and allowing the 3GL code to do a block of work independently. Avoid large numbers of calls into low-level library entry points.

With this interface defined, you can proceed along parallel paths, as illustrated in Figure 2-1. You can proceed on the paths in any order that suits the available resources.

Figure 2-1 Cartridge Development Process

Description of addci040.gif follows
Description of the illustration addci040.gif

The leftmost of these parallel paths packages existing 3GL code that performs relevant operations in a runtime library such as a DLL, possibly with new entry points on top of old code. The library routines will be called by the SQL component of the object's method code. Where possible, this code should be tested in a standalone fashion using a 3GL test program.

The middle path defines and writes the object's type specification and the PL/SQL components of the object's method code. Some methods can be written entirely in PL/SQL, while others call into the external library. If your application requires an external library, provide the library definition and the detailed bindings to library entry routines.

The direction you take at the choice point depends on the complexity of the access methods you need to deploy to manipulate your data. If the query methods you need are relatively simple, you can build regular indexes. If your data is complex, you will need to define complex index types to make use of Oracle's extensible indexing technology. If you also need to allow multi-domain queries, you should make use of Oracle's extensible optimizer technology.

If your situation does not involve executing queries on multiple domains, and I/O is the only significant factor affecting performance, then the standard optimizing techniques are probably sufficient. However, if there are other factors such as CPU cost affecting performance, you might still need to use the extensible optimizer.

The final steps are to test the application and create the necessary installation scripts.

Cartridge Installation and Use

Before you can use a data cartridge, you must install it. Installation is the process of assembling the sub-components so that the server can locate them and understand the user-defined type definitions.

Putting the sub-components in place involves:

Telling the server about the user-defined types involves running SQL scripts that load the individual user-defined types defined by the cartridge. This step must be done from a privileged account.

Finally, users of the cartridge must be granted the necessary privileges to use it.

Requirements and Guidelines for Data Cartridge Constituents

The following requirements and guidelines apply to certain database objects associated with data cartridges.

Cartridge Schemas

The database components that make up each cartridge must be installed in a schema whose name matches the cartridge name. If a cartridge needs multiple schemas, the first 10 characters of the schema must be the same as the cartridge name. Note that the maximum permissible length of schema names in Oracle is 30 bytes (30 characters in single-byte languages).

The following database components of a data cartridge must be placed in the cartridge schema:

  • Type names

  • Table names

  • View names

  • Directory names

  • Library names

  • Package names

The choice of a schema name determines the Oracle username, because the schema name and username are always the same in Oracle.

Cartridge Globals

Some database-level constituents of cartridges can be global in scope, and so not within the scope of a particular user (schema) but visible to all users. Examples of such globals are:

  • Roles

  • Synonyms

  • Sequences

All globals should start with the cartridge name. For example, a global role for the Acme video cartridge should have a unique global name like C$ACMEVID1ROL1, and not merely ROL1.

Cartridge Error Message Names or Error Codes

Currently, error codes 20000-20999 are reserved for user errors or application errors. When a cartridge encounters an error, it should generate an error of the form ORA 20000: %s, where %s is a place holder for a cartridge-specific error message. Cartridge developers must ensure that their error messages are unique. You can ensure uniqueness by having all cartridge-specific error messages consist of a cartridge message name in the format C$pppptttm-nnnn plus message text. For example, an error raised by the Acme video cartridge might reported as:

ORA 20000: C$ACMEVID1-0001: No such file

In this example:

  • ORA 20000 is the server error code

  • C$ACMEVID1 is the cartridge name

  • 0001 is the number assigned by Acme for this specific error

  • No such file is the description of the error, as written by Acme

Cartridge Installation Directory

In many cases, a cartridge installation directory is desirable. You can put all the operating system-level components of the cartridge, such as shared libraries, configuration files, and so on, under a directory that is specific to a vendor or organization.

This directory name should be the same as the prefix chosen by the organization, and the directory should be created under the root directory for the platform. For example, if the Acme Cartridge Company needs to store any files, libraries, or directories, it must create a directory /ACME, and then store any files in cartridge-specific subdirectories.

Cartridge Files

You can put message files that associate cartridge error or message numbers with message text in one or more cartridge-specific subdirectories.

It is convenient to keep configuration files in a cartridge-specific subdirectory. For example:


Shared Library Names for External Procedures

Shared libraries (.so or .dll files) can be handled by either of these methods:

  • Place the library in the cartridge installation directory. In this case, ensure that all library names are unique.

  • Place the library in a directory other than the cartridge installation directory. In this case, the file name should start with the cartridge name, excluding the initial C$. If there are many such libraries, each name should start with the first seven letters of the cartridge name, again excluding the C$.

Data Cartridge Deployment Checklist

At the deployment level, you face a number of common issues. The optimal approach to these problems depends on the needs of your application. The following list includes tasks that should form the basis of your checklist, and some proposed solutions.

Data Cartridge Naming Conventions

This section discusses how the components of a data cartridge should be named. It is intended for independent software vendors (ISVs) and others who are creating cartridges to be used by others.


Most examples in this manual do not follow the naming conventions, because they are intended to be as simple and generic as possible. However, as your familiarity with the technology increases and you consider building data cartridges to be used by others, you should understand and follow these naming conventions.

The naming conventions in this chapter assume a single-byte character set.

See Also:

Need for Naming Conventions

In a production environment, an Oracle database might have multiple data cartridges installed. These data cartridges could be from different development groups or vendors, thus developed in isolation. Each data cartridge consists of various schema objects inside the database, as well as other components visible at the operating system level, such as external procedures in shared libraries. If multiple data cartridges tried to use the same names for schema objects or operating system-level entities, the result would be incorrect and inconsistent behavior.

Furthermore, because exception conditions during the runtime operation of data cartridges can cause the Oracle server to return errors, it is important to prevent conflicts between error or message codes of different data cartridges. These conflicts can arise if, for example, two cartridges use the same error code for different error conditions. Having unique error and message codes ensures that the origin of the exception condition can be readily identified.

Unique Name Format

To prevent multiple data cartridge components from having the same name, Oracle recommends the following convention to ensure unique naming of data cartridges. This convention depends on each organization developing data cartridges choosing a unique name. To ensure uniqueness, Oracle provides a name reservation service.

Each organization should choose and reserve a prefix. Oracle will add C$ to the start of the prefix string. This prefix can then be used to name the database schema in which the database components of the data cartridge reside, or to name the directory in which the operating-system components of the data cartridge are placed.

Data cartridges and their components should have names of the following format:


Table 2-1 describes the parts of this naming convention format.

Table 2-1 Data Cartridge Naming Conventions

Part Explanation Example
C$ Recommended by Oracle for all data cartridges.
pppp Prefix selected by the data cartridge creator. (Must be exactly four characters.) ACME
ttt Type of cartridge, using an abbreviation meaningful to the creator. Three characters. AUD (for audio)
m Miscellaneous information indicator, to allow a designation meaningful to the creator. One character. 1 (perhaps a version number)
. (period) Period required if specifying an object in full schema.object form.
ccccc Component name. Variable length. mf_set_volume

Oracle recommends that all characters in the name except for the dollar sign ($) as the second character be alphanumeric: letters, numbers, underscores, and hyphens.

For example, Acme Cartridge Company chooses and registers a prefix of ACME. It provides an audio data cartridge and a video data cartridge, and chooses AUD and VID as the type codes, respectively. It has no other information to include in the cartridge name, and so it chooses an arbitrary number 1 for the miscellaneous information indicator. As a result, the two cartridge names are:



For each cartridge, a separate schema must be created, and Acme uses the cartridge name as the schema name. Thus, all database components of the audio cartridge must be created under the schema C$ACMEAUD1, and all database components of the video cartridge must be created under the schema C$ACMEVID1. Examples of some components might include:

  • C$ACMEVID1.mf_rewind

  • C$ACMEVID1.vid_ops_package

  • C$ACMEVID1.vid_stream_lib

Each organization is responsible for specific naming requirements after the C$pppp portion of the object name. For example, Acme Cartridge Company must ensure that all of its cartridges have unique names and that all components within a cartridge have unique names.

Cartridge Registration

A naming scheme requires a registration process to handle the administration of names of components that make up a data cartridge.

Cartridge Directory Structure and Standards

You need some directory standards that specify where to put your binaries, support files, messages files, administration files, and libraries.

You also need to define a database user who will install your cartridges. One possible solution is to use EXDSYS, for External Data Cartridge System user.


The EXDSYS user is a user with special privileges required for running cartridges. This user could be installed as part of cartridge installation, but a better solution is to make it part of the database installation. To do this, you need to move this process into a standard database creation script.

Cartridge Upgrades

Administrators need a safe way to upgrade a cartridge and its related metadata to a newer version of the cartridge. You also require a process for upgrading data and removing obsolete data. This may entail installation support and database support for moving to newer database cartridge types

Administrators also require a means to update tables using cartridge types when a cartridge changes.

Import and Export of Cartridge Objects

To import and export objects, you need to understand how Oracle's import and export facilities handle Oracle objects. In particular, you need to know how types are handled and whether the type methods are imported and exported, and also whether user-defined methods are supported.

Cartridge Versioning

There are two types of cartridge versioning problems that need to be addressed:

  • Internal Versioning

  • External Versioning

Internal Versioning

Internal versioning is the harder problem. Ideally, you would like a mechanism to support multiple versions of a cartridge in the database. This would provide backward compatibility and also make for high availability.

External Versioning

External versioning is the easier of the two versioning problems. You need to be able to track a cartridge version number and take action accordingly upon installation or configuration based on versioning information.

Cartridge Internationalization

You might want to internationalize your cartridges, so they can support multiple languages and access Globalization Support facilities for messages and parsing.

Oracle recommends that data cartridge component names use the ASCII character set.

If you must name the data cartridge components in a character set other than ASCII, Oracle will still assign you a four-character unique prefix. However, this increases the number of bytes required to hold the prefix. The names of all Oracle schema objects must fit into 30 bytes. In ASCII, this equals 30 characters. If you have, for example, a six-byte character set and request a four-character prefix string, Oracle might truncate your request to a smaller number of characters.

Cartridge Administration

When planning and developing a data cartridge, you should consider the issues involved in administering its use.

Administering Cartridge Access

  • How do administrators know who has access to a cartridge?

    Administrators need to administer access rights to internal and external components such as programs and data files to specific users and roles.

  • How do administrators restrict access to certain tables, types, views, and other cartridge components to individual users and roles?

    For security reasons, administrators must be allowed to restrict access to types on an individual basis.

    Some data cartridges, such as Oracle's Image Cartridge, have few security issues. These cartridges might grant privileges to every user in the database. Other cartridges that are more complex might need differing security models. In building complex data cartridges, you need a way to identify the various components of your cartridge as well as instances of the cartridge, so administrators can grant and revoke security roles on identifiable components.

Invoker's Rights

Invoker's rights is a special privilege that allows the system to access database objects to which it would not normally have access. The special user SYS has such rights. Unless you are willing to grant privileges to public, the user you create to install and run your cartridge needs this privilege.


Data cartridges need a front end to handle deployment issues, such as installation, as well as configuration tools. While each data cartridge may have differing security needs, a basic front end that allows a user to install, configure, and administer data cartridge components is necessary.

This front end may just be some form of knowledge base or on-line documentation. In any case, it should be online, easy to navigate, and contain templates exhibiting standards and starting points.

Suggested Development Approach

In developing a data cartridge, take a systematic approach, starting with small, easy tasks and building incrementally toward a comprehensive solution.This section presents a suggested approach.

To create a prototype data cartridge:

  1. Read the relevant chapters of this book. Experiment with the examples in the example chapters (" Power Demand Cartridge Example ", " PSBTREE: Extensible Indexing Example", and "Pipelined Table Functions: Interface Approach Example").

  2. Create the prototype of your own data cartridge, starting with a single user-defined type and a few data elements and methods. You can add user-defined types, data elements, and methods, specific indextypes, and user-defined operators as you expand the cartridge's capabilities.

  3. Begin by implementing your methods entirely in SQL, and add callouts to 3GL code later if you need them.

  4. Test and debug your cartridge.

When you have the prototype working, you might want to follow a development process that includes these steps:

  1. Identify your areas of domain expertise.

  2. Identify those areas of expertise that are relevant to persistent data.

  3. Consider the feasibility of packaging one or more of these areas as a new data cartridge or as an extension to an existing cartridge.

  4. Use an object-oriented methodology to help decide what object types to include in data cartridges.

  5. Build and test the cartridges, one at a time.