Preface

This Guide describes features of application development on the Oracle Server having to do with Large Objects (LOBs). Information in this Guide applies to versions of the Oracle Server that run on all platforms, and does not include system-specific information.

The Preface includes the following sections:

Information in This Guide

The Oracle8i Application Developer's Guide - Large Objects (LOBs) is intended for programmers developing new applications that use LOBs, as well as those who have already implemented this technology and now wish to take advantage of new features.

The increasing importance of multimedia data as well as unstructured data has led to this topic being presented as an independent volume within the Oracle Application Developers documentation set.

Feature Coverage and Availability

The Oracle8i Application Developer's Guide - Large Objects (LOBs) contains information that describes the features and functionality of the Oracle8 and the Oracle8 Enterprise Edition products. Oracle8 and Oracle8 Enterprise Edition have the same basic features. However, several advanced features are available only with the Enterprise Edition, and some of these are optional. For example, to use object functionality, you must have the Enterprise Edition and the Objects Option.

There are no special restrictions in dealing with LOBs. However, you will need the Partitioning option to use LOBs in partitioned tables. Also, you will not be able to use LOBs with object types unless you have purchased the object option. For information about the differences between Oracle8 and the Oracle8 Enterprise Edition and the features and options that are available to you, see Getting to Know Oracle8i and the Oracle8i Enterprise Edition.

New Features Introduced with Oracle8i

The new features included in the Oracle8i, release 8.1.5 are as follows:

Temporary LOBs
Varying width CLOB and NCLOB support
Support for LOBs in partitioned tables
New API for LOBs (open/close/isopen, writeappend, getchunksize)
Support for LOBs in non-partitioned index-organized tables
Copying the value of a LONG to a LOB

Other Guides

Use the PL/SQL User's Guide and Reference to learn PL/SQL and to get a complete description of this high-level programming language, which is Oracle Corporation's procedural extension to SQL.

The Oracle Call Interface (OCI) is described in theOracle Call Interface Programmer's Guide. You can use the OCI to build third-generation language (3GL) applications that access the Oracle Server.

Oracle Corporation also provides the Pro* series of precompilers, which allow you to embed SQL and PL/SQL in your application programs. If you write 3GL application programs in Ada, C, C++, COBOL, or FORTRAN that incorporate embedded SQL, refer to the corresponding precompiler manual. For example, if you program in C or C++, refer to the Pro*C/C++ Precompiler Programmer's Guide..

Oracle 8i offers the opportunity of working with Java in the database. The Oracle Java documentation set includes the Enterprise JavaBeans and CORBA Developer's Guide, the Oracle8i JDBC Developer's Guide and Reference , the Oracle8i Java Developer's Guide , the Oracle8i JPublisher User's Guide and the Oracle8i Java Stored Procedures Developer's Guide.You can access Oracle's development environment for multimedia technology in a number of different ways.

To build self-contained applications that integrate with the database, you can learn about how to use Oracle's extensibility framework in Oracle8i Data Cartridge Developer's Guide
To utilize Oracle's own intermedia applications, refer to Oracle8i interMedia Audio, Image, and Video User's Guide and Reference.

For SQL information, see the Oracle8i SQL Reference and Oracle8i Administrator's Guide. If you need information about Oracle replication with LOB data, refer to Oracle8i Replication. LOBsFor basic Oracle concepts, see Oracle8i Concepts..

How This Book Is Organized

The Oracle8i Application Developer's Guide - Large Objects (LOBs) contains six chapters organized into two volumes. A brief summary of what you will find in each chapter follows:

VOLUME I

Chapter 1, "Introduction to Working With LOBs"

In this chapter we describe the LOB datatype in terms of three main kinds of LOBs: Internal persistent LOBs, Internal temporary LOBs, and External LOBs (BFILEs). We discuss the use of LOBs to promote internationalization by way of CLOBS, and the advantages of using LOBs over LONGs. We then turns to the various programmatic environments by which you can operate on LOBs

The PL/SQL language by means of the DBMS_LOB package as described in Oracle8i Application Developer's Reference - Packages.
The C language by means of the Oracle Call Interface (OCI) described in the Oracle Call Interface Programmer's Guide
The C++ language by means of the Pro*C/C++ precompiler as described in the Pro*C/C++ Precompiler Programmer's Guide
The COBOL language by means of the Pro*COBOL precompiler as described in the Pro*COBOL Precompiler Programmer's Guide
The Visual Basic language by means of Oracle Objects For OLE (OO4O) as described in its accompanying online documentation.
The Java language by means of the JDBC Application Programmers Interface (API) as described in the Oracle8i JDBC Developer's Guide and Reference .

The chapter also includes an example scenario that frames examples provided throughout the rest of the book. Various general topics that underlie LOB operations are discussed as an introduction to the later chapters.

Chapter 2, "Advanced Topics"

The last chapter in the book covers advanced topics that touch on all the other chapters. Specifically, we focus on:

Read consistency
The LOB buffering subsystem
LOBs and the issue of spanning transactions
LOBs in the object cache
Working with varying-width character data
Guidelines for optimal performance

VOLUME II

Chapter 3, "Internal Persistent LOBs"

The basic operations concerning internal persistent LOBs are discussed, along with pertinent issues in the context of the scenario outlined in Chapter 1. We introduce the Unified Modeling Language (UML) notation with a special emphasis on use cases. Specifically, each basic operation is described as a use case. A full description of UML is beyond the scope of this book, but the small set of conventions used in this book appears later in the Preface. Wherever possible, we provide the same example in each of the programmatic environments.

Chapter 4, "Temporary LOBs"

This chapter follows the same pattern as Chapter 2 but here focuses on the new feature of temporary LOBs. The new API and its attendant issues are discussed in detail.

Chapter 5, "External LOBs (BFILEs)"

The focus in this chapter is on external LOBs, also known as BFILEs. The same treatment is provided here as in Chapters 2 and 3, namely every operation is treated as a use case, and we provide matching code examples in every available programmatic environment.

Chapter 6, "LOBs and Partitioned Tables"

This new feature is also presented in terms of the overarching scenario. Please note that using LOBs in partitioned tables requires that you purchase the partition option.

Visual Modeling

This release of the documentation introduces the Universal Modeling Language (UML) as a way of explaining the technology that we hope will help you develop applications. A full presentation of the UML is beyond the scope of this documentation set, however we do provide a description of the subset of UML notation that we use in a chapter devoted to visual modeling inOracle8i Application Developer's Guide - Fundamentals. What follows here is a selection from that chapter of those elements that are used in this book.

Use Case Diagrams

Graphic Element Description

This release of the documentation introduces and makes heavy use of the Use Case Diagram. Each primary use case is instigated by an actor ('stickman') that could be a human user, an application, or a sub-program. The actor is connected to the primary use case which is depicted as an oval (bubble) enclosing the use case action.
The totality of primary use cases is described by means of a Use Case Model Diagram.

Primary use cases may require other operations to complete them. In this diagram fragment

specify queue name

is one of the sub-operations, or secondary use cases, needed to complete

ENQUEUE a message

The downward lines from the primary use case lead to the other required operations (not shown).

Secondary use cases that have drop shadows 'expand' in that they are described by means of their own use case diagrams. There are two reasons for doing this:
(a) it makes it easier to understand the logic of the operation;
(b) it would not have been possible to place all the operations and sub-operations on the same page.
In this example

specify message properties,

specify options

add payload

are all expanded in separate use case diagrams.

This diagram fragment shows the use case diagram ad expanded. While the standard diagram has the actor as the initiator), here the use case itself is the point of departure for the sub-operation. In this example, the expanded view of

add payload

represents a constituent operation of

ENQUEUE a message

This convention (a, b, c) shows that there are three different ways of creating a table that contains LOBs.

This fragment shows one of the uses of a NOTE box, here distinguishing the first of a number of ways of creating a table containing LOBs.

Graphic Element	Description
	This release of the documentation introduces and makes heavy use of the Use Case Diagram. Each primary use case is instigated by an actor ('stickman') that could be a human user, an application, or a sub-program. The actor is connected to the primary use case which is depicted as an oval (bubble) enclosing the use case action. The totality of primary use cases is described by means of a Use Case Model Diagram.
	Primary use cases may require other operations to complete them. In this diagram fragment `specify` `queue name` is one of the sub-operations, or secondary use cases, needed to complete `ENQUEUE` `a message` The downward lines from the primary use case lead to the other required operations (not shown).
	Secondary use cases that have drop shadows 'expand' in that they are described by means of their own use case diagrams. There are two reasons for doing this: (a) it makes it easier to understand the logic of the operation; (b) it would not have been possible to place all the operations and sub-operations on the same page. In this example `specify` `message properties,` `specify` `options` `add` `payload` are all expanded in separate use case diagrams.
	This diagram fragment shows the use case diagram ad expanded. While the standard diagram has the actor as the initiator), here the use case itself is the point of departure for the sub-operation. In this example, the expanded view of `add` `payload` represents a constituent operation of `ENQUEUE` `a message`
	This convention (a, b, c) shows that there are three different ways of creating a table that contains `LOB`s.
	This fragment shows one of the uses of a NOTE box, here distinguishing the first of a number of ways of creating a table containing `LOB`s.

Graphic Element

Description
This drawing shows two other common use of NOTE boxes:
(a) as a way of presenting an alternative name, as in this case the action SELECT propagation schedules in the user schema is represented by the view USER_QUEUE_SCHEDULES
(b) the action list attribute names is qualified by the note to the user that you must list at least one attribute if you elect not to list all the propagation schedule attributes.

Graphic Element Description

The dotted arrow in the use case diagram indicates dependency. In this example

free a temporary LOB

requires that you first

create a temporary LOB

Put another way: you should not execute the free operation on a LOB that is not temporary.
What you need to remember is that the target of the arrow shows the operation that must be performed first.

Use cases and their sub-operations can be linked in complex relationships. In this example of a callback, you must earlier

REGISTER for notification

in order to later

receive a notification

Graphic Element

Description
In this case the branching paths of an OR condition are shown. In invoking the view, you may choose either to list all the attributes or you may view one or more attributes. The fact that you may stipulate which of the attributes you wish made visible is indicated by the grayed arrow.

Graphic Element

Description
Not all lined operations are mandatory. While the black dashed-line and arrow indicate that you must perform the targeted operation to complete the use case, actions that are optional are shown by the grey dashed-line and arrow. In this example, executing

write append

on a LOB requires that you first

SELECT a LOB

As a facilitating operations, you may choose to

OPEN a LOB and/or get chunk size

However, note that if you OPEN a LOB, you will later have to CLOSE it.

Graphic Element Description

Use Case Model Diagrams summarize all the use cases in a particular domain, such as Internal temporary LOBs. Often these diagrams are too complex to contain within a single page. When that happens we have resorted to dividing the diagram into two parts. Please note that there is no sequence implied in this division.

In some cases we have had to split a diagram simply because it is too long for the page. In such cases, we have included this marker.

Conventions Used in this Guide

The following notational and text formatting conventions are used in this guide:

[ ]

Square brackets indicate that the enclosed item is optional. Do not type the brackets.

{ }

Braces enclose items of which only one is required.

|

A vertical bar separates items within braces, and may also be used to indicate that multiple values are passed to a function parameter.

...

In code fragments, an ellipsis means that code not relevant to the discussion has been omitted.

font change

SQL or C code examples are shown in monospaced font.

italics

Italics are used for OCI parameters, OCI routines names, file names, and data fields.

UPPERCASE

Uppercase is used for SQL keywords, like SELECT or UPDATE.

This guide uses special text formatting to draw the reader's attention to some information. A paragraph that is indented and begins with a bold text label may have special meaning. The following paragraphs describe the different types of information that are flagged this way.

Note: The "Note" flag indicates that the reader should pay particular attention to the information to avoid a common problem or increase understanding of a concept.

Warning: An item marked as "Warning" indicates something that an OCI programmer must be careful to do or not do in order for an application to work correctly.

See Also: Text marked "See Also" points you to another section of this guide, or to other documentation, for additional information about the topic being discussed.

Your Comments Are Welcome

We value and appreciate your comment as an Oracle user and reader of our manuals. As we write, revise, and evaluate our documentation, your opinions are the most important feedback we receive.

You can send comments and suggestions about this manual to the following e-mail address:

infodev@us.oracle.com

If you prefer, you can send letters or faxes containing your comments to the following address:

Server Technologies Documentation Manager

Oracle Corporation

500 Oracle Parkway

Redwood Shores, CA 94065

Fax: (650) 506-7228

Graphic Element	Description
	Use Case Model Diagrams summarize all the use cases in a particular domain, such as `Internal` `temporary` `LOBs`. Often these diagrams are too complex to contain within a single page. When that happens we have resorted to dividing the diagram into two parts. Please note that there is no sequence implied in this division.
	In some cases we have had to split a diagram simply because it is too long for the page. In such cases, we have included this marker.