Copyright: Copyright (c) 1994, Oracle Corporation.


Entry Topic
Oracle7 Server Utilities User's Guide Release 7.1

Oracle7 Server™ Utilities User's Guide

PREFACE

CHAPTER 1. EXPORT

CHAPTER 2. IMPORT

CHAPTER 3. EXPORT/IMPORT TIPS

CHAPTER 4. SQL*LOADER CONCEPTS AND FEATURES

CHAPTER 5. SQL*LOADER EXAMPLES

CHAPTER 6. SQL*LOADER CONTROL FILE REFERENCE

CHAPTER 7. SQL*LOADER COMMAND-LINE REFERENCE

CHAPTER 8. SQL*LOADER COMMAND-LINE REFERENCE

CHAPTER 9. SQL*LOADER DIRECT PATH LOADS

CHAPTER 10. INTRODUCTION TO SQL*DBA

CHAPTER 11. SQL*DBA MENUS

CHAPTER 12. SQL*DBA COMMANDS

CHAPTER 13. THE SQL*DBA MONITORS

APPENDIX A. CHANGES IN THE ORACLE7 SERVER UTILITIES

APPENDIX B. RESERVED WORDS

APPENDIX C. NOTES FOR DB2/DXT USERS

APPENDIX D. COMPATIBILITY OF SQL*DBA AND SERVER MANAGER

APPENDIX E. OPERATING SYSTEM DEPENDENCIES


This help file created via:

Oracle Book to Microsoft Help Version 1.0p

© 1994 Oracle Corporation Inc.

Authored by KM .


Oracle7 Serverä Utilities User's Guide
Oracle7 Server™ Utilities User's Guide

Second Edition

Part No. A12389-1

Release 7.1

May, 1994

Oracle7 Server Utilities User's Guide, Second Edition

Part No. A12389-1

Copyright © Oracle Corporation, May 1994

Contributing Author: Eric Armstrong

Contributors: Martin Gruber, Anurag Gupta, Michael Hartstein,  Christopher Heigham, Ken Jacobs, Jonathon Klein, Brian Linden,  Virginia Lyons, Valarie Moore, Rajesh Nakhwa, Patricia Reilly,  Hasan Rizvi, Krishnamurth Sudarshan, Raghu Viswanathan

This software/documentation contains proprietary information of Oracle Corporation; it is provided under a license agreement containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited.

If this software/documentation is delivered to a U.S. Government Agency of the Department of Defense, then it is delivered with Restricted Rights and the following legend is applicable: Restricted Rights Legend

, duplication, or disclosure by the Government is subject to restrictions

set forth in subparagraph (c)(1)(ii) of DFARS 252.227-7013, Rights in

Data and Computer Software (October 1988).Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065 If this software/documentation is delivered to a U.S. Government Agency not within the Department of Defense, then it is delivered with " Restricted Rights," as defined in FAR 52.227-14, Rights in Data - General, including Alternate III (June 1987).

The information in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error free.

Oracle, SQL*DBA, SQL*Loader, SQL*Net, and SQL*Plus are registered trademarks of Oracle Corporation. Oracle7, Trusted Oracle7, Trusted Oracle, Oracle Parallel Server, Oracle Server Manager, and PL/SQL are trademarks of Oracle Corporation.

IBM and DB2 are trademarks of International Business Machines Corporation. DEC, RMS, and VMS are trademarks of Digital Equipment Corporation. All other products or company names are used for identification purposes only, and may be trademarks of their respective owners.


PREFACE

This Guide shows you how to use the following Oracle utilities for data transfer, maintenance, and data entry.

Import/Export	Import and Export are two complementary programs that constitute a single utility. Export writes data from an Oracle database into transportable files. Import reads data from those files back into an Oracle database. These utilities help you back up data, upgrade to new releases of Oracle, and move data between Oracle databases.

SQL*Loader	The SQL*Loader utility loads data from external files into Oracle database tables. It processes a wide variety of input file formats and gives you control over how records are loaded.

SQL*DBA	SQL*DBA is an interactive utility that manages operation of the Oracle server and interact with the database.

Basic concepts are described for each utility, and examples are given to show the utilities in actual use.

Some information in this Guide varies for the high-security version of the server, Trusted Oracle7. Such information is marked with references to the Trusted Oracle7 documentation.

 Audience

This Guide was written for Oracle users who want to perform the following tasks:

•	archive data, back up an Oracle database, or move data between Oracle databases using the export/import utility set

•	load data into Oracle tables from operating system files using SQL*Loader

•	perform a variety of administrative tasks with SQL*DBA

To use this Guide, you need a working knowledge of the SQL language and Oracle database fundamentals. Much of this information is contained in Chapter 1, "A Technical Introduction to the Oracle Server", in the Oracle7 Server Concepts Manual. In addition, SQL*Loader requires that you know how to use your operating system's file management facilities.

Note:	This Guide does not contain installation instructions, since they vary by operating system. Directions for installing the utilities can be found in your operating-system-specific Oracle7 documentation.

 What's New in this Version

Chapter 4, "SQL*Loader Concepts and Features", contains a new section that shows how data record fields are translated into database columns.

A new section on parallel loads was added to Chapter 9, "SQL*Loader Direct Path Loads".

New Export, Import, and SQL*Loader functions were added to the appropriate chapters. See Appendix A, "Changes in the Oracle Utilities", for details.

Corrections were made throughout the Guide, and omissions rectified. Extensive revisions and additions were made in the index.

 Changes to Release 7.0 of this Guide

Chapters 10 through 13 were added to describe the menu-based administration utility, SQL*DBA.

The section on Import/Export was revised to describe the new database objects present in Oracle7. The material on incremental import/export and database reorganization was revised to improve accuracy and understandability.

Chapter 9 was added to describe SQL*Loader's direct path. The material on SQL*Loader (chapters 4 through 9) was significantly revised, reorganized, and extended to simplify its presentation and increase its thoroughness. Diagrams were added for greater clarity.  In addition to covering SQL*Loader's new features, several new sections have been added:

•	calculation of bind array sizes

•	continuing interrupted loads

•	using quotes /specifying filenames

•	how whitespace is trimmed from fields

The discussion of SQL*Loader datatypes was reworked. The new material is more thorough. In addition, it shows the relationship between SQL*Loader datatypes and RDBMS datatypes. It describes how SQL*Loader determines field lengths from the specifications.

Much of the detailed information previously contained in the introduction, in the examples, or in the command-line chapter was consolidated into Chapter 6, the main reference chapter for SQL*Loader. The introductory chapter, Chapter 4, was streamlined so that it focuses more on concepts than detail.

The causes and actions for all error and information messages were moved to the Oracle7 Server Messages and Codes Manual. Appendix A was added to describe changes from previous versions of the utilities.

 How this Guide Is Organized

This Guide is divided into four parts. A brief description of each part follows.

 PART I EXPORT/IMPORT

 Chapter 1:  Export      This chapter shows you how to use Export to write data from an Oracle database into transportable files. It discusses guidelines, export modes, interactive and command-line methods, parameter specifications, and incremental exports. It also provides several sample exports.

 Chapter 2:  Import      This chapter shows you how to use Import to read data from export files into an Oracle database. It discusses guidelines, interactive and command-line methods, parameter specifications, and incremental imports. It also provides several sample imports.

 Chapter 3:  Export/Import Tips      This chapter offers helpful tips on making the best use of Export/Import. It discusses methods for reorganizing tablespaces, creating new rollback segments, exporting and importing with SQL*Net, importing large tables, importing LONG data, reducing database fragmentation, coping with error messages, and other important issues.

 PART II SQL*LOADER

 Chapter 4:  SQL*Loader Concepts and Features      This chapter introduces SQL*Loader and describes its features. It also introduces data loading concepts. It discusses input to SQL*Loader, database preparation, and output from SQL*Loader.

 Chapter 5:  SQL*Loader Examples      This chapter presents case studies that illustrate some of the features of SQL*Loader. It demonstrates the loading of variable-length data, fixed-format records, a free-format file, multiple physical records as one logical record, multiple tables, and direct file loads.

 Chapter 6:  SQL*Loader Control File Reference      This chapter describes the control file syntax used by SQL*Loader. It discusses creating the control file, using the LOAD DATA statement, specifying data files, specifying tables and columns, and signalling the start of data.

 Chapter 7:  SQL*Loader Command Line Reference      This chapter describes the command-line syntax used by SQL*Loader. It discusses the SQLLOAD command, command-line arguments, suppressing SQL*Loader messages, and sizing the bind array.

 Chapter 8:  SQL*Loader Log File Reference      This chapter describes the information contained in the log file.

 Chapter 9:  SQL*Loader Direct Path Loads      This chapter describes the direct path load -- a high performance option that significantly reduces the time required to load large quantities of data.

 PART III SQL*DBA

 Chapter 10:  Introduction to SQL*DBA      This chapter gives an overview of SQL*DBA, describing general characteristics of its menu and command interfaces.

 Chapter 11:  SQL*DBA Menus      This chapter describes all the database operations that can be performed with SQL*DBA's menu interface.

 Chapter 12:  SQL*DBA Commands      This chapter describes all SQL*DBA commands. It includes functions that cannot be accessed from menus.

 Chapter 13:  The SQL*DBA Monitors      This chapter describes SQL*DBA's realtime monitors. These monitors provide a window through which to view the Oracle Server in operation.

 PART IV APPENDIXES

 Appendix A:  Changes in the Oracle Utilities      This appendix describes changes to the Oracle utilities.

 Appendix B:  Reserved Words      This appendix lists words reserved for use by the Oracle utilities.

 Appendix C:  Notes for DB2/DXT Users      This appendix describes differences between the syntax of SQL*Loader and DB2 Load Utility control files. It discusses SQL*Loader extensions to the DB2 Load Utility, the DB2 RESUME option, options included for compatibility, and SQL*Loader restrictions.

 Appendix D:  Operating System Dependencies      This appendix lists the Oracle utilities operating system dependencies.

 Conventions Used in this Guide

This section tells you how to read syntax diagrams, examples, and interface descriptions.

 Interface Elements

The user-interface descriptions in this Guide use the following elements:

 Menu Options      Choices you can select from a menu, submenu, or dialog box are printed in bold. For example, SQL*DBA dialog boxes contain a button labeled Cancel.

 Screen Elements      Other text that appears on the screen is also shown in bold; for example, the Session ID column on the Table Access monitor.

 Menu and Keyboard Operations      Operations you can perform from the keyboard are specified in square brackets, with initial capital letters. For example, pressing any of the keys assigned to the [Accept] operation performs the same action as selecting the button labeled OK.

Operations are described, rather than keystrokes, because multiple keystrokes can be assigned to the same operation. In addition, the assignments are different on different devices, and they can be changed at the administrator's discretion.

 Keycaps      On those occasions when it is necessary to name a particular key, the name is specified in normal text with initial caps. For example: "the Return key" or "the Newline key".

 Syntax Diagrams

The syntax diagrams in this Guide show the complete syntax for the Oracle utilities. Syntax diagrams are made up of these items:

 Keywords      Keywords are words that have special meanings. In the syntax diagrams in this Guide, keywords appear in uppercase. When you specify them, they can be uppercase or lowercase, but they must be used exactly as they appear in the syntax diagram. For example, you must use the INTO TABLE keywords exactly as they appear in the syntax diagram to specify the tables you want SQL*Loader to load.

 Parameters      Parameters act as place holders in syntax diagrams. They appear in lowercase. Parameters are usually names of schema objects, Oracle datatypes, or expressions. When you see a parameter in a syntax diagram, you should substitute an object or expression of the appropriate type. For example, to write an INTO TABLE statement, you specify the name of the table you want to load, such as EMP, in place of the table parameter in the syntax diagram. Note that parameter names appear in italics in the text of this Guide.

The following list shows common parameters that appear in the syntax diagrams in this Guide, along with examples:

Parameter	Description	Example

------------------------------------------------------------------------

table	The substitution value must be the name of a 	EMP

table.

filename	The substitution value must be the name of a 	`\mydir\myfile'

file on your system. Single quotes are needed

if the filename contains spaces or

special characters.

char	The substitution value must be a single 	T

character from your computer's character set.

`char_str'	The substitution value must be a character	`Employee records'

 literal in single quotes.

"char_str"	The substitution value must be a character 	"Employee records"

literal in double quotes.

hex_char	The substitution value must be a hexadecimal 	F

character.

hex_str	The substitution value must be a hexadecimal 	4A1F

string.

n	The substitution value must be an integer.	100

length

start	The substitution value must be a column 	6

end	position in a logical or physical record.

 Table 1.

Parameter Descriptions

 Graphic Components      Syntax diagrams use lines and arrows to show syntactic structure. This list shows combinations of lines and arrows and their meanings within railroad diagrams:

 Examples

This Guide also contains many examples. This is an example of an INTO TABLE statement:

INTO TABLE accounts

( accno	INTEGER,

  owner	VARCHAR2(10),

  balance	FLOAT EXTERNAL(8)

)

Note that the text of the examples appears in a different size and type style than the text of the Guide.

Examples in this Guide follow these case conventions:

•	Keywords, such as CREATE and NUMBER, appear in uppercase.

•	Names of database objects and their parts, such as ACCOUNTS and ACCNO, appear in lowercase, although they appear in uppercase in the text of the Guide.

The data transfer utilities are not case sensitive (except for quoted identifiers), so you need not follow these conventions when writing your own statements, although your statements may be easier for you to read if you do.

 Additional Information

Additional Information:  This Guide does not contain any installation instructions or port-specific information. See your operating system-specific Oracle documentation for this information.

Warning:     Some paragraphs contain warning information. It is a good idea to understand the meaning of the warning before you act on information contained in the current section.

Suggestion:     Some paragraphs provide useful information that is helpful to know, but not essential to understanding the current section.

 Related Publications

Besides this User's Guide and the manuals you receive with the tools you purchase, you may want to refer to the documents listed below.

•	Oracle7 Server Concepts Manual, Part No. 6693-70-1292

•	Oracle7 Server Administrator's Guide, Part No. 6694-70-1292

•	Oracle7 Server Application Developer's Guide,  Part No. 6695-70-1292

•	Oracle7 Server Messages and Codes Manual, Part No. A12379-2

•	Oracle7 Server Migration Guide, Part No. 6617-70-1292

•	Oracle7 Server SQL Language Reference, Part No. 778-70-1292

•	Oracle7 Parallel Server Administrator's Guide,  Part No. 5990-70-1292

•	Oracle*Terminal User's Guide, Part No. A1170-1

•	PL/SQL User's Guide and Reference, Part No. A12715-1

•	Trusted Oracle7 Server Administrator's Guide,  Part No. 6610-70-0193

•	Oracle Server Manager User's Guide, Part No. A14808-1

•	Oracle7 Server Addendum, Release 7.1, Part No. A12042-3

•	Understanding SQL*Net, Version 2.1, Part No. A16029-1.

 Operating System Documentation

Documentation that is unique to each operating system is also provided. In the text, these manuals are referred to as "your operating-system-specific Oracle7 documentation". An example of such a manual is the

Oracle7 for Sun Sparc SunOS 4.1.z Installation and Configuration Guide, Part No. A11853-1

README File

Finally, you should consult the README file that comes with each version of Oracle for the latest information on its features and functions. This file contains much valuable information that has not yet reached the printed documentation. The actual name of this file depends on your operating system. See your platform specific Oracle documentation for this information.

 Your Comments Are Welcome

The Oracle Corporation technical staff values your comments. As we write and revise, your opinions are the most important feedback we receive. Please use the Reader's Comment Form at the back of this addendum to tell us what you like and dislike about this Oracle publication. If you want to contact us, please fax us at (415) 506-7200 or write to us at the following address: Oracle7 Server Documentation Manager

Corporation

Oracle Parkway

City, CA 94065


CHAPTER 1. EXPORT

Before you can import objects (tables, views, and so on) into your Oracle7 Server database, you have to export them. This chapter shows you how to use the Export utility to write data from an Oracle database into operating system files in Oracle-binary format. These files can be stored independently of the database or read into another Oracle database, using the Import utility (described in Chapter 2).

Because of their special format, export files cannot be read by utilities other than Import. Similarly, Import can read files written by Export, but not other files.

This chapter discusses the following subjects:

•	export guidelines

•	export modes

•	interactive and command-line methods

•	export parameters

•	incremental and cumulative exports

It also provides several sample exports to help you learn how to  use Export.

 ________________________________________

Export Guidelines

Export's basic function is to extract the objects of a database and put them in a flat file that is usually on tape or on disk. This process is shown in Figure 1 - 1.

Figure 1 - 1. Exporting a Database

You can save the export file as a database backup. You can also use the export file to load objects into a database on another system. This section offers guidelines to help you make the best use of Export.

 Preparations

Before running Export, be sure there is enough storage space on disk or tape to write the export file. If there is not enough space, Export terminates with a write-failure error. You can use table sizes to estimate the maximum space needed. Table sizes can be found in the USER_SEGMENTS view in the Oracle data dictionary (see the Oracle7 Server Administrator's Guide for more information).

To use Export, the script CATEXP.SQL must be run. After creating the database, do one of the following:

•	run CATEXP.SQL

•	run CATALOG.SQL (which runs CATEXP.SQL)

Additional Information:  The actual names of the script files depend on the operating system. The script file names and the  method for running them are described in your operating system-specific Oracle7 documentation.

CATEXP.SQL only needs to be run once. Once run, it does not need to be run again for future exports. CATEXP.SQL performs the following operations to prepare the database for export:

•	creates the export views

•	assigns all necessary privileges to the EXP_FULL_DATABASE role

•	assigns EXP_FULL_DATABASE to the DBA role

 Access Privileges

To use Export you must have the CREATE SESSION privilege on an Oracle database. To export tables owned by another user, you must have the EXP_FULL_DATABASE role enabled.

 File Handling

Export writes data from an Oracle database to operating system files (on disk or tape) called export files. You can archive the export files as backups to be imported when needed. You can transfer them to other systems, where they can be imported into another Oracle database.

Export writes export files using the character set specified for the user session; for example, 7-bit ASCII or IBM Code Page 500 (EBCDIC). If necessary, Import automatically translates the data to the character set of its host system. Import automatically converts character data to the character set specified for the user session if it is different from that used in the export file.

It is a good idea to give each export file a name that indicates its contents and the date it was written.

Additional Information:  In Trusted Oracle7, export files are labeled in the operating system. See the Trusted Oracle7 Server Administrator's Guide for details.

 Restrictions

Unless you have the system privileges contained in the EXP_FULL_DATABASE role, you cannot export objects contained in another user's schema. For example, you cannot export a table in another user's schema, even if you have created a synonym for it.

Exports in table mode do not include cluster definitions. As a result, the data is imported into unclustered tables. Thus, you can use Export to uncluster tables when there is not enough free space in your database.

Because files created by Export are stored in a special format, they cannot be used by any Oracle7 Server utility or product other than Import. (However, you can display the contents of an export file by using the Import SHOW option described in Chapter 2.) In addition, export files can be read only by Import. You cannot use them to transfer data to non-Oracle systems.

The storage parameter OPTIMAL for rollback segments is not exported; so, it is not preserved on import.

Additional Information:  There are additional steps and considerations when you are exporting data from a Trusted Oracle7 Server. The Trusted Oracle7 Server Administrator's Guide contains more guidelines for using Export with the Trusted Oracle7 Server.

 ________________________________________

Error Handling

Export's goal is to save as much of the database as possible--even when part of it has become corrupted. This section discusses the ways in which Export handles errors.

 Log Files

Oracle Corporation recommends that you capture all of Export's messages in a log file either using the LOG parameter or, for those systems that permit it, by redirecting Export's output to a file.

Additional Information:  See page 1 - 13 for log file specification. See your operating system-specific Oracle7 documentation for information on redirecting output.

 Warnings

Export continues after non-fatal errors. If an error occurs while exporting a row, for example, Export puts out an error message, skips to the next table, and continues processing. Non-fatal errors are known as warnings.

Warnings are issued whenever an invalid object is exported. For example, if a non-existent table was specified as part of a table-mode export, then all other tables would be exported, after which the export would terminate with a warning, as shown in the following listing:

exp scott/tiger tables=xxx,emp

...

About to export specified tables ...

EXP-00011: SCOTT.XXX does not exist

EXP-00222:

System error message 2

. exporting table              EMP        10 rows

exported

Export terminated successfully with warnings.

 Fatal Errors

Some errors are fatal, which means that Export cannot continue. They occur because of an internal problem or because a resource, such as memory, is not available or has been exhausted. For example, you see the following message if you run Export without having created the necessary Export views using CATEXP.SQL:

EXP-00024: Export views not installed, please notify your DBA

Additional Information:  Messages are documented in the Oracle7 Server Messages and Codes Manual and in your operating system-specific Oracle7 documentation.

 Final Message

When an export completes without problems, the message "Export terminated successfully without warnings" is issued. If one or more non-fatal errors occurred, but Export was able to continue to completion, then the message "Export terminated successfully with warnings" occurs. If a fatal error occurs, then Export ends immediately with the message "Export terminated unsuccessfully".

 ________________________________________

Export Modes

The objects that are exported depend on the mode you choose. All users have at least two choices of export mode; a user with the EXP_FULL_DATABASE role (a privileged user) has three choices:

Table	Exports specified tables in your schema, rather than all tables. A privileged user can qualify the tables by specifying the schema containing them. The default is to export all tables belonging to the user doing the export.

User	Exports all objects in a user's schema (such as tables, data, grants, and indexes). A privileged user exporting in user mode can export all objects in the schemas of a specified set of users.

Full Database	Only users with the EXP_FULL_DATABASE role can export in this mode. All objects in the database are exported, except those in the schema of SYS.  (Objects owned by SYS are generated during database creation for internal and administrative use. Because they are not exported, you should not create a user table or any other object under SYS.)

To select table, user, or full database mode, specify TABLES=tablelist, OWNER=userlist, or FULL=Y, respectively.

The following table shows the objects that are exported in each mode:

Table Mode	User Mode	Full Database Mode

------------------------------------------------------------------------

table definitions1	table definitions1	table definitions1

table data	table data	table data

owner`s table grants2	owner's grants	grants

owner's table indexes3	owner's indexes4	indexes

table constraints	table constraints	table constraints

table triggers	table triggers	all triggers

clusters	clusters

database links	database links

job queues	job queues

refresh groups	refresh groups

sequences	sequences

snapshots	snapshots

snapshot logs	snapshot logs

stored procedures	stored procedures

private synonyms	all synonyms

views	views

profiles

replication catalog

resource cost

roles

rollback segment definitions

system audit options

system privileges

tablespace definitions

tablespace quotas

user definitions

Notes:

    1. Table definitions include comments and audit options.

    2. Owner's grants for the tables are exported in table mode.

    3. Owner's indexes on the specified tables are exported in table mode.

    4. Only indexes on the user's tables are exported.

Table 1 - 1.  Exported Objects

 ________________________________________

Exporting Sequences

If transactions continue to access sequence numbers during an export, sequence numbers can be skipped. This section describes the circumstances under which it can happen. The best way to ensure that sequence numbers are not skipped is to ensure that the sequences are not accessed during the export.

 Sequence Numbers Skipped

Sequence numbers can be skipped only when cached sequence numbers are in use. When a cache of sequence numbers has been allocated, they are available for use in the current database. The exported value is the next sequence number (after the cached values). Sequence numbers that are cached, but unused, are lost when the sequence is imported.

 ________________________________________

How to Use Export

You can use Export in three ways:

•	Enter the command EXP username/password PARFILE=filename with the remaining export parameters contained in the specified file. This is the preferred method.

•	Enter the command EXP username/password followed by various parameters that control how Export runs. You can use this method as long as the number of parameters does not exceed the maximum length of a command line on your system.

•	Enter the command EXP username/password to begin an interactive session and let Export prompt you for the information it needs. The interactive option does not provide as much functionality as the parameter-driven method. It exists only for backward compatibility.

The username and password can also be specified in the parameter file, although it is not recommended that you do so if security is important. If you omit the username/password parameter, Export prompts for it. This lets you hide your password from view, because Export does not echo the entered password at your terminal.

 Getting Help

Export provides online help. Enter EXP HELP=Y on the command line to see a help screen like the one shown in Figure 1 - 2.

Figure 1 - 2. Export Help Screen

 Multilingual Values

Export allows Y/N values to be specified with the national language used in the current session. For example, a user with the French national language enabled could specify O or Oui for Yes. In the pages that follow, the value "Y" could be replaced by "YES", "TRUE", "T", or by the appropriate response for the current session's language. Similarly, "N" could be replaced by "NO", "FALSE", and so on.

 Parameter File Method

The PARFILE option allows you to specify Export parameters in a file where they can easily be modified and reused. This option can only be specified on the command line. With all your parameter specifications in a file, enter either of the following commands:

EXP PARFILE=filename

EXP username/password PARFILE=filename

The general form of a parameter specification is as follows:

KEYWORD=value  or

KEYWORD=(value) or KEYWORD=(value1, value2, ...)

You can format the parameter file like a command, separating parameters with spaces, or you can separate parameters with carriage returns, as in the following example:

SYSTEM/MANAGER

FULL=Y

FILE=DBA.DMP

GRANTS=Y

INDEXES=Y

Additional Information: The size of the parameter file may be limited. See your operating system-specific Oracle7 documentation for detailed information.

 Comments

You can comment the parameter file with the # sign. All characters to the right of the # sign are ignored.

 Table Name Restriction

Because parameter files allow comments, table names specified on the command line cannot include a # sign, unless the table name is enclosed in quotation marks.

Additional Information:  For details on the type of quotation marks required on your operating system, see your operating system-specific specific Oracle7 documentation.

Similarly, in a parameter file, if a table has a # sign in the name, the rest of the line is interpreted as a comment unless the table name is enclosed in quotation marks. For example, if the parameter file contains the line

TABLES=(EMP#, DEPT, MYDATA)

then nothing on the line after EMP# is seen as input by Export. As a result, DEPT and MYDATA are not exported. The following line fixes the problem:

TABLES=("EMP#", DEPT, MYDATA)

Attention: When the name is specified in quotation marks, it becomes case-sensitive. The name must then exactly match the table name stored in the database. By default, database names are stored as uppercase.

 Export Parameters

The parameters listed below, except for PARFILE, can be specified in the parameter file. They are described in detail in the remainder of this section.

USERID	RECORDLENGTH

BUFFER	INCTYPE

FILE	RECORD

GRANTS	HELP

INDEXES	PARFILE

ROWS	LOG

CONSTRAINTS	CONSISTENT

COMPRESS	STATISTICS

FULL	MLS*

OWNER	MLS_LABEL_FORMAT*

TABLES

*Trusted Oracle7 Server parameters

The order of the parameters is significant. Parameters specified in this order can be specified without the introductory keyword. For example, USERID=system/manager can be specified as system/manager, provided this parameter is specified first. Buffer size can be specified second, and so on. However, use of this functionality for parameters other than USERID is not recommended. It is provided for backward compatibility only.

Note: This order is guaranteed up to the PARFILE parameter only.

BUFFER	Default: operating system dependent

The size in bytes of the buffer into which data rows are fetched. If zero is specified or if rows contain LONG data, only one row at a time is fetched.

The BUFFER (buffer size) parameter determines the number of rows in the array fetched by Export. You can calculate the buffer size needed to fetch a given array of rows as follows:

buffer_size = rows_in_array * maximum_row_size

Additional Information:  See your operating system-specific Oracle7 documentation to determine the default value for this parameter.

COMPRESS	Default: Y

A flag to indicate whether to compress table data into one extent during an import.

On import, data is compressed into one initial extent, unless you specify COMPRESS=N when the data is exported. This option preserves the original size of the initial extent.

When you specify COMPRESS=Y, Export sums the lengths of all current extents and uses that value as the size of the initial extent for the exported table. When a table has had a great many deletes, this size may be much larger than the table actually requires.

CONSISTENT	Default: N

When YES is specified, a read-consistent view of the database is exported. This flag is useful when other applications are updating the database during the export.

Use of this parameter requires a rollback segment to be retained for the duration of the export to back out the effects of any uncommitted transactions when a table is exported. If the volume of updates is sizable, the rollback segment can become very large. In addition, the export of each table is slowed, because the rollback segment must be scanned for uncommitted transactions.

Suggestion: To minimize the time and space required for such exports, tables that need to remain consistent should be exported together, and only those tables should be exported. The remainder of the database should be exported separately. For example, export the EMP and DEPT tables together in a consistent export. Then, export the remainder of the database in a second pass.

Exporting the minimum number of objects that must be guaranteed consistent also helps to reduce the chances of encountering a "snapshot too old" error. This error occurs when rollback space has been used up, and space taken up by committed transactions is reused for uncommitted transactions. Reusing space in the rollback segment allows database integrity to be preserved with minimum space requirements, but it imposes a limit on the amount of time that a read-consistent image can be preserved. If a committed transaction has been overwritten and the information is needed for a read-consistent view of the database, then a "snapshot too old" error results.

To avoid this error, minimize the time taken by a read-consistent export (by restricting the number of objects export and, if possible, by reducing the database transaction rate). Also, make the rollback segment as large as possible.

Note: This parameter cannot be used with an incremental export.

CONSTRAINTS	Default: Y

A flag to indicate whether to export table constraints.

FILE	Default: EXPDAT.DMP

The name of the output file created by Export.

FULL	Default: N

A flag to indicate whether to export the entire database. Specify FULL=Y to export in full database mode.

GRANTS	Default: Y

A flag to indicate whether to export grants.

HELP	Default: N

Displays descriptions of export parameters.

INCTYPE	Default: none

The type of incremental export. Valid values are COMPLETE, CUMULATIVE, and INCREMENTAL.

INDEXES	Default: Y

A flag to indicate whether to export indexes.

LOG	Default: none

Specifies a file to receive informational and error messages. For example:

EXP system/manager LOG=export.log FULL=y

If this parameter is specified, all messages go to the file and to the terminal.

MLS	The Export utility can be used on any Trusted Oracle7 database to produce a normal export file. In DBMS Mandatory Access Control (MAC) mode, the MLS parameter can also be specified. With this parameter, the Multi-Level Security (MLS) labels on each row and object in the database are included in the export file. This parameter is described in the Trusted Oracle7 Server Administrator's Guide.

MLS_LABEL_ FORMAT	With this parameter you can override the default format specified in the database for human-readable MLS labels. The format you specify will be used in the export file instead of the format defined by the database initialization parameter. This parameter is further described in the Trusted Oracle7 Server Administrator's Guide.

OWNER	Default: undefined

A list of usernames whose objects will be exported. Specify OWNER=userlist to export in user mode.

PARFILE	Default: none

Specifies a file containing parameter specifications.

RECORD	Default: Y

A flag to indicate whether to record an incremental or cumulative export in database tables SYS.INCVID, SYS.INCFIL, and SYS.INCEXP.

RECORDLENGTH	Default: operating system dependent

The length in bytes of the file record. The RECORDLENGTH parameter is needed when you must transfer the export file to another operating system that uses a different default value.

Additional Information:  See your operating system-specific Oracle7 documentation for that system to determine the proper value, or when you want to create a file with a different record size.

ROWS	Default: Y

A flag to indicate whether to export the rows of table data.

STATISTICS	Default: ESTIMATE

This parameter specifies the type of database optimizer statistics to generate when the exported data is imported later. Options are ESTIMATE, COMPUTE, and NONE. For more information, see "Generating Statistics on Imported Data".

TABLES	Default: undefined

A list of table names to export. Specify TABLES=tablelist to export in table mode.

 Storage Parameters:     Tables are exported using the current storage parameters. Unless ALTER TABLE command has been executed to change them, these are the parameters in effect when the tables were created.

USERID	Default: none

The username and password (separated by a slash) of the user performing the export. If these comprise the first argument, the keyword USERID is not required.

 Parameter Interactions

Some parameters conflict. For example, because TABLES conflicts with owner, the following command will cause Export to terminate with an error:

EXP system/manager OWNER=jones TABLES=scott.emp

Similarly, OWNER conflicts with FULL=Y.

Although ROWS=N and INCTYPE=INCREMENTAL can both be used, specifying ROWS=N (no data) defeats the purpose of incremental exports, which is to make a backup copy of tables that have changed.

 Command Line Method

All parameters that can be specified in a parameter file can also be specified on the command line. Parameters specified on the command line override parameters specified in a parameter file.

Here are two examples of the Export command:

EXP USERID=scott/tiger TABLES=(emp,dept,parts) GRANTS=Y

EXP system/manager FULL=Y FILE=nov13.exp

 Interactive Method

Export's interactive prompts are described below. This method provides a subset of Export capabilities. It is provided for backward compatibility only.

You may not see all the prompts in a given Export session because some prompts depend on your responses to other prompts. Some prompts show a default answer. If the default is acceptable, press ENTER or RETURN. To end your input, enter a period (.) followed by RETURN.

If you have not specified a username/password on the command line, Import first prompts you for this information. Then the prompts described below are issued.

 Buffer Size

The response to the following prompt, like the value of the BUFFER parameter, determines the space available to buffer rows. Export uses the array fetch program interface call to speed performance. The default is usually adequate, but the buffer must be at least as large as the longest row. If you enter zero, only one row at a time is fetched.

Enter array fetch buffer size: 4096 >

 Export File

At the next prompt, enter the name of the export file (the default is EXPDAT.DMP). If you enter a filename only, the file extension or file type of the export file will be DMP.

Export file: EXPDAT.DMP >

 Export Mode

At the following prompt, most users can choose either table or user mode. Privileged users can also choose full database mode:

E(ntire database), U(sers), or T(ables): U >

 Grants

At the next prompt, if you answer Y (for "Yes"), the grants that are exported depend on whether you are in full database mode or user mode. In full database mode, all grants on a table are exported. In user mode, only those granted by the owner of the table are exported.

Export grants (Y/N): Y >

 Table Data

At the following prompt, if you answer Y, the data in the tables is exported with the table definitions. If you answer N, then only the table definitions are exported.

Export table data (Y/N): Y >

 Compress

At the next prompt, if you answer Y, the data for each exported table will be compressed into one initial extent when imported. If you answer N, then all tables are created with the storage parameters in effect when the table was exported.

Although the data is compressed at import time, you must request data compression at export time, because your request causes the table definition to be exported differently. Thus, if you request data compression at export time, you can import the data in compressed form only.

Compress extents (Y/N): Y >

 Schemas to Export

If the following prompt appears, you may enter the name of the next schema to export. To indicate "no user" (and terminate the current Export session), press ENTER or RETURN.

Schema to export: (RETURN to quit) >

 Tables to Export

If the following prompt appears, Export is requesting the name of the next table to export. Entering a null table list causes all tables in the schema to be exported.

You can enter table names with or without the prefix of their schema name. If no prefix is entered, it defaults to the exporter or the schema containing the last table exported in that session.

For instance, if BETH is a privileged user exporting in table mode, then Export assumes that all tables are in BETH's schema until another schema is specified. Only a privileged user (someone with the BACKUP ANY TABLE privileges, contained in the standard EXP_FULL_DATABASE role) can export tables in another user's schema.

Table to be exported: (RETURN to quit) >

 ________________________________________

Sample Exports

The following sample exports show you how to use the command-line and interactive methods in the full database, user, and table modes.

 Sample Export in Full Database Mode

Only users with the DBA role, the EXP_FULL_DATABASE role, or the BECOME USER privilege can export in full database mode. In this example, an entire database is exported to file DBA.DMP with all GRANTs and all data.

The command-line method follows:

exp system/manager full=Y file=dba.dmp

The equivalent interactive method follows:

exp system/manager

...

Enter array fetch buffer size: 4096 >  (RETURN)

Export file: EXPDAT.DMP>  dba.dmp

E(ntire database), U(sers), T(ables): U> e

Export grants (Y/N): Y> y

Export table data (Y/N): Y> y

Compress extents (Y/N): Y> y

In either case, Export responds with the following messages:

About to export the entire database...

. exporting tablespace definitions

. exporting profiles

. exporting user definitions

. exporting roles

. exporting resource costs

. exporting rollback segment definitions

. exporting database links

. exporting sequence numbers

. exporting job queues

. exporting refresh groups and children

. exporting cluster definitions

. exporting stored procedures

. about to export SYSTEM's tables ...

. about to export SCOTT's tables ...

. exporting table                   BONUS        0 rows exported

. exporting table                    DEPT        7 rows exporte

. exporting table                     EMP       22 rows exported

. exporting table                    PROJ        0 rows exported

. exporting table                SALGRADE        5 rows exported

. about to export ADAMS's tables ...

. about to export JONES's tables ...

. about to export CLARK's tables ...

. about to export BLAKE's tables ...

. exporting referential integrity constraints

. exporting triggers

. exporting posttables actions

. exporting synonyms

. exporting views

. exporting default and system auditing options

Export terminated successfully without warnings.

 Sample Export in User Mode

Exports in user mode can back up one database user. For example, a DBA may want to back up the tables of a deleted user for a period of time. User mode is also appropriate for users who want to back up their own data, or who want to move objects from one owner to another.

This example shows user SCOTT exporting all his tables in user mode.

The command-line method follows:

exp scott/tiger file=scott.dmp

The equivalent interactive method follows:

exp scott/tiger

...

Enter array fetch buffer size: 4096 >    (RETURN)

Export file: EXPDAT.DMP>    scott.dmp

U(sers), or T(ables): U>  u

Export grants (Y/N): Y>  y

Export table data (Y/N): Y>   y

Compress extents (Y/N): Y> y

In either case, Export responds with the following messages:

About to export SCOTT's objects ...

. exporting job queues

. exporting refresh groups and children

. exporting database links

. exporting sequence numbers

. exporting cluster definitions

. exporting stored procedures

. about to export SCOTT's tables ...

. exporting table                   BONUS        0 rows exported

. exporting table                    DEPT        7 rows exported

. exporting table                     EMP       22 rows exported

. exporting table                    PROJ        0 rows exported

. exporting table                SALGRADE        5 rows exported

. exporting synonyms

. exporting views

. exporting referential integrity constraints

. exporting triggers

. exporting posttables actions

Export terminated successfully without warnings.

 Sample Exports in Table Mode

In this mode, you can export table data or the table definitions. (If no data is exported, the CREATE TABLE statement is placed in the export file, with grants and indexes, if they are specified.)

A user with the EXP_FULL_DATABASE role can use this mode to export tables from any user's schema by specifying TABLE=(schema.table). If schema is not specified, it defaults to the previous schema from which an object was exported. If there is not a previous object, it defaults to the exporter's schema. In the following example, schema defaults to SYSTEM for table A and to SCOTT for table C:

exp system/manager tables=(a, scott.b, c, mary.d)

A user without the EXP_FULL_DATABASE role can export only tables that he or she owns.

Exports in table mode do not include cluster definitions. As a result, the data is imported into unclustered tables. Thus, you can use Export to uncluster tables when there is not enough free space in your database.

 First Example

In the first example, a DBA exports specified tables for two users.

The command-line method follows:

exp system/manager tables=(mort.bar, mary.app) grants=Y indexes=Y

The equivalent interactive method follows:

exp system/manager

...

Enter array fetch buffer size: 4096 >    (RETURN)

Export file: EXPDAT.DMP >   (RETURN)

E(ntire database), U(sers), T(ables): U>  t

Export table data (Y/N): Y>    (RETURN)

Compress extents (Y/N): Y> y

Export responds with the following messages:

About to export specified tables ...

Table Name:  mort.bar            [interactive session only]

Current user changed to MORT

. exporting table                 BAR   2355 rows exported

Table Name:  mary.app             [interactive session only]

Current user changed to MARY

. exporting table                 APP   14947 rows exported

Table Name:  (RETURN)             [interactive session only]

[Export writes file]

 Second Example

In the next example, user LEWIS exports selected tables that he owns.

The command-line method follows:

exp lewis/newyork file=lew.dmp tables=(credits, debits)

The equivalent interactive method follows:

exp lewis/newyork

...

Enter array fetch  buffer size: 4096 >    (RETURN)

Export file: EXPDAT.DMP>    lew.dmp

U(sers), T(ables): U>  T

Export table data (Y/N): Y> y

Compress extents (Y/N): Y> y

Export responds with the following messages:

About to export specified tables ...

Table Name:  credits                    [interactive session only]

. exporting table           CREDITS  423 rows exported

Table Name:  debits                     [interactive session only]

. exporting table           DEBITS   423 rows exported

Table Name:  (RETURN)                   [interactive session only]

[Export writes file]

 ________________________________________

Incremental and Cumulative Exports

To improve export performance, incremental, cumulative, and complete exports may be selected. This section shows how to set up a time-effective and space-effective backup strategy using these different kinds of export.

Note: Incremental exports cannot be specified as read-consistent.

 Incremental Exports

An incremental export backs up only tables that have changed since the last incremental, cumulative, or complete export. An incremental export exports the table's definition and all its data, not just the changed rows. Incremental exports are typically done more often than cumulative or complete exports.

Figure 1 - 3 shows an incremental export at time 1, after 3 tables have been modified. Only the modified tables (and associated indexes) are exported.

Figure 1 - 3. Incremental Export at Time 1

Figure 1 - 4 shows another incremental export at time 2, after 2 tables have been modified. Table 3 was modified a second time, so it is exported at time 2 as well as at time 1.

Figure 1 - 4. Incremental Export at Time 2

 Cumulative Exports

A cumulative export backs up tables that have changed since the last cumulative or complete export. In essence, a cumulative export compresses a number of incremental exports into a single cumulative export file. It is not necessary to save incremental export files taken before a cumulative export, because the cumulative export file replaces them.

Figure 1 - 5 shows a cumulative export at time 1, after 3 tables have been modified. The modified tables (and associated indexes) are exported. This export is equivalent to an incremental export at  this time.

Figure 1 - 5. Cumulative Export at Time 1

Figure 1 - 6 shows a cumulative export at time 2, after 2 tables have been modified. This time, the two tables modified at time 2 are exported, and the tables modified at time 1 are exported as well.

Figure 1 - 6. Cumulative Export at Time 2

This cumulative export file is a combination of the incremental exports from time 1 and time 2, except that table 3 (which was modified at both times) only occurs once in the export file. In this way, cumulative exports save space over multiple incremental exports.

 Complete Exports

A complete export establishes a base for incremental and cumulative exports. It is equivalent to a full database export, except that it also updates the tables that track incremental and cumulative exports.

Figure 1 - 7 shows a complete export at time 2. With the complete export, all objects in the database are exported regardless of when (or if) they were modified.

Figure 1 - 7. Complete Export

 Benefits

Incremental and cumulative exports help solve the problems faced by administrators who work in environments where many users create their own tables. For example, administrators can restore tables accidentally dropped by users.

The benefits of incremental and cumulative exports include:

•	smaller export files

•	less time to export

These benefits result because not all tables have changed. So the time and space required for an incremental or cumulative export is shorter than for a full database export.

 A Scenario

Cumulative and incremental exports require that a complete export occur periodically, to form the base backup. Following the complete export, the administrator can take frequent incremental exports and occasional cumulative exports. After a given period of time, the cycle should begin again with another complete export.

The following scenario shows how you can use cumulative and incremental exports.

Assume that as manager of a data center, you do the following tasks:

•	a complete export (X) every three weeks

•	a cumulative export (C) every weekend

•	an incremental export (I) every night

Your export schedule follows:

DAY: 1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21

     X  I  I  I  I  I  C  I  I  I  I  I  I  I  C  I  I  I  I I  X

To restore through day 18, you would first import the system information from the incremental export taken on day 18. You would then import the data from:

•	the complete export taken on day 1

•	the cumulative export taken on day 7

•	the cumulative export taken on day 15

•	and three incremental exports taken on days 16, 17, and 18

The incremental exports on days 2 through 6 can be discarded on day 7, when the cumulative export is done, because it incorporates all of them. Similarly, the incremental exports on days 8 through 14 can be discarded after the cumulative export on day 15.

Note: The section "Incremental Imports" shows you how to run an incremental import.

 Which Data Is Exported?

The purpose of an incremental or cumulative export is to identify and export only those database objects (such as clusters, tables, views, and synonyms) that have changed since the last export. Each table is associated with other objects that you can export. Besides the data itself, there are indexes and grants.

The entire grant structure for tables or views is exported with the underlying base table(s). Indexes are exported with their base table, regardless of who created the index.

Export automatically exports a read-consistent view of a table, even if the table is being updated during the export.

Any modification (UPDATE, INSERT, or DELETE) on a table automatically qualifies that table for export.

Also, if database structures have changed in the following ways, then the underlying base tables and data are exported:

•	a table is created

•	a table definition is changed by an ALTER TABLE statement

•	comments are added or edited

•	auditing options are updated

•	grants (of any level) are altered

•	indexes are added or dropped

•	index storage parameters are changed by an ALTER INDEX statement

In addition, the following data is backed up:

•	all system objects (including tablespace definitions, rollback segment definitions, and user privileges, but not including temporary segments)

•	information about dropped objects

•	clusters, tables, views, and synonyms created since the last export

Restrictions

You can do incremental, cumulative, and complete exports only in full database mode (FULL=Y). Only users who have the EXP_FULL_DATABASE role can run incremental, cumulative, and complete exports. This role contains the privileges needed to modify the system tables that track incremental exports. Those tables are discussed at the end of this section.

 Command Syntax

The command syntax is as follows:

 where:

INCREMENTAL	Exports all database objects that have changed since the last incremental export, as tracked by table SYS.INCEXP, then updates the table with a new ITIME and EXPID.

CUMULATIVE	Exports all database objects that have changed since the last cumulative export, as tracked by SYS.INCEXP, then updates the table with a new CTIME, ITIME, and EXPID.

COMPLETE	Exports all objects and updates the tables SYS.INCEXP and SYS.INCVID. (A FULL=Y export does not update these tables unless you specify the INCTYPE parameter.)

Note: For incremental and cumulative exports, a row is also added to table SYS.INCFIL to identify the export file and the user doing the export. For more information on the system tables that support incremental export, see page 1 - 27. When exporting with the parameter "INCTYPE = COMPLETE", all the previous entries are removed from SYS.INCFIL and a new row is added specifying an "x" in the column EXPTYPE.

 Sample Incremental Export

The following example shows an incremental export session after the tables SCOTT.EMP and SCOTT.DEPT are modified:

exp system/manager inctype=incremental

...

About to export the entire database ...

. exporting tablespace definitions

. exporting profiles

. exporting user definitions

. exporting roles

. exporting resource costs

. exporting rollback segment definitions

. exporting database links

. exporting sequence numbers

. exporting job queues

. exporting refresh groups and children

. exporting cluster definitions

. exporting stored procedures

. about to export SYSTEM's tables ...

. about to export SCOTT's tables ...

. exporting table                    DEPT        7 rows exported

. exporting table                     EMP       22 rows exported

. about to export ADAMS's tables ...

. about to export JONES's tables ...

. about to export CLARK's tables ...

. about to export BLAKE's tables ...

. exporting referential integrity constraints

. exporting triggers

. exporting posttables actions

. exporting synonyms

. exporting views

. exporting default and system auditing options

. exporting information about dropped objects

Export terminated successfully without warnings.

 System Tables

SYS owns three tables (INCEXP, INCFIL, and INCVID) maintained by Export/Import. None of these tables should be altered in any way.

 SYS.INCEXP

Export maintains a table to track which objects were exported in specific exports. That table, SYS.INCEXP, contains these columns:

OWNER#	The userid of the schema containing the table.

NAME	The object name. With OWNERID, this column forms the primary key for the table.

TYPE	The type of the object (a code standing for INDEX, TABLE, CLUSTER, VIEW, SYNONYM, SEQUENCE, PROCEDURE, FUNCTION, PACKAGE, TRIGGER, SNAPSHOT, SNAPSHOT LOG, or PACKAGE BODY).

CTIME	The date of the last cumulative export that included this object.

ITIME	The date of the last incremental export that included this object.

EXPID	The ID of the incremental or cumulative export, also found in table SYS.INCFIL.

You can use this information in several ways. For example, you could generate a report from SYS.INCEXP after each export to document the export file.

 SYS.INCFIL

The table SYS.INCFIL tracks the incremental and cumulative exports and assigns a unique identifier to each. This table contains the following columns:

EXPID	The ID of the incremental or cumulative export, also found in table SYS.INCEXP.

EXPFILE	The name of the export file.

EXPDATE	The date of the export.

EXPUSER	The username of the user doing the export.

EXPTYPE	The type of export (incremental or cumulative).

 SYS.INCVID

A third table, SYS.INCVID, contains one column for the EXPID of  the last valid export. This information determines the EXPID of the next export.


CHAPTER 2. IMPORT

This chapter shows you how to use the Import utility. Import reads export files into an Oracle database. For example, if you export all your tables and data into a file named MYDATA.EXP, when you import MYDATA.EXP, Import re-creates each table and loads the data.

Import reads files written by Export, only. For more information on how to export a file, see Chapter 1, "Export". To load data from other operating system files, see the discussion of SQL*Loader in Part II of this Guide.

This chapter discusses the following subjects:

•	guidelines for using Import

•	interactive and command-line methods

•	Import parameters

•	incremental imports

Several sample imports are also provided to help you learn how to  use Import.

 ________________________________________

Import Guidelines

Import extracts objects from an export file and puts them into a database. Figure 2 - 1 shows a newly-created database. Figure 2 - 2 shows this result of doing the import.

Figure 2 - 1. After Creating a Database

Figure 2 - 2. After Importing the Export File

The remainder of this section offers guidelines to help you make the best use of Import.

 Preparation

To use Import, the script CATEXP.SQL must be run. After creating the database, do one of the following:

•	run CATEXP.SQL

•	run CATALOG.SQL (which runs CATEXP.SQL)

Additional Information:  The actual names of the script files depend on the operating system. The script file names and the method for running them are described in your operating system-specific Oracle7 documentation.

CATEXP.SQL only needs to be run once. Once run, it does not need to be run again for future imports. CATEXP.SQL performs the following operations to prepare the database for an import:

•	assigns all necessary privileges to the IMP_FULL_DATABASE role

•	assigns IMP_FULL_DATABASE to the DBA role

 Read-Only Tablespaces

You cannot import into a read-only tablespace, unless you first declare it to be a read-write tablespace. When the import completes, you can return the tablespace to its read-only status.

 Access Privileges

To use Import, you need the CREATE SESSION privilege to log on to the Oracle Server. This privilege belongs to the CONNECT role established during database creation.

You can do an import even if you did not create the export file. However, if the export file is a full database export (created by someone using the EXP_FULL_DATABASE role), then it will only be possible to import that file if you have the IMP_FULL_DATABASE role enabled.

Additional Information:  You can import any export file into a Trusted Oracle7 database. For example, if you create an export file from an OS MAC database, you can import that file into a DBMS MAC database.

 Storage Parameters

A table is imported into its original tablespace using the original storage parameters.

If the tablespace no longer exists, or the user does not have sufficient quota in the tablespace, the system uses the default tablespace for that user. If the user does not have sufficient quota in the default tablespace, the user's tables are not imported. (See "Reorganizing Tablespaces" for a way to use this to your advantage.)

If you selected the "compress extents" option at export time, then the storage parameters for large tables are adjusted to place all data imported for a table into its initial extent. To preserve the original  size of an initial extent, you must specify at export time that data not  be compressed.

 Character Translation

Export writes export files using the character set specified for the user session; for example, 7-bit ASCII or IBM Code Page 500 (EBCDIC). If necessary, Import automatically translates the data to the character set of its host system. Import converts character data to the user-session character set if that character set is different from the one in the  export file.

 Restrictions

When you initialize a database, Oracle creates a single system rollback segment (named SYSTEM). Oracle uses this rollback segment only for transactions that manipulate objects in the SYSTEM tablespace. This restriction does not apply if you intend to import only into the SYSTEM tablespace. However, if you want to import into a different tablespace, you must create a new rollback segment. For details on creating rollback segments, see Chapter 9 "Managing Rollback Segments" of the Oracle7 Server Administrator's Guide.

Full database export files can only be imported by users with the IMP_FULL_DATABASE role enabled.

Import can read export files created by Export Version 5.1.22 and later.

The storage parameter OPTIMAL for rollback segments is not preserved during export and import.

Additional Information:  There are additional steps and considerations when you are importing to a Trusted Oracle7 Server database. The Trusted Oracle7 Server Administrator's Guide contains more guidelines for using Import with Trusted Oracle7 Server.

 ________________________________________

Error Handling

Whenever possible, Import continues after encountering an error. Row errors allow for continued import of the same table or views. Object errors force the import of the current object to be discontinued. Import then continues with the next object. Row errors and object errors are non-fatal errors, or warnings. Fatal errors cause Import to terminate.

All error messages go to the display screen. If a log file has been specified, error messages go to the log file, as well. A log file should always be generated during import. (On those systems that permit I/O redirection, Import's output can be redirected to a file instead.)

Additional Information:  For information on the LOG specification, see page 2 - 21. See your operating system-specific Oracle7 documentation for information on redirecting output.

When an import completes without problems, the message "Import terminated successfully without warnings" is issued. If one or more non-fatal errors occurred, but Import was able to continue to completion, then the message "Import terminated successfully with warnings" occurs. If a fatal error occurs, then Import ends immediately with the message "Import terminated unsuccessfully".

Additional Information:

Specific messages are documented in the Oracle7 Server Messages and Codes Manual and in your operating system-specific Oracle7 documentation.

Messages that are specific to Trusted Oracle7 Server are addressed in the Trusted Oracle7 Server Administrator's Guide. General kinds of errors are discussed in the remainder of this section.

 Row Errors

If a row error occurs, Import puts out an error message and continues processing the rest of the table. Row errors occur when Oracle rejects a row for some reason, such as a violation of integrity constraints or invalid data.

 Failed Integrity Constraints

A row error is generated if a row violates one of the integrity constraints in force on your system, including:

•	not null constraints

•	uniqueness constraints

•	primary key (not null and unique) constraints

•	referential integrity constraints

•	check constraints

See Chapter 6, "Maintaining Data Integrity", in the Oracle7 Server Application Developer's Guide and Chapter 7, "Data Integrity", in  the Oracle7 Server Concepts Manual for more information on  integrity constraints.

 Invalid Data

Row errors also occur when importing data into an existing table with a slightly shorter character-data column. The error is caused by data that is too long to fit into a new table's columns, by invalid data types, and by any other INSERT error.

 Long Raw Data Errors

Some LONG RAW data columns may be too large to fit into Import's data buffer due to memory limitations. On Export, Oracle allows selecting such columns in sections. However, on Import, a contiguous region of memory is required. As a result, some columns that are successfully exported may not be importable until more memory is available. Such columns can produce row errors.

 Setting Buffer Size for LONG Data

Tables with LONG data usually require large insert buffer sizes. If you are trying to import LONG data and Import fails with the message

IMP-00020 column (size num) in export file too large for column

          buffer (size num)

then you can gradually increase the insert buffer size (for example, by 10,000 bytes at a time) up to 66,000 or greater. Use this step-by-step approach because a buffer size that is too large may cause a similar problem.

 Solving LONG Data Errors

If LONG or LONG RAW data on your system can become sufficiently large to create an import problem, then you need to make alternative plans for backup or file transfer. One good idea is to put such columns in a separate table so that all other data can be exported and imported normally.

Such data does not change once it is in place. One method of backup is to preserve the original source of the data. Another option is to use a separate backup facility.

 Object Errors

An object error occurs when import of the current object must be discontinued. Import then attempts to continue with the next object in the export file. If COMMIT=N has been specified, a rollback occurs before Import goes on. Otherwise, a commit is issued. (See the description of COMMIT for more information.)

 Object Already Exists

If an object to be imported already exists in the database, then an object creation error occurs. What happens next depends on the setting of the IGNORE parameter.

If IGNORE=N, the error is reported, and Import continues with the next object. The current object is not replaced. For tables, this behavior means that rows contained in the export file are not imported.

If IGNORE=Y, object creation errors are not reported. The object is still not replaced. If the object is a table, rows are imported into it.

Warning: Specifying IGNORE=Y can cause duplicate rows to be entered into a table unless one or more columns of the table are specified with the UNIQUE integrity constraint. This could occur, for example, if Import were run twice.

 Sequences      When importing into an existing database, sequences that will be imported should be dropped before the import. A sequence that is not dropped before the import is not set to the value captured in the export dump file. Import does not drop and re-create a sequence that already exists. If the sequence already exists, then the export file's "create sequence" statement fails and the sequence is not imported.

 Resource Errors

Resource limitations can cut short parts of an import. When importing tables, for example, resource errors can occur as a result of internal problems, or when a resource such as memory has been exhausted. If such an error occurs while importing a row, Import stops processing the current table and skips to the next table.

If you specified COMMIT=Y, Import commits the partial import of the current table. Otherwise, a rollback of the current table occurs before Import continues. (See the description of COMMIT for information about the COMMIT parameter.)

 Fatal Errors

When a fatal error occurs, Import terminates. For example, such an error occurs when DESTROY=N is specified (so as not to reuse datafiles) and the datafiles named in the export file already exist. In that event, the Import terminates.

 ________________________________________

Privileges Required for Import

This section describes the privileges (or roles) needed for Import.

 Importing Objects into Your Own Schema

The following privileges are needed to import objects into your own schema. All of these privileges initially belong to the RESOURCE role.

Object	Privileges	Privilege Type

------------------------------------------------------------------------

clusters	CREATE CLUSTER	system

And:	tablespace quota, or

UNLIMITED TABLESPACE	system

database links	CREATE DATABASE LINK	system

CREATE SESSION on remote db	system

database triggers	CREATE TRIGGER	system

indexes	CREATE INDEX	system

And:	tablespace quota, or

UNLIMITED TABLESPACE	system

integrity constraints	ALTER TABLE	object

packages	CREATE PROCEDURE	system

private synonyms	CREATE SYNONYM	system

sequences	CREATE SEQUENCE	system

snapshots	CREATE SNAPSHOT	system

stored functions	CREATE PROCEDURE	system

stored procedures	CREATE PROCEDURE	system

table data	INSERT TABLE	object

table definitions	CREATE TABLE	system

And:	tablespace quota, or

UNLIMITED TABLESPACE	system

views	CREATE VIEW	system

And:	SELECT on the base table, or	object

SELECT ANY TABLE	system

Table 2 - 1.  Privileges Required to Import Objects

Notes:    	•	Table definitions include comments and audit options.

•	In Trusted Oracle7 Server, you must have write access to all labels at which you are importing data. See the Trusted Oracle7 Server Administrator's Guide for more information.

 Importing Grants

To import the authorizations that a user has extended to others, the user must be empowered to grant the privileges. The following table shows the required conditions for the authorizations to be valid on the target system:

Grant   	Conditions

object privileges	Object must exist in the user's schema, or user must have

the privileges accompanied by the WITH GRANT OPTION.

system privileges	User must have the privileges accompanied by the WITH

ADMIN OPTION.

Table 2 - 2.  Privileges Required to Import Grants

 Importing Objects into Other Schemas

To import objects into another user's schema, you need to have the IMP_FULL_DATABASE role enabled.

 Importing System Objects

To import system objects from a full database export file, the IMP_FULL_DATABASE role must be enabled. The import parameter FULL specifies that system objects are included in the import. The system objects are

•	profiles

•	public database link

•	public synonyms

•	roles

•	rollback segment definitions

•	system audit options

•	system privileges

•	tablespace definitions

•	tablespace quotas

•	user definitions

Additional Information:  To perform a full database import in Trusted Oracle7 Server, your operating system label must match DBHIGH. See the Trusted Oracle7 Server Administrator's Guide for more information.

 ________________________________________

Table Objects: Order of Import

Table objects are imported from the export file in the following order:

1.	table definitions

2.	table data

3.	table indexes

4.	integrity constraints and triggers

First, new tables are created. Then data is imported. After all data has been imported into all tables, indexes are built. Then triggers are imported, and integrity constraints are enabled on the new tables. This sequence prevents data from being rejected due to the order in which tables are imported. This sequence also prevents redundant triggers from firing twice on the same data (once when it was originally inserted and again during the import).

For example, if the EMP table has a referential integrity constraint on the DEPT table and the EMP table is imported first, then all EMP rows that reference departments that have not yet been imported into DEPT would be rejected provided that the constraints are enabled.

When data is imported into existing tables, however, the order of import can still produce referential integrity failures. In the situation given above, if the EMP table already existed and referential integrity constraints were in force, many rows could be rejected.

A similar situation occurs when a referential integrity constraint on a table references itself. For example, if SCOTT's manager in the EMP table is DRAKE, and DRAKE's row has not yet been loaded; then SCOTT's row will fail--even though it would be valid at the end of the import.

Suggestion: For these reasons, it is a good idea to disable referential constraints when importing into an existing table. You can then re-enable the constraints when the import completes.

 ________________________________________

Importing Users

When user definitions are imported into Oracle7, they are created with the CREATE USER command. So, when importing from export files created by previous versions of Export, users are not granted CREATE SESSION privileges automatically.

 ________________________________________

Importing Stored Procedures, Functions, and Packages

When a stored procedure, function, or package is imported, it retains its original timestamp. Remote procedures are not recompiled at import time; while this functionality prevents unnecessary recompilation, you will have to check that remote procedures that are imported have been recompiled.

If the timestamp of the imported version matches the timestamp of the version currently in the database, then local dependent procedures (functions and packages that use it) are not marked for recompilation. If the timestamps differ, then local dependent procedures are marked for recompilation. When a remote package or procedure calls one of these dependent procedures, the dependent procedure is recompiled. The timestamp of the dependent procedure then changes, signaling an error in the remote procedure that called it.

Note: Imported procedures, functions, and packages are not automatically compiled after import. Instead, they are marked for compilation. Such components are compiled when they are invoked. Use the COMPILE ALL command to recompile each schema's marked procedures. For more information, see the Oracle7 Server Applications Developer's Guide.

 ________________________________________

Importing Snapshots

There are four interrelated objects in a snapshot system: the master table, optional snapshot log, the master table trigger that updates the snapshot log, and the snapshot itself. All of these objects are exported normally. The master table trigger, if it exists, is exported as part of the master table. The tables (master table, snapshot log table definition, and snapshot tables) can be exported independently of one another. This section discusses how fast refreshes are affected when these objects are imported.

 Master Table

If the master table already exists, and it has a snapshot log; then imported data is recorded in the snapshot log.

 Master Table Trigger

The snapshot log update trigger, if it exists, is exported as part of the master table. Similarly, it is automatically imported from the export file. Because all triggers are imported after all tables, the update trigger is imported after the master table and snapshot log.

 Snapshot Log

When a snapshot log is exported, only the table definition is placed in the export file, because the master table rowids stored in the snapshot log would have no meaning upon import. So, after importing a snapshot log, the log is empty. As a result, each snapshot's first attempt to do a fast refresh fails, generating an error that says a complete refresh is required.

To avoid the refresh error, do a complete refresh after importing a snapshot log. After doing a complete refresh, subsequent fast refreshes work properly.

 Snapshots

A snapshot that has been restored from a backup file has "gone back in time" to a previous state. On import, the time of the last refresh is imported as part of the snapshot table definition. The function that calculates the next refresh time is also imported.

Each refresh leaves a signature. A fast refresh uses the log entries that date from the time of that signature to bring the snapshot up to date. When the fast refresh is complete, the signature is deleted and a new signature is created. Any log entries that are not needed to refresh other snapshots are also deleted (all log entries with times before the earliest remaining signature).

 Importing a Backup

When restoring a dropped snapshot from a backup, there are two potential problems:

•	If a snapshot is refreshed at time A, exported at time B, and refreshed again at time C, then the re-imported version has the last refresh time recorded as time A. Log entries needed for a fast refresh may no longer exist. If the log entries do exist (because they are needed for another snapshot that has yet to be refreshed), then they are used, and the fast refresh completes successfully. Otherwise, the fast refresh fails, generating an error that says a complete refresh is required.

•	Whether the fast refresh succeeds or fails, the signature left at time C remains. All log entries after time C will remain in the log, waiting for a refresh that never occurs. This situation causes the log to grow continuously -- it does not shrink, even when all snapshots have been refreshed. Subsequent fast refreshes fail, generating an error that says a complete refresh is required. This problem can be solved by purging the snapshot log.

Suggestion: Both of these problems can be avoided by exporting backup copies of snapshots immediately after doing a fast refresh. If out of date backups must be imported, do a complete refresh at the earliest opportunity.

 Importing into an Existing Snapshot

If snapshot rows have been lost, and the snapshot is restored from a backup without dropping it; other problems may result. If the snapshot is exported at time A and a refresh occurs at time B, the snapshot's signature reflects time B, but data is imported as of time A. Subsequent fast refreshes update from time B, not from time A. So changes logged in the master table between time A and B are not reflected in the snapshot. This situation can only occur if IGNORE=Y is specified for the import. (Otherwise, the snapshot rows are not imported.) As a result, the situation is undetectable -- the IGNORE setting prevents a warning from being issued.

Suggestion: To avoid such problems, export backup copies of snapshots immediately after doing a fast refresh. If out of date backups must be imported, do a complete refresh at the earliest opportunity.

 Second Copy of a Snapshot

Here is another unusual case.

Warning: If a snapshot is imported into two databases or into two different schemas, then there are two copies of the snapshot, but only one signature. The first snapshot to do a fast refresh recognizes the signature and gets the expected results. The second snapshot finds the signature missing and gets an error that says a complete refresh is required. After doing the complete refresh, the second snapshot has its own signature. Subsequent fast refreshes then work properly.

 ________________________________________

Character Set Conversion

The export file identifies the character encoding scheme used for the character data in the file. If that character set is any single-byte character set (for example, EBCDIC or USASCII-7), and if the character set used by the target database is also a single-byte character set; then the data is automatically converted to the character encoding scheme specified for the user session during import, as specified by the NLS_LANG parameter. After the data has been converted to the session character set, it is then converted to the database character set.

During the conversion, any characters in the export file that have no equivalent in the target character set are replaced with a default character. (The default character is defined by the target character set.) To guarantee 100% conversion, the target character set should be a superset or equivalent of the source character set.

For multi-byte character sets, conversion is only performed if the length of the character string cannot change as a result of the conversion.

For more information, refer to the National Language Support section of the Oracle7 Server Administrator's Guide.

 ________________________________________

Import Modes

The objects that are imported depend on the mode you choose. All users have at least two choices of import mode. A user with the IMP_FULL_DATABASE role (a privileged user) has three choices:

Table	This mode allows you to import specified tables in your schema, rather than all your tables. A privileged user can qualify the tables by specifying the schema that contains them. The default is to import all tables in the schema of the user doing the import.

User	This mode allows you to import all objects that belong to you (such as tables, data, grants, and indexes). A privileged user importing in user mode can import all objects in the schemas of a specified set of users.

Full Database	Only users with the IMP_FULL_DATABASE role can import in this mode. All objects in the export file are imported.

To select table, user, or full database mode, specify TABLES=tablelist, FROMUSER=userlist, or FULL=Y, respectively. A user with the IMP_FULL_DATABASE role must specify one of these options, or else an error results. If a user without the IMP_FULL_DATABASE role fails to specify one of these options, then a user-level import is performed.

The table shows objects that are imported in each mode.

 ________________________________________

How to Use Import

You can use Import in three ways:

•	Enter the command IMP username/password PARFILE=filename with the remaining import parameters contained in the specified file. This is the preferred method.

•	Enter the command IMP username/password followed by various arguments that control how Import runs. This is a highly useful method, provided the number of parameters does not exceed the maximum length of a command line on your operating system.

•	Enter the command IMP username/password to begin an interactive session, and let Import prompt you for the information it needs. The interactive option does not provide as much functionality as the parameter-driven method. It exists only for backward compatibility.

The username and password can also be specified in the parameter file, although it is not recommended that you do so if security is important at your installation. If you do not specify this parameter, Import prompts for it. This lets you hide your password from view, because Import does not echo the entered password.

 Getting Help

Import provides online help. Enter IMP HELP=Y on the command line to see a help screen like the one shown in the following figure:

Figure 2 - 3.  Import Help Screen

 Multilingual Values

Import allows Y/N values to be specified with the national language used in the current session. For example, a user with the French language enabled could specify "O" or "OUI" instead of  "Y". In the pages that follow, the value "Y" could be replaced by "YES", "TRUE", "T", or by the appropriate response for the current session's language. Similarly, "N" could be replaced by "NO", "FALSE", and so on.

 Parameter File Method

The PARFILE option allows you to specify Import parameters in a file. This option can only be specified on the command line. With all your parameter specifications in a file, enter one of the following commands:

IMP PARFILE=filename

IMP username/password PARFILE=filename

The general form of a parameter specification is as follows:

KEYWORD=value   or

KEYWORD=(value) or

KEYWORD=(value1, value2, ...)

You can format the parameter file like a command, separating parameters with spaces. You can also separate parameters with carriage returns, as in the following example:

SYSTEM/MANAGER

FULL=Y

FILE=DBA.DMP

GRANTS=Y

INDEXES=Y

Additional Information:  The size of the parameter file may be limited. See your operating system-specific Oracle7 documentation for detailed information.

 Comments

You can comment the parameter file with the # sign. All characters to the right of the # sign are ignored.

 Table Name Restriction

Because parameter files allow comments, table names specified on the command line cannot include a # sign, unless the table name is enclosed in quotation marks.

Additional Information:  For details on the type of quotation marks required on your operating system, see your operating system-specific Oracle7 documentation.

Similarly, in a parameter file, if a table has a # sign in the name, the rest of the line is interpreted as a comment unless the table name is enclosed in quotation marks. For example, if the parameter file contains the line

TABLES=(EMP#, DEPT, MYDATA)

then nothing on the line after EMP# is seen as input by Import. As a result, DEPT and MYDATA are not imported. The following line fixes the problem:

TABLES=("EMP#", DEPT, MYDATA)

Attention: When the name is specified in quotes, it becomes case-sensitive. The name must then exactly match the table name stored in the database. By default, database names are stored as uppercase.

 Import Parameters

The following parameters, except for PARFILE, can be specified in the parameter file. They are described in detail in the remainder of this section.

USERID	RECORDLENGTH

BUFFER	INCTYPE

FILE	COMMIT

SHOW	HELP

IGNORE	PARFILE

GRANTS	LOG

INDEXES	DESTROY

ROWS	INDEXFILE

FULL	CHARSET

FROMUSER	MLS*

TOUSER	MLS_LISTLABELS*

TABLES	MLS_MAPFILE*

*This is a Trusted Oracle7 Server parameter.

The order of the parameters is significant. Parameters specified in this order can be specified without the introductory keyword. For example, USERID=system/manager can be specified simply as system/manager, provided this parameter is specified first. However, use of this functionality for parameters other than USERID is not recommended. It is provided for backward compatibility only.

Note: This order is guaranteed up to the PARFILE  parameter only.

BUFFER	Default: operating system dependent

The size in bytes of the buffer through which data rows are transferred. The BUFFER (buffer size) parameter determines the number of rows in the array inserted by Import. The following formula gives a rough approximation of the buffer size that inserts a given array of rows:

buffer_size = rows_in_array * maximum_row_size

Additional Information: See your operating system-specific Oracle7 documentation to determine the default value for this parameter.

CHARSET	Default: none

This parameter is used for Release 6 export files only. It specifies the NLS character set used in the export file. Use of this parameter is not recommended. It is only provided for compatibility with previous versions. Eventually, it will no longer be supported.

In Oracle7, the character set is specified within the export file, and conversion to the current database's character set is automatic. Specification of this parameter serves only as a check to ensure that the export file's character set matches the expected value. Otherwise, an error results.

Valid values for CHARSET are contained in the V$NLS_PARAMETERS view. Consult the Data Dictionary appendix of the Oracle7 Server Administrator's Guide for details.

COMMIT	Default: N

A flag to indicate whether to commit after each array insert. By default, Import commits after loading each object. If COMMIT=N is specified, Import performs a rollback when an error occurs before continuing the import with the next object.

Specifying COMMIT=Y keeps rollback segments from growing inordinately large and improves the performance of large imports. This is a good choice if the table has a uniqueness constraint. If the import is restarted, any rows that have already been imported will be rejected with a non-fatal error. If there is no uniqueness constraint, then COMMIT=N is probably a wiser choice, because re-importing the data could produce duplicate rows.

DESTROY	Default: N

Specifies whether the existing datafiles making up the database should be reused.

The export file contains the datafile names used in each tablespace. Attempting to create a second database on the same machine (for testing or other purposes) has the undesirable effect of overwriting the original database's datafiles when creating the tablespace. With this parameter set to N, an error occurs if the datafiles already exist when the tablespace is created.

To eliminate this error when importing into a secondary database, precreate the tablespace and specify its datafiles. (Specifying IGNORE=Y suppresses the warning that the tablespace already exists.)

To bypass the error when importing into the original database, specify IGNORE=Y to add to the existing datafiles without replacing them. To reuse the original database's datafiles after eliminating their contents, specify DESTROY=Y.

FILE	Default: EXPDAT.DMP

The name of the export file to import.

FROMUSER	Default: undefined

A list of schemas containing objects to import. When given by itself, this parameter specifies a user mode import. That is, all objects for the named user are imported. (If the TABLES parameter is also specified, then a table mode import is performed.)

When importing in user mode, all other objects in the export file are ignored. The effect is the same as if the export file had been created in user mode (or table mode). See page 1 - 7 for the list of objects that are imported in user mode and table mode.

For example, the following command treats the export file as though it were simply a user mode export of SCOTT's objects:

IMP system/manager FROMUSER=scott

If user SCOTT does not exist in the current database, then his objects are imported into the importer's schema -- in this case, the system manager's. Otherwise, the objects are installed in SCOTT's schema.

If a list of schemas is given, each schema can be specified only once. Duplicate schema names are ignored. For example:

FROMUSER=(scott,sanchez)

Note: Specifying FROMUSER=SYSTEM does not import system objects. It imports only those objects that belong to user SYSTEM. To import system objects (for example, user definitions and tablespaces), you must import from a full export file specifying FULL=Y.

FULL	Default: N

A flag to indicate whether to import the entire file. This parameter can be specified only by a user with the IMP_FULL_DATABASE role enabled.

GRANTS	Default: Y

A flag to indicate whether to import grants.

HELP	Default: N

Displays descriptions of import parameters.

IGNORE	Default: N

A flag to indicate how object creation errors should be handled. Specifying IGNORE=Y causes Import to overlook "object already exists" errors when attempting to create database objects.

For objects other than tables, if you specify IGNORE=Y, Import continues without reporting the error. If you specify IGNORE=N, Import reports the object creation error before continuing.

For tables, IGNORE=Y causes rows to be imported into existing tables. No message is given. IGNORE=N causes an error to be reported, and the table is skipped if it already exists.

Warning: When importing into existing tables, if no column  in the table is uniquely indexed; then rows could be duplicated if they were already present in the table. (This warning applies to non-incremental imports only. Incremental imports replace the table from the last complete export and then rebuild it to  its last backup state from a series of cumulative and incremental exports.)

INCTYPE	Default: undefined

The type of incremental import. Valid values are SYSTEM and RESTORE.

INDEXES	Default: Y

A flag to indicate whether to import indexes.

INDEXFILE	Default: none

Specifies a file to receive index-creation commands.

When this parameter is specified, index-creation commands are extracted and put in the specified file, rather than used to create indexes in the database. Tables and other database objects are not imported.

The file can then be edited (for example, to change storage parameters) and used as a SQL script to create the indexes. This is the most efficient way to create indexes for new tables--even if the index file is not edited. To make it easier to identify the indexes defined in the file, the export file's CREATE TABLE statements and CREATE CLUSTER statements are included as comments.

Perform the following steps to make use of this feature:

1.	Import using the INDEXFILE command to create a file of index-creation commands.

2.	Edit the file as desired.

3.	Rerun Import, specifying INDEXES=N.

This step imports the database objects while preventing Import from using the index definitions stored in the export file.

4.	Run the file of index-creation commands to create the index.

Suggestion: It is frequently possible to modify the resulting list to reimport specific objects, or edit it to create a script of SQL commands that applies to the imported objects.

LOG	Default: none

Specifies a file to receive informational and error messages. If specified, all information that goes to the display also goes to the log.

MLS	Imports data into a secure database. It says that the export file contains Multi-Level Security (MLS) labels. For more information on this parameter, see the Trusted Oracle7 Server Administrator's Guide and the Oracle7 Server Addendum.

MLS_LISTLABELS	Lists the MLS labels in the export file. For more information on this parameter, see the Trusted Oracle7 Server Administrator's Guide and the Oracle7 Server Addendum.

MLS_MAPFILE	Maps the MLS labels in the export file to the labels used in the target database for the import. For more information on this parameter, see the Trusted Oracle7 Server Administrator's Guide and the Oracle7 Server Addendum.

PARFILE	Default: none

Specifies a file containing parameter specifications.

RECORDLENGTH	Default: operating system dependent

The length in bytes of the file record. The RECORDLENGTH parameter is required when you import to another operating system that uses a different default value (see your Oracle installation or user's guide for the proper value).

Additional Information: See your operating system-specific Oracle7 documentation to determine the default value for this parameter.

ROWS	Default: Y

A flag to indicate whether to import the rows of table data.

SHOW	Default: N

Indicates whether the contents of the export file should only be listed, without importing the table data, without creating any objects, and without modifying the database.

TABLES	Default: none

A list of table names to import. Use an asterisk (*) to indicate all tables. This parameter specifies a table mode import, which restricts the import to tables and their associated objects, as listed. Up to 50 tables may be specified at once.

Although you can qualify table names with schema names (as in SCOTT.EMP) when exporting, you cannot do so when importing. In the following example, the TABLES parameter is specified incorrectly:

IMP system/manager TABLES=(jones.accts, scott.emp,scott.dept)

Here is a valid specification to import these tables:

IMP system/manager FROMUSER=(scott,jones) TABLES=(accts,emp,dept)

If user SCOTT does not exist in the current database, then his tables are imported into the importer's schema -- in this case, the system manager's. Otherwise, the tables and associated objects are installed in SCOTT's schema.

TOUSER	Default: none

A list of usernames to whom data will be imported. The IMP_FULL_DATABASE role is required to use this parameter.

To import to a different schema than the one that originally contained the object, specify TOUSER. For example:

IMP system/manager FROMUSER=scott TOUSER=joe TABLES=emp

If multiple schemas are specified, then the schema names are paired. For example,

IMP system/manager FROMUSER=(scott,fred) TOUSER=(joe, ted)

imports SCOTT's objects into JOE's schema, and FRED's objects into TED's schema. If the FROMUSER list is longer than the TOUSER list, the extra objects go into the schema of the last specified TOUSER. If the TOUSER list is longer, then excess TOUSER names are ignored.

USERID	Default: undefined

The username and password (separated by a slash) of the user performing the import. If these comprise the first argument, the keyword USERID is not needed.

 Command-line Method

All parameters that can be specified in a parameter file can also be specified on the command line. Parameters specified on the command line override parameters specified in a parameter file.

Here are two examples of Import specified with all parameters on the command line:

IMP USERID=scott/tiger IGNORE=Y FULL=N

IMP system/manager FULL=Y FILE=nov13.exp IGNORE=N GRANTS=N

 Interactive Method

Import's interactive prompts are described next. This method provides a subset of Import capabilities. It is provided for backward compatibility only.

You may not see all the prompts in a given Import session because some prompts depend on your responses to other prompts. Some prompts show a default answer; if the default is acceptable, press ENTER or RETURN. To end your input, enter a period (.) followed by RETURN.

Parameters that cannot be specified interactively can be specified on the command line or in a parameter file. If you have not specified a username/password on the command line, Import first prompts you for this information. Then the prompts described below are issued.

 File to Import

At the following prompt, if you want to import a file other than the default, enter the full name of the file to be imported. You do not have to be the Oracle user who exported the file. However, you do need to have current access to the file, which must reside where Import expects to find it.

Import file: EXPDAT.DMP >

 Buffer Size

At the next prompt, the default buffer size will be adequate for most of your tables. However, you may need to increase it for tables that have LONG columns. The buffer must be at least as large as the longest row.

Enter insert buffer size (minimum is 4096): 10240 >

 Show Export File Contents

The following prompt allows you to see what is in the export file (for example, whether you exported a particular table to this file). You get the same results by specifying the SHOW parameter on the command line. If you answer N, Import continues with the next prompt.

If you answer Y, Import does not import the rows but asks more questions to determine whether to display the whole export file or only portions of it. Based on your answers, Import may display the SQL statements contained in the export file in the order they would be executed on import.

List contents of import file only (Y/N): N >

 Object Creation Errors

Import always generates an error if an object to be imported already exists. The answer you give to the following prompt determines how you want the errors to be handled:

Ignore create errors due to object existence (Y/N): N >

For objects other than tables, if you answer Y, Import continues without reporting the error. If you answer N (the default), Import reports object creation errors. For tables, answering Y causes rows to be imported into existing tables. No message is given. Answering N causes an error to be reported, and the table is skipped if it already exists.

For example, you may want to import data into a pre-existing table--perhaps because you want to use particular storage parameters, or because you have precreated the table in a cluster. You do so by answering Y to this prompt. Your rows of data are imported, although Import cannot first create the table. So the rows are added to the existing table. If you answer N, Import does not import rows when the CREATE TABLE fails.

Some situations may require that you answer Y:

•	When importing to a database with limited free space, be careful if Import is compressing all data for a large table into an initial extent or is moving a table into other than its original tablespace. If enough contiguous blocks are not available for the initial extent, you receive the following message:

ORA-01547: failed to allocate extent of size num in

           tablespace 'name'

After this import session ends, you should manually create the affected tables with adequate storage parameters, then reimport the tables answering Y to this prompt. Because all the other tables were successfully imported during the earlier import, answer N to the prompt "Import entire export file?"

•	You should follow the same procedure if you encounter one of the following errors:

ORA-01631: maximum number extents (n) reached in table name

ORA-01632: maximum number extents (n) reached in index name

 Grants

At the next prompt, if you answer Y, any grants that were exported are now imported. If the export was done in user mode, only first-level grants (those granted by the owner) are in the export file. If the export was done in full database mode, all grants are in the export file, including lower-level grants (those granted by users given a privilege with the WITH GRANT option).

Import grants (Y/N): Y >

 Importing Data

By default, Import expects to import the data rows. However, if you answer N to the following prompt, Import executes the Data Definition Language statements such as CREATE TABLE or CREATE VIEW, but does not insert any data rows. Indexes and grants are created.

Import table data (Y/N): Y >

 Full Import

The following prompt gives you the option of choosing tables in a particular schema and of specifying which tables are imported from the export file. If you answer Y (the default), then all objects in the export file are imported.

Import entire import file (Y/N): Y >

 Tables to Import

If you answer N to the previous prompt, Import prompts you for a schema, after which you specify the tables you want to import for that schema. Entering a null table list causes all tables in the schema to be imported. Only one schema at a time can be specified with this interface. For example:

Username: scott

Enter table names. Null list means all tables for user

Enter table name or . if done:

. importing SCOTT's objects into SCOTT

. . importing table "BONUS"                     0 rows imported

. . importing table "DEPT"                      4 rows imported

   ...

Import terminated successfully without warnings

 ________________________________________

Sample Imports

This section gives some sample imports that show you how to use the command-line and interactive methods. These samples illustrate three cases:

1.	Tables imported by an administrator into the same schema from which they were exported.

2.	Tables imported by a user from another schema into the user's own schema.

3.	Tables imported into a different schema by an administrator.

 Sample Import of Selected Tables for a Specific User

In this example, using a full database export file, an administrator imports selected tables from a specific schema. With the command-line method, you specify FROMUSER=(schema) and TABLES=(tablename). If schema is not specified, it defaults to the schema from which the previous table was imported. If there is not a previous table, it defaults to the importer's schema. In the following example, schema defaults to JOE for table THINGS.

The command-line method follows:

imp system/manager file=dba.dmp fromuser=scott tables="(emp,dept)"

The equivalent interactive method follows:

imp system/manager

...

Import file: expdat.dmp >

Enter insert buffer size (minimum is 4096) 30720>

Export file created by EXPORT:V07.01.03

List contents of import file only (yes/no): no >

Ignore create error due to object existence (yes/no): yes >

Import grants (yes/no): yes >

Import table data (yes/no): yes >

Import entire export file (yes/no): yes > no

Username: scott

Enter table names. Null list means all tables for user

Enter table name or . if done: dept

Enter table name or . if done: emp

Enter table name or . if done: .

Import responds with the following messages:

Export file created by EXPORT:V07.01.03

Warning: the objects were exported by SCOTT, not by you

. importing SCOTT's objects into SYSTEM

. . importing table "DEPT"                         7 rows imported

. . importing table "EMP"                         22 rows imported

Import terminated successfully without warnings.

 Sample Import of Tables Exported by Another User

This example illustrates importing selected tables from a file exported by another Oracle user.

The command-line method follows:

imp adams/ez4me file=scott.dmp tables="(emp,dept)"

The equivalent interactive method follows:

imp adams/ez4me

...

Import file: expdat.dmp > scott.dmp

Enter insert buffer size (minimum is 4096) 30720>

Export file created by EXPORT:V07.01.03

Warning: the objects were exported by SCOTT, not by you

List contents of import file only (yes/no): no >

Ignore create error due to object existence (yes/no): yes >

Import grants (yes/no): yes > n

Import table data (yes/no): yes >

Import entire export file (yes/no): yes > n

Username: scott

Enter table names. Null list means all tables for user

Enter table name or . if done: emp

Enter table name or . if done: dept

Enter table name or . if done: .

Import responds with the following messages:

Export file created by EXPORT:V07.01.03

Warning: the objects were exported by SCOTT, not by you

. importing SCOTT's objects into ADAMS

. . importing table "EMP"                         22 rows imported

. . importing table "DEPT"                         7 rows imported

Import terminated successfully without warnings.

 Sample Import of Tables from One User to Another

In this example, a DBA imports all tables belonging to one user into another user's account. The command-line interface is required for this case, because the TOUSER parameter cannot be specified interactively.

The command line follows:

imp system/manager file=scott.dmp fromuser=scott touser=rosemary

tables=(*)           [use an asterisk to specify all tables]

Import responds with the following messages:

Export created by Oracle version EXPORT:V7.1

. importing user SCOTT into ROSEMARY

.. importing table "BONUS"	32 rows imported

.. importing table "SALGRADE"	10 rows imported

 ________________________________________

Incremental Imports

This section describes the incremental import facility.

 Restrictions

Incremental imports operate only on the entire database. There is no user-mode or table-mode incremental import. Any user with the BECOME_USER system privilege can do an incremental import. This privilege is contained in the IMP_FULL_DATABASE role.

 Command Syntax

The command syntax for an incremental import follows:

 where:

SYSTEM	Using the most recent incremental export file, imports the most recent version of system objects (those owned by SYS). A SYSTEM import does not import user data or objects. One SYSTEM incremental import must be done as the first step in restoring a database, using a combination of full, cumulative, and incremental exports.

RESTORE	Using export files in chronological order, imports all user database objects and data that have changed since the last export.

 Behavior

Because incremental imports bring in new versions of existing objects, they drop existing objects before importing the new ones. This behavior is different from a normal import. In a normal import, objects are never dropped -- an error is generated if the object already exists.

 Importing from Incremental or Cumulative Exports

To restore a set of objects, first you import the most recent incremental export file to import the system objects (INCTYPE=SYSTEM). Then you import export files in chronological order, based on their export time (INCTYPE=RESTORE). The import sequence follows:

1.	Import the most recent incremental export file (or cumulative export file, if no incremental exports have been taken) with the SYSTEM option.

2.	Import the most recent complete export file.

3.	Import all cumulative export files after the last complete export.

4.	Import all incremental export files after the last cumulative export.

For example, if you have

•	one complete export called X1

•	two cumulative exports called C1 and C2

•	three incremental exports called I1, I2, and I3

then you should import in the following order:

IMP system/manager INCTYPE=SYSTEM  FULL=Y FILE=I3

IMP system/manager INCTYPE=RESTORE FULL=Y FILE=X1

IMP system/manager INCTYPE=RESTORE FULL=Y FILE=C1

IMP system/manager INCTYPE=RESTORE FULL=Y FILE=C2

IMP system/manager INCTYPE=RESTORE FULL=Y FILE=I1

IMP system/manager INCTYPE=RESTORE FULL=Y FILE=I2

IMP system/manager INCTYPE=RESTORE FULL=Y FILE=I3

Notes:

•	You import the last incremental export file twice; once at the beginning to import the most recent version of the system objects, and once at the end to apply the most recent changes made to the user data and objects.

•	When restoring tables with this method, you should drop the tables from the database (if they exist) before starting the import sequence. This step prevents you from importing duplicate rows.


CHAPTER 3. EXPORT/IMPORT TIPS

This chapter offers helpful tips on making the best use of Export/Import. It covers a broad range of topics to widen your perspective and help you handle a variety of special situations.

The following topics are discussed:

•	importing into existing tables (page 3 - 2)

•	generating statistics on imported data (page 3 - 3)

•	exporting and importing LONGs (page 3 - 3)

•	dropping a tablespace (page 3 - 4)

•	reorganizing tablespaces (page 3 - 4)

•	retaining storage parameters (page 3 - 5)

•	reducing database fragmentation (page 3 - 5)

•	transferring read-only tablespaces (page 3 - 5)

•	network considerations (page 3 - 6)

•	NLS considerations (page 3 - 6)

•	using Oracle Server Release 6 export files (page 3 - 7)

•	creating Oracle Server Release 6 export files (page 3 - 10)

•	exporting and importing with the Trusted Oracle7 Server (page 3 - 12)

 ________________________________________

Importing Into Existing Tables

 Manually Creating Tables before Importing Data

When you choose to create tables manually before importing data into them from an export file, you should either use the same table definition as was previously used or a compatible format. For example, while you can increase the width of columns and change their order, you cannot add NOT NULL columns, change the names of columns, or change the datatype of a column to an incompatible datatype (LONG to NUMBER, for example).

 Disabling Referential Constraints

In the normal import order, constraints are imported only after all tables are imported. This sequence prevents the errors that could occur if a referential integrity constraint existed for data that has not yet been imported.

These errors can still occur when data is loaded into existing tables, however. For example, if table EMP has a referential integrity constraint on the MGR column that verifies the manager number exists in EMP, then a perfectly legitimate employee row might fail the referential integrity constraint if the manager's row has not yet been imported. When such an error occurs, Import generates an error message, bypasses the failed row, and continues importing other rows in the table.

Similarly, a referential check from table AEMP into table BDEPT using DEPTNO would cause rows to fail, because the tables are loaded in alphabetic order, and rows from AEMP would be loaded before the corresponding rows in BDEPT.

To prevent errors like these, it is a good idea to disable referential integrity constraints when importing data into existing tables.

 Manually Ordering the Import

When the constraints are re-enabled after importing, the entire table is checked, which may take a long time for a large table. If the time required for that check is too long, it may be beneficial to order the import manually.

To do so, do several imports from an export file instead of one. First, import tables that are the targets of referential checks, before importing the tables that reference them. Provided tables do not reference each other in circular fashion, and provided a table does not reference itself, this option works.

 ________________________________________

Generating Statistics on Imported Data

An export parameter controls the generation of database optimizer statistics during import. To get statistics, specify one of the following parameters on export:

STATISTICS=COMPUTE

STATISTICS=ESTIMATE

When one of these options is specified during the export, all database objects that have had ANALYZE applied to them are exported with the commands necessary to generate the appropriate statistics (estimated or computed) on import.

Note: Generation of statistics is limited to those objects that already had them before export. So statistics are not suddenly generated on every object in the database.

If your installation generally uses either estimated or computed statistics, then it is a good idea to include one of these commands whenever you use Export. The cost during export is negligible -- statistics are not recorded in the export file, only a command to generate them.

By issuing this command during export, you ensure that the appropriate statistics are gathered when the data is imported. If your export file was created without this command, or if you have changed your method of collecting statistics, then use Import's INDEXFILE option to generate a list of imported objects. Then edit that list to produce a series of ANALYZE commands on them. (For more information, see the INDEXFILE parameter).

 ________________________________________

Exporting and Importing LONGs

Warning: LONG columns can be up to 2 gigabytes in length. Because they can be exported in sections, Oracle LONGs are always exportable.

On import, however, LONGs require contiguous memory. Therefore, it is not always possible to export LONG columns from one operating system and import them on another system. Even on the same system, memory limitations may make it impossible to import very large LONG columns that were successfully exported on that system.

 ________________________________________

Dropping a Tablespace

You can drop a tablespace by doing a full database export, then creating a zero-block tablespace with the same name as the tablespace you want to drop. Upon import, the relevant CREATE TABLESPACE command fails, preventing creation of the unwanted tablespace. All objects from that tablespace are imported into their owner's default tablespaces.

 ________________________________________

Reorganizing Tablespaces

If a user's quotas allow it, the user's tables are imported into the same tablespace from which they were exported. However, if the tablespace no longer exists or the user does not have the needed quota, the system uses the default tablespace for that user. If the user is not able to use the default tablespace, then the user's tables are not imported. You can exploit this circumstance to move users' tables from one tablespace to another.

Suppose you want to move JOE's tables from tablespace A to tablespace B after a full database export. Follow these steps:

1.	If JOE has the UNLIMITED TABLESPACE privilege, revoke it. Set his quota on tablespace A to zero. Also revoke all roles that might have such privileges or quotas.

Note: Role revokes do not cascade, so users who were granted these roles by Joe are unaffected.

2.	Export JOE's tables.

3.	Drop JOE's tables from the database.

4.	Give JOE a quota on tablespace B and make it his default tablespace.

5.	Import JOE's tables. (By default, Import puts JOE's tables in tablespace B.)

Note: An index on the table is created in the same tablespace as the table itself, unless it already exists.

 ________________________________________

Retaining Storage Parameters

Export files do not include table storage parameters, So you may want to precreate large tables with the appropriate storage parameters before importing their data. In this case, you must answer Y to the prompt:

Ignore create errors due to object existence (Y/N): Y > Y

Alternatively, you can specify the following parameter on the command line:

IGNORE=Y

Note: The storage parameter OPTIMAL is not exported for rollback segments and is therefore not imported.

 ________________________________________

Reducing Database Fragmentation

A database with many small blocks of free space is said to be fragmented. A fragmented database should be reorganized to make space available in larger blocks. You can reduce database fragmentation by performing a full database export/import as follows:

1.	Do a full database export (FULL=Y) to back up the entire database.

2.	Use the MONITOR command in SQL*DBA or Server Manager to check for active database users and shut down Oracle when all users have logged off.

3.	Re-create the database using the CREATE DATABASE command.

4.	Do a full database import (FULL=Y) to restore the entire database.

See the Oracle7 Server Administrator's Guide for more information about creating databases.

 ________________________________________

Transferring Read-Only Tablespaces

Read-only tablespaces can be exported. On import, if the tablespace does not already exist in the target database; then the tablespace is created as a read/write tablespace. If read-only functionality is desired, you must make the tablespace read-only after the import.

If the tablespace already exists in the target database of an import and it is a read-only tablespace; then you must first declare it to be a read-write tablespace to import into it. When the import completes, you should return the tablespace to its read-only status.

 ________________________________________

Network Considerations

This section describes factors to take into account when using Export and Import across a network.

 Transporting Export Files Across a Network

When transferring an export file across a network, be sure to transmit the file using a protocol that preserves the integrity of the file. For example, using SQL*Net or FTP, transmit the file in binary mode. Transmitting export files in character mode causes errors when the file is imported.

 Exporting/Importing with SQL*Net

By eliminating the boundaries between different machines and operating systems on a network, SQL*Net provides a distributed processing environment for Oracle7 Server products. SQL*Net lets you export and import over a network.

For example, running Export locally, you can write data from a remote Oracle database into a local export file. Running Import locally, you can read data into a remote Oracle database.

To use Export or Import with SQL*Net, include the @ connect_string clause when entering the EXP or IMP command. For the exact syntax of this clause, see the user's guide for your SQL*Net protocol. For more information on SQL*Net, see Understanding SQL*Net.

 ________________________________________

NLS Considerations

This section describes behavior of Export and Import with respect to National Language Support (NLS).

 Export/Import and Single-Byte Character Sets

Some eight-bit characters can be "lost" when importing an eight-bit character set export file. This occurs if the client machine has a native seven-bit character set, or the NLS_LANG operating system environment parameter is set to a seven-bit character set. "Lost" implies that some eight-bit characters are converted to seven-bit equivalents. Typically, accented European characters lose their accent mark.

This problem occurs because the eight-bit characters in the export file are converted to seven-bit characters via the client application. When sent to the database, the seven-bit characters are converted by the server into eight-bit characters. To avoid this problem, it is necessary to turn off one of these conversions. One possibility is to set NLS_LANG to the character set of the export file data.

When importing an Oracle version 6 export file with a character set different than that of the native operating system or the setting for NLS_LANG, you need to set the CHARSET import parameter to indicate the character set of the export file data. The CHARSET parameter is described.

 Export/Import and Multi-Byte Character Sets

An export file that is produced with a multi-byte character set (for example, Chinese or Japanese) must be imported on a system that has a character set with the same character length. That is, the export character set and the import character set must have a 1:1 ratio.

 ________________________________________

Using Oracle Server Release 6 Export Files

This section describes the guidelines and restrictions that apply when importing data from a Release 6 database into the Oracle7 Server. Additional information may be found in the Oracle7 Server Migration Guide.

 CHAR columns

Release 6 CHAR columns are automatically converted into the Oracle VARCHAR2 datatype.

If you precreate tables from prepared scripts, then the CHAR columns are created as Oracle fixed-width columns instead of the desired VARCHAR2 (variable-width) columns. If you modify the scripts to create VARCHAR2 columns, however, the data types do not match those stored in the export file and the import fails.

Instead, set V6 compatibility mode before running the creation script so that variable-length columns are created instead of fixed-width columns. Then do the import with the database in V6 compatibility mode so that the column types match.

 LONG columns

Memory limitations may make it impossible to Import some LONG columns when the values contained in those columns are extremely long. Although Export can output LONG data in sections, Import requires contiguous memory.

 Syntax of Integrity Constraints

The SQL syntax for integrity constraints in Release 6 is different from the Oracle syntax. Import automatically adjusts the declaration so that integrity constraints are properly imported into Oracle, unless V6-compatibility mode is in effect.

 Status of Integrity Constraints

Release 6 integrity constraints are imported with the status recorded in the export file. In Release 6, all constraints other than NOT NULL are disabled, and that status is recorded in the export file. NOT NULL constraints imported into Oracle are either ENABLED or DISABLED, depending on the status recorded in the export file.

 Length of DEFAULT Column Values

A table with a default column value that is longer than the maximum size of that column generates the following error on import to Oracle7:

ORA-1401: inserted value too large for column

Release 6 of the Oracle Server did not check the columns in a CREATE TABLE statement to be sure they were long enough to hold their DEFAULT values so these tables could be imported into a Version 6 database. The Oracle7 Server does make this check, however. As a result, tables that could be imported into a Release 6 database may not import into Oracle7.

If the DEFAULT is a value returned by a function, then the column must be large enough to hold the maximum value that can be returned by that function. Otherwise, the CREATE TABLE statement recorded in the export file produces an error on import.

Note: The maximum value of the USER function increased in Oracle7, so columns with a default of USER may not be long enough in Oracle7. To determine the maximum size that the USER function will return, execute the following SQL command:

DESCRIBE user_sys_privs

The length shown for the USERNAME column is the maximum length returned by the USER function.

 ________________________________________

Using Oracle Server Release 5 Export Files

In V6 compatibility mode, Oracle Import reads export files created by Oracle 5.1.22 and later. The only way to do this is by precreating the tables in V6 compatibility mode from SQL*Plus. See the Oracle7 Server Migration Guide for the information on precreating tables.

 ________________________________________

Using Different Versions of Export

This section describes the general behavior and restrictions of running an Export version that is different from the Oracle7 Server.

 Using a Lower Level Export

In general, any lower-level Export utility may be run with a higher-level Oracle7 Server. For example, Export Release 6 can be used with the Oracle7 Server to create a Release 6 export file. (This procedure is described in the next section, "Creating Oracle Server Release 6 Export Files from Oracle7".)

Whenever a lower-level Export utility runs with a higher-level version of the Oracle Server, any categories of database objects that did not exist in the lower version are excluded from the export. For example, when running a Release 6 version of Export with the Oracle7 Server, snapshots (which did not exist in Release 6) are excluded from the export. (A complete list of objects excluded in this export is given in the next section.)

 Using a Higher Level Export

Attempting to use a higher-level version of Export with an Oracle7 Server often produces the following error:

EXP-37: Database export views not compatible with Export utility

EXP-0:  Export terminated unsuccessfully

The error occurs because views that the higher-level version of Export expects are not present. To avoid this problem, use the version of the Export utility that matches the Oracle7 Server.

 Change in Export File Format

In Release 7.1, the export file format was changed to accommodate stored procedures, functions, and packages that have comments embedded among the creation-statement keywords. As a result, these code objects (and triggers) exported from 7.1 cannot be imported into earlier releases, unless a patch is applied that makes earlier versions of Import and Export use the new export file format. All other objects can be imported normally, without the patch.

To export from a 7.0.16 database containing code objects with comments between the creation keywords, for example:

CREATE PROCEDURE /* comment */ FOO /* comment */ AS ...

or to export from a 7.0.12 or earlier 7.0 database that contains such code objects, or that contain code objects in which the above creation keywords spanned multiple lines; then the export can be made to succeed either by appropriately re-creating the code objects, or by applying a patch that makes earlier versions of Import and Export use the new export file format.

The following table summarizes the situations and solutions:

Exporting 	Objects Affected	Situation	Solution

From

------------------------------------------------------------------------

    7.0.12	procedures, func-	If the creation keywords for 	Apply the patch or

tions, packages, 	these objects are defined on 	change the definitions

package bodies	multiple lines, or if they have 	so that the creation

comments embedded among 	keywords are all one

the creation keywords, ex-	line to successfully ex-

port fails with a memory 	port these objects.

violation.

    7.0.16	procedures, func-	If these objects have com-	Apply the patch or

tions, packages, 	ments embedded among the 	change the definitions

package bodies	creation keywords, they can-	to remove the em-

not be imported from the ex-	bedded comments,

port file.	then re-export these

objects.

     7.1	triggers, proce-	These objects cannot be im-	Apply the patch to the

dures, functions, 	ported into a 7.0 release from 	earlier release in to

packages, package 	a 7.1 export file.	read the new export

bodies	file format or else put

the objects into the

proper format and use

a Release 7.0 export

on the 7.1 database.

Table 3 - 1.  Exports and Imports Affected by the Change in Export File Format

 ________________________________________

Creating Oracle Server Release 6 Export Files from Oracle7

It is possible to create a Release 6 export file from Oracle7 by running the Release 6 export executable with the Oracle7 Server. To do so, you must first run CATEXP6.SQL as SYS. This script creates the export views that make the database look to Export like a Release 6 database.

Note: A normal Oracle7 export requires CATEXP.SQL to be run by SYS after CATALOG.SQL to create the necessary views. If needed, both CATEXP.SQL and CATEXP6.SQL can be run, in any order. Once one of these scripts has been run, it does not have to be run again.

 Excluded Objects

The Release 6 export utility produces a Release 6 export file by issuing queries against the views created by CATEXP6.SQL. Because this file is Release-6 compatible, it excludes the following Oracle7 objects:

•	database triggers

•	hash clusters

•	job queues

•	profiles

•	refresh groups

•	replication catalog

•	roles

•	snapshots

•	snapshot logs

•	stored procedures, functions, and packages

•	system auditing options

•	tables stored in hash clusters

Suggestion: You can use the UTLEXP6.SQL script to obtain the names of all objects that are excluded from the export file. Review this script for the most up-to-date notes on conversion issues.

 Datatype Conversion

The Oracle7 VARCHAR2 datatype is automatically converted to its Release 6 equivalent CHAR. Fixed-length Oracle7 CHAR columns are also converted to variable-length Release 6 CHAR data.

 Database Link Names Truncated

Database link names in Oracle7 have the format name.d1.d2.d3..., where name is the database name, d1 is a domain specification, and d2..d3 are optional components in a domain name. In a Release 6 export, link names are truncated, leaving only the name component.

 VARCHAR Errors

Oracle7 character data (VARCHAR2) can be up to 2,000 characters long, whereas Release 6 CHAR data is limited to 255. The entire column is placed in the export file. The CREATE TABLE statement in the export file includes the actual length of the column, as it was defined in the Oracle7 database.

When Release 6 Import attempts to create the table, the specification of a CHAR column greater than 255 produces an error. One solution is to change the table's datatype to LONG, but be aware of the many restrictions on the Release 6 LONG datatype. See "Selecting a Datatype" in the Oracle7 Server Application Developer's Guide for details.

 LONG Errors

Oracle7 LONG data can be 2 gigabytes. Unlike VARCHAR data, Release 6 Export truncates LONG data when writing to the export file.

In Release 6.0.35.0 and later, Export truncates LONG data to 64K - 3 bytes and produces a warning message. Earlier releases truncate to 64K - 2 bytes, with no warning.

Warning:  When importing into a Release 6 database, such overly long data produces an error and causes the rest of the table data to be skipped.

 System Audit Options Dropped

Oracle7 object audit options on tables and views are automatically exported in their equivalent Release 6 form. However, the wide array of Oracle7 privileges makes it impossible to translate them into any Release 6 equivalent. As a result, system audit options are not exported. After Importing into Release 6, issue one or more of the following statements to re-establish system audits:

AUDIT DBA [WHENEVER [NOT] SUCCESSFUL]

AUDIT CONNECT [WHENEVER [NOT] SUCCESSFUL]

AUDIT NOT EXISTS

AUDIT ALL [WHENEVER [NOT] SUCCESSFUL]

 ________________________________________

Exporting and Importing with Trusted Oracle7 Server

The Trusted Oracle7 Server Administrator's Guide documents additional import and export options for Trusted Oracle7 Server. It also includes important guidelines for using Import and Export with Trusted Oracle7 Server. Be sure to refer to the Trusted Oracle7 Server Administrator's Guide before performing an import or export with Trusted Oracle7 Server.


CHAPTER 4. SQL*LOADER CONCEPTS AND FEATURES

This chapter explains the basic concepts of loading data into an Oracle database with SQL*Loader. After introducing SQL*Loader and describing its features, this chapter discusses the following subjects:

•	what is SQL*Loader? (a general introduction) (page 4 - 2)

•	direct path, conventional path, and bind array (page 4 - 3)

•	input you provide to SQL*Loader (page 4 - 3)

•	the log file SQL*Loader produces (page 4 - 7)

•	discarded and rejected records (page 4 - 8)

•	conditions for loading (page 4 - 7)

For a list of changes and enhancements to SQL*Loader in recent revisions, see Appendix A, "Changes in the Oracle7 Server Utilities".

 ________________________________________

What is SQL*Loader?

SQL*Loader is a product for moving data from external files into tables in an Oracle database. It has many features of the DB2 Load Utility from IBM. It also has several other features that add power and flexibility.

SQL*Loader loads data in a variety of formats, performs filtering (selectively loading records based upon the data values), and loads multiple tables simultaneously. During execution, SQL*Loader produces a detailed log file with statistics about the load. It may also produce a bad file (records rejected because of incorrect data) and a discard file (records that did not meet your selection criteria). You have control over several loading options.

SQL*Loader can do the following tasks:

•	load data from multiple datafiles of different file types

•	handle fixed-format, delimited-format, and variable-length records

•	manipulate data fields with SQL functions before inserting the data into database columns

•	support a wide range of datatypes, including DATE, BINARY, PACKED DECIMAL, and ZONED DECIMAL

•	load multiple tables during the same run, loading selected rows into each table

•	combine multiple physical records into a single logical record

•	treat a single physical record as multiple logical records

•	generate unique, sequential key values in specified columns

•	use your operating system's file or record management system to access datafiles

•	load data from disk or tape

•	provide thorough error reporting capabilities, so you can easily adjust and load all records

•	use control files acceptable to the IBM DB2 Load Utility, including those produced by the IBM DXT Utility

•	use high-performance "direct" loads to load data directly into database files without Oracle processing. This feature is discussed in Chapter 9, "SQL*Loader Direct Path Loads".

 ________________________________________

Direct Path, Conventional Path, and Bind Array

This section introduces the different ways that SQL*Loader uses to load data. These are the conventional path, which uses the bind array, and the direct path, which stores data directly into the database.

 Conventional Path

In the conventional path, multiple data records are read in and placed in a bind array. When the bind array is full (or there is no more data left to read), it is passed to Oracle for insertion. This path uses the Oracle SQL interface with the array option.

For more information on the conventional path, see the section "Overview of Data Paths". For information on the bind array, see the discussion of the ROWS parameter and the BINDSIZE parameter starting.

 Direct Path

In the direct path, data records are put into formatted database blocks and written directly to the database, bypassing most RDBMS processing.

This path is much faster than the conventional load, but entails several restrictions. For more information on the direct path, see the section "Overview of Data Paths".

 ________________________________________

Input to SQL*Loader

You must provide two types of input to SQL*Loader to load data from external files into an Oracle database: the data itself and control information describing how to perform the load.

Data to be loaded into the Oracle database must exist in files on disk or on tape. These datafiles require interpretation to be loaded by SQL*Loader. This information is found in the control file.

 The Control File

You must provide a file called the control file as an input to SQL*Loader. The control file tells SQL*Loader how to interpret the datafile. For example, it describes the following items:

•	the names of the datafiles

•	the format of the datafiles

•	the character sets used in the datafiles

•	the datatypes of the fields in those files

•	how to identify the start and end of data fields

•	which tables and columns to load

The control file's datatype specifications tell SQL*Loader how to interpret the fields in the datafiles. SQL*Loader uses this information when working with the fields and uses it to describe the data that is being passed to Oracle. Then Oracle converts the data into the datatype specified by the table definition.

Some information is mandatory, such as where to find the data and how it corresponds to the database tables. However, many options are also available to describe and manipulate the file data. For example, the instructions can include directions on how to format or filter the data, or to generate unique ID numbers.

Data and control information can be provided together in the same file, as shown in Case 1, or in separate files, as shown in Case 2. Detailed information on the contents of control files is contained in Chapter 6, "SQL*Loader Control File Reference".

SQL*Loader uses a data loading language that is upwardly compatible with the DB2 Load Utility from IBM. If you have a control file for the DB2 Load Utility, you can also use it with SQL*Loader. See Appendix C, "Notes for DB2/DXT Users" for differences in syntax.

 The Data

You may load data in various formats. It is usually read from one or more datafiles. However, the data may also be placed in the control file after the control file information.

 Binary versus Character Format Data

You can load numeric data in binary or character format. Binary format data is what is stored in the computer's memory. If you printed it to paper, you could not make sense of it, as you could with data in character format. Character format is also referred to as numeric external format.

Data in character formats can be included in both fixed-format and variable-format files. SQL*Loader cannot handle binary data in variable record format. Binary data is one example of the native datatypes -- datatypes that are implemented differently on different operating systems. For more information on these and other native datatypes, see "Native Datatypes". For more information on the character datatypes, see "Character Datatypes".

 Fixed versus Variable Format

Data records may be in fixed or variable format. In fixed format, the data is contained in records that all have the same (fixed) format. That is, the records have a fixed length, and the data fields in those records have fixed length, type, and position, as shown in Figure 4 - 1.

Figure 4 - 1. Fixed Format Records

In this example, columns 1 to 6 contain a character variable while columns 7 to 10 contain an integer for all the records. The fields are the same size in each record, regardless of the length of the data. The fields are fixed length, rather than variable length. In consequence, the record size is also fixed at 10 characters for each of the records.

In variable format (sometimes called stream format), each record is only as long as necessary to contain the data. Figure 4 - 2 shows variable length records containing two varying-length character fields.

Figure 4 - 2. Variable Format Records

In addition, the type of data in each record may vary. One record may contain a character string, the next may contain seven integers, the third may contain three decimals and a float, and so on. Operating systems use a record terminator character (such as newline) to mark where variable records end.

 Data Fields

Data in records is divided into fields. Fields can be specified with specific positions and lengths, or their position and length can vary based on delimiters.

There are two types of delimited fields: terminated and enclosed. Terminated fields are followed by a specified character (called a termination delimiter), such as the commas in the following example:

1,1,2,3,5,8,13

Enclosed fields are both preceded and followed by specified characters (called enclosure delimiters), such as the quotation marks in the following example:

"BUNKY"

Case 2 shows fixed-length records. Case 1 shows delimited fields. For more details on delimited data, see "Specifying Delimiters".

 Logical versus Physical Records

A final distinction concerns the difference between logical and physical records. A record or line in a file (either of fixed length or terminated) is referred to as a physical record. An operating-system-dependent file/record management system, such as DEC's Record Management System (RMS) or IBM's Sequential Access Method (SAM) returns physical records.

Logical records, on the other hand, correspond to a row in a database table. Sometimes the logical and physical records are equivalent. Such is the case when only a few short columns are being loaded. However, sometimes several physical records must be combined to make one logical record. For example, you could have a file containing 24 10-character columns in a format of 80-character, fixed-length records. In this case, three physical records would constitute a single logical record.

In SQL*Loader, you can compose logical records from multiple physical records using continuation fields. Physical records are combined into a single, logical record when some condition of the continuation field is true. You can specify that a logical record should be composed of multiple, physical records in the following ways:

•	A fixed number of physical records are concatenated to form a logical record (no continuation field is used).

•	Physical records are appended if the continuation field contains a specified string (or another test, such as "not equal", succeeds when applied to the continuation field).

•	Physical records are appended if they contain a specified character as their last non-blank character.

Case 4 uses continuation fields to form one logical record from multiple physical records.

 ________________________________________

SQL*Loader Log File

When SQL*Loader begins execution, it creates a log file. If it cannot create a log file, execution terminates. The log file contains a detailed summary of the load, including a description of any errors that occurred during the load. For details on the information contained in the log file, see Chapter 8, "SQL*Loader Log File Reference". All of the case studies in Chapter 5 also contain sample log files.

 ________________________________________

Conditions for Loading

To load data with a conventional load, the tables to receive the data must already exist in the database. There are no special requirements for these tables. The tables may be clustered or indexed, or they may actually be a view for which you have insert privileges. Tables may already contain data, or they may be empty.

 Privileges Required

The following privileges are required for a conventional load:

•	You must have INSERT privileges on the table to be loaded.

•	You must have DELETE privilege on the table to be loaded, when using the REPLACE option to empty out the table's old data before loading the new data in its place.

Additional privileges required for a direct load are discussed in Chapter 9, "SQL*Loader Direct Path Loads".

In addition to the above privileges, you must have write access to all labels you are loading data into a Trusted Oracle7 database. See the Trusted Oracle7 Server Administrator's Guide for more information.

 ________________________________________

Discarded and Rejected Records

Records that are read from the input file might not be inserted into the database. Figure 4 - 3 shows the stages at which records may be rejected or discarded.

Figure 4 - 3. Record Filtering

 The Bad File

The bad file contains records that are rejected, either by SQL*Loader or by Oracle. Some of the possible reasons for rejection are discussed in the next sections.

 SQL*Loader Rejects

Records are rejected by SQL*Loader when the input format is invalid. For example, if the second enclosure delimiter is missing, or if a delimited field exceeds its maximum length, SQL*Loader rejects the record. Rejected records are placed in the bad file. For details on how to specify the bad file, see "Specifying the Bad File".

 Oracle Rejects

After a record is accepted for processing by SQL*Loader, a row is sent to Oracle for insertion. If Oracle determines that the row is valid, then the row is inserted into the database. Otherwise, the record is rejected, and SQL*Loader puts it in the bad file. The row may be rejected, for example, because a key is not unique, because a required field is null, or because the field contains invalid data for the Oracle datatype.

The bad file is written in the same format as the datafile. So the rejected data can be loaded with the existing control file, after any necessary editing or correcting.

Case 4 shows an application that uses a bad file.

 SQL*Loader Discards

As SQL*Loader executes, it may create a file called the discard file. This file is created only when it is needed, and only if it is requested. The discard file contains records that were filtered out of the load because they did not match any of the record-selection criteria specified in the control file.

The discard file therefore contains records that were not inserted into any table, up to a specifiable maximum. If a record's data is written to any table, it is not written to the discard file.

The discard file is written in the same format as the datafile. The discard data can be loaded with the existing control file, after any necessary editing or correcting.

Case 4 shows how the discard file is used. For more details, see "Specifying the Discard File".

 ________________________________________

Data Conversion and Datatype Specification

Figure 4 - 4 shows the stages in which fields in the datafile are converted into columns in the database. The top of the diagram shows a data record containing one or more fields. The bottom shows the database column in which the data winds up. It is important to understand the intervening steps when using SQL*Loader.

This diagram depicts the "division of labor" between SQL*Loader and the Oracle Server. The field specifications tell SQL*Loader how to interpret the format of the datafile. The Oracle Server then converts that data and stores it into the database columns, using the column datatypes as a guide.

Attention: When reading about SQL*Loader, you need to keep in mind the distinction between a field (in a datafile) and a column (in the database).

It is also important to remember that the field datatypes defined in a SQL*Loader control file are not the same as the column datatypes defined in the control file.

SQL*Loader uses the field specifications in the control file to recognize data and creates a SQL row insert using that data. The row insert is then passed to the Oracle Server to be stored in the table. The Oracle Server uses the datatype of the column to convert the data into its final, stored form.

Figure 4 - 4. Field to Column Translation

In actuality, then, there are two conversion steps:

1.	SQL*Loader identifies a field in the datafile, interprets the data, and passes it to the Oracle Server.

2.	Oracle Server accepts the data and stores it in the database.

Knowing about these two steps can make it a lot easier to understand what the load is doing. Figure 4 - 5 shows a more concrete example.

Figure 4 - 5. Example of Field Conversion

In this example, two CHAR fields are defined for a data record. The field specifications are contained in the control file. Note that the control file CHAR specification is not the same as the database CHAR specification. A data field defined as CHAR in the control file merely tells SQL*Loader how to create the row insert. The data could then be inserted into a CHAR, VARCHAR2, or even a NUMBER column in the database, with the Oracle Server handling any necessary conversions.

By default, SQL*Loader removes trailing spaces from CHAR data before passing it to the database. So, in Figure 4 - 5, both field A and field B are passed to the database as three-column fields. When the data is inserted into the table, however, there is a difference.

Column A is defined in the database as a fixed-length CHAR column of length 5. So the data (XXX) is left justified in that column, which remains five characters wide. The extra space on the right is padded with blanks. Column B, however, is defined as a varying length field with a maximum length of five characters. The data for that column (YYY) is left-justified as well, but the length remains three characters.

The name of the field tells SQL*Loader what column to insert the data into. Because the first data field has been specified with the name "A" in the control file, SQL*Loader knows to insert the data into column A of the target database table.

 Summary

When thinking about how SQL*Loader loads data, it is helpful to keep the following points in mind:

•	The name of the data field corresponds to the name of the table column into which the data is loaded.

•	The datatype of the field tells SQL*Loader how to read the data in the datafile. It is not the same as the column datatype.

Or, in a nutshell:

•	The names are the same, but the datatypes are different.


CHAPTER 5. SQL*LOADER EXAMPLES

The case studies in this chapter illustrate some of the features of SQL*Loader. These case studies start simply and progress in complexity. A brief description of each case study follows:

Case 1:  Loads stream format records in which the fields are delimited by commas and may be enclosed by quotation marks. The data is found at the end of the control file (page 5 - 3).    Case 2:  Loads a datafile with fixed-length, fixed-format records (page 5 - 5).    Case 3:  Loads data from stream format records with delimited fields and sequence numbers. The data is found at the end of the control file (page 5 - 7).    Case 4:  Combines multiple physical records into one logical record corresponding to one database row (page 5 - 10).    Case 5:  Loads data into multiple tables in one run (page 5 - 14).    Case 6:  Loads data with the direct path option (page 5 - 19).    Case 7:  Extracts data from a formatted report (page 5 - 21).

________________________________________

Case Study Files

The distribution media for SQL*Loader contains files for each case:

•	control files (for example, ulcase1.ctl)

•	datafiles (for example, ulcase2.dat)

•	setup files (for example, ulcase3.sql)

If the sample data is contained in the control file, then the .DAT file does not exist. If no special setup steps are required, then the .SQL file may not exist. Starting (setup) and ending (cleanup) scripts are denoted by an S or E after the case number. The following files exist:

    CASE	   .CTL	   .DAT	   .SQL

     1	    ?	    ?

     2	    ?	    ?

     3	    ?	    ?

     4	    ?	    ?	    ?

     5	    ?	    ?	    ?

     6	    ?	    ?	    ?

     7	    ?	    ?	   S, E

Table 5 - 1.  Case Study Files

Additional Information:  For more information on the names of the case study files, consult your operating-system-specific Oracle7 documentation.

 ________________________________________

Tables Used in the Case Studies

These examples are based upon the standard Oracle demonstration database tables EMP and DEPT owned by SCOTT/TIGER. (In some of the case studies, additional columns have been added.)

CREATE TABLE emp

   (empno          NUMBER(4) NOT NULL,

   ename           VARCHAR2(10),

   job             VARCHAR2(9),

   mgr             NUMBER(4),

   hiredate        DATE,

   sal             NUMBER(7,2),

   comm            NUMBER(7,2),

   deptno          NUMBER(2))

CREATE TABLE dept

   (deptno         NUMBER(2) NOT NULL,

   dname           VARCHAR2(14),

   loc             VARCHAR2(13))

 ________________________________________

Case 1:  Loading Variable-Length Data

Case 1 demonstrates

•	a simple control file identifying one table and three columns to be loaded (page 6 - 4)

•	including data to be loaded from the control file itself, so there is no separate datafile (page 6 - 13)

•	loading data in stream format, with both types of delimited fields -- terminated and enclosed (page 6 - 67)

 Control File

In the following listing of the control file (ulcase1.ctl), the numbers on the left are not in the actual file; they are keyed to the comments following the control file. Do not use these numbers when you write a control file.

1)	LOAD DATA

2)	INFILE *

3)	INTO TABLE dept

4)	FIELDS TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"'

5)	(deptno, dname, loc)

6)	BEGINDATA

12,RESEARCH,"SARATOGA"

10,"ACCOUNTING",CLEVELAND

11,"ART",SALEM

13,FINANCE,"BOSTON"

21,"SALES",PHILA.

22,"SALES",ROCHESTER

42,"INT'L","SAN FRAN"

Notes:

1) The LOAD DATA statement is required at the beginning of the control file.

2) The data is found in the control file.

3) The INTO TABLE statement is required to identify the table to be loaded (DEPT). By default, SQL*Loader requires the table to be empty before it inserts any records.

4) Data is ended by commas, but may also be enclosed by quotation marks. Datatypes for all fields default to CHAR.

5) Names of columns to load are enclosed in parentheses.

6) Specifies the beginning of the data.

 Invoking SQL*Loader

To run this example, first prepare the database by using SQL*Plus or SQL*DBA to run ulcase1.sql. Then invoke SQL*Loader with a command such as:

sqlldr userid=scott/tiger control=ulcase1.ctl log=ulcase1.log

Executing SQL*Loader loads the DEPT table and creates the log file.

Additional Information:  The command "sqlldr" is a Unix-specific invocation. To invoke SQL*Loader on your operating system, refer to your operating-system-specific Oracle7 documentation.

 Log File

The log file follows. Numbers on the left correspond to notes following the file; they do not appear in the actual log file.

Control File:      ULCASE1.CTL

Data File:         *

  Bad File:        ULCASE1.BAD

  Discard File:     none specified

 (Allow all discards)

Number to load:    ALL

Number to skip:    0

Errors allowed:    50

Bind array:        64 rows, maximum of 65336 bytes

Continuation:       none specified

Path used:         Conventional

Table DEPT, loaded from every logical record.

Insert option in effect for this table: INSERT

Column Name    Position     Len      Term    Encl   Datatype

 ---------------   --------     ---      ----    ----   ---------

1)	DEPTNO            FIRST       *        ,     O(")   CHARACTER

 	DNAME              NEXT       *        ,     O(")   CHARACTER

2)	LOC                NEXT       *        ,     O(")   CHARACTER

Table DEPT:

7 Rows successfully loaded.

0 Rows not loaded due to data errors.

0 Rows not loaded because all WHEN clauses were failed.

0 Rows not loaded because all fields were null.

Space allocated for bind array:	49920 bytes(64 rows)

Space allocated for memory besides bind array: 76000 bytes

Total logical records skipped:           0

Total logical records read:              7

Total logical records rejected:          0

Total logical records discarded:         0

Notes:

1) Position and length for each field are determined for each record, based on delimiters in the input file.

2) WHT signifies that field LOC is terminated by WHITESPACE. The notation O(") signifies optional enclosure by quotation marks.

 ________________________________________

Case 2:  Loading Fixed-Format Records

Case 2 demonstrates

•	a separate datafile (page 6 - 14)

•	fixed-format data (page 6 - 67)

•	data conversions (page 6 - 47)

In this file, the field positions and datatypes are specified explicitly.

 Control File

In the following listing of the control file (ulcase2.ctl), the numbers on the left are not in the actual file; they are keyed to the comments following the control file. Do not use these numbers when you write a control file.

1)	LOAD DATA

2)	INFILE 'ulcase2.dat'

3)	INTO TABLE emp

4)	(empno         POSITION(01:04)  INTEGER EXTERNAL,

ename          POSITION(06:15)  CHAR,

job            POSITION(17:25)  CHAR,

mgr            POSITION(27:30)  INTEGER EXTERNAL,

sal            POSITION(32:39)  DECIMAL EXTERNAL,

comm           POSITION(41:48)  DECIMAL EXTERNAL,

5)	deptno         POSITION(50:51)  INTEGER EXTERNAL)

Notes:

1) The LOAD DATA statement is required at the beginning of the control file.

2) The name of the file containing data follows the keyword INFILE.

3) The INTO TABLE statement is required to identify the table to be loaded.

4) Lines between 4 and 5 identify a column name and the location of the data in the datafile to be loaded into that column. EMPNO, ENAME, JOB, and so on are names of columns in table EMP. The datatypes (INTEGER EXTERNAL, CHAR, DECIMAL EXTERNAL) identify the datatype of data fields in the file, not of corresponding columns in the EMP table.

5) Note that the set of column specifications is enclosed in parentheses.

 Datafile

Below are a few sample data lines from the file ulcase2.dat.

7782 CLARK      MANAGER   7839 2572.50           10

7839 KING       PRESIDENT      5500.00           10

7934 MILLER     CLERK     7782 920.00            10

7566 JONES      MANAGER   7839 3123.75           20

7499 ALLEN      SALESMAN  7698 1600.00   300.00  30

7654 MARTIN     SALESMAN  7698 1312.50  1400.00  30

7658 CHAN       ANALYST   7566 3450.00           20

Blank fields are set to null automatically.

 Invoking SQL*Loader

If you have not already done so, follow the instructions in CASE 1 (page 5 - 4) to run ulcase1.sql and populate the DEPT table. The EMP records loaded in this example contain department numbers. Unless the DEPT table is loaded first, referential integrity checking rejects these records (if referential integrity constraints are enabled for the EMP table).

Then invoke SQL*Loader with a command such as:

sqlldr userid=scott/tiger control=ulcase2.ctl log=ulcase2.log

Additional Information:  The command "sqlldr" is a Unix-specific invocation. To invoke SQL*Loader on your operating system, refer to your operating-system-specific Oracle7 documentation.

 Log File

A portion of the log file follows:

Control File:      ULCASE2.CTL

Data File:         ULCASE2.DAT

  Bad File:        ULCASE2.BAD

  Discard File:     none specified

 (Allow all discards)

Number to load:    ALL

Number to skip:    0

Errors allowed:    50

Bind array:        64 rows, maximum of 65336 bytes

Continuation:       none specified

Path used:         Conventional

Table EMP, loaded from every logical record.

Insert option in effect for this table: INSERT

  Column Name       Position       Len     Term    Encl   Datatype

-------------       ---------      ----    ----    ----   --------

  EMPNO                   1:4         4                  CHARACTER

  ENAME                  6:15        10                  CHARACTER

  JOB                   17:25         9                  CHARACTER

  MGR                   27:30         4                  CHARACTER

  SAL                   32:39         8                  CHARACTER

  COMM                  41:48         8                  CHARACTER

  DEPTNO                50:51         2                  CHARACTER

Table EMP:

7 Rows successfully loaded.

0 Rows not loaded due to data errors.

0 Rows not loaded because all WHEN clauses were failed.

0 Rows not loaded because all fields were null.

Space allocated for bind array                 4352 bytes(64 rows)

Space allocated for memory besides bind array: 37051 bytes

Total logical records skipped:                   0

Total logical records read:                      7

Total logical records rejected:                  0

Total logical records discarded:                 0

 ________________________________________

Case 3:  Loading a Delimited, Free-Format File

Case 3 demonstrates

•	loading data in (enclosed and terminated) stream format (page 6 - 67)

•	loading dates (page 6 - 54)

•	using the SEQUENCE function to generate unique keys for loaded data (page 6 - 45)

•	using APPEND to indicate that the table need not be empty before inserting new records (page 6 - 23)

•	using comments in the control file set off by double dashes (page 6 - 9)

•	overriding general specifications with declarations for individual fields (page 6 - 31)

 Control File

This control file loads the same table as Case 2, but it loads three additional columns (HIREDATE, PROJNO, LOADSEQ). The demonstration table EMP does not have columns PROJNO and LOADSEQ. So if you want to test this control file, add these columns to the EMP table with the command:

ALTER TABLE EMP ADD (PROJNO NUMBER, LOADSEQ NUMBER)

The data is in a different format than in Case 2. Some data is enclosed in quotation marks, some is set off by commas, and the values for DEPTNO and PROJNO are separated by a colon.

In the following listing of the control file, the numbers on the left are not in the actual file; they are keyed to the comments following the control file. Do not use these numbers when you write a control file.

1)	-- Variable-length, delimited and enclosed data format

LOAD DATA

2)	INFILE *

3)	APPEND

INTO TABLE emp

4)	FIELDS TERMINATED BY "," OPTIONALLY ENCLOSED BY '"'

(empno, ename, job, mgr,

5)	hiredate DATE(20) "DD-Month-YYYY",

sal, comm, deptno CHAR TERMINATED BY ':',

projno,

6)	loadseq  SEQUENCE(MAX,1))

7)	BEGINDATA

8)	7782, "Clark", "Manager", 7839, 09-June-1981, 2572.50,,  10:101

7839, "King", "President", , 17-November-1981,5500.00,,10:102

7934, "Miller", "Clerk", 7782, 23-January-1982, 920.00,, 10:102

7566, "Jones", "Manager", 7839, 02-April-1981, 3123.75,, 20:101

7499, "Allen", "Salesman", 7698, 20-February-1981, 1600.00,

(same line continued)                 300.00, 30:103

7654, "Martin", "Salesman", 7698, 28-September-1981, 1312.50,

(same line continued)                1400.00, 3:103

7658, "Chan", "Analyst", 7566, 03-May-1982, 3450,,  20:101

Notes:

1) Comments may appear anywhere in the command lines of the file, but they should not appear in data. They are preceded with a double dash that may appear anywhere on a line.

2) Signifies that the data is found at the end of the control file.

3) Indicates that data may be loaded even if the table already contains rows. The table need not be empty.

4) The default terminator for the data fields is a comma, and some fields may be enclosed by double quotation marks (").

5) The data to be loaded into column HIREDATE appears in the format DD-Month-YYYY.

6) The SEQUENCE function generates a unique value in the column LOADSEQ. This function finds the current maximum value in column LOADSEQ and adds the increment (1) to it to obtain the value for LOADSEQ for each row inserted.

7) Signifies the end of the control information and the beginning of the data.

8) Although each physical record equals one logical record, the fields vary in length so that some records are longer than others. Note also that several rows have null values for COMM.

 Invoking SQL*Loader

To run this example, first prepare the database by running ulcase3.sql. Then invoke SQL*Loader with a command such as:

sqlldr userid=scott/tiger control=ulcase3.ctl log=ulcase3.log

Additional Information:  The command "sqlldr" is a Unix-specific invocation. To invoke SQL*Loader on your operating system, see your operating system-specific Oracle7 documentation.

 Log File

A portion of the log file follows:

Control File:      ULCASE3.CTL

Data File:         *

  Bad File:        ULCASE3.BAD

  Discard File:     none specified

 (Allow all discards)

Number to load:    ALL

Number to skip:    0

Errors allowed:    50

Bind array:        64 rows, maximum of 65336 bytes

Continuation:       none specified

Path used:         Conventional

Table EMP, loaded from every logical record.

Insert option in effect for this table: APPEND

Column Name     Position   Len   Term   Encl   Datatype

-------------   --------   ---   ----   ----   ----------

EMPNO           FIRST      *     ,      O(")   CHARACTER

ENAME           NEXT       *     ,      O(")   CHARACTER

JOB             NEXT       *     ,      O(")   CHARACTER

MGR             NEXT       *     ,      O(")   CHARACTER

HIREDATE        NEXT       20    ,      O(")   DATE DD-Month-YYYY

SAL             NEXT       *     ,      O(")   CHARACTER

COMM            NEXT       *     ,      O(")   CHARACTER

DEPTNO          NEXT       *     :      O(")   CHARACTER

PROJNO          NEXT       *     ,      O(")   CHARACTER

LOADSEQ      SEQUENCE (MAX, 1)

Table EMP:

7 Rows successfully loaded.

0 Rows not loaded due to data errors.

0 Rows not loaded because all WHEN clauses were failed.

0 Rows not loaded because all fields were null.

Space allocated for bind array:               63810 bytes(30 rows)

Space allocated for memory besides bind array: 94391 bytes

Total logical records skipped:           0

Total logical records read:              7

Total logical records rejected:          0

Total logical records discarded:         0

 ________________________________________

Case 4:  Loading Combined Physical Records

Case 4 demonstrates

•	combining multiple physical records to form one logical record with CONTINUEIF (page 6 - 27)

•	inserting negative numbers

•	indicating with REPLACE that the table should be emptied before the new data is inserted (page 6 - 23)

•	specifying a discard file in the control file using DISCARDFILE (page 6 - 19)

•	specifying a maximum number of discards using DISCARDMAX (page 6 - 21)

•	rejecting records due to duplicate values in a unique index or due to invalid data values (page 6 - 18)

 Control File

In the following listing of the control file (ulcase4.ctl), the numbers on the left are not in the actual file; they are keyed to the comments following the control file. Do not use these numbers when you write a control file.

LOAD DATA

INFILE 'ulcase4.dat'

1)	DISCARDFILE 'ulcase4.dsc'

2)	DISCARDMAX 999

3)	REPLACE

4)	CONTINUEIF THIS (1) = '*'

INTO TABLE emp

(empno         POSITION(1:4)         INTEGER EXTERNAL,

ename          POSITION(6:15)        CHAR,

job            POSITION(17:25)       CHAR,

mgr            POSITION(27:30)       INTEGER EXTERNAL,

sal            POSITION(32:39)       DECIMAL EXTERNAL,

comm           POSITION(41:48)       DECIMAL EXTERNAL,

deptno         POSITION(50:51)       INTEGER EXTERNAL,

hiredate       POSITION(52:60)       INTEGER EXTERNAL)

Notes:

1) Specifies a discard file named "ulcase4.dsc".

2) Specifies a maximum of 999 discards allowed before terminating the run (for practical purposes, allows all discards).

3) Specifies that if there is data in the table being loaded, then SQL*Loader should delete that data before loading new data.

4) Specifies that if an asterisk is found in column 1 of the current record, then the next physical record after that record should be appended to it to form the logical record. Note that column 1 in each physical record should then contain either an asterisk or a non-data value.

 Datafile

The datafile, ulcase4.dat, follows. Note the asterisks in the first position and, though not visible, a new line indicator is in position 20 (following "MA", "PR", and so on). Note that CLARK's commission is -10, and SQL*Loader loads the value converting it to a negative number.

 Rejected Records

The last two records are rejected, given two assumptions. If there is a unique index created on column EMPNO, then the record for CHIN will be rejected because his EMPNO is identical to CHAN's. If EMPNO is defined as NOT NULL, then CHEN's record will be rejected because it has no value for EMPNO.

*7782 CLARK      MA

 NAGER   7839 2572.50    -10    2512-NOV-85

*7839 KING       PR

 ESIDENT      5500.00           2505-APR-83

*7934 MILLER     CL

 ERK     7782 920.00            2508-MAY-80

*7566 JONES	      MA

 NAGER   7839 3123.75           2517-JUL-85

*7499 ALLEN	      SA

 LESMAN  7698 1600.00   300.00  25 3-JUN-84

*7654 MARTIN     SA

 LESMAN  7698 1312.50  1400.00  2521-DEC-85

*7658 CHAN       AN

 ALYST   7566 3450.00           2516-FEB-84

*     CHEN       AN

 ALYST   7566 3450.00           2516-FEB-84

*7658 CHIN       AN

 ALYST   7566 3450.00           2516-FEB-84

 Invoking SQL*Loader

To run this example, first prepare the database by using SQL*Plus or SQL*DBA to run ulcase4.sql. Then invoke SQL*Loader with a command such as:

sqlldr userid=scott/tiger control=ulcase4.ctl log=ulcase4.log

Additional Information:  The command "sqlldr" is a Unix-specific invocation. To invoke SQL*Loader on your operating system, see your operating system-specific Oracle7 documentation.

 Log File

The log file follows:

Control File:     ULCASE4.CTL

Data File:        ULCASE4.DAT

  Bad File:       ULCASE4.BAD

  Discard File:   ULCASE4.DSC

 (Allow 999 discards)

Number to load:   ALL

Number to skip:   0

Errors allowed:   50

Bind array:       64 rows, maximum of 65336 bytes

 Continuation:    1:1 = 0X2a(character '*'),

                  in current physical record

Path used:        Conventional

Table EMP, loaded from every logical record.

Insert option in effect for this table: REPLACE

   Column Name    Position        Len     Term   Encl   Datatype

 -------------    --------        ---     ----   -----  ----------

   EMPNO               1:4          4                   CHARACTER

   ENAME              6:15         10                   CHARACTER

   JOB               17:25          9                   CHARACTER

   MGR               27:30          4                   CHARACTER

   SAL               32:39          8                   CHARACTER

   COMM              41:48          8                   CHARACTER

   DEPTNO            50:51          2                   CHARACTER

   HIREDATE          52:60          9                   CHARACTER

Rejected logical records and errors:

Data File ULCASE4.DAT -

Record 8: Rejected - Error on table EMP,        --EMPNO null

ORA-01400: mandatory (NOT NULL) column is missing or NULL during

           insert

Record 9: Rejected - Error on table EMP.        --EMPNO not unique

ORA-00001: unique constraint (SCOTT.SYS_C00328) violated

Table EMP:

    7 Rows successfully loaded.

    2 Rows not loaded due to data errors.

    0 Rows not loaded because all WHEN clauses were failed.

    0 Rows not loaded because all fields were null.

Space allocated for bind array:                5120 bytes(64 rows)

Space allocated for memory besides bind array: 40195 bytes

Total logical records skipped:           0

Total logical records read:              9

Total logical records rejected:          2

Total logical records discarded:         0

 Bad File

The bad file, shown below, lists records 8 and 9. (The discard file is not created.)

*     CHEN         ANALYST

      7566         3450.00           2516-FEB-84

*     CHIN         ANALYST

      7566         3450.00           2516-FEB-84

 ________________________________________

Case 5:  Loading Data into Multiple Tables

Case 5 demonstrates

•	loading multiple tables (page 6 - 42)

•	using SQL*Loader to break down repeating groups in a flat file and load the data into normalized tables -- one file record may generate multiple database rows

•	deriving multiple logical records from each physical record (page 6 - 40)

•	using a WHEN clause (page 6 - 31)

•	loading the same field (empno) into multiple tables

 Control File

In the following listing of the control file, the numbers on the left are not in the actual file; they are keyed to the comments following the control file. Do not use these numbers when you write a control file.

-- Loads EMP records from first 23 characters

-- Creates and loads PROJ records for each PROJNO listed

-- for each employee

LOAD DATA

INFILE 'ulcase5.dat'

BADFILE 'ulcase5.bad'

DISCARDFILE 'ulcase5.dsc'

1)	REPLACE

2)	INTO TABLE emp

(empno   POSITION(1:4)     INTEGER EXTERNAL,

ename    POSITION(6:15)    CHAR,

deptno   POSITION(17:18)   CHAR,

mgr      POSITION(20:23)   INTEGER EXTERNAL)

2)	INTO TABLE proj

-- PROJ has two columns, both not null: EMPNO and PROJNO

3)	WHEN projno != '   '

(empno   POSITION(1:4)     INTEGER EXTERNAL,

3)	projno   POSITION(25:27)   INTEGER EXTERNAL)   -- 1st proj

3)	INTO TABLE proj

4)	WHEN projno != '   '

(empno   POSITION(1:4)     INTEGER EXTERNAL,

4)	projno   POSITION(29:31    INTEGER EXTERNAL)   -- 2nd proj

2)	INTO TABLE proj

5)	WHEN projno != '   '

(empno   POSITION(1:4)    INTEGER EXTERNAL,

5)	projno   POSITION(33:35)  INTEGER EXTERNAL)   -- 3rd proj

Notes:

1) If there is data in the tables to be loaded (EMP and PROJ), then this specification tells SQL*loader to delete the data before loading new rows.

2) Multiple INTO clauses load two tables, EMP and PROJ. The same set of records is processed three times, using different combinations of columns each time to load table PROJ.

3) WHEN loads only rows with non-blank project numbers. When PROJNO is defined as columns 25..27, rows are inserted into PROJ only if there is a value in those columns.

4) When PROJNO is defined as columns 29..31, rows are inserted into PROJ only if there is a value in those columns.

5) When PROJNO is defined as columns 33..35, rows are inserted into PROJ only if there is a value in those columns.

 Datafile

The datafile for Case 5 follows:

1234 BAKER      10 9999 101 102 103

1234 JOKER      10 9999 777 888 999

2664 YOUNG      20 2893 425 abc 102

5321 OTOOLE     10 9999 321  55  40

2134 FARMER     20 4555 236 456

2414 LITTLE     20 5634 236 456  40

6542 LEE        10 4532 102 321  14

2849 EDDS       xx 4555     294  40

4532 PERKINS    10 9999  40

1244 HUNT       11 3452 665 133 456

123  DOOLITTLE  12 9940         132

1453 MACDONALD  25 5532     200

 Invoking SQL*Loader

To run this example, first prepare the database by using SQL*Plus or SQL*DBA to run ulcase5.sql. Then invoke SQL*Loader with a command such as:

sqlldr userid=scott/tiger control=ulcase5.ctl log=ulcase5.log

Additional Information:  The command "sqlldr" is a Unix-specific invocation. To invoke SQL*Loader on your operating system, see your operating system-specific Oracle7 documentation.

 Log File

The log file for Case 5 follows:

Control File:     ULCASE5.CTL

Data File:        ULCASE5.DAT

  Bad File:       ULCASE5.BAD

  Discard File:   ULCASE5.DSC

 (Allow all discards)

Number to load:   ALL

Number to skip:   0

Errors allowed:   50

Bind array:       64 rows, maximum of 65336 bytes

Continuation:      none specified

Path used:        Conventional

Table EMP, loaded from every logical record.

Insert option in effect for this table: REPLACE

Column Name        Position       Len    Term    Encl   Datatype

-------------      ---------      ---    ----    ----   ----------

EMPNO                    1:4        4                   CHARACTER

ENAME                   6:15       10                   CHARACTER

DEPTNO                 17:18        2                   CHARACTER

MGR                    20:23        4                   CHARACTER

Table PROJ, loaded when PROJNO != 0x202020(character '   ')

Insert option in effect for this table: REPLACE

Column Name        Position       Len    Term    Encl   Datatype

-----------        ---------      ---    ----    ----   ----------

EMPNO                    1:4        4                   CHARACTER

PROJNO                 25:27        3                   CHARACTER

Table PROJ, loaded when PROJNO != 0x202020(character '   ')

Insert option in effect for this table: REPLACE

Column Name        Position       Len    Term    Encl   Datatype

-----------        ---------      ---    ----    ----   ----------

EMPNO                    1:4        4                   CHARACTER

PROJNO                 29:31        3                   CHARACTER

Table PROJ, loaded when PROJNO != 0x202020(character '   ')

Insert option in effect for this table: REPLACE

Column Name        Position       Len    Term    Encl   Datatype

------------       ---------      ---    ----    ----   ----------

EMPNO                    1:4        4                   CHARACTER

PROJNO                 33:35        3                   CHARACTER

Rejected records and errors:

1)	Record 2: Rejected - Error on table EMP, column DEPTNO.

1)	ORA-00001: unique constraint (SCOTT.C000328) violated

1)	ORA-01722: invalid number

1)	Record 8: Rejected - Error on table EMP, column DEPTNO.

1)	ORA-01722: invalid number

1)	Record 3: Rejected - Error on table PROJ, column PROJNO.

1)	ORA-01722: invalid number

Table EMP:

2)	   9 Rows successfully loaded.

2)	   3 Rows not loaded due to data errors.

2)	   0 Rows not loaded because all WHEN clauses were failed.

2)	   0 Rows not loaded because all fields were null.

Table PROJ:

3)	   7 Rows successfully loaded.

3)	   2 Rows not loaded due to data errors.

3)	   3 Rows not loaded because all WHEN clauses were failed.

3)	   0 Rows not loaded because all fields were null.

Table PROJ:

4)	   7 Rows successfully loaded.

4)	   3 Rows not loaded due to data errors.

4)	   2 Rows not loaded because all WHEN clauses were failed.

4)	   0 Rows not loaded because all fields were null.

Table PROJ:

5)	   6 Rows successfully loaded.

5)	   3 Rows not loaded due to data errors.

5)	   3 Rows not loaded because all WHEN clauses were failed.

5)	   0 Rows not loaded because all fields were null.

Space allocated for bind array:               5120 bytes (64 rows)

Space allocated for memory besides bind array:  46763 bytes

Total logical records skipped:      0

Total logical records read:        12

Total logical records rejected:     3

Total logical records discarded:    0

Notes:

1) Errors are not encountered in the same order as the physical records due to buffering (array batch). The bad file and discard file contain records in the same order as they appear in the log file.

2) Of the 12 logical records for input, three rows were rejected (rows for JOKER, YOUNG, and EDDS). No data was loaded for any of the rejected records.

3) Nine records met the WHEN clause criteria, and two (JOKER and YOUNG) were rejected due to data errors.

4) Ten records met the WHEN clause criteria, and three (JOKER, YOUNG, and EDDS) were rejected due to data errors.

5) Nine records met the WHEN clause criteria, and three (JOKER, YOUNG, and EDDS) were rejected due to data errors.

 Loaded Tables

The results of this execution of SQL*Loader follow:

SQL> SELECT empno, ename, mgr, deptno FROM emp;

EMPNO      ENAME           MGR           DEPTNO

------     ------          ------        ------

1234       BAKER           9999          10

5321       OTOOLE          9999          10

2134       FARMER          4555          20

2414       LITTLE          5634          20

6542       LEE             4532          10

4532       PERKINS         9999          10

1244       HUNT            3452          11

123        DOOLITTLE       9940          12

1453       MACDONALD       5532          25

SQL> SELECT * from PROJ order by EMPNO;

EMPNO              PROJNO

------             ------

123                132

1234               101

1234               103

1234               102

1244               665

1244               456

1244               133

1453               200

2134               236

2134               456

2414               236

2414               456

2414               40

4532               40

5321               321

5321               40

5321               55

6542               102

6542               14

6542               321

 ________________________________________

Case 6:  Loading with the Direct Path

This example loads the EMP table using the direct path and concurrently builds all indexes. It illustrates the following functions:

•	use of the direct path to load and index data (Chapter 9)

•	how to specify the indexes for which the data is presorted (page 9 - 14)

•	loading all-blank numeric fields as null (page 6 - 66)

•	the NULLIF clause (page 6 - 66)

Note: Specify the name of the table where you wish to load data; otherwise, you will see LDR-927. Specifying DIRECT=TRUE as a command-line parameter is not an option when loading into a synonym for a table.

 Control File

In this example, the field positions and datatypes are specified explicitly. In the following listing, the numbers on the left are not in the actual file; they correspond to the comments following the control file listing.

LOAD DATA

INFILE 'ulcase6.dat'

INSERT

INTO TABLE emp

1)	SORTED INDEXES (empix)

2)	(empno POSITION(01:04) INTEGER EXTERNAL NULLIF empno=BLANKS,

ename  POSITION(06:15) CHAR,

job    POSITION(17:25) CHAR,

mgr    POSITION(27:30) INTEGER EXTERNAL NULLIF mgr=BLANKS,

sal    POSITION(32:39) DECIMAL EXTERNAL NULLIF sal=BLANKS,

comm   POSITION(41:48) DECIMAL EXTERNAL NULLIF comm=BLANKS,

deptno POSITION(50:51) INTEGER EXTERNAL NULLIF deptno=BLANKS)

Notes:

1) The SORTED INDEXES clause identifies the indexes on which the data is sorted. This clause indicates that the datafile is sorted on the columns in the EMPIX index. This clause allows SQL*Loader to optimize index creation by eliminating the sort phase for this data when using the direct path.

2) The NULLIF...BLANKS clause specifies that the column should be loaded as NULL if the field in the datafile consists of all blanks. Refer to "Loading All-Blank Fields" for more information.

 Invoking SQL*Loader

To run this example, first prepare the database by using SQL*Plus or SQL*DBA to run ulcase6.sql. Then invoke SQL*Loader with a command such as:

sqlldr scott/tiger ulcase6.ctl log=ulcase6.log direct=true

Additional Information:  The command "sqlldr" is a Unix-specific invocation. To invoke SQL*Loader on your operating system, see your operating system-specific Oracle7 documentation.

 Log File

The log file for Case 6 follows:

Control File:   	'ULCASE6.CTL'

Data File:      	'ULCASE6.DAT'

  Bad File:     	'ULCASE6.BAD'

  Discard File:	 none specified

 (Allow all discards)

Number to load: ALL

Number to skip: 0

Errors allowed: 50

Continuation:    none specified

Path used:      Direct

Table EMP, loaded from every logical record.

Insert option in effect for this table: REPLACE

  Column Name              Position  Len  Term  Encl  Datatype

------------------------  --------- ----- ----  ----  --------

  EMPNO                        1:4      4             CHARACTER

  ENAME                       6:15     10             CHARACTER

  JOB                        17:25      9             CHARACTER

  MGR                        27:30      4             CHARACTER

  SAL                        32:39      8             CHARACTER

  COMM                       41:48      8             CHARACTER

  DEPTNO                     50:51      2             CHARACTER

Column EMPNO is NULL if EMPNO = BLANKS

Column MGR is NULL if MGR = BLANKS

Column SAL is NULL if SAL = BLANKS

Column COMM is NULL if COMM = BLANKS

Column DEPTNO is NULL if DEPTNO = BLANKS

The following index(es) on table EMP were processed:

Index EMPIX was loaded.

Table EMP:

7 Rows successfully loaded.

0 Rows not loaded due to data errors.

0 Rows not loaded because all WHEN clauses were failed.

0 Rows not loaded because all fields were null.

Bind array size not used in direct path.

Space allocated for memory besides bind array:        164342 bytes

Total logical records skipped:          0

Total logical records read:             7

Total logical records rejected:         0

Total logical records discarded:        0

 ________________________________________

Case 7:  Extracting Data from a Formatted Report

In this example, SQL*Loader's string processing functions extract data from a formatted report. It illustrates the following functions:

•	using SQL*Loader with an INSERT trigger (see Chapter 8, "Using Database Triggers", in the Oracle7 Server Application Developer's Guide)

•	use of the SQL string to manipulate data (page 6 - 73)

•	different initial and trailing delimiters (page 6 - 58)

•	use of SYSDATE (page 6 - 44)

•	use of the TRAILING NULLCOLS clause (page 6 - 33)

•	ambiguous field length warnings (pages 6 - 53 and 6 - 58)

Note: This example creates a trigger that uses the last value of unspecified fields.

 Datafile

The following listing of the report shows the data to be loaded:

         Today's Newly Hired Employees

Dept  Job       Manager   MgrNo Emp Name   EmpNo  Salary    (Comm)

----  --------  --------  -----  --------  -----  --------- ------

20    Salesman  Blake     7698  Shepard    8061   $1,600.00 (3%)

                                Falstaff   8066   $1,250.00 (5%)

                                Major      8064   $1,250.00 (14%)

30    Clerk     Scott     7788  Conrad     8062   $1,100.00

                Ford      7369  DeSilva    8063     $800.00

      Manager   King      7839  Provo      8065   $2,975.00

 Insert Trigger

A BEFORE INSERT trigger is needed with this example to fill in department number, job name, and manager's number when these fields are not present on a data line. When values are present, they should be saved in a global variable. When values are not present, the global variables are used.

Here is the INSERT trigger and the package defining the global variables:

CREATE OR REPLACE PACKAGE uldemo7 AS   -- Global Package Variables

    last_deptno   NUMBER(2);

    last_job      VARCHAR2(9);

    last_mgr      NUMBER(4);

    END uldemo7;

/

CREATE OR REPLACE TRIGGER uldemo7_emp_insert

  BEFORE INSERT ON emp

  FOR EACH ROW

BEGIN

  IF :new.deptno IS NOT NULL THEN

     uldemo7.last_deptno := :new.deptno;  -- save value for later

  ELSE

     :new.deptno := uldemo7.last_deptno;  -- use last valid value

  END IF;

  IF :new.job IS NOT NULL THEN

     uldemo7.last_job := :new.job;

  ELSE

     :new.job := uldemo7.last_job;

  END IF;

  IF :new.mgr IS NOT NULL THEN

     uldemo7.last_mgr := :new.mgr;

  ELSE

     :new.mgr := uldemo7.last_mgr;

  END IF;

END;

/

Note: The phrase FOR EACH ROW is important. Otherwise, because SQL*Loader uses the array interface, the INSERT trigger would only fire once for each array of inserts.

To clean up after running this example, remove the trigger and package definition with the following commands:

DROP PACKAGE uldemo7;

DROP TRIGGER uldemo7_emp_insert;

 Control File

In the following listing, the numbers on the left are not in the actual file; they correspond to the comments following the control file listing:

LOAD DATA

INFILE 'ULCASE7.DAT'

APPEND

INTO TABLE emp

1)	  WHEN (57) = '.'

2)	TRAILING NULLCOLS

3)	(hiredate SYSDATE,

4)	   deptno POSITION(1:2)  INTEGER EXTERNAL(3)

5)	          NULLIF deptno=BLANKS,

   job    POSITION(7:14)  CHAR  TERMINATED BY WHITESPACE

6)	          NULLIF job=BLANKS  "UPPER(:job)",

7)	   mgr    POSITION(28:31) INTEGER EXTERNAL

          TERMINATED BY WHITESPACE, NULLIF mgr=BLANKS,

   ename  POSITION(34:41) CHAR

          TERMINATED BY WHITESPACE  "UPPER(:ename)",

   empno  POSITION(45) INTEGER EXTERNAL

          TERMINATED BY WHITESPACE,

   sal    POSITION(51) CHAR  TERMINATED BY WHITESPACE

8)	          "TO_NUMBER(:sal,'$99,999.99')",

9)	   comm   INTEGER EXTERNAL  ENCLOSED BY '(' AND '%'

          ":comm * 100"

)

Notes:

1) The decimal point in column 57 (the salary field) identifies a line with data on it. All other lines in the report are discarded.

2) The TRAILING NULLCOLS clause causes SQL*Loader to treat any fields that are missing at the end of a record as null. Because the commission field is not present for every record, this clause says to load a null commission instead of rejecting the record when only six fields are found instead of the expected seven.

3) Employee's hire date is filled in using the current system date.

4) This specification generates a warning message because the specified length does not agree with the length determined by the field's position. The specified length (3) is used.

5) Because the report only shows department number, job, and manager when the value changes, these fields may be blank. This control file causes them to be loaded as null, and an RDBMS insert trigger fills in the last valid value.

6) The SQL string changes the job name to uppercase letters.

7) It is necessary to specify starting position here. If the job field and the manager field were both blank, then the job field's TERMINATED BY BLANKS clause would cause SQL*Loader to scan forward to the employee name field. Without the POSITION clause, the employee name field would be mistakenly interpreted as the manager field.

8) Here, the SQL string is translates the field from a formatted character string into a number. The numeric value takes less space and can be printed with a variety of formatting options.

9) In this case, different initial and trailing delimiters pick the numeric value out of a formatted field. The SQL string is then converts the value to its stored form.

 Invoking SQL*Loader

To run this example, first prepare the database by using SQL*Plus or SQL*DBA to run ulcase7s.sql. Then invoke SQL*Loader with a command such as:

sqlldr scott/tiger ulcase7.ctl ulcase7.log

Additional Information:  The command "sqlldr" is a Unix-specific invocation. To invoke SQL*Loader on your operating system, see your operating system-specific Oracle7 documentation.

After running the example, use ulcase7e.sql to drop the insert trigger and global-variable package.

 Log File

The log file for Case 7 follows:

1) SQL*Loader-307: Warning: conflicting lengths 2 and 3 specified

   for column EMP.DEPTNO.

   Control File:   ulcase7.ctl

   Data File:      ulcase7.dat

     Bad File:     ulcase7.bad

     Discard File:  none specified

    (Allow all discards)

   Number to load: ALL

   Number to skip: 0

   Errors allowed: 50

   Bind array:     64 rows, maximum of 65536 bytes

   Continuation:    none specified

   Path used:      Conventional

   Table EMP, loaded when 57:57 = 0X2e(character '.')

   Insert option in effect for this table: APPEND

   TRAILING NULLCOLS option in effect

   Column Name          Position   Len  Term Encl Datatype

   ------------------- ---------- ----- ---- ---- -----------

   DEPTNO                    1:2      3           CHARACTER

   JOB                       7:14     8  WHT      CHARACTER

   MGR                      28:31     4  WHT      CHARACTER

   ENAME                    34:41     8  WHT      CHARACTER

   EMPNO                     NEXT     *  WHT      CHARACTER

   SAL                         51     *  WHT      CHARACTER

   COMM                      NEXT     *           CHARACTER

                                                  %

   HIREDATE               SYSDATE

   Column DEPTNO is NULL if DEPTNO = BLANKS

   Column JOB is NULL if JOB = BLANKS

   Column JOB had SQL string

   "UPPER(:job)"

    applied to it.

   Column MGR is NULL if MGR = BLANKS

   Column ENAME had SQL string

   "UPPER(:ename)"

    applied to it.

   Column SAL had SQL string

   "TO_NUMBER(:sal,'$99,999.99')"

    applied to it.

   Column COMM had SQL string

   ":comm * 100"

    applied to it.

2) Record 1: Discarded - failed all WHEN clauses.

   Record 2: Discarded - failed all WHEN clauses.

   Record 3: Discarded - failed all WHEN clauses.

   Record 4: Discarded - failed all WHEN clauses.

   Record 5: Discarded - failed all WHEN clauses.

   Record 6: Discarded - failed all WHEN clauses.

   Record 10: Discarded - failed all WHEN clauses.

   Table EMP:

     6 Rows successfully loaded.

     0 Rows not loaded due to data errors.

2)   7 Rows not loaded because all WHEN clauses were failed.

     0 Rows not loaded because all fields were null.

   Space allocated for bind array:            52480 bytes(64 rows)

   Space allocated for memory besides bind array:   108185 bytes

   Total logical records skipped:          0

   Total logical records read:            13

   Total logical records rejected:         0

2) Total logical records discarded:        7

Notes:

1) Warning generated by the difference between the specified length and the length derived from the position specification.

2) The 6 header lines at the top of the report are rejected, as is the blank separator line in the middle.


CHAPTER 6. SQL*LOADER CONTROL FILE REFERENCE

This chapter describes the SQL*Loader data-loading language that write control files.

The information in this chapter falls into the following main categories:

•	general syntactical information

•	managing files

•	managing data

The sections that belong to each category follow:

General Syntactical Information:

•	creating the control file (page 6 - 3)

•	control file syntax (page 6 - 4)

•	adding comments (page 6 - 9)

•	specifying command-line parameters (page 6 - 10)

•	specifying filenames and database objects (page 6 - 11)

Managing Files:

•	including data in the control file (page 6 - 13)

•	identifying datafiles (page 6 - 14)

•	specifying datafile format and buffering (page 6 - 16)

•	specifying the bad file (page 6 - 17)

•	rejected records (page 6 - 18)

•	specifying the discard file (page 6 - 19)

•	discarded records (page 6 - 18)

•	loading data for different countries (page 6 - 22)

•	loading into non-empty database tables (page 6 - 23)

•	continuing interrupted loads (page 6 - 25)

•	assembling logical records from physical records (page 6 - 27)

Managing Data:

•	loading logical records into tables (page 6 - 30)

•	specifying field conditions (page 6 - 31)

•	specifying columns and fields (page 6 - 36)

•	specifying the position of a data field (page 6 - 37)

•	using multiple INTO TABLE clauses (page 6 - 40)

•	generating data (page 6 - 43)

•	loading without files (page 6 - 43)

•	specifying datatypes (page 6 - 47)

•	loading data across different operating systems (page 6 - 60)

•	determining bind array size (page 6 - 61)

•	setting a column to null or zero (page 6 - 65)

•	loading all-blank fields (page 6 - 66)

•	trimming of blanks and tabs (page 6 - 67)

•	preserving whitespace (page 6 - 72)

•	applying SQL operators to fields (page 6 - 73)

 ________________________________________

Creating a Control File

A control file provides the following information:

•	where to find data. There are three possibilities:

•	The data may be directly contained in the control file, in which case it will be flagged with a BEGIN DATA clause.

•	The data may be contained in datafiles identified in the control file through use of an INFILE clause.

•	The data may be in a file to be specified on the command line when the control file is used.

•	which database tables to load the data into, specified with the INTO TABLE clause.

•	the relationship between datafile fields and database table columns, specified with LOAD DATA statement.

Guidelines for writing a control file follow:

•	The file is written in free format. That is, statements can continue from line to line with new lines beginning at any word.

•	The file is written in uppercase or lowercase. Case is not significant except in strings specified with single or double quotation marks.

•	Comments can be included by prefixing them with two hyphens, as in the following example:

--This is a comment

•	The double hyphens can appear anywhere on a line; SQL*Loader ignores anything from the double hyphens to the end of line. Comments should not appear in the datafile or the data portion of the control file. If a double dash appears in this area, it is treated as data.

•	SQL*Loader reserved words must be enclosed in quotation marks if you want to use them for table or column names. (See Appendix B for a complete list of SQL*Loader reserved words.)

 ________________________________________

Control File Syntax

The control file usually begins with the phrase LOAD DATA, followed by several phrases that describe the data to be loaded. (Although the DATA keyword is optional, it is normally included.)

LOAD DATA is the main statement in a control file, and the phrases following it are clauses modifying it. The clauses generally may be broken down into subclauses and components. Only the phrases shown preceding LOAD DATA below can precede the LOAD DATA phrase in the control file.

 Position Specification

A position specification (pos_spec) gives the starting location for a field and, optionally, the ending location as well. A pos_spec is specified as follows:

 The position must be surrounded by parentheses. The starting location may be specified as a column number, as * (next column), or *+n (next column plus an offset). The start and end locations may be separated with either a colon (:) or a dash (-).

 Operators

The valid operators indicate equality or inequality:

=      !=     =      <>

 Field Condition

A field condition compares a named field or an area of the record to some value. When the condition evaluates to true, the specified function is performed. For example, a true condition might cause the NULLIF function to insert a NULL data value, or cause DEFAULTIF to insert a default value. The field_condition is specified as follows:

 The char_string and hex_string can be enclosed in either single quotation marks or double quotation marks. The hex_string is a string of hexadecimal digits, where each pair of digits corresponds to one byte in the field. The BLANKS keyword allows you to test a field to see if it consists entirely of blanks. It is necessary when you are loading delimited data and you cannot predict the length of the field, or when using a multi-byte character set that has multiple blanks.

There must not be any spaces between the operator and the operands on either side of it. Thus,

(1)='x'

is legal, while

(1) = 'x'

generates an error.

 Column Name

The column name you specify in a field condition must be one of the columns defined for the input record. It must be specified with double quotation marks if its name is a reserved word. See the section "Specifying Filenames and Database Objects" for more details.

 Datatype Specification

The datatype_spec tells SQL*Loader how to interpret the field in the input record. The syntax is as follows:

 Precision vs. Length

The precision of a numeric field is the number of digits it contains. The length of a numeric field is the number of byte positions on the record. The byte length of a ZONED decimal field is the same as its precision. However, the byte length of a (packed) DECIMAL field is (p+1)/2, rounded up, where p is the number's precision, because packed numbers contain two digits (or digit and sign) per byte.

 Date Mask

The date mask specifies the format of the date value. For more information, see the DATE datatype.

 Delimiter Specification

The delimiter_spec can specify a termination delimiter, enclosure delimiters, or a combination of the two, as shown below:

 For more information, see "Specifying Delimiters".

 ________________________________________

Comments

Comments may appear anywhere in the command section of the file, but they should not appear in data. Comments are preceded with a double hyphen, which may appear anywhere on a line. For example,

--This is a comment

All text to the right of the double hyphen is ignored, until the end of line. Case 3 contains an example in a control file.

 ________________________________________

Specifying Command-Line Parameters in the Control File

The OPTIONS clause is useful when you usually invoke a control file with the same set of options, or when the number of arguments makes the command line very long.

 The Options Clause

This clause allows you to specify runtime arguments in the control file, rather than on the command line. The following arguments can be specified with the OPTIONS clause. They are described in Chapter 7, "SQL*Loader Command-Line Reference".

SKIP = n

LOAD = n

ERRORS = n

ROWS = n

BINDSIZE = n

SILENT = {HEADER | FEEDBACK | ERROR | DISCARDS | ALL}

DIRECT = {TRUE | FALSE}

PARALLEL = {TRUE | FALSE}

For example:

OPTIONS (BINDSIZE=100000, SILENT=(ERRORS, FEEDBACK) )

Values specified on the command line override values specified in the OPTIONS clause of the control file. With this precedence, the OPTIONS keyword in the control file establishes default values that are easily changed from the command line.

Note: When SILENT=HEADER is specified in the control file, it is too late to take effect. A request to suppress the header must be made on the command line.

 ________________________________________

Specifying RECOVERABLE and UNRECOVERABLE

The following options apply to direct path loads:

RECOVERABLE	Loaded data is logged in the redo log. This option is the default for direct path loads. All conventional loads are recoverable.

UNRECOVERABLE	This option can be specified for a direct path load only. Loaded data is not logged, which improves load performance. (Other changes to the database are logged.) For details, see "Specifying UNRECOVERABLE". This option cannot be specified with a conventional load.

 ________________________________________

Specifying Filenames and Database Objects

This section explains how to use quotation marks for specifying database objects and filenames in the load control file. It also shows how the escape character is used in quoted strings.

 Database Object Names within Double Quotation Marks

SQL*Loader follows the SQL standard for specifying object names (for example, table and column names):  SQL and SQL*Loader reserved words must be specified within double quotation marks. The reserved words most likely to be column names are:

COUNT	DATA	DATE	FORMAT

OPTIONS	PART	POSITION

So if you had an inventory system with columns named PART, COUNT, and DATA, you would specify these column names within double quotation marks in your SQL*Loader control file. For example:

INTO TABLE inventory

(partnum   INTEGER,

 "PART"    CHAR(15),

 "COUNT"   INTEGER,

 "DATA"    VARCHAR2(30))

See Appendix B, "Reserved Words", for a complete list of reserved words.

You use double quotation marks if the object name contains special characters other than those recognized by SQL ($, #, _), or if the name is case sensitive.

 SQL String within Double Quotation Marks

You also specify the SQL string within double quotation marks. The SQL string applies SQL operators to data fields. It is described.

 Filenames within Single Quotation Marks

On many operating systems, attempting to specify a complete file pathname produces an error, due to the use of special characters other than $, #, or _. Usually, putting the pathname within single quotation marks avoids the error. Filenames that use the backslash character, \, may require special treatment, as described in the section, "Using a Backslash in Filenames",.

For example:

INFILE 'mydata.dat'

BADFILE 'mydata.bad'

 Quotation Marks in Quoted Strings

SQL*Loader uses strings within double quotation marks and strings within single quotation marks in the control file. Each type of string can appear within the other.

 Backslash Escape Character

For commands in the control file, you can place a double quotation mark inside a string delimited by double quotation marks by preceding it with the escape character, \, whenever the escape character is allowed in the string. (The following section tells when the escape character is allowed.) The same holds true for putting a single quotation mark into a string delimited by single quotation marks. For example, a double quotation mark is included in the following string by preceding it with \:

"This quote (\") is included with a backslash."

This example produces a string that contains the following text:

This quote (") is included with a backslash.

To put the escape character into a string, you enter it twice, like this: \\

Some examples follow:

"so'\"far"	    or	  'so\'"far'	  produces   so'"far

"'so\\far'"	    or	  '\'so\\far\''  produces   'so\far'

"so\\\\far"	    or	  'so\\\\far'	  produces   so\\far

 Using a Backslash in Filenames

This section is of interest only to users of PC's and other systems that use backslash characters in file specifications. For all other systems, a backslash is always treated as an escape character, as described in the preceding section.

 Non-Portable Strings

There are two kinds of character strings in a SQL*Loader control file that are not portable between operating systems: filename strings and file processing options strings. When converting to a different operating system, these strings must generally be rewritten. They are the non-portable strings. All other strings in a SQL*Loader control file are portable between operating systems.

 Double Backslash Sometimes Needed

If your operating system uses the backslash character to separate directories in a pathname and if the version of Oracle running on your operating system implements the backslash escape character for filenames and other non-portable strings, then you need to specify double backslashes in your pathnames and use single quotation marks.

Additional Information:  To find out if your version of Oracle implements the backslash escape character for filenames, see your operating system-specific Oracle7 documentation.

To load a file named "topdir\mydir\mydata", for example, you must specify:

INFILE 'topdir\\mydir\\mydata'

 Escape Character Sometimes Disallowed

The version of Oracle running on your operating system may not implement the escape character for non-portable strings. When the escape character is disallowed, a backslash is treated as a normal character, rather than as an escape character (although it is still usable in all other strings). Then pathnames such as:

INFILE 'topdir\mydir\myfile'

can be specified normally. Double backslashes are not needed.

Because the backslash is not recognized as an escape character, strings within single quotation marks cannot be embedded inside another string delimited by single quotation marks. This rule also holds for double quotation marks: A string within double quotation marks cannot be embedded inside another string delimited by double quotation marks.

 Determining If the Escape Character is Allowed

As previously mentioned, you can learn if the backslash is used as an escape character in non-portable strings by checking your operating-system-specific Oracle7 documentation, Another way is to specify "test\me" in the file processing options string. Then check the log file. If the log file shows the file processing options string as

"test\me"

then the backslash is not used as an escape character, and double backslashes are not required for file specifications.

However, if the log file shows the file processing options string as:

"testme"

then the backslash is treated as an escape character, and double backslashes are needed.

 ________________________________________

Including Data in the Control File with BEGINDATA

If your data is in the control file, it is placed at the end of the control specifications. You must place the BEGINDATA clause before the first data record to separate the data from your control statements. The syntax is:

BEGINDATA

This clause is used in conjunction with the INFILE clause, described. Case 1 contains an example.

If you omit BEGINDATA, SQL*Loader tries to interpret your data as control information, and you receive an error message. If the data is in a separate file, reaching the end of the control file signals that control information is complete, and BEGINDATA should not be used.

There should not be any spaces or other characters on the same line after the BEGINDATA clause. Otherwise, the line containing BEGINDATA is interpreted as the first line of data.

Do not put comments after BEGINDATA--they are also interpreted  as data.

 ________________________________________

Identifying Datafiles

To specify the datafile fully, use a filename clause, optionally followed by a file-processing options string. You may specify multiple files by using multiple INFILE clauses. You can also specify the datafile from the command line, using the DATA parameter described.

 Naming the File

To specify the file containing the data to be loaded, use the INFILE or INDDN keyword, followed by the filename and optional processing options string. A filename specified on the command line overrides the first INFILE or INDDN clause in the control file. If no filename is specified, the filename defaults to the control filename with an extension or file type of DAT.

If the control file also contains the data to be loaded, specify a filename of "*". This specification works with the BEGINDATA keyword, described.

 where:

INFILE or INDDN	Either keyword may be used.

filename 	Name of the file containing the data to be loaded. May be any valid filename for your operating system. All filenames containing spaces or punctuation marks should be enclosed in single quotation marks. For more details, see "Specifying Filenames and Database Objects".

*	An asterisk (*) replaces a filename to specify that the data is in the control file. If multiple datafiles are specified, this specification must be first.

processing options	This is the file-processing options string. It indicates datafile format. It also optimizes datafile reads. See "Specifying Datafile Format and Buffering".

 Specifying Multiple Datafiles

To load data from multiple datafiles in one run of SQL*Loader, use an INFILE clause for each datafile. Datafiles do not need the same file format, although the layout of the records must be identical. For example, two files could be specified with completely different file processing options strings, and a third could consist of data in the control file.

For each datafile, you can also specify a discard file and a bad file. These files should be declared after each datafile name. The following portion of a control file specifies four files:

INFILE  mydat1.dat  BADFILE  mydat1.bad  DISCARDFILE mydat1.dis

INFILE  mydat2.dat

INFILE  mydat3.dat  DISCARDFILE  mydat3.dis

INFILE  mydat4.dat  DISCARDMAX  10

For the first datafile (MYDAT1.DAT), both a bad file and discard file are explicitly named. So both files are created, if needed.

For the second datafile (MYDAT2.DAT), neither a bad file nor a discard file is specified. So only the bad file is created, if it is needed. If created, the bad file has a default filename and extension. The discard file is not created, even if rows are discarded.

For the third file (MYDAT3.DAT), the default bad file is created, if needed. A discard file with the given name is also created, if it is needed.

For the fourth file (MYDAT4.DAT), the default bad file is created, if needed. Because the DISCARDMAX option is used, SQL*Loader assumes that a discard file is wanted and creates it with the default name (MYDAT4.DSC), if it is needed.

Note: It is not possible to join physical records from separate datafiles into one logical record.

 Examples of How to Specify a Datafile

In the first example, you specify that the data is contained in the control file itself:

INFILE  *

In the next example, you specify that the data is contained in a file named WHIRL with the default file extension or file type of DAT:

INFILE  WHIRL

The following example specifies the full path to a file:

INFILE 'c:/topdir/subdir/datafile.dat'

Note: Filenames that include spaces or punctuation marks should be enclosed in single quotation marks. For more details on filename specification, see "Specifying Filenames and Database Objects".

 ________________________________________

Specifying READBUFFERS

The READBUFFERS clause can controls memory usage. This clause can be specified for direct path loads, only. For more information, see Chapter 9, "SQL*Loader Direct Path Loads".

 ________________________________________

Specifying Datafile Format and Buffering

You specify an operating-system-dependent file processing options string to control file processing. You use this string to specify file format and buffering.

Additional Information:   For details on the syntax of the file processing options string, see your operating system-specific Oracle7 documentation.

 File Processing Example

For example, suppose that your operating system has the following option-string grammar:

 where RECSIZE is the size of a fixed-length record, and BUFFERS is the number of buffers to use for asynchronous I/O.

Note:   This example is platform specific. It may not work on your operating system. For details on the syntax of the file processing options string on your system, see your operating system-specific Oracle7 documentation.

To declare a file named MYDATA.DAT as a file that contains 80-byte records and tell SQL*Loader to use eight I/O buffers with this syntax, you would use the following clause:

INFILE 'mydata.dat' "RECSIZE 80 BUFFERS 8"

Note: This example uses the recommended convention of single quotation marks for filenames and double quotation marks for everything else. See "Specifying Filenames and Database Objects" for more details.

 ________________________________________

Specifying the Bad File

When SQL*Loader executes, it may create a file called a bad file or reject file where it places records that were rejected because of formatting errors, or because they caused Oracle errors. The bad file is created according to the following rules:

•	A bad file is created only if one or more records are rejected.

•	If no records are rejected, then a bad file is not created.

•	If the bad file is created, it overwrites an existing file with the same name.

•	If a bad file is not created, then an existing file with the same name remains intact.

Suggestion: If a file exists with the same name as the bad file that SQL*Loader may create, delete or rename it before running SQL*Loader.

Additional Information:  On some systems a new version of the file is created if a file with the same name already exists. See your operating system-specific Oracle7 documentation to find out if this is the case on your system.

To specify the name of this file, use the BADFILE or BADDN keyword, followed by the filename. If you do not specify a name for the bad file, the name defaults to the name of the datafile with an extension or file type of BAD. You can also specify the bad file from the command line with the BAD parameter described.

A filename specified on the command line is associated with the first INFILE or INDDN clause in the control file, overriding any bad file that may have been specified as part of that clause.

The bad file is created in the same record and file format as the datafile so that the data can be reloaded after corrections. The syntax is

 where:

BADFILE or BADDN	Either keyword may be used.

bad_file_name	Any valid file specification, naming a file to receive rejected records.

Note: Filenames that include spaces or punctuation marks should be enclosed in single quotation marks. For more details on filename specification, see "Specifying Filenames and Database Objects".

 Examples of How to Specify a Bad File

In the following example, you specify a bad file with filename UGH and default file extension or file type of BAD:

BADFILE UGH

In the next examples, you specify a bad file with filename BAD0001 and file extension or file type of REJ:

BADDN BAD0001.REJ

BADDN '/REJECT_DIR/BAD0001.REJ'

 ________________________________________

Rejected Records

A record is rejected if it meets either of the following conditions:

•	Upon insertion the record causes an Oracle error (such as invalid data for a given datatype).

•	SQL*Loader cannot determine if the data is acceptable. That is, it cannot determine if the record meets WHEN-clause criteria, as in the case of a field that is missing its final delimiter.

If the data can be evaluated according to the WHEN-clause criteria (even with unbalanced delimiters) then it is either inserted or rejected.

If a record is rejected on insert, then no part of that record is inserted into any table. For example, if data in a record is to be inserted into multiple tables, and most of the inserts succeed, but one insert fails; then all the inserts from that record are rolled back. The record is then written to the bad file, where it can be corrected and reloaded. Previous inserts from records without errors are not affected.

The log file indicates the Oracle error for each rejected record. Case 4 has an example of rejected records.

 Integrity Constraints

All integrity constraints are honored for conventional path loads. On the direct path, some constraints are unenforceable. See Chapter 9 for more details.

 ________________________________________

Specifying the Discard File

As SQL*Loader executes, it may create a discard file for records that do not meet any of the loading criteria. The records contained in this file are called discarded records. Discarded records do not satisfy any of the WHEN clauses specified in the control file. These records are different from rejected records. Discarded records do not necessarily have any bad data. No insert is attempted on a discarded record.

The discard file is created according to the following rules:

•	A discard file is only created if a discard filename is specified.

•	A discard file is only created if one or more records fail to satisfy any of the WHEN clauses specified in the control file, even if it has been specified.

•	If the discard file is created, it overwrites an existing file with the same name.

•	If no records are discarded then a discard file is not created.

•	If a discard file is not created, then an existing file with the same name remains intact.

Suggestion: If a file exists with the same name as the discard file that SQL*Loader may create, delete or rename it before running SQL*Loader.

To create a discard file, use any of the following options:

In a Control File	On the Command Line

DISCARDFILE filename	DISCARD

DISCARDON filename	DISCARDMAX

DISCARDS

DISCARDMAX

Note that you can request the discard file directly with a parameter specifying its name, or indirectly by specifying the maximum number of discards.

 Using a Command-Line Parameter

You can specify the discard file from the command line, with the DISCARD parameter or the DISCARDMAX parameter described.

A filename specified on the command line goes with the first INFILE or INDDN clause in the control file, overriding any bad file that may have been specified as part of that clause.

 Using a Control-File Clause

To specify the name of the file, use the DISCARDFILE or DISCARDDN clause, followed by the filename.

 where:

DISCARDFILE or DISCARDDN	Either keyword may be used.

discard_file_name	Any valid filename, specifying a file to receive discard records.

Note: Filenames that include spaces or punctuation marks should be enclosed in single quotation marks. For more details on filename specification, see "Specifying Filenames and Database Objects".

The default filename is the name of the datafile, and the default file extension or file type is DSC. A discard filename specified on the command line overrides one specified in the control file. If a discard file with that name already exists, it is either overwritten or a new version is created, depending on your operating system.

The discard file is created with the same record and file format as the datafile. So it can easily be used for subsequent loads with the existing control file, after changing the WHEN clauses or editing the data.

 Examples of How to Specify a Discard File

In the first example, you specify a discard file with filename CIRCULAR and default file extension or file type of DSC:

DISCARDFILE  CIRCULAR

In this example, you specify a file extension or file type of MAY:

DISCARDDN   NOTAPPL.MAY

In the next example, you specify a full path to filename FORGET.ME:

DISCARDFILE  '/DISCARD_DIR/FORGET.ME'

 ________________________________________

Discarded Records

If there is no INTO TABLE clause that applies to a record, the record is discarded. This situation occurs when every INTO TABLE clause in the loader control file has a WHEN clause; and either the record fails to match any of them or all fields are null.

No records are discarded if an INTO TABLE clause is specified without a WHEN clause. An attempt is made to insert every record into such a table. So records may be rejected, but none are discarded.

Case 4 has an example of a discard file.

 Limiting the Number of Discards

You may limit the number of records to be discarded for each datafile with the clause:

 where n must be an integer. When the discard limit is reached, processing of that datafile terminates and continues with the next datafile, if one exists.

You can specify a different number of discards for each datafile. Alternatively, if the number of discards is only specified once, then the maximum number of discards is the same for all files.

If you specify a maximum number of discards, but no discard filename; SQL*Loader creates a discard file with the default filename and file extension or file type. Case 4 has an example.

 ________________________________________

Handling Different Character Encoding Schemes

This section describes the features that allow SQL*Loader to operate with different character encoding schemes (called character sets, or code pages). SQL*Loader uses Oracle's NLS (National Language Support) features to handle the different single-byte and multi-byte character encoding schemes used on different computers and in different countries.

 Multi-Byte (Asian) Character Sets

Multi-byte character sets support Asian languages. Data can be loaded in multi-byte format, and database objects (fields, tables, and so on) can be specified with multi-byte characters. In the control file, comments and object names may also use multi-byte characters.

 Input Character Conversion

SQL*Loader also has the capacity to convert data from the datafile character set to the database character set, when they are different. When using the conventional path, data is converted into the session character set specified by the NLS_LANG parameter for that session. Then the data is loaded using SQL INSERT statements. The session character set is the character set supported by your terminal.

On the direct path, data converts directly into the database character set. As a consequence, the direct path can load data in a character set that is not supported by your terminal.

When data conversion occurs, it is essential that the target character set contains a representation of all characters that exist in the data. Otherwise, characters that have no equivalent in the target character set are converted to a default character, with consequent loss of data. When using the direct path, the database character set should be a superset of, or equivalent to, the datafile character sets. Similarly, when using the conventional path, the session character set should be a superset of, or equivalent to, the datafile character sets.

The character set used in each input file is specified with the CHARACTERSET clause.

CHARACTERSET Clause

The control file tells SQL*Loader how to interpret the datafile. The file processing options string tells SQL*Loader how to divide the file into records. The field specifications describe the format of each record. The CHARACTERSET clause tells SQL*Loader what character set is used in each datafile. Different datafiles can be specified with different character sets. Only one character set can be specified for each datafile.

Using the CHARACTERSET clause causes character data to be automatically converted when it is loaded into Oracle. Only CHAR, DATE, and numeric EXTERNAL fields are affected. If the CHARACTERSET clause is not specified, then no conversion occurs.

The syntax for this option is:

CHARACTERSET character_set_spec

where character_set_spec is the acronym used by Oracle to refer to your particular encoding scheme.

For more information on supported character sets, code pages, and the NLS_LANG parameter, see the National Language Support section of the Oracle7 Server Administrator's Guide.

 Control File Characterset

The SQL*Loader control file itself is assumed to be in the character set specified for your session by the NLS_LANG parameter. However, delimiters and comparison clause values must be specified to match the character set in use in the datafile. To ensure that the specifications are correct, it may be preferable to specify hexadecimal strings, rather than character string values.

Any data included after the BEGINDATA statement is also assumed to be in the character set specified for your session by the NLS_LANG parameter. Data that uses a different character set must be in a separate file.

 ________________________________________

Loading into Empty and Non-Empty Tables

You can specify one of the following methods for loading tables:

 This section describes those methods.

 How Non-Empty Tables are Affected

This section corresponds to the DB2 keyword RESUME; users of DB2 should also refer to the description of RESUME in Appendix C. If the tables you are loading already contain data, you have four choices for how SQL*Loader proceeds:

INSERT	Returns an error and terminates the load if the table contains data. This option only loads data into empty tables. It is the default.

APPEND	Extends the table by adding new rows.

REPLACE	Deletes the rows in the table and loads the new data in its place.

TRUNCATE	TRUNCATEs the table and loads the new data in place of the old.

Warning: When the REPLACE or TRUNCATE keyword is specified, the entire table is replaced, not individual rows. After the rows are successfully deleted, a commit is issued. You cannot recover the data that was in the table before the load, unless it was saved with Export or a comparable utility.

The remainder of this section provides additional detail on these options.

 INSERT

This is the default method. It requires the table to be empty before loading. SQL*Loader terminates with an error if the table contains rows. Case 1 has an example.

 APPEND

If data already exists in the table, SQL*Loader appends the new rows to it; if data doesn't already exist, the new rows are simply loaded. Case 3 has an example.

 REPLACE

All rows in the table are deleted and the new data is loaded. The table must be in your schema, or you must have DELETE privilege on the table. Case 4 has an example.

The row deletes cause any delete triggers defined on the table to fire. If DELETE CASCADE has been specified for the table, then the cascaded deletes are carried out, as well. For more information on cascaded deletes, see the "Data Integrity" chapter of the Oracle7 Server Concepts Manual.

 Updating Existing Rows

The REPLACE method is a table replacement, not a replacement of individual rows. SQL*Loader does not update existing records, even if they have null columns. To update existing rows, use the following procedure:

1.	Load your data into a temporary table.

2.	Use the SQL language UPDATE statement with correlated subqueries.

3.	Drop the temporary table.

For more details, see the "UPDATE" statement in the Oracle7 Server SQL Language Reference Manual.

 TRUNCATE

With this method, SQL*Loader uses the SQL TRUNCATE command to achieve the best possible performance. For the TRUNCATE command to operate, the table's referential integrity constraints must first be disabled. If they have not been disabled, SQL*Loader returns an error.

Once the integrity constraints have been disabled, DELETE CASCADE is no longer defined for the table. If the DELETE CASCADE functionality is needed, then the contents of the table must be manually deleted before the load begins.

The table must be in your schema or you must have the DELETE ANY TABLE privilege.

 Specifying One Method for All Tables

You specify one table-loading method that applies to all tables by placing the keyword before any INTO TABLE clauses. This choice applies to any table that does not have its own method. You can specify a table-loading method for a single table by including the keyword in the INTO TABLE clause, as described in "Specifying Local Table Loading Options".

 ________________________________________

Continuing an Interrupted Load

If SQL*Loader runs out of space for data rows or index entries, the load is discontinued. (For example, the table might reach its maximum number of extents.) Discontinued loads can be continued after more space is made available.

 State of Tables and Indexes

When a load is discontinued, any data already loaded remains in the tables, and the tables are left in a valid state. If the conventional path is used, all indexes are left in a valid state.

If the direct path is used, any indexes that run out of space are left in direct load state -- they must be dropped before the load can continue. Other indexes are valid provided no other errors occurred. (See "Indexes Left in Direct Load State" for other reasons why an index might be left in direct load state.)

 Using the Log File

SQL*Loader's log file tells you the state of the tables and indexes and the number of logical records already read from the input datafile. Use this information to resume the load where it left off.

 Dropping Indexes

Before continuing a direct path load, inspect the SQL*Loader log file to make sure that no indexes are in direct load state. Any indexes that are left in direct load state must be dropped before continuing the load. The indexes can then be re-created either before continuing or after the load completes.

 Continuing Single Table Loads

To continue a discontinued direct or conventional path load involving only one table, specify the number of logical records to skip with the command-line parameter SKIP. If the SQL*Loader log file says that 345 records were previously read, then the command to continue would look like this:

SQLLDR USERID=scott/tiger CONTROL=FAST1.CTL DIRECT=TRUE SKIP=345

 Continuing Multiple Table Conventional Loads

It is not possible for multiple tables in a conventional path load to become unsynchronized. So a multiple table conventional path load can also be continued with the command-line parameter SKIP. Use the same procedure that you would use for single-table loads, as described in the preceding paragraph.

 Continuing Multiple Table Direct Loads

If SQL*Loader cannot finish a multiple-table direct path load, the number of logical records processed could be different for each table. If so, the tables are not synchronized and continuing the load is slightly more complex.

To continue a discontinued direct path load involving multiple tables, inspect the SQL*Loader log file to find out how many records were loaded into each table. If the numbers are the same, you can use the previously described simple continuation.

 CONTINUE_LOAD

If the numbers are different, use the CONTINUE_LOAD statement and specify SKIP at the table level, instead of at the load level. These statements exist to handle unsynchronized interrupted loads. Instead of specifying:

LOAD DATA...

at the start of the control file, specify:

  SKIP

Then, for each INTO TABLE clause, specify the number of logical records to skip for that table using the SKIP clause:

...

INTO TABLE emp

SKIP 2345

...

INTO TABLE dept

SKIP 514

...

 Combining SKIP and CONTINUE_LOAD

The CONTINUE_LOAD clause is only needed after a direct load failure because multiple table loads cannot become unsynchronized when using the conventional path.

If you specify CONTINUE_LOAD, you cannot use the command-line parameter SKIP. You must use the table-level SKIP clause. If you specify LOAD, you can optionally use the command-line parameter SKIP, but you cannot use the table-level SKIP clause.

 ________________________________________

Assembling Logical Records from Physical Records

You can create one logical record from multiple physical records using one of the following two clauses, depending on your data:

CONCATENATE

CONTINUEIF

CONCATENATE is appropriate in the simplest case, when SQL*Loader should always add the same number of physical records to form one logical record. The syntax is:

CONCATENATE  n

where n indicates the number of physical records to combine.

If the number of physical records to be continued varies, then CONTINUEIF must be used. The keyword CONTINUEIF is followed by a condition that is evaluated for each physical record, as it is read. For example, two records might be combined if there were a pound sign (#) in character position 80 of the first record. If any other character were there, the second record would not be added to the first. The full syntax for CONTINUEIF adds even more flexibility:

where:

THIS	If the condition is true in this record, then the next physical record is read and concatenated to the current physical record, continuing until the condition is false. If the condition is false in the current record, then the current physical record is the last physical record of the current logical record. THIS is the default.

NEXT	If the condition is true in the next record, then the next physical record is concatenated to the current record, continuing until the condition is false.

If the condition is false in the next record, then the current physical record is the last physical record of the current logical record.

pos_spec	Indicates starting and ending column numbers in the physical record, as shown below:

Column numbers start with 1. Either a hyphen or a colon is acceptable (start-end or start:end).

If you omit end, the length of the continuation field is the length of the byte string or character string. If you use end, and the length of the resulting continuation field is not the same as that of the byte string or character string, the shorter one is padded. Character strings are padded with blanks, hexadecimal strings with zeros.

LAST	This test is similar to THIS, but the test is always against the last non-blank character. If the last non-blank character in this physical record meets the test, then the next physical record is read and concatenated to the current physical record, continuing until the condition is false. If the condition is false in the current record, then the current physical record is the last physical record of the current logical record.

operator	The supported operators are equal and not equal:

=    !=     =   <>

For the equal operator, the field and comparison string must match exactly for the condition to be true. For the not equal operator, they may differ in any character.

char_string	A string of characters to be compared to the continuation field defined by start and end, according to the operator. The string must be enclosed in double or single quotation marks. The comparison is made character by character, blank padding on the right if necessary.

X'hex_string' 	A string of bytes in hexadecimal format, used in the same way as the character string above. X'1FB033' would represent the three bytes with values 1F, B0 and 33 (hex).

Note: The positions in the CONTINUEIF clause refer to positions in each physical record. This is the only time you refer to character positions in physical records. All other references are to logical records.

For CONTINUEIF THIS and CONTINUEIF NEXT, the continuation field is removed from all physical records before the logical record is assembled. This allows data values to span the records with no extra characters (continuation characters) in the middle. Two examples showing CONTINUEIF THIS and CONTINUEIF NEXT follow:

CONTINUEIF THIS	CONTINUEIF NEXT

(1:2) = '%%'  	(1:2) ='%%'

Assume physical data records 12 characters long and that a period means a space:

%%aaaaaaaa....	..aaaaaaaa....

%%bbbbbbbb....	%%bbbbbbbb....

..cccccccc....	%%cccccccc....

%%dddddddddd..	..dddddddddd..

%%eeeeeeeeee..	%%eeeeeeeeee..

..ffffffffff..	%%ffffffffff..

The logical records would be the same in each case:

aaaaaaaa....bbbbbbbb....cccccccc....

dddddddddd..eeeeeeeeee..ffffffffff..

Notes:

•	CONTINUEIF LAST differs from CONTINUEIF THIS and CONTINUEIF NEXT. With CONTINUEIF LAST the continuation character is not removed from the physical record. Instead, this character is included when the logical record is assembled.

•	Trailing blanks in the physical records are part of the logical records.

 Examples of How to Specify CONTINUEIF

In the first example, you specify that if the current physical record (record1) has an asterisk in column 1, then the next physical record (record2) should be appended to it. If record2 also has an asterisk in column 1, then record3 is appended also.

If record2 does not have an asterisk in column 1, then it is still appended to record1, but record3 begins a new logical record.

CONTINUEIF THIS (1) = "*"

In the next example, you specify that if the current physical record (record1) has a comma in the last non-blank data column, then the next physical record (record2) should be appended to it. If a record does not have a comma in the last column, it is the last physical record of the current logical record.

CONTINUEIF LAST = ","

In the last example, you specify that if the next physical record (record2) has a "10" in columns 7 and 8, then it should be appended to the preceding physical record (record1). If a record does not have a "10" in columns 7 and 8, then it begins a new logical record.

CONTINUEIF NEXT (7:8) = '10'

Case 4 shows the CONTINUEIF clause in use.

 ________________________________________

Loading Logical Records into Tables

This section describes the way in which you specify:

•	which tables you want to load

•	which records you want to load into them

•	default characteristics for the columns in those records

 Specifying Table Names

The section of the LOAD DATA statement in which you identify tables, fields, and datatypes is the INTO TABLE clause. This section concentrates on the relationship between records in the datafile and tables in the database. The specification of fields and datatypes is described in later sections.

 INTO TABLE Clause

Among its many functions, the INTO TABLE clause allows you to specify the table into which you load data. To load multiple tables, you include one INTO TABLE clause for each table you wish to load.

To begin an INTO TABLE clause, use the keywords INTO TABLE, followed by the name of the Oracle table that is to receive the data.

 The table must already exist. The table name should be enclosed in double quotation marks if it is the same as any SQL or SQL*Loader keyword, if it contains any special characters, or if it is case sensitive.

INTO TABLE SCOTT."COMMENT"

INTO TABLE SCOTT."comment"

INTO TABLE SCOTT."-COMMENT"

The user running SQL*Loader should have INSERT privileges on the table. Otherwise, the table name should be prefixed by the username of the owner as follows:

INTO TABLE SOPHIA.EMP

 Table-Specific Loading Method

The INTO TABLE clause may include a table-specific loading method (INSERT, APPEND, REPLACE, or TRUNCATE) that applies only to that table. Specifying one of these methods within the INTO TABLE clause overrides the global table-loading method. The global table-loading method is INSERT, by default, unless a different method was specified before any INTO TABLE clauses. For more information on these options, see "Loading into Empty and Non-Empty Tables".

 Table-Specific OPTIONS clause

An OPTIONS clause can be specified for individual tables in a parallel load. (It is only valid for a parallel load.) For more information, see "Parallel Data Loading" beginning.

 Choosing which Rows to Load

You can choose to load or discard a logical record by using the WHEN clause to test a condition in the record.

The WHEN clause appears after the table name and is followed by one or more field conditions.

 For example, the following clause indicates that any record with the value "q" in the fifth column position should be loaded:

WHEN (5) = 'q'

A WHEN clause can contain several comparisons provided each is preceded by AND. Parentheses are optional, but should be used for clarity with multiple comparisons joined by AND. For example

WHEN (DEPTNO = '10') AND (JOB = 'SALES')

To evaluate the WHEN clause, SQL*Loader first determines the values of all the fields in the record. Then the WHEN clause is evaluated. A row is inserted into the table only if the WHEN clause is true.

Field conditions are discussed in detail. Case 5 shows the WHEN clause in use.

 Specifying Default Data Delimiters

If all data fields are terminated similarly in the datafile, you can use the FIELDS clause to indicate the default delimiters. The syntax follows:

 You can override the delimiter for any given column by specifying it after the column name. Case 3 contains an example. See "Specifying Delimiters" for more information on delimiter specification.

 Handling Short Records with Missing Data

When the control file specifies more fields for a record than are present in the record, SQL*Loader must determine whether the remaining (specified) columns should be considered null or whether an error should be generated.

If the control file explicitly states that a field's starting position is beyond the end of the logical record, then SQL*Loader always defines the field as null. If a field is defined with a relative position (such as DNAME and LOC in the example below), and the record ends before the field is found; then SQL*Loader could either treat the field as null or generate an error. SQL*Loader uses the presence or absence of the TRAILING NULLCOLS clause to determine the course of action.

TRAILING NULLCOLS Clause

The TRAILING NULLCOLS clause tells SQL*Loader to treat any relatively positioned columns that are not present in the record as null columns.

For example, if the following data

10 Accounting

is read with the following control file

INTO TABLE dept

TRAILING NULLCOLS

( deptno CHAR TERMINATED BY " ",

  dname  CHAR TERMINATED BY WHITESPACE,

  loc    CHAR TERMINATED BY WHITESPACE

)

and the record ends after DNAME, then the remaining LOC field is set to null. Without the TRAILING NULLCOLS clause, an error would be generated due to missing data.

Case 7 has an example of the TRAILING NULLCOLS clause.

 ________________________________________

Index Options

This section describes the SQL*Loader options that control how index entries are created.

 SORTED INDEXES Option

The SORTED INDEXES option applies to direct path loads. It tells SQL*Loader that the incoming data has already been sorted on the specified index(es), allowing SQL*Loader to optimize performance. Syntax for this feature is given, further details are in Chapter 9, "SQL*Loader Direct Path Loads" beginning.

 SINGLEROW Option

The SINGLEROW option is intended for use with APPEND on systems with limited memory, or when loading a small number of rows into a large table. This option inserts each index entry directly into the index, one row at a time.

By default, SQL*Loader does not use SINGLEROW when APPENDing rows to a table. Instead, index entries are put into a separate, temporary storage area and merged with the original index at the end of the load. This method achieves better performance and produces an optimal index, but it requires extra storage space. During the merge, the original index, the new index, and the space for new entries all simultaneously occupy storage space.

With the SINGLEROW option, storage space is not required for new index entries or for a new index. The resulting index may not be as optimal as a freshly sorted one, but it takes less space to produce. It also takes more time, since additional UNDO information is generated for each index insert. This option is suggested for use when:

•	available storage is limited, or

•	the number of rows to be loaded is small compared to the size of the table (a ratio of 1:20, or less, is recommended)

 ________________________________________

Specifying Field Conditions

A field condition is a statement about a field in a logical record that evaluates as true or false. It is used in the NULLIF and DEFAULTIF clauses, as well as in the WHEN clause.

A field condition is similar to the condition in the CONTINUEIF clause, with two important differences. First, positions in the field condition refer to the logical record, not to the physical record. Second, you may specify either a position in the logical record or the name of a field that is being loaded.

 where:

start	Specifies the starting position of the comparison field in the logical record.

end	Specifies the ending position of the comparison field in the logical record. Either start:end or start-end is acceptable. If you omit end, the length of the field is determined by the length of the comparison string. If the lengths are different, the shorter field is padded: character strings are padded with blanks, hexadecimal strings are padded with zeroes.

column_name 	The name of a column in the database table. If column_name is used instead of start:end, then the specification for that column defines the comparison field. Column_name must match exactly the name of the column in the table's database definition. Use quotation marks around the column name if it is a SQL or SQL*Loader keyword, contains special characters, or is case sensitive. See "Specifying Filenames and Database Objects" for more information.

operator	A comparison operator for either equal or not equal:

= 	!=	 =	<>

'char string'	A string of characters enclosed within single or double quotation marks that is compared to the comparison field. If the comparison is true, then this row is inserted into the table.

X'hex string'	A byte string in hexadecimal format used in the same way as the character string above.

BLANKS	A keyword denoting an arbitrary number of blanks, described next.

 Comparing Fields to BLANKS

The BLANKS keyword makes it possible to determine easily if a field of unknown length is blank.

For example, use the following clause to load a blank field as null:

column_name ... NULLIF column_name=BLANKS

The BLANKS keyword only recognizes blanks, not tabs. It can be used in place of a literal string in any field comparison. The condition is TRUE whenever the column is entirely blank.

The BLANKS keyword also works for fixed-length fields. Using it is the same as specifying an appropriately-sized literal string of blanks. For example, the following specifications are equivalent:

fixed_field CHAR(2) NULLIF (fixed_field)=BLANKS

fixed_field CHAR(2) NULLIF (fixed_field)="  "

Note: There can be more than one "blank" in a multi-byte character set. It is a good idea to use the BLANKS keyword with these character sets instead of specifying a string of blank characters. The character string will match only a specific sequence of blank characters, while the BLANKS keyword will match combinations of different blank characters. For more information on multi-byte character sets, see page 6 - 22.

 Comparing Fields to Literals

When a data field is compared with a shorter literal string, the literal string is padded for the comparison. Character strings are padded with blanks. For example

NULLIF (1:4)="_"

compares the data in position 1:4 with 4 blanks. If position 1:4 contains 4 blanks, then the clause evaluates as true.

Hexadecimal strings are padded with hexadecimal zeroes. The clause

NULLIF (1:4)=X'FF'

compares position 1:4 to hex 'FF000000'.

 ________________________________________

Specifying Columns and Fields

You may load any number of a table's columns. Columns defined in the database, but not specified in the control file, are assigned null values (this is the proper way to insert null values).

A column specification is the name of the column, followed by a specification for the value to be put in that column. The list of columns is enclosed by parentheses and separated with commas as follows:

( columnspec,  columnspec,  ... )

Each column name must correspond to a column of the table named in the INTO TABLE clause. A column name must be enclosed in quotation marks if it is a SQL or SQL*Loader reserved word, contains special characters, or is case sensitive.

If the value is to be generated by SQL*Loader, the specification includes the keyword RECNUM, the SEQUENCE function, or the keyword CONSTANT. See "Generating Data".

If the column's value is read from the datafile, the data field that contains the column's value is specified. In this case, the column specification includes a column name that identifies a column in the ydatabase table, and a field specification that describes a field in a data record. The field specification includes position, datatype, null restrictions, and defaults.

 Specifying the Datatype of a Data Field

A field's datatype specification tells SQL*Loader how to interpret the data in the field. For example, a datatype of INTEGER specifies binary data, while INTEGER EXTERNAL specifies character data that represents a number. A CHAR field, however, can contain any character data.

You may only specify one datatype for each field. If you omit the datatype, a type of CHAR is assumed.

"Specifying Datatypes" describes how SQL*Loader datatypes are converted into the Oracle datatypes and gives detailed information on each of SQL*Loader's datatypes.

Before specifying the datatype, however, the field's position must be specified. That is the subject of the next section.

 ________________________________________

Specifying the Position of a Data Field

To load data from the datafile SQL*Loader must know a field's location and its length. To specify a field's position in the logical record, use the POSITION clause in the column specification. The position may either be stated explicitly or relative to the preceding field. Arguments to POSITION must be enclosed in parentheses.

 where:

start	The starting column of the data field in the logical record. The first character position in a logical record is 1.

end	Indicates the ending position of the data field in the logical record. Either start:end or start-end is acceptable. If end is omitted, the length of the field is derived from the datatype in the datafile. (See the sections on each datatype. Note that CHAR data specified without a start and end is assumed to be length 1.) If it is impossible to derive a length from the datatype, an error message results.

* 	Indicates that the data field follows immediately after the previous field. If * is used for the first data field in the control file, the field is assumed to be at the beginning of the logical record. When * is used for position, the length of the field is derived from the datatype.

+n	An offset, specified as +n, may be used with * to offset this field from the previous one. n characters are skipped before reading the value for this field.

You may omit the POSITION clause entirely. If you do, the position specification for the data field is the same as if POSITION(*) had been used.

For example

ENAME  POSITION (1:20)  CHAR

EMPNO  POSITION (22-26) INTEGER EXTERNAL

ALLOW  POSITION (*+2)   INTEGER EXTERNAL TERMINATED BY "/"

Column ENAME is character data in positions 1 through 20, followed by column EMPNO, which is presumably numeric data in columns 22 through 26. Column ALLOW is offset from the end of EMPNO by +2. So it starts in column 28 and continues until a slash is encountered.

 Using POSITION with Data that Contains TABs

When you are determining field positions, be alert for TABs in the datafile. The following situation is highly likely when using SQL*Loader's advanced SQL string capabilities to load data from a formatted report:

•	You look at a printed copy of the report, carefully measuring all of the character positions, and create your control file.

•	The load then fails with dozens of "invalid number" and "missing field" errors.

These kinds of errors occur when the data contains TABs. When printed, each TAB expands to consume several columns on the paper. In the datafile, however, each TAB is still only one character. As a result, when SQL*Loader reads the datafile, the POSITION specifications are wrong.

To fix the problem, inspect the datafile for tabs and adjust the POSITION specifications, or else use delimited fields.

The use of delimiters to specify relative positioning of fields is discussed in detail beginning. Especially note how the delimiter WHITESPACE can be used.

 Using POSITION with Multiple Table Loads

In a multiple table load, you specify multiple INTO TABLE clauses. When you specify POSITION(*) for the first column of the first table, the position is calculated relative to the beginning of the logical record. When you specify POSITION(*) for the first column of subsequent tables, the position is calculated relative to the last column of the last table loaded.

Thus, when a subsequent INTO TABLE clause begins, the position is not set to the beginning of the logical record automatically. This allows multiple INTO TABLE clauses to process different parts of the same physical record. For an example, see the second example in the section "Extracting Multiple Logical Records" beginning.

A logical record may contain data for one of two tables, but not both. In this case, you would reset POSITION. Instead of omitting the position specification or using POSITION(*+n) for the first field in the INTO TABLE clause, use POSITION(1) or POSITION(n).

Some examples follow:

SITEID  POSITION (*) SMALLINT

SITELOC POSITION (*) INTEGER

If these were the first two column specifications, SITEID would begin in column1, and SITELOC would begin in the column immediately following.

ENAME  POSITION (1:20)  CHAR

EMPNO  POSITION (22-26) INTEGER EXTERNAL

ALLOW  POSITION (*+2)   INTEGER EXTERNAL TERMINATED BY "/"

Column ENAME is character data in positions 1 through 20, followed by column EMPNO which is presumably numeric data in columns 22 through 26. Column ALLOW is offset from the end of EMPNO by +2, so it starts in column 28 and continues until a slash is encountered.

 ________________________________________

Using Multiple INTO TABLE Clauses

Multiple INTO TABLE clauses allow you to:

•	load data into different tables

•	extract multiple logical records from a single input record

•	distinguish different input record formats

In the first case, it is common for the INTO TABLE clauses to refer to the same table. This section illustrates the different ways to use multiple INTO TABLE clauses and shows you how to use the POSITION keyword with them.

Note: A key point when using multiple INTO TABLE clauses is that field scanning continues from where it left off when a new INTO TABLE clause is processed. The remainder of this section details important ways to make use of that behavior. It also describes alternative ways using fixed field locations or the POSITION keyword.

 Extracting Multiple Logical Records

Some data storage and transfer media have fixed-length physical records. When the data records are short, more than one can be stored in a single, physical record to use the storage space efficiently.

In this example, SQL*Loader treats a single physical record in the input file as two logical records and uses two INTO TABLE clauses to load the data into the EMP table. For example, if the data looks like

1119 Smith      1120 Snyder

1121 Spellini   1130 Thompson

then the following control file extracts the logical records:

INTO TABLE emp

(empno POSITION(1:4)  INTEGER EXTERNAL,

 ename POSITION(6:15) CHAR)

INTO TABLE emp

(empno POSITION(17:20) INTEGER EXTERNAL,

 dname POSITION(21:30) CHAR)

 Relative Positioning

The same record could be loaded with a different specification. The following control file uses relative positioning instead of fixed positioning. It specifies that each field is delimited by a single blank  (" "), or with an undetermined number of blanks and tabs (WHITESPACE):

INTO TABLE emp

(empno INTEGER EXTERNAL TERMINATED BY " ",

 ename CHAR             TERMINATED BY WHITESPACE)

INTO TABLE emp

(empno INTEGER EXTERNAL TERMINATED BY " ",

 dname CHAR)            TERMINATED BY WHITESPACE)

The important point in this example is that the second EMPNO field is found immediately after the first ENAME, although it is in a separate INTO TABLE clause. Field scanning does not start over from the beginning of the record for a new INTO TABLE clause. Instead, scanning continues where it left off.

To force record scanning to start in a specific location, you use the POSITION keyword. That mechanism is described next.

 Distinguishing Different Input Record Formats

A single datafile might contain records in a variety of formats. Consider the following data, in which EMP and DEPT records are intermixed:

1 50   Manufacturing	-- DEPT record

2 1119 Smith     50	-- EMP record

2 1120 Snyder     50

1 60   Shipping

2 1121 Stevens    60

A record ID field distinguishes between the two formats. Department records have a "1" in the first column, while employee records have a "2". The following control file uses exact positioning to load this data:

INTO TABLE dept

WHEN recid = 1

(recid  POSITION(1:1)  INTEGER EXTERNAL,

 deptno POSITION(3:4)  INTEGER EXTERNAL,

 dname  POSITION(8:21) CHAR)

INTO TABLE emp

WHEN recid <> 1

(recid  POSITION(1:1)   INTEGER EXTERNAL,

 empno  POSITION(3:6)   INTEGER EXTERNAL,

 ename  POSITION(8:17)  CHAR,

 deptno POSITION(19:20) INTEGER EXTERNAL)

 Relative Positioning

Again, the records in the previous example could also be loaded as delimited data. In this case, however, it is necessary to use the POSITION keyword. The following control file could be used:

INTO TABLE dept

WHEN recid = 1

(recid  INTEGER EXTERNAL TERMINATED BY WHITESPACE,

 deptno INTEGER EXTERNAL TERMINATED BY WHITESPACE,

 dname  CHAR TERMINATED BY WHITESPACE)

INTO TABLE emp

WHEN recid <> 1

(recid  POSITION(1) INTEGER EXTERNAL TERMINATED BY ' ',

 empno  INTEGER EXTERNAL TERMINATED BY ' '

 ename  CHAR TERMINATED BY WHITESPACE,

 deptno INTEGER EXTERNAL TERMINATED BY ' ')

The POSITION keyword in the second INTO TABLE clause is necessary to load this data correctly. This keyword causes field scanning to start over at column 1 when checking for data that matches the second format. Without it, SQL*Loader would look for the RECID field after DNAME.

 Loading Data into Multiple Tables

By using the POSITION clause with multiple INTO TABLE clauses, data from a single record can be loaded into multiple normalized tables. Case 5 illustrates this concept.

 Summary

Multiple INTO TABLE clauses allow you to extract multiple logical records from a single input record and recognize different record formats in the same file.

For delimited data, proper use of the POSITION keyword is essential for achieving the expected results.

When the POSITION keyword is not used, multiple INTO TABLE clauses process different parts of the same (delimited data) input record, allowing multiple tables to be loaded from one record. When the POSITION keyword is used, multiple INTO TABLE clauses can process the same record in different ways, allowing multiple formats to be recognized in one input file.

 ________________________________________

Generating Data

The functions described in this section provide the means for SQL*Loader to generate the data stored in the database row, rather than reading it from a datafile. The following functions are described:

•	CONSTANT

•	RECNUM

•	SYSDATE

•	SEQUENCE

 Loading Data Without Files

It is possible to use SQL*Loader to generate data by specifying only sequences, record numbers, system dates, and constants as field specifications.

SQL*Loader inserts as many rows as are specified by the records-to-load (LOAD) parameter. The LOAD parameter is required in this situation. The records-to-skip (SKIP) parameter is not permitted.

SQL*Loader is optimized for this case. Whenever SQL*Loader detects that only generated specifications are used, it ignores any specified datafile -- no read I/O is done. In addition, no memory is required for a bind array. If there are any WHEN clauses in the control file, SQL*Loader assumes that data evaluation is necessary, and input records are read.

 Setting a Column to a Constant Value

This is the simplest form of generated data. It does not vary during the load, and it does not vary between loads.

 CONSTANT

To set a column to a constant value, use the keyword CONSTANT followed by a value:

CONSTANT  value

CONSTANT data is interpreted by SQL*Loader as character input. It is converted, as necessary, to the database column type.

You may enclose the value within quotation marks, and must do so if it contains white space or reserved words. Be sure to specify a legal value for the target column. If the value is bad, every row is rejected.

Numeric values larger than 2**32 - 1 (4,294,967,295) must be enclosed in quotes.

Note: Do not use the CONSTANT keyword to set a column to null. To set a column to null, do not specify that column at all. Oracle automatically sets that column to null when loading the row. The combination of CONSTANT and a value is a complete column specification.

 Setting a Column to the Datafile Record Number

Use the RECNUM keyword after a column name to set that column to the number of the logical record from which that row was loaded. Records are counted sequentially from the beginning of the first datafile, starting with record 1. RECNUM is incremented as each logical record is assembled. Thus it increments for records that are discarded, skipped, rejected, or loaded.

If you use the option SKIP=10, then the first record loaded has a RECNUM of 11.

 RECNUM

The combination of column name and the RECNUM keyword is a complete column specification.

column_name  RECNUM

 Setting a Column to the Current Date

A column specified with SYSDATE gets the current system date, as defined by the SQL language SYSDATE function. See the section "DATE Datatype" in  Oracle7 Server SQL Language Reference Manual.

SYSDATE

The combination of column name and the SYSDATE keyword is a complete column specification.

column_name  SYSDATE

The database column must be of type CHAR or DATE. If the column is of type CHAR, then the date is loaded in the form 'dd-mon-yy.' After the load, it can be accessed only in that form. If the system date is loaded into a DATE column, then it can be accessed in a variety of forms that include the time and the date.

A new system date/time is used for each array of records inserted in a conventional path load and for each block of records loaded on the direct path.

 Setting a Column to a Unique Sequence Number

The SEQUENCE function ensures a unique value for a particular column. SEQUENCE increments for each record that is loaded or rejected. It does not increment for records that are discarded or skipped.

It takes two optional arguments. The first argument is the starting value. The second, optional argument, is the increment. If the start point is a positive integer n, the first row inserted has a value of n for that column. The values of successive rows are increased by the increment. However, both the starting value and the increment default to 1.

SEQUENCE

The combination of column name and the SEQUENCE function is a complete column specification.

 where:

SEQUENCE	Use the SEQUENCE function to determine the value for a column.

n	The sequence starts with the integer value n. The value must be positive or zero. Default value is 1.

COUNT	The sequence starts with the number of rows already in the table, plus the increment.

MAX	The sequence starts with the current maximum value for the column, plus the increment.

increment	The sequence is incremented by this amount for each successive row. The default increment is 1. The increment must be positive.

If a row is rejected (that is, it has a format error or causes an Oracle error), the generated sequence numbers are not reshuffled to mask this. If four rows are assigned sequence numbers 10, 12, 14, and 16 in a particular column, and the row with 12 is rejected; the three rows inserted are numbered 10, 14, and 16, not 10, 12, 14. This allows the sequence of inserts to be preserved despite data errors. When you correct the rejected data and reinsert it, you can manually set the columns to agree with the sequence.

Case 3 shows the SEQUENCE function in use.

 Generating Sequence Numbers for Multiple Tables

Because a unique sequence number is generated for each logical input record, rather than for each table insert, the same sequence number can be used when inserting data into multiple tables. This is frequently useful behavior. Case 3 illustrates this situation.

Sometimes, you might want to generate different sequence numbers for each INTO TABLE clause. For example, your data format might define three logical records in every input record. In that case, you can use three INTO TABLE clauses, each of which inserts a different part of the record into the same table.

To generate sequence numbers for these records, you must generate unique numbers for each of the three inserts. There is a simple technique to do so. Use the number of table-inserts per record as the sequence increment and start the sequence numbers for each insert with successive numbers.

 Example

Suppose you want to load the following department names into the DEPT table. Each input record contains three department names, and you want to generate the department numbers automatically.

Accounting     Personnel      Manufacturing

Shipping       Purchasing     Maintenance

...

You could use the following control file to generate unique department numbers:

INTO TABLE dept

(deptno  sequence(1, 3),

 dname   position(1:14) char)

INTO TABLE dept

(deptno  sequence(2, 3),

 dname   position(16:29) char)

INTO TABLE dept

(deptno  sequence(3, 3),

 dname   position(31:44) char)

The first INTO TABLE clause generates department number 1, the second number 2, and the third number 3. They all use 3 as the sequence increment (the number of department names in each record).

This control file loads Accounting as department number 1, Personnel as 2, and Manufacturing as 3. The sequence numbers are then incremented for the next record, so Shipping loads as 4, Purchasing as 5, and so on.

 ________________________________________

Specifying Datatypes

This section describes SQL*Loader's datatypes and explains how they are converted to the Oracle datatypes.

 Datatype Conversions

The datatype specifications in the control file tell SQL*Loader how to interpret the information in the datafile. The server defines the datatypes for the columns in the database. The link between these two is the column name specified in the control file.

SQL*Loader extracts data from a field in the input file, guided by the datatype specification in the control file. SQL*Loader then sends the field to the server to be stored in the appropriate column (as part of an array of row inserts). The server does any data conversion necessary to store the data in the proper internal format. The "Data Conversions and Datatype Specifications" section beginning contains diagrams that illustrate these points.

The datatype of the data in the file does not necessarily have to be the same as the datatype of the column in the Oracle table. Oracle automatically performs conversions, but you need to ensure that the conversion makes sense and does not generate errors. For instance, when a datafile field with datatype CHAR is loaded into a database column with datatype NUMBER, you must make sure that the contents of the character field represent a valid number.

Note: SQL*Loader does not contain datatype specifications for Oracle internal datatypes such as NUMBER or VARCHAR2. SQL*Loader's datatypes describe data that can be produced with text editors (character datatypes) and with standard programming languages (native datatypes). However, although SQL*Loader does not recognize datatypes like NUMBER and VARCHAR2, any data that Oracle is capable of converting may be loaded into these or other database columns.

 Native Datatypes

Some datatypes consist entirely of binary data or contain binary data in their implementation. See page 4 - 4 for a discussion of binary vs. character data. These non-character datatypes are the native datatypes:

INTEGER	ZONED  SMALLINT	VARCHAR  FLOAT	GRAPHIC  DOUBLE	GRAPHIC EXTERNAL  BYTEINT	VARGRAPHIC  (packed) DECIMAL	RAW  MLSLABEL (Trusted Oracle)

Because these datatypes contain binary data, most of them do not readily transport across operating systems. (See "Loading Data Across Different Operating Systems".) RAW data and GRAPHIC data are the exceptions. SQL*Loader does not attempt to interpret these datatypes, but simply stores them "as is".

Additional Information:  Native datatypes cannot be specified with delimiters. The size of the native datatypes INTEGER, SMALLINT, FLOAT, and DOUBLE are determined by the host operating system. Their size is fixed -- it cannot be overridden in the control file. (Refer to your operating-system-specific Oracle7 documentation for more details.) The sizes of the other native datatypes may be specified in the control file.

 INTEGER

The data is a fullword binary integer. If you specify start:end in the POSITION clause, end is ignored. The length of the field is the length of a fullword integer on your system. (Datatype LONG INT in C.) This length cannot be overridden in the control file.

INTEGER

SMALLINT

The data is a half-word binary integer. If you specify start:end in the POSITION clause, end is ignored. The length of the field is a half-word integer is on your system.

SMALLINT

Additional Information:  This is the SHORT INT datatype in the C programming language. One way to determine its length is to make a small control file with no data and look at the resulting log file. This length cannot be overridden in the control file. See your operating-system-specific Oracle7 documentation for details.

 FLOAT

The data is a single-precision, floating-point, binary number. If you specify end in the POSITION clause, it is ignored. The length of the field is the length of a single-precision, floating-point binary number on your system. (Datatype FLOAT in C.) This length cannot be overridden in the control file.

FLOAT

 DOUBLE

The data is a double-precision, floating-point binary number. If you specify end in the POSITION clause, it is ignored. The length of the field is the length of a double-precision, floating-point binary number on your system. (Datatype DOUBLE or LONG FLOAT in C.) This length cannot be overridden in the control file.

DOUBLE

 BYTEINT

The decimal value of the binary representation of the byte is loaded. For example, the input character x"1C" is loaded as 28. The length of a BYTEINT field is always 1 byte. If POSITION(start:end) is specified, end is ignored.

The syntax for this datatype is

BYTEINT

An example is

(column1 position(1) BYTEINT,

 column2 BYTEINT,

 ...

)

ZONED

ZONED data is in zoned decimal format: a string of decimal digits, one per byte, with the sign included in the last byte. (In COBOL, this is a SIGN TRAILING field.) The length of this field is equal to the precision (number of digits) that you specify.

The syntax for this datatype is:

 where precision is the number of digits in the number, and scale (if given) is the number of digits to the right of the (implied) decimal point. For example:

sal  POSITION(32)  ZONED(8),

specifies an 8-digit integer starting at position 32.

 DECIMAL

DECIMAL data is in packed decimal format: two digits per byte, except for the last byte which contains a digit and sign. DECIMAL fields allow the specification of an implied decimal point, so fractional values can be represented.

The syntax for the this datatype is:

 where:

precision	Is the number of digits in the value. The character length of the field, as computed from digits, is (digits + 2) / 2, rounded down.

scale	Is the scaling factor, or number of digits to the right of the decimal point. Default is zero (indicating an integer). May be greater than the number of digits but may not be negative.

For example,

sal DECIMAL (7,2)

would load a number equivalent to +12345.67. In the data record, this field would take up 4 bytes, as shown in Figure 6 - 1. (The byte length of a DECIMAL field is equivalent to (N+1)/2, rounded up, where N is the number of digits in the value, and one is added for the sign.)

Figure 6 - 1. Packed Decimal Representation of +12345.67

RAW

The data is raw, binary data loaded "as is". It does not undergo character set conversion. If loaded into a RAW database column, it is not converted by Oracle. If it is loaded into a CHAR column, Oracle converts it to hexadecimal. It cannot be loaded into a DATE or number column.

The syntax for this datatype is

 The length of this field is the number of bytes specified in the control file. This length is limited only by the length of the target column in the database and by memory resources.

 GRAPHIC

The data is a string of double-byte characters (DBCS). Oracle does not support DBCS, however SQL*Loader reads DBCS as single bytes. Like RAW data, GRAPHIC fields are stored without modification in whichever column you specify.

The syntax for this datatype is

 For both GRAPHIC and GRAPHIC EXTERNAL, if you specify POSITION(start:end) you give the exact location of the field in the logical record. If you specify the length after the GRAPHIC (EXTERNAL) keyword, however, then you give the number of double-byte graphic characters. That value is multiplied by 2 to find the length of the field in bytes. If the number of graphic characters is specified, then any length derived from POSITION is ignored.

 GRAPHIC EXTERNAL

If the DBCS field is surrounded by shift-in and shift-out characters, use GRAPHIC EXTERNAL. This is identical to GRAPHIC, except that the first and last characters (the shift-in and shift-out) are not loaded.

The syntax for this datatype is:

 where:

GRAPHIC	Data is double-byte characters.

EXTERNAL	First and last characters are ignored.

graphic_char_length	Length in DBCS (see GRAPHIC, above)

For example, let [ ] represent shift-in and shift-out characters, and let # represent any double-byte character.

To describe ####, use "POSITION(1:4) GRAPHIC" or "POSITION(1) GRAPHIC(2)".

To describe [####], use "POSITION(1:6) GRAPHIC EXTERNAL" or "POSITION(1) GRAPHIC EXTERNAL(2)".

VARGRAPHIC

The data is a varying-length, double-byte character string. It consists of a length subfield followed by a string of double-byte characters (DBCS).

Additional Information:  The size of the length subfield is the size of the SQL*Loader SMALLINT datatype on your system (C type SHORT INT). See SMALLINT for more information.

The length of the current field is given in the first two bytes. This length is a count of graphic (double-byte) characters. So it is multiplied by two to determine the number of bytes to read.

The syntax for this datatype is

 A maximum length specified after the VARGRAPHIC keyword does not include the size of the length subfield. The maximum length specifies the number of graphic (double byte) characters. So it is also multiplied by two to determine the maximum length of the field in bytes.

The default maximum field length is 4K graphic characters, or 8 Kb (2 * 4K). It is a good idea to specify a maximum length for such fields whenever possible, to minimize memory requirements. See "Determining the Size of the Bind Array" for more details.

The POSITION clause, if used, gives the location of the length subfield, not of the first graphic character. If you specify POSITION(start:end), the end location determines a maximum length for the field. Both start and end identify single-character (byte) positions in the file. Start is subtracted from (end + 1) to give the length of the field in bytes. If a maximum length is specified, it overrides any maximum length calculated from POSITION.

If a VARGRAPHIC field is truncated by the end of the logical record before its full length is read, a warning is issued. Because a VARCHAR field's length is embedded in every occurrence of the input data for that field, it is assumed to be accurate.

VARGRAPHIC data cannot be delimited.

 VARCHAR

A VARCHAR field is a varying-length character string. It is considered a native datatype, rather than a character datatype because it includes binary data (a length). It consists of a length subfield followed by a character string of the given length.

Additional Information:  The size of the length subfield is the size of the SQL*Loader SMALLINT datatype on your system (C type SHORT INT). See SMALLINT for more information.

The syntax for this datatype is:

 A maximum length specified in the control file does not include the size of the length subfield. If you specify the optional maximum length after the VARCHAR keyword, then a buffer of that size is allocated for these fields.

The default buffer size is 4 Kb. Specifying the smallest maximum length that is needed to load your data can minimize SQL*Loader's memory requirements, especially if you have many VARCHAR fields. See "Determining the Size of the Bind Array" for more details.

The POSITION clause, if used, gives the location of the length subfield, not of the first text character. If you specify POSITION(start:end), the end location determines a maximum length for the field. Start is subtracted from (end + 1) to give the length of the field in bytes. If a maximum length is specified, it overrides any length calculated from POSITION.

If a VARCHAR field is truncated by the end of the logical record before its full length is read, a warning is issued. Because a VARCHAR field's length is embedded in every occurrence of the input data for that field, it is assumed to be accurate.

VARCHAR data cannot be delimited.

Conflicting Native Datatype Field Lengths

There are several ways to specify a length for a field. If multiple lengths are specified and they conflict, then one of the lengths takes precedence. A warning is issued when a conflict exists. The following rules determine which field length is used:

1.	The size of INTEGER, SMALLINT, FLOAT, and DOUBLE data is fixed. It is not possible to specify a length for these datatypes in the control file. If starting and ending positions are specified, the end position is ignored -- only the start position is used.

2.	If the length specified (or precision) of a DECIMAL, ZONED, GRAPHIC, GRAPHIC EXTERNAL, or RAW field conflicts with the size calculated from a POSITION(start:end) specification, then the specified length (or precision) is used.

3.	If the maximum size specified for a VARCHAR or VARGRAPHIC field conflicts with the size calculated from a POSITION(start:end) specification, then the specified maximum is used.

For example, if the native datatype INTEGER is 4 bytes long and the following field specification is given:

column1 POSITION(1:6) INTEGER

then a warning is issued, and the proper length (4) is used. In this case, the log file shows the actual length used under the heading "Len" in the column table:

Column Name             Position   Len  Term Encl Datatype

----------------------- --------- ----- ---- ---- ---------

COLUMN1                     1:6     4           INTEGER

 Character Datatypes

The character datatypes are CHAR, DATE, and the numeric EXTERNAL datatypes. These fields can be delimited and can have lengths (or maximum lengths) specified in the control file.

Additional Information: In addition, the MLSLABEL character datatype exists in Trusted Oracle. See the Trusted Oracle7 Server Administrator's Guide for more information on this datatype.

 CHAR

The data field contains character data. The length is optional and is taken from the POSITION specification if it is not present here. If present, this length overrides the length in the POSITION specification. If no length is given, CHAR data is assumed to have a length of 1.

The syntax for this datatype is:

 A field of datatype CHAR may also be variable-length delimited or enclosed. See "Specifying Delimiters".

 To Load LONG Data:      If the column in the database table is defined as LONG, you must explicitly specify a maximum length either with a length specifier on the CHAR keyword or with the POSITION keyword. This guarantees that a large enough buffer is allocated for the value, and is necessary even if the data is delimited or enclosed.

DATE

The data field contains character data that should be converted to an Oracle date using the specified date mask.

The syntax for this datatype is:

 For example:

LOAD DATA

INTO TABLE DATES (COL_A POSITION (1:15) DATE "DD-Mon-YYYY")

BEGINDATA

1-Jan-1991

1-Apr-1991 28-Feb-1991

The length specification is optional, unless a varying-length date mask is specified. In the example above, the date mask specifies a fixed-length date format of 11 characters. SQL*Loader counts 11 characters in the mask, and therefore expects a maximum of 11 characters in the field, so the specification works properly. But, with a specification such as

DATE "Month dd, YYYY"

the date mask is 14 characters, while the maximum length of a field such as

September 30, 1991

is 18 characters. In this case, a length must be specified. Similarly, a length is required for any Julian dates (date mask "J")--a field length is required any time the length of the date string could exceed the length of the mask (that is, the count of characters in the mask).

If an explicit length is not specified, it can be derived from the POSITION clause. It is a good idea to specify the length whenever you use a mask, unless you are absolutely sure that the length of the data is less than, or equal to, the length of the mask.

An explicit length specification, if present, overrides the length in the POSITION clause. Either of these overrides the length derived from the mask. The mask may be any valid Oracle date mask. If you omit the mask, the default Oracle date mask of "dd-mon-yy" is used. The length must be enclosed in parentheses and the mask in quotation marks. Case 3 has an example of the DATE datatype.

A field of datatype DATE may also be specified with delimiters. For more information, see "Specifying Delimiters".

A date field that consists entirely of whitespace produces an error unless NULLIF BLANKS is specified. For more information, see "Loading All-Blank Fields".

 MLSLABEL

This is a Trusted Oracle7 datatype that stores the binary format of an operating system label. For more information see the Trusted Oracle7 Server Administrator's Guide.

 Numeric External Datatypes

The numeric external datatypes are the numeric datatypes (INTEGER, FLOAT, DECIMAL, and ZONED) specified with the EXTERNAL keyword with optional length and delimiter specifications. These datatypes are the human-readable, character form of numeric data.

The data is a number in character form (not binary representation). As such, these datatypes are identical to CHAR and are treated identically, with one exception: The use of DEFAULTIF. If you want the default to be null, use CHAR. If you want it to be zero, use EXTERNAL.

Numeric EXTERNAL may be specified with lengths and delimiters, just like CHAR data. Length is optional, but if specified, overrides POSITION.

The syntax for this datatype is:

  FLOAT EXTERNAL Data Values

FLOAT EXTERNAL data can be given in either scientific or regular notation. Both "5.33" and "533E-2" are valid representations of the same value.

 Specifying Delimiters

The boundaries of CHAR, DATE, MLSLABEL, or numeric EXTERNAL fields may also be marked by specific delimiter characters contained in the input data record. You indicate how the field is delimited by using a delimiter specification after specifying the datatype.

Delimited data can be TERMINATED or ENCLOSED.

 TERMINATED Fields

TERMINATED fields are read from the starting position of the field up to, but not including, the first occurrence of the delimiter character. If the terminator delimiter is found in the first column position, the field is null.

 TERMINATED BY WHITESPACE

If TERMINATED BY WHITESPACE is specified, data is read until the first occurrence of a whitespace character (space, tab, newline). Then the current position is advanced until no more adjacent whitespace characters are found. This allows field values to be delimited by varying amounts of whitespace.

 Enclosed Fields

Enclosed fields are read by skipping whitespace until a non-whitespace character is encountered. If that character is the delimiter, then data is read up to the second delimiter. Any other character causes an error.

If two delimiter characters are encountered next to each other, a single occurrence of the delimiter character is used in the data value. For example, 'DON''T' is stored as DON'T. However, if the field consists of just two delimiter characters, its value is null. You may specify a TERMINATED BY clause, an ENCLOSED BY clause, or both. If both are used, the TERMINATED BY clause must come first.

The syntax for delimiter specifications is:

 where:

TERMINATED	Data is read until first occurrence of a delimiter.

BY	This is an optional keyword for readability.

WHITESPACE	Delimiter is any whitespace character, including linefeed, formfeed, or carriage return. (Only used with TERMINATED, not with ENCLOSED.)

OPTIONALLY	Data may be enclosed by the indicated character. If SQL*Loader finds a first occurrence of the character, it reads the data value until it finds the second occurrence. If the data is not enclosed, the data is read as a terminated field. If optional enclosure is specified, there must be a TERMINATED BY clause--either locally in the field definition, or globally, in the FIELDS clause.

ENCLOSED	The data value is found between two delimiters.

char	Delimiter is the single character char.

X'hex-byte'	Delimiter is the single character that has the value specified by hex-byte in the character encoding scheme, such as X`1F' (equivalent to 31 decimal). "X" must be uppercase.

AND   	This keyword specifies a trailing enclosure delimiter, which may be different from the initial enclosure delimiter. If the AND clause is not present, then the initial and trailing enclosure delimiters are the same.

Here are some examples, with samples of the data they describe:

TERMINATED BY ','	 a data string,

ENCLOSED BY '"'	"a data string"

TERMINATED BY ',' ENCLOSED BY '"'	"a data string",

ENCLOSED BY "(" AND ')'	(a data string)

Delimiter Marks in the Data

Sometimes the same punctuation mark that is a delimiter also needs to be included in the data. To make that possible, two adjacent delimiter characters are interpreted as a single occurrence of the character, and this character is included in the data. For example, this data:

(The delimiters are left paren's, ((, and right paren's, )).)

with this field specification:

ENCLOSED BY "(" AND ")"

puts the following string into the database:

The delimiters are left paren's, (, and right paren's, ).

For this reason, problems can arise when adjacent fields use the same delimiters. For example, the following specification:

field1 TERMINATED BY "/"

field2 ENCLOSED by "/"

the following data will be interpreted properly:

This is the first string/      /This is the second string/

But if field1 and field2 were adjacent, then the results would be incorrect, because

This is the first string//This is the second string/

would be interpreted as a single character string with a "/" in the middle of it, and that string would belong to field1.

 Maximum Length of Delimited Data

The default maximum length of delimited data is 255 bytes. So delimited fields can require significant amounts of storage for the bind array. It is a good idea to specify the smallest possible maximum value. See "Determining the Size of the Bind Array".

 Loading Trailing Blanks with Delimiters

Trailing blanks can only be loaded with delimited datatypes. If a data field is nine characters long and contains the value DANIELbbb, where bbb is three blanks, it is loaded into Oracle as "DANIEL" if declared as CHAR(9). If you want the trailing blanks, you could declare it as CHAR(9) TERMINATED BY `:', and add a colon to the datafile so that the field is DANIELbbb:. This field is loaded as "DANIEL   ", with the trailing blanks. For more discussion on whitespace in fields, see "Trimming of Blanks and Tabs".

 Conflicting Character Datatype Field Lengths

A control file can specify multiple lengths for the character-data  fields CHAR, DATE, MLSLABEL, and numeric EXTERNAL. If conflicting lengths are specified, one of the lengths takes precedence.  A warning is also issued when a conflict exists. This section explains which length is used.

 Predetermined Size Fields

If you specify a starting position and ending position for one of these fields, then the length of the field is determined by these specifications. If you specify a length as part of the datatype and do not give an ending position, the field has the given length. If starting position, ending position, and length are all specified, and the lengths differ; then the length given as part of the datatype specification is used for the length of the field.

For example, if

position(1:10) char(15)

is specified, then the length of the field is 15.

 Delimited Fields

If a delimited field is specified with a length, or if a length can be calculated from the starting and ending position, then that length is the maximum length of the field. The actual length can vary up to that maximum, based on the presence of the delimiter. If a starting and ending position are both specified for the field, and a field length is specified in addition; then the specified length value overrides the length calculated from the starting and ending position.

If the expected delimiter is absent and no maximum length has been specified, then the end of record terminates the field. If TRAILING NULLCOLS is specified, remaining fields are null. If either the delimiter or the end of record produce a field that is longer than the specified maximum, SQL*Loader generates an error.

 Date Field Masks

The length of a date field depends on the mask, if a mask is specified. The mask provides a format pattern, telling SQL*Loader how to interpret the data in the record. For example, if the mask is specified as:

"Month dd, yyyy"

then "May 3, 1991" would occupy 11 character positions in the record, while "January 31, 1992" would occupy 16.

If starting and ending positions are specified, however, then the length calculated from the position specification overrides a length derived from the mask. A specified length such as "DATE (12)" overrides either of those. If the date field is also specified with terminating or enclosing delimiters, then the length specified in the control file is interpreted as a maximum length for the field.

 MLSLABEL Field Masks

These are Trusted Oracle7 masks. For more information, see the Trusted Oracle7 Server Administrator's Guide.

 ________________________________________

Loading Data Across Different Operating Systems

When a datafile is created on one operating system that is to be loaded under a different operating system, the data must be written in a form that the target system can read. For example, if the source system has a native, floating-point representation that uses 16 bytes, and the target system's floating-point numbers are 12 bytes; then there is no way for the target system to directly read data generated on the source system. One solution is to load data across a SQL*Net link, taking advantage of the automatic conversion of datatypes. This is the recommended approach, whenever feasible.

In general, the problems of inter-operating system loads occur with the native datatypes. Sometimes, it is possible to get around them by padding a field with zeros to lengthen it, or reading only part of the field to shorten it. (For example, when an 8-byte integer is to be read on a system that uses 6-byte integers, or vice versa.) Frequently, however, problems of incompatible byte-ordering, or incompatible implementations of the datatypes, make even this approach unworkable.

In the absence of a SQL*Net link, it is a good idea to use only the CHAR, DATE, and NUMERIC EXTERNAL datatypes. Datafiles written in this manner are longer than those written with native datatypes. They take more time to load, but they transport most readily across operating systems. However, where incompatible byte-ordering is an issue, special filters may still be required to reorder the data.

 Trusted Oracle7

For information specific to Trusted Oracle7, see the Trusted Oracle7 Server Administrator's Guide.

 ________________________________________

Determining the Size of the Bind Array

The determination of bind array size pertains to SQL*Loader's conventional path option. It does not apply to the direct path option. Because the direct path formats database blocks directly, rather than using Oracle's SQL interface, it does not use a bind array.

SQL*Loader uses the SQL array-interface option to transfer data to the RDBMS. Multiple rows are read at one time and stored in the bind array. When SQL*Loader sends Oracle an INSERT command, the entire array is inserted at one time. After the rows in the bind array are inserted, a COMMIT is issued.

 Minimum Requirements

The bind array has to be large enough to contain a single row. If the maximum row length exceeds the size of the bind array, as specified by the BINDSIZE parameter, SQL*Loader generates an error. Otherwise, the bind array contains as many rows as can fit within it, up to the limit set by the value of the ROWS parameter. The BINDSIZE parameter is described, the ROWS parameter.

Although the entire bind array need not be in contiguous memory, the buffer for each field in the bind array must occupy contiguous memory. If the operating system cannot supply enough contiguous memory to store a field, SQL*Loader generates an error.

 Performance Implications

To minimize the number of calls to Oracle and maximize performance, large bind arrays are preferable. In general, you gain large improvements in performance with each increase in the bind array size up to 100 rows. Increasing the bind array size above 100 rows generally delivers more modest improvements in performance. So the size (in bytes) of 100 rows is typically a good value to use. The remainder of this section details the method for determining that size.

In general, any reasonably large size will permit SQL*Loader to operate effectively. It is not usually necessary to perform the detailed calculations described in this section. This section should be read when maximum performance is desired, or when an explanation of memory usage is needed.

 Specifying Number of Rows vs. Size of Bind Array

When you specify a bind array size using the command line's BINDSIZE parameter (refer to chapter 7 of this guide) or the control file's OPTIONS clause (page 6 - 10), you impose an upper limit on the bind array. The bind array never exceeds that maximum.

As part of its initialization, SQL*Loader determines the space required to load a single row. If that size is too large to fit within the specified maximum, the load terminates with an error.

SQL*Loader then multiplies that size by the number of rows for the load, whether that value was specified with the command-line ROWS parameter (page 9 - 9) or the control file's OPTIONS clause (page 6 - 10). If that size fits within the bind array maximum, the load continues--SQL*Loader does not try to expand the number of rows to reach the maximum bind array size. That is, if the number of rows and the maximum bind array size are both specified, SQL*Loader always uses the smaller value for the bind array.

If the maximum bind array size is too small to accommodate the initial number of rows, SQL*Loader uses a smaller number of rows that fits within the maximum.

 Calculations

The bind array's size is equivalent to the number of rows it contains times the maximum length of each row. The maximum length of a row is equal to the sum of the maximum field lengths, plus overhead.

bind array size = (number of rows) * (maximum row length)

where:

(maximum row length) = SUM(fixed field lengths) +

SUM(maximum varying field lengths) +

SUM(overhead for varying length fields)

Many fields do not vary in size. These fixed-length fields are the same for each loaded row. For those fields, the maximum length of the field is the field size, in bytes, as described in "Specifying Datatypes". There is no overhead for these fields.

The fields that can vary in size from row to row are

VARCHAR                VARGRAPHIC

CHAR                   DATE

numeric EXTERNAL

The maximum length of these datatypes is described in "Specifying Datatypes". The maximum lengths describe the number of bytes, or character positions, that the fields can occupy in the input data record. That length also describes the amount of storage that each field occupies in the bind array, but the bind array includes additional overhead for fields that can vary in size.

When the character datatypes (CHAR, DATE, and numeric EXTERNAL) are specified with delimiters, any lengths specified for these fields are maximum lengths. When specified without delimiters, the size in the record is fixed, but the size of the inserted field may still vary, due to whitespace trimming. So internally, these datatypes are always treated as varying-length fields--even when they are fixed-length fields.

A length indicator is included for each of these fields in the bind array. The space reserved for the field in the bind array is large enough to hold the longest possible value of the field. The length indicator gives the actual length of the field for each row.

In summary:

bind array size =

    (number of rows) * (  SUM(fixed field lengths)

                        + SUM(maximum varying field lengths)

                        + ( (number of varying length fields)

                             * (size of length-indicator) )

                        )

 Determining the Size of the Length Indicator

On most systems, the size of the length indicator is two bytes. On a few systems, it is three bytes. To determine its size, use the following control file:

OPTIONS (ROWS=1)

LOAD DATA

INFILE *

APPEND

INTO TABLE DEPT

(deptno POSITION(1:1) CHAR)

BEGINDATA

a

This control file "loads" a one-character field using a one-row bind array. No data is actually loaded, due to the numeric conversion error that occurs when "a" is loaded as a number. The bind array size shown in the log file, minus one (the length of the character field) is the value of the length indicator.

Note: A similar technique can determine bind array size without doing any calculations. Run your control file without any data and with ROWS=1 to determine the memory requirements for a single row of data. Multiply by the number of rows you want in the bind array to get the bind array size.

 Calculating the Size of Field Buffers

The following tables summarize the memory requirements for each datatype. "L" is the length specified in the control file. "P" is precision. "S" is the size of the length indicator. For more information on these values, see "Specifying Datatypes" starting.

Datatype	Size

INTEGR

OS-dependent

SMALLINT

FLOAT

DOUBLE

Table 6 - 1.  Invariant fields

Datatype	Default Size	Specified Size

------------------------------------------------------------------------

(packed) DECIMAL	None	(P+1)/2, rounded up

ZONED	None	P

RAW	None	L

CHAR (no delimiters)	1

L+S

DATE (no delimiters)	None

numeric EXTERNAL (no delimiters)	None

MLSLABEL	None

Table 6 - 2.  Non-graphic fields

Datatype	Default Size	Length Specified	Length Specified

with POSITION	with DATATYPE

GRAPHIC	None	L	2*L

GRAPHIC	None	L - 2	2*(L-2)

RXTERNAL

VARGRAPGIC	4Kb*2	L+S	(2*L)+S

Table 6 - 3.  Graphic Fields

Datatype	Default Size	Maximum Length

Specified (L)

VARCHAR	4Kb	L+S

CHAR (delimited)

DATE (delimited)

numeric EXTERNAL	255	L+S

(delimited)

MLSLABEL (delimited)

Table 6 - 4.  Variable-length fields

 Minimizing Memory Requirements for the Bind Array

Pay particular attention to the default sizes allocated for VARCHAR, VARGRAPHIC, and the delimited forms of CHAR, DATE, and numeric EXTERNAL fields. They can consume enormous amounts of memory--especially when multiplied by the number of rows in the bind array. It is best to specify the smallest possible maximum length for these fields. For example:

CHAR(10) TERMINATED BY ","

uses (10 + 2) * 64 = 768 bytes in the bind array, assuming that the length indicator is two bytes long. However:

CHAR TERMINATED BY ","

uses (255 + 2) * 64 = 16,448 bytes, because the default maximum size for a delimited field is 255. This can make a considerable difference in the number of rows that fit into the bind array.

 Multiple INTO TABLE Clauses

When calculating a bind array size for a control file that has multiple INTO TABLE clauses, act as if the INTO TABLE clauses are not present. Imagine all of the fields listed in the control file as one, long data structure -- that is, the format of a single row in the bind array.

If the same field in the data record is mentioned in multiple INTO TABLE clauses, it requires additional space in the bind array each time it is mentioned. So, it is especially important to minimize the buffer allocations for fields like these.

 Generated Data

Generated data is produced by the SQL*Loader functions CONSTANT, RECNUM, SYSDATE, and SEQUENCE. Such generated data does not require any space in the bind array.

 ________________________________________

Setting a Column to Null or Zero

If you want all inserted values for a given column to be null, omit the column's specifications entirely. To set a column's values conditionally to null based on a test of some condition in the logical record, use the NULLIF clause, described in this section. To set a numeric column to zero instead of NULL, use the DEFAULTIF clause, described next.

 DEFAULTIF Clause

Using DEFAULTIF on numeric data sets the column to zero when the specified field condition is true. Using DEFAULTIF on character data (CHAR, DATE, or numeric EXTERNAL) data sets the column to null. See "Specifying Field Conditions" for details on the conditional tests.

DEFAULTIF  field_condition

A column may have both a NULLIF clause and a DEFAULTIF clause, although this often would be redundant.

Note: The same effects can be achieved with the SQL string and the DECODE function. See "Applying SQL Operators to Fields".

 NULLIF Clause

Use the NULLIF keyword after the datatype and optional delimiter specification, followed by a condition. The condition has the same format as that specified for a WHEN clause. The column's value is set to null if the condition is true. Otherwise, the value remains unchanged.

NULLIF field_condition

The NULLIF clause may refer to the column that contains it, as in the following example:

COLUMN1  POSITION(11:17)  CHAR  NULLIF  (COLUMN1 = "unknown")

This specification may be useful if you want certain data values to be replaced by nulls. The value for a column is first determined from the datafile. It is then set to null just before the insert takes place. Case 6 includes more examples of the NULLIF clause.

Note: The same effect can be achieved with the SQL string and the NVL function. See "Applying SQL Operators to Fields".

 Null Columns at the End of a Record

When the control file specifies more fields for a record than are present in the record, SQL*Loader must determine whether the remaining (specified) columns should be considered null or whether an error should be generated. The TRAILING NULLCOLS clause, described, tells SQL*Loader how to proceed in this case.

 ________________________________________

Loading All-Blank Fields

Totally blank fields for numeric or DATE fields cause the record to be rejected. To load one of these fields as null, use the NULLIF clause with the BLANKS keyword, as described in the section "Comparing Fields to BLANKS". Case 6 shows how to load all-blank fields as null with the NULLIF clause.

If an all-blank CHAR field is surrounded by enclosure delimiters, then the blanks within the enclosures are loaded. Otherwise, the field is loaded as null. More details on whitespace trimming in character fields are presented in the following section.

 ________________________________________

Trimming of Blanks and Tabs

Blanks and tabs constitute whitespace. Depending on how the field is specified, whitespace at the start of a field (leading whitespace) and at the end of a field (trailing whitespace) may, or may not be, included when the field is inserted into the database. This section describes the way character data fields are recognized, and how they are loaded. In particular, it describes the conditions under which whitespace is trimmed from fields.

Note: Specifying PRESERVE BLANKS changes this behavior. See "Preserving Whitespace" for more information.

 Datatypes

The information in this section applies only to fields specified with one of the character-data datatypes :

•	CHAR datatype

•	DATE datatype

•	numeric EXTERNAL datatypes:

•	INTEGER EXTERNAL

•	FLOAT EXTERNAL

•	(packed) DECIMAL EXTERNAL

•	ZONED (decimal) EXTERNAL

 VARCHAR Fields

Although VARCHAR fields also contain character data, these fields are never trimmed. A VARCHAR field includes all whitespace that is part of the field in the datafile.

 Field Length Specifications

There are two ways to specify field length. If a field has a constant length that is defined in the control file, then it has a predetermined size. If a field's length is not known in advance, but depends on indicators in the record, then the field is delimited.

 Record Formats

When all of the fields in a record have known positions and lengths, then the record is in fixed format, as shown in Case 2. If the size or position of any fields in the record vary from record to record, then the record has a variable format, as shown in Case 1. When the record size also varies, then the file is in stream format. Variable format fields are specified with delimiters. Fixed format fields are specified with predetermined sizes and fixed positions.

 Predetermined Size Fields

Fields that have a predetermined size are specified with a starting position and ending position, or with a length, as in the following examples:

loc POSITION(19:31)

loc CHAR(14)

In the second case, even though the field's exact position is not specified, the field's length is predetermined.

 Delimited Fields

Delimiters are characters that demarcate field boundaries. Enclosure delimiters surround a field, like the quotes in:

"__aa__"

where "__" represents blanks or tabs. Termination delimiters signal the end of a field, like the comma in:

__aa__,

Delimiters are specified with the control clauses TERMINATED BY and ENCLOSED BY, as shown in the following examples:

loc POSITION(19) TERMINATED BY ","

loc POSITION(19) ENCLOSED BY '"'

loc TERMINATED BY "." OPTIONALLY ENCLOSED BY '|'

 Combining Delimiters with Predetermined Size

If predetermined size is specified for a delimited field, and the delimiter is not found within the boundaries indicated by the size specification; then an error is generated. For example, if you specify:

loc POSITION(19:31) CHAR TERMINATED BY ","

and no comma is found between positions 19 and 31 of the input record, then the record is rejected. If a comma is found, then it delimits the field.

 Relative Positioning of Fields

When a starting position is not specified for a field, it begins immediately after the end of the previous field. Figure 6 - 2 illustrates this situation when the previous field has a predetermined size.

Figure 6 - 2. Relative positioning after a fixed field

If the previous field is terminated by a delimiter, then the next field begins immediately after the delimiter, as shown in Figure 6 - 3.

Figure 6 - 3. Relative positioning after a delimited field

When a field is specified both with enclosure delimiters and a termination delimiter, then the next field starts after the termination delimiter, as shown in Figure 6 - 4. If a non-whitespace character is found after the enclosure delimiter, but before the terminator, then SQL*Loader generates an error.

Figure 6 - 4. Relative positioning after enclosure delimiters

 Leading Whitespace

In Figure 6 - 4, both fields are stored with leading whitespace. Fields do not include leading whitespace in the following cases:

•	when the previous field is terminated by whitespace, and no starting position is specified for the current field

•	when optional enclosure delimiters are specified for the field, and the enclosure delimiters are not present

These cases are illustrated in the following sections.

 Previous Field Terminated by Whitespace

If the previous field is TERMINATED BY WHITESPACE, then all the whitespace after the field acts as the delimiter. The next field starts at the next non-whitespace character. Figure 6 - 5 illustrates this case.

Figure 6 - 5. Fields terminated by whitespace

This situation occurs when the previous field is explicitly specified with the TERMINATED BY WHITESPACE clause, as shown in the example. It also occurs when you use the global FIELDS TERMINATED BY WHITESPACE clause.

 Optional Enclosure Delimiters

Leading whitespace is also removed from a field when optional enclosure delimiters are specified but not present.

Whenever optional enclosure delimiters are specified, SQL*Loader scans forward, looking for the first delimiter. If none is found, then the first non-whitespace character signals the start of the field. SQL*Loader skips over whitespace, eliminating it from the field. This situation is shown in Figure 6 - 6.

Figure 6 - 6. Fields terminated by optional enclosing delimiters

Unlike the case when the previous field is TERMINATED BY WHITESPACE, this specification removes leading whitespace even when a starting position is specified for the current field.

Note: If enclosure delimiters are present, leading whitespace after the initial enclosure delimiter is kept, but whitespace before this delimiter is discarded. See the first quote in FIELD1, Figure 6 - 6.

 Trailing Whitespace

Trailing whitespace is only trimmed from character-data fields that have a predetermined size. It is always trimmed from those fields.

 Enclosed Fields

If a field is enclosed, or terminated and enclosed, like the first field shown in Figure 6 - 6, then any whitespace outside the enclosure delimiters is not part of the field. Any whitespace between the enclosure delimiters belongs to the field, whether it is leading or trailing whitespace.

 Trimming Whitespace: Summary

Table 6 - 5 summarizes when and how whitespace is removed from input data fields when PRESERVE BLANKS is not specified. See the following section, "Preserving Whitespace", for details on how to prevent trimming.

Specification	Data	Result	Leading	Trailing

Whitespace	Whitespace

Present(1)	Present(1)

------------------------------------------------------------------------

Predetermined	__aa__	__aa	Y	N

Size

Terminated	__aa__,	__aa__	Y	Y(2)

Enclosed	"__aa__"	__aa__	Y	Y

Terminated	"__aa__",	__aa__	Y	Y

and

Enclosed

Optional	"__aa__",	__aa__	Y	Y

Enclosure

(present)

Optional	__aa__,	aa__	N	Y

Enclosure

(absent)

Previous Field	__aa__	aa(3)	N	(3)

Terminated by

Whitespace

(1) When an allow-blank field is trimmed, its value is null.

(2) Except for fields that are TERMINATED BY WHITESPACE

(3) Presence of trailing whitespace depends on the current field's

   specification, as shown by the other entries in the table.

Table 6 - 5. Trim Table

 ________________________________________

Preserving Whitespace

To prevent whitespace trimming in all CHAR, DATE, and NUMERIC EXTERNAL fields, you specify PRESERVE BLANKS in the control file. Whitespace trimming is described in the previous section, "Trimming of Blanks and Tabs".

 PRESERVE BLANKS Clause

PRESERVE BLANKS retains leading whitespace when optional enclosure delimiters are not present. It also leaves trailing whitespace intact when fields are specified with a predetermined size. This keyword preserves tabs and blanks.

For example, if the field

__aa__,

(where underscores represent blanks) is loaded with the following control clause:

TERMINATED BY ',' OPTIONALLY ENCLOSED BY '"'

then both the leading whitespace and the trailing whitespace are retained if PRESERVE BLANKS is specified. Otherwise, the leading whitespace is trimmed.

Note: The word BLANKS is not optional. Both words must be specified.

 Terminated by Whitespace

When the previous field is terminated by whitespace, then PRESERVE BLANKS does not preserve the space at the beginning of the next field, unless that field is specified with a POSITION clause that includes some of the whitespace. Otherwise, SQL*Loader scans past all whitespace at the end of the previous field until it finds a non-blank, non-tab character.

 ________________________________________

Applying SQL Operators to Fields

A wide variety of SQL operators may be applied to field data with the SQL string. This string may contain any combination of SQL expressions that are recognized by Oracle as valid for the VALUES clause of an INSERT statement. In general, any SQL function that returns a single value may be used. See the section "Expressions" in Chapter 4, "Operators and Functions", in the Oracle7 Server SQL Language Reference Manual.

The SQL string must be enclosed in double quotation marks. It appears after any other specifications for a given column. It is evaluated after any NULLIF or DEFAULTIF clauses, but before a DATE mask. It may not be used on RECNUM, SEQUENCE, CONSTANT, or SYSDATE fields. If the RDBMS does not recognize the string, the load terminates in error. If the string is recognized, but causes a database error, the row that caused the error is rejected.

 Referencing Fields

To refer to fields in the record, precede the field name with a colon (:). Field values from the current record are substituted. The following examples illustrate references to the current field:

field1 POSITION(1:6) CHAR "LOWER(:field1)"

field1 CHAR TERMINATED BY ','

       NULLIF ((1) = 'a') DEFAULTIF ((1)= 'b')

       "RTRIM(:field1)"

field1 CHAR(7) "TRANSLATE(:field1, ':field1', ':1')"

In the last example, only the :field1 that is not in single quotes is interpreted as a column name. For more information on the use of quotes inside quoted strings, see "Specifying Filenames and Database Objects".

Other fields in the same record can also be referenced, as in the following example:

field1 POSITION(1:4) INTEGER EXTERNAL

"decode(:field2, '22', '34', :field1)

 Common Uses

Loading external data with an implied decimal point:

field1 POSITION(1:9) DECIMAL EXTERNAL(8) ":field1/1000"

Truncating fields that could be too long:

field1 CHAR TERMINATED BY "," "SUBSTR(:field1, 1, 10)"

 Combinations of Operators

Multiple operators can also be combined, as in the following examples:

field1 POSITION(*+3) INTEGER EXTERNAL

       "TRUNC(RPAD(:field1,6,'0'), -2)"

field1 POSITION(1:8) INTEGER EXTERNAL

       "TRANSLATE(RTRIM(:field1),'N/A', '0')"

field1 CHARACTER(10)

       "NVL( LTRIM(RTRIM(:field1)), 'unknown' )"

 Use with Date Mask

When used with a date mask, the date mask is evaluated after the SQL string. A field specified as:

field1 DATE 'dd-mon-yy' "RTRIM(:field1)"

would be inserted as:

TO_DATE(RTRIM(<field1_value>), 'dd-mon-yyyy')

 Interpreting Formatted Fields

It is possible to use the TO_CHAR operator to store formatted dates and numbers. For example:

field1 ... "TO_CHAR(:field1, '$09999.99')"

could store numeric input data in formatted form, where field1 is a character column in the database. This field would be stored with the formatting characters (dollar sign, period, and so on) already in place.

You have even more flexibility, however, if you store such values as numeric quantities or dates. You can then apply arithmetic functions to the values in the database, and still select formatted values for your reports.

The SQL string is used in Case 7 (page 5 - 21) to load data from a formatted report.


CHAPTER 7. SQL*LOADER COMMAND-LINE REFERENCE

This chapter shows you how to run SQL*Loader with command-line parameters. The following subjects are discussed:

•	invoking SQL*Loader (page 7 - 2)

•	command-line parameters (page 7 - 4)

For a list of changes and enhancements to recent versions of SQL*Loader, refer to Appendix A, "Changes in the Oracle7 Utilities".

 ________________________________________

The SQL*Loader Command

You invoke SQL*Loader with the name of the SQL*Loader utility on your system followed by arguments.

Additional Information:  The name of the SQL*Loader utility is operating system dependent. The following examples use the name, "sqlldr". To find the name of the SQL*Loader utility on your system, see your operating system-specific Oracle7 documentation.

If you invoke SQL*Loader with no arguments, SQL*Loader returns a summary of the arguments and default values. The following example showsdefault values that are the same on all operating systems.

sqlldr

...

Valid Keywords:

    userid -- Oracle username/password

   control -- Control file name

       log -- Log file name

       bad -- Bad file name

      data -- Data file name

   discard -- Discard file name

discardmax -- Number of discards to terminate the load

(Default all)

      skip -- Number of logical records to skip

(Default 0)

      load -- Number of logical records to load

(Default all)

    errors -- Number of errors to terminate the load

(Default 50)

      rows -- Number of rows in conventional path bind array

or between direct path data saves

(Default: Conventional Path 64, Direct path all)

  bindsize -- Size of conventional path bind array in bytes

(System-dependent default)

    silent -- Suppress messages during run

(header, feedback, errors, discards)

    direct -- Use direct path

(Default FALSE)

   parfile -- Parameter file name

  parallel - Perform parallel load

(Default FALSE)

      file - File to allocated extents from

You can specify command-line parameters either by position or by keyword. An example of the former is:

SQLLDR scott/tiger foo

An example of the latter is:

SQLLDR CONTROL=foo USERID=scott/tiger

You may specify parameters by position before parameters specified by keywords, but not after. For example:

SQLLDR scott/tiger CONTROL=foo LOG=logfile

is allowed, but:

SQLLDR scott/tiger CONTROL=foo logfile

is not, even though the position of the parameter logfile is correct.

Arguments follow the command and are optionally separated by commas. They may be entered in two ways:

•	in any order, using a keyword to identify the argument

•	in a predefined order, without keywords

For example, the following two command lines are equivalent:

SQLLDR CONTROL=foo.ctl, LOG=bar.log, BAD=baz.bad, DATA=etc.dat,

USERID=scott/tiger, ERRORS=999, LOAD=2000, DISCARD=toss.dis,

DISCARDMAX=5

SQLLDR scott/tiger, foo.ctl, bar.log, baz.bad, etc.dat,

 	 toss.dis, 5, 0, 2000, 999

You may indicate arguments with keywords following positional arguments, but you may not place positional arguments after keywords. Thus, the following is a valid command:

SQLLDR jane/pride, jobctl.ctl, DISCARD=jobctl.dis

but the following is not:

SQLLDR USERID=jane/pride, jobctl.ctl, DISCARD=jobctl.dis

although the positional argument is in the right place.

 Specifying Arguments in the Control File

If the command line's length exceeds the size of the maximum command line on your system, you can put some of the command-line options in the control file, using the OPTIONS keyword.

Command-line arguments can also be specified in the control file with the OPTIONS clause. See page 6 - 10. They can also be specified in a separate file with the PARFILE parameter. See page 7 - 6. These options are useful for arguments that seldom change. Parameters specified in this manner can still be overridden from the command line.

 ________________________________________

Command-Line Parameters

This section describes each of the SQL*Loader command-line parameters.

Keyword 	Identifies	          Position

------------------------------------------------------------------------

BAD	Bad File	             4

BAD names the bad file created by SQL*Loader to store records that cause errors during insert or that are improperly formatted. If a filename is not specified, the name of the control file is used by default. If a file extension or file type is not specified, it defaults to BAD. This file has the same format as the input datafile. So it can be loaded by the same control file after appropriate updates or corrections are made.

A bad file filename specified on the command line becomes the bad file associated with the first INFILE statement in the control file. If the bad file filename was also specified in the control file, the command-line value overrides it.

BINDSIZE	Maximum sizes	             12

BINDSIZE specifies the maximum size of the bind array in bytes. The size of the bind array given by BINDSIZE overrides the default size (which is system dependent) and any size determined by ROWS. The bind array is discussed6 - 61.

CONTROL	Control File	             2

CONTROL names the control file that describes how to load data. If a file extension or file type is not specified, it defaults to CTL. If omitted, you are prompted for it.

DATA 	Datafile	             5

DATA names the datafile containing the data to be loaded. If a filename is not specified, the name of the control file is used by default. If a file extension or file type is not specified, it defaults to DAT. Data may be stored directly in the control file.

Keyword 	Identifies	          Position

------------------------------------------------------------------------

DIRECT	Data path	             14

DIRECT specifies the data path to use when loading the data. TRUE means that the direct path loads the data. FALSE means that the conventional path loads the data. If you omit this parameter, it defaults to FALSE. Direct path loads are discussed in Chapter 9.

DISCARD	Discard file	             6

DISCARD names an optional discard file created by SQL*Loader to store records that are neither rejected, nor inserted, into a table. If a filename is not specified, the name of the control file is used by default. If a file extension or file type is not specified, it defaults to DSC. This file has the same format as the input datafile. So it can be loaded by the same control file after appropriate updates or corrections are made.

A discard file filename specified on the command line becomes the discard file associated with the first INFILE statement in the control file. If the discard file filename was also specified in the control file, the command-line value overrides it.

DISCARDMAX	Discards to allow	             7

DISCARDMAX specifies the number of discard records that will terminate the load. The default value is all. To stop on the first discarded record, specify one (1).

ERRORS	Errors to allow	             10

ERRORS specifies the number of insert errors that will terminate the load. The default is 50. To stop on the first error, specify one (1). To specify that all errors be allowed, use a very high number.

LOAD	Records to load	             9

LOAD specifies the maximum number of logical records to load (after skipping the specified number of records). By default all records are loaded. No error occurs if fewer than the maximum number of records are found.

Keyword 	Identifies	          Position

------------------------------------------------------------------------

LOG	Log File	             3

LOG names the log file created by SQL*Loader to store information about the loading process. If a filename is not specified, the name of the control file is used by default. If a file extension or file type is not specified, it defaults to LOG.

PARFILE	Parameter File	             15

PARFILE specifies the name of a file that contains other command-line parameters. For example, the command line could read:

SQLLDR PARFILE=example.par

and the parameter file could have the following contents:

userid=scott/tiger

control=example.ctl

errors=9999

log=example.log

Note: Although it is not usually important, on some systems it may be necessary to have no spaces around the equals sign ("=") in the parameter specifications.

PARALLEL	Parallel Load	             16

PARALLEL determines whether direct loads can operate in multiple concurrent sessions to load data into the same table. For more information on PARALLEL loads, see "Parallel Data Loading".

PFILE	File to Load Into	             17

The FILE parameter tells SQL*Loader what database file to allocate extents from. It is only used for a parallel load. By varying the value of the FILE parameter for different SQL*Loader processes, data can be loaded onto a system with minimal disk contention. For more information, see "Parallel Data Loading".

Keyword 	Identifies	          Position

------------------------------------------------------------------------

ROWS	Rows per commit	             11

In the conventional path, ROWS specifies the number of rows in the bind array. The default is 64. (The bind array is discussed.)

When using the direct path, ROWS identifies the number of rows you want to read from the datafile before doing a data save. The default is to save data once at the end of the load. For more information, see "Data Saves".

Because the direct load is optimized for performance, it uses buffers that are the same size and format as the system's I/O blocks. Only full buffers are written to the database, so the value of ROWS is approximate.

SILENT	Feedback mode	             13

When SQL*Loader begins, a header message like this one appears on the screen and is placed in the log file:

SQL*Loader:   Production on Wed Feb 24 15:07:23...

Copyright (c) Oracle Corporation...

As SQL*Loader executes, you receive feedback messages on the screen, like this:

Commit point reached - logical record count 20

SQL*Loader may also put data error messages like these in the logfile:

Record 4: Rejected - Error on table EMP

ORA-00001: duplicate key in index

You can suppress messages using the SILENT option on the command line. For example, you can suppress the header and feedback messages that normally appear on the screen with the following command-line argument:

SILENT=(HEADER, FEEDBACK)

Errors are also logged in the log file. Also, see the Oracle7 Server Messages and Codes Manual.

Use the appropriate keyword to suppress:

HEADER	Suppresses the SQL*Loader header messages that

normally appear on the screen. Header messages still

appear in the log file.

FEEDBACK	Suppresses the "commit point reached" feedback

messages that normally appear on the screen.

ERRORS	Suppresses the data error messages in the log file that

occur when a record generates an Oracle error that

causes it to be written to the bad file. A count of

rejected records still appears.

DISCARDS	Suppresses the messages in the log file for each record

written to the discard file.

ALL	All of the above.

Keyword 	Identifies	          Position

------------------------------------------------------------------------

SKIP	Records to skip	             8

This parameter continues loads that have been interrupted for some reason. It is used for all conventional loads, for single-table direct loads, and for multiple-table direct loads when the same number of records were loaded into each table. It is not used for multiple table direct loads when a different number of records were loaded into each table. See "Continuing Multiple Table Direct Loads" for more information.

USERID	Userid	             1

USERID gives your Oracle username and password. If omitted, you are prompted for it. If just a slash is used, USERID defaults to your operating system logon. A SQL*Net database specification string can be used for a conventional path load into a remote database. For more information on SQL*Net, see Understanding SQL*Net.


CHAPTER 8. SQL*LOADER COMMAND-LINE REFERENCE

When SQL*Loader begins execution, it creates a log file. The log file contains a detailed summary of the load.

Much of this information is written for a successful SQL*Loader execution. However, different errors result in different portions of the log being written. For example, errors found during parsing of the control file appear in the log file, while errors found on the command line do not. If the log file itself cannot be written, SQL*Loader run.

 ________________________________________

Header Information

The Header Section contains the following information:

•	date of the run

•	software version number

The following log file segment illustrates this section.

SQL*Loader: Version 7.1.3.0.0 - Production on Mon Nov 26...

Copyright (c) Oracle Corporation...

 ________________________________________

Global Information

The Global Information Section contains the following information:

•	names of all input/output files

•	echo of command-line arguments

•	continuation character specification

If the data is in the control file, then the data file is shown as "*".

Control File:   LOAD.CTL

Data File:      LOAD.DAT

Bad File:       LOAD.BAD

Discard File:   LOAD.DSC

(Allow 999 discards)

Number to load: ALL

Number to skip: 0

Errors allowed: 50

Bind array:     64 rows, maximum of 65336 bytes

Continuation:   1:1 = '*', in current physical record

Path used:      Conventional

 ________________________________________

Table Information

The Table Information Section repeats the following information for each table to be loaded:

•	table name

•	load conditions, if any. That is, whether to load every record or just those meeting WHEN-clause criteria.

•	INSERT, APPEND, or REPLACE specification

•	the following column information:

•	if found in data file, the position, length, datatype, and delimiter

•	if specified, RECNUM, SEQUENCE, or CONSTANT

•	if specified, DEFAULTIF, or NULLIF

is shown as "*".

Table EMP, loaded from every logical record.

Insert option in effect for this table: REPLACE

Column Name                   Position   Len  Term Encl Datatype

--------------------------------------   ---  ---- ---- ---------

EMPNO                               1:4     4           CHARACTER

ENAME                              6:15    10           CHARACTER

JOB                               17:25     9           CHARACTER

MGR                               27:30     4           CHARACTER

SAL                               32:39     8           CHARACTER

COMM                              41:48     8           CHARACTER

DEPTNO                            50:51     2           CHARACTER

Column EMPNO is NULL if EMPNO = BLANKS

Column MGR is NULL if MGR = BLANKS

Column SAL is NULL if SAL = BLANKS

Column COMM is NULL if COMM = BLANKS

Column DEPTNO is NULL if DEPTNO = BLANKS

 ________________________________________

Data File Information

The Data File Information Section appears only for data files with data errors, and gives the following information:

•	SQL*Loader/Oracle error for data records in error

•	records discarded

Rejected records and errors:

Data File LOAD.DAT -

Record 2: Rejected - Error on table EMP.

ORA-00001:  duplicate key in index

Record 8: Rejected - Error on table EMP, column DEPTNO.

ORA-01722:  invalid number

Record 3: Rejected - Error on table PROJ, column PROJNO.

ORA-01722:  invalid number

 ________________________________________

Table Load Information

The Table Load Information Section repeats the following information for each table that was loaded:

•	number of rows loaded

•	number of rows that qualified for loading but were rejected due to data errors

•	number of rows that were discarded because they met no WHEN-clause tests

•	number of rows whose relevant fields were all null

The following indexes on table EMP were processed:

Index EMPIX was left in Direct Load State due to

ORA-01452: cannot CREATE UNIQUE INDEX; duplicate keys found

Table EMP:

7 Rows successfully loaded.

2 Rows not loaded due to data errors.

0 Rows not loaded because all WHEN clauses were failed.

0 Rows not loaded because all fields were null.

 ________________________________________

Summary Statistics

The Summary Statistics Section displays the following data:

•	amount of space used:

•	for binary array (what was actually used, based on what was specified by BINDSIZE)

•	for other overhead (always required, independent of BINDSIZE)

•	cumulative load statistics. That is, for all data files, the number of records that were:

•	skipped

•	read

•	rejected

•	discarded

•	beginning/ending time of run

•	total elapsed time

•	total CPU time (includes all file I/O but may not include background Oracle CPU time)

For example:

Space allocated for bind array:	65336 bytes (64 rows)

Space allocated for memory besides bind array:	6470 bytes

Total logical records skipped:          0

Total logical records read:             7

Total logical records rejected:         0

Total logical records discarded:        0

Run began on Mon Nov 26 10:46:53 1990

Run ended on Mon Nov 26 10:47:17 1990

Elapsed time was:     00:00:15.62

CPU time was:         00:00:07.76


CHAPTER 9. SQL*LOADER DIRECT PATH LOADS

This chapter describes SQL*Loader's direct path load. The direct path loads data several times faster than the "conventional" loader. Direct loading achieves this performance gain by eliminating much Oracle overhead. It writes directly to the database files. The direct loader doesn't compete with other users for database resources so it can usually load data at close to disk speed. There are certain considerations for this method of access to the database files, including security and backup implications that are discussed in this chapter.

The following major topics are covered:

•	overview of data paths (page 9 - 2)

•	direct path loading (page 9 - 7)

•	maximizing performance of direct path loads (page 9 - 13)

For an example of loading with the direct path, see Case 6 on  page 5 - 19.

Additional Information:   You can use the direct path with Trusted Oracle7 just as you can with standard Oracle.

 ________________________________________

Overview of Data Paths

SQL*Loader provides two data paths for loading data:

•	the conventional path

•	the direct path

Figure 9 - 1 shows the difference in the way these two paths perform database writes. This section discusses these differences in detail. The following topics are covered:

•	how the conventional data path works

•	how the direct path works

•	when to use each path

•	conditions for loading

•	integrity constraints

 The Conventional Path

The conventional path uses the SQL command INSERT with the array interface to load data into database tables. This path is used by all Oracle tools and applications.

With conventional path loading, SQL*Loader competes equally with all other processes for buffer resources. This can slow downloads significantly. Extra overhead is added as SQL commands are generated, passed to Oracle, and processed.

Oracle looks for partially filled blocks and attempts to fill them on each insert. Although appropriate during normal use, this action can slow bulk loads dramatically .

 The Direct Path

The direct path is highly optimized for maximum data loading capability. Like the conventional path, the direct path option for SQL*Loader provides full support for media recovery.

Instead of filling a bind array buffer and passing it to Oracle with a SQL INSERT command, the direct path option creates data blocks that are already in Oracle database block format. These database blocks are then written directly to the database.

Internally, multiple buffers are used for the formatted data. While one buffer is being filled, multiple buffers are being written if asynchronous I/O is available on the host platform. This parallelism increases load performance.

Figure 9 - 1. Database Writes on Direct Path and Conventional Path

The direct path does make a few, fast calls to Oracle. At the beginning of the load, tables are locked and, the locks are released at the end. During the load, space management routines are used to get new extents when needed and to adjust the high-water mark. The high-water mark is described in "Data Saves".

Oracle calls are also used to sort the data and build the index. SQL calls are not performed anytime during the load.

The direct path option is faster than the conventional path for many reasons:

•	Partial blocks are not used, so no reads are needed to find them and fewer writes are performed.

•	SQL INSERT commands are not generated by SQL*Loader or processed by Oracle

•	The bind-array buffer is bypassed -- formatted database blocks are written directly.

•	The direct path calls Oracle to lock tables and indexes at the start of the load and releases them when the load is finished. The conventional path calls Oracle once for each array of rows to process a SQL INSERT statement.

•	Unlike the conventional path, the direct path option uses asynchronous I/O, if available, to perform these operations in parallel:

•	reading from input files

•	writing to database files

•	Processes using the direct path perform their own write I/O, instead of using Oracle's buffer cache with all other Oracle users. So the direct path does not contend for free buffers in the buffer cache.

•	The direct path's presorting option allows you to use high-performance sort routines that are native to your system or installation.

•	When the table to be loaded is empty, the presorting option eliminates the sort and merge phases of index-building -- the index is simply filled in as data arrives.

•	With the direct path, protection against instance failure does not require redo log file entries. So, if Oracle is operating in NOARCHIVELOG mode, no time is required to log the load. See "Instance Recovery with the Direct Path".

 When to Use the Direct Path

The direct path load has several distinct advantages. You should use the direct path load in the following situations:

•	You have a large amount of data to load in a short period of time, the direct path option can quickly load and index large amounts of data. The direct path option can load data into an empty or non-empty table.

•	You want to load data in PARALLEL, for maximum performance. See page 9 - 22.

•	You want to load data in a character set that cannot be supported in your current session, or when the conventional conversion to the database character set would cause errors.

 When to Use the Conventional Path

Because the direct path is many times faster than the conventional path, it is highly desirable to use the direct path. But there are times when the conventional path is preferred. You should use the conventional path in the following situations:

•	When accessing an indexed table concurrently with the load, or when applying inserts or updates to a non-indexed table concurrently with the load.

To use the direct path, SQL*Loader must have exclusive write access to the table and exclusive read-write access to any indexes.

•	When loading data with SQL*Net.

You cannot load data through the direct path with SQL*Net; unless both systems belong to the same family of computers, and both are using the same character set. Even then, load performance can be significantly impaired by network overhead.

•	When loading data into a clustered table.

Clustered tables cannot be loaded through the direct path.

•	When loading a relatively small number of rows into a large indexed table.

On the direct path, the existing index is copied when it is merged with the new index keys. If the existing index is very large and the number of new keys is very small, then the index copy time can offset the time saved by loading the data with the direct path.

•	When loading a relatively small number of rows into a large table with referential and column-check integrity constraints

Because these constraints cannot be applied to rows loaded on the direct path, they are disabled for the duration of the load. Then they are applied to the whole table when the load completes. The costs could outweigh the savings for a very large table and a small number of new rows.

•	When you want to apply SQL functions to data fields.

SQL functions are not available on the direct path. For more information on the SQL functions, see "Applying SQL Operators to Fields".

Conditions for Using Direct Path Loads

In addition to the general load conditions described9, the following conditions must be satisfied in order to use the direct path loading option:

•	The table cannot be clustered.

•	The table to be loaded cannot have any active transactions on it.

Use the SQL*DBA MONITOR TABLE command to get the object ID for the table you want to load. Then use the MONITOR LOCK command to find any locks on the table.

•	SQL strings are not used in the control file.

•	If the table is indexed, there cannot be any SELECT statements on that table.

It may be necessary to log off users that have SELECT statements on the table. The SQL*DBA MONITOR TABLE command shows you which Oracle users are accessing the table.

 Integrity Constraints

All integrity constraints are enforced for direct path loads, although not all at the same time. All constraints that can be checked without referring to other rows or tables, such as the NOT NULL constraint, are enforced during the load. Records that fail these constraints are rejected.

Integrity constraints that depend on other rows or tables, such as referential constraints, are disabled before a direct path load and must be re-enabled afterwards. If requested, SQL*Loader can re-enable them automatically at the end of the load. When the constraints are re-enabled, the entire table is checked. Any rows that fail this check are reported in the specified error table.

 Field Defaults on the Direct Path

DEFAULT column specifications defined in the database are not available when loading on the direct path. Fields for which default values are desired must be specified with the DEFAULTIF clause, described. If a DEFAULTIF clause is nor specified, and the filed is NULL, then a NULL value loads into the database.

 Loading into Synonyms

You can load data into a synonym for a table on the direct path, but the synonym must point directly to a table. It cannot be a synonym for a view or a synonym for another synonym.

 Exact VersionRequirement

Only the version of direct loader that matches the database version can be used to load directly into the database. For example, you cannot use version 7.1.2 direct loader to load into a version 7.1.3 database.

 ________________________________________

Direct Path Loading

This section shows you how to use SQL*Loader's direct path option.  It covers the following topics:

•	setting up for direct path loads

•	how direct path loads are specified

•	how indexes are built

•	estimating storage requirements for indexing

•	state of indexes after an unsuccessful load

•	using data saves for safety

•	recovery from media failures and instance failures

 Setting Up for Direct Path Loads

You need to run the setup script, CATLDR.SQL, to create the views needed for direct path loads. You need to perform this step only once. Usually, it is performed as part of database installation.

 Specifying a Direct Path Load

Direct path loads are specified with a command-line parameter.  (Case 6 gives an example.) Specify the following clause anywhere on the command line:

DIRECT=TRUE

 Building Indexes

With the conventional path, each index is updated every time a row is inserted. This method does not require temporary storage space, but takes time.

With the direct path, performance is improved by using temporary storage. After the data is loaded into the table, the new keys are copied to a temporary segment and sorted. The old index and the new keys are then merged to create the new index. The old index, temporary segment, and new index all require storage until the merge is complete. Then the old index and temporary segment are removed.

Note: If the data is presorted and the existing index is empty, a temporary segment is not required, and no merge occurs--the keys are put directly into the index. See "Maximizing Performance of Direct Path Loads" for  more information.

When multiple indexes are built, the temporary segments corresponding to each index exist simultaneously, in addition to the old indexes. The new keys are then merged with the old indexes, one index at a time. As each new index is created, the old index and the corresponding temporary segment are removed.

 Index Storage Requirements

The formula for calculating the amount of space needed for storing the index itself can be found in Chapter 7 "Managing the Size and Files of the Database" of the Oracle7 Server Administrator's Guide. Remember that two indexes exist until the load is complete: the old index and the new index.

 Temporary Segment Storage Requirements

The amount of temporary segment space needed for storing the new index keys (in bytes) can be estimated using the following formula:

1.3 * key_storage

where:

key_storage = (number_of_rows) *

              ( 10 + sum_of_column_sizes + number_of_columns )

The columns included in this formula are the columns in the index. There is one length byte per column, and 10 bytes per row are used for a rowid and additional overhead.

The constant 1.3 reflects the average amount of extra space needed for sorting. This value is appropriate for most randomly ordered data. If the data arrives in exactly opposite order, twice the key-storage space is required for sorting, and the value of this constant would be 2.0. That is the worst case.

If the data is fully sorted, only enough space to store the index  entries is required, and the value of this constant reduces to 1.0.  See "Presorting Data for Faster Indexing" for  more information.

 Indexes Left in Direct Load State

SQL*Loader may leave indexes in direct load state if a direct path load does not complete successfully.

Any SQL statement that tries to use an index that is in direct load state returns an error. The following conditions cause the direct path option to leave an index in direct load state:

•	SQL*Loader runs out of space for the index.

•	The data is not in the order specified by the SORTED INDEXES clause.

•	There is an instance failure while building the index.

•	There are duplicate keys in a unique index.

To determine if an index is in direct load state, you can execute a simple query:

SELECT INDEX_NAME, STATUS

FROM USER_INDEXES

WHERE TABLE_NAME = 'tablename';

If you are not the owner of the table, then search ALL_INDEXES or DBA_INDEXES instead of USER_INDEXES.

 Data  Saves

You can use data saves to protect against loss of data due to instance or media failure. All data loaded up to the last data save is protected against media failure and instance failure if you are operating in ARCHIVELOG mode, or against instance failure alone, if you are operating in NOARCHIVELOG mode. See "Recovery" for more information on media and instance failure.

Note: Indexes are not protected by a data save, because SQL*Loader usually does not build indexes until after data loading completes. (The only time indexes are built during the load is when presorted data is loaded into an empty table -- but these indexes are also unprotected.)

 Using the ROWS Parameter

The command-line parameter ROWS determines when data saves occur in direct path loads. The value you specify for ROWS is the number of rows you want SQL*Loader to read from the input file before saving inserts in the database.

The number of rows you specify for a data save is an approximate number. Direct loads always act on full data buffers that match the format of Oracle database blocks. So, the actual number of data rows saved is rounded up to a multiple of the number of rows in a database block.

SQL*Loader always reads the number of rows needed to fill a database block. Discarded and rejected records are then removed, and the remaining records are inserted into the database. So the actual number of rows inserted before a save is the value you specify, rounded up to the number of rows in a database block, minus the number of discarded and rejected records.

 Data Save Versus Commit

In a conventional load, ROWS is the number of rows to read before a commit. A direct load data save is similar to a conventional load commit, but it is not identical. The major differences are as follows:

•	Only full database blocks are written to the database. They are written to unused blocks beyond the table's "high-water mark" -- the maximum amount of storage space that the database has ever used for that table. The database saves the data by simply changing the table's high-water mark.

•	Internal resources are not released.

•	The transaction is not ended.

•	Indexes are not updated.

•	Data saves interrupt the flow of asynchronous I/O, which can reduce performance. See "Infrequent Data Saves" for more information on minimizing the performance impact.

 Recovery

SQL *Loader provides full support for data recovery when using the direct path option. There are two main types of recovery:

Media Recovery	Media recovery is recovering from the loss of a database file. You must operate in ARCHIVELOG mode in order to recover after a file has been lost.

Instance Recovery	Instance recovery is recovering from a system failure in which in-memory data was changed (but not written to disk) before the failure occurred. Oracle can always recover from instance failures, even if redo log files are not archived.

See Oracle7 Server Administrator's Guide for more information on recovery.

 Conventional Path Logging

When using the conventional path, all changes to the database are logged in the redo log file. In the event of instance failure, all changes can be recovered, up to the last commit point. If archiving is enabled, then changes can be recovered in the event of media failure, up to the last commit point.

 Instance Recovery with the Direct Path

Because SQL*Loader writes directly to the database files, all rows inserted up to the last data save are automatically present in the database files when the instance is restarted. Changes do not need to be recorded in the redo log file in order to make instance recovery possible.

If an instance failure occurs, the indexes being built may be left in direct load state. Drop and re-create any affected indexes before using the table or continuing the load. See "Indexes Left in Direct Load State" for more information on how to determine if an index has been left in direct load state.

 Media Recovery with the Direct Path

If redo log file archiving is enabled (you are operating in ARCHIVELOG mode), SQL*Loader logs loaded data when using the direct path, making media recovery possible. If redo log archiving is not enabled (you are operating in NOARCHIVELOG mode), then media recovery is not possible.

To recover a database file that was lost while it was being loaded, use the same method that you use to recover data loaded with the conventional path:

1.	Restore the most recent backup of the affected database file.

2.	Recover the tablespace using the RECOVER command. (See the Oracle7 Server Administrator's Guide for more information on the RECOVER command.)

 Loading LONG Data Fields

Data that is longer than SQL*Loader's maximum buffer size can be loaded on the direct path with either the PIECED option or by specifying the number of READBUFFERS. This section describes those two options.

 Loading Data as PIECED

The data can be loaded in sections with the pieced option if it is the last column of the logical record. The syntax for this specification is given.

Declaring a column as PIECED informs the direct path loader that the field may be processed in pieces, one buffer at once.

The following restrictions apply when declaring a column as PIECED:

•	This option is only valid on the direct path.

•	Only field per table may be PIECED.

•	The PIECED field must be the last field in the logical record.

•	The PIECED field may not be used in any WHEN, NULLIF, or DEFUALTIF clauses.

•	The PIECED field's region in the logical record must not overlap with any other field's region.

•	The PIECED corresponding database column may not be part of the index.

•	It may be possible to load a rejected record from the bad file if it contains a PIECED field.

For example, a PIECED filed could span 3 records. SQL*Loader loads the piece from the first record and then reuses the buffer for the second buffer. After loading the second piece, the buffer is reused for the third record. If an error is then discovered, only the third record is placed in the bad file because the first two records no longer exist in the buffer. As a result, the record in the bad file would not be valid.

 Using the READBUFFERS Parameter

For data that is not divided into separate sections, or not in the last column, READBUFFERS can be specified. With READBUFFERS a buffer transfer area can be allocated that is large enough to hold the entire logical record at one time.

READBUFFERS specifies the number of buffers to use during a direct path load. (A LONG can span multiple buffers.) The default value is four buffers. If the number of read buffers is too small, the following error results:

ORA-02374 ... No more slots for read buffer queue

The placement of the READBUFFERS parameter in the control file is shown.

Attention: Do not specify a value for READBUFFERS unless it becomes necessary, as indicated by ORA-2374. Values of READBUFFERS that are larger than necessary do not enhance performance. Instead, higher values unnecessarily increase system overhead.

 ________________________________________

Maximizing Performance for Direct Path Loads

You can control the time and temporary storage used during direct path loads. Guidelines are listed below; details on them are given in the remainder of this section.

To minimize time:

•	allocate I/O Buffers

•	preallocate storage space.

•	presort the data.

•	do infrequent data saves.

•	disable archiving of redo log files.

To minimize space:

•	When sorting data prior to the load, sort data on the index that requires the most temporary storage space.

•	Drop indexes and recreate them after the load.

 Allocating I/O Buffers

When using the direct path, it is a good idea to specify a large number of buffers, if your operating system provides for that capacity. Buffers are allocated with the I/O processing options string, described on  page 6 - 16.

On some systems, as many as 200 buffers are needed to keep the CPU busy. Otherwise, the CPU spends most of its time idling, waiting for I/O's to complete. If you can measure CPU utilization, you will achieve maximum performance of direct loads when the number of buffers allow the CPU to operate at 95% to 98% utilization.

Additional Information:   The procedure for allocating additional I/O buffers depends on your operating system. See your operating system-specific Oracle7 documentation for more information.

 Preallocating Storage for Faster Loading

SQL*Loader automatically adds extents to the table if necessary, but this process takes time. For faster loads into a new table, allocate the required extents when the table is created.

To calculate the space required by a table, see Chapter 7 "Managing the Size and Files of the Database" in the Oracle7 Server Administrator's Guide. Then use the INITIAL or MINEXTENTS clause in the SQL command CREATE TABLE to allocate the required space.

 Presorting Data for Faster Indexing

You can improve the performance of direct path loads by presorting your data on indexed columns. Presorting minimizes temporary storage requirements during the load. Presorting also allows you to take advantage of high-performance sorting routines that are optimized for your operating system or application.

If the data is presorted and the existing index is not empty, then presorting minimizes the amount of temporary segment space needed for the new keys. The sort routine appends each new key to the key list. Instead of requiring extra space for sorting, only space for the keys is needed. To calculate the amount of storage needed, use a sort factor of 1.0 instead of 1.3. For more information on estimating storage requirements, see "Temporary Segment Storage Requirements".

If presorting is specified and the existing index is empty, then maximum efficiency is achieved. The sort routines are completely bypassed, with the merge phase of index creation. The new keys are simply inserted into the index. Instead of having a temporary segment and new index existing simultaneously with the empty, old index, only the new index exists. So, temporary storage is not required, and time is saved.

 SORTED INDEXES Clause

The SORTED INDEXES clause identifies the indexes on which the data is presorted. This clause is allowed only for direct path loads. See Chapter 6, "SQL*Loader Control File Reference," for the syntax of this clause. See Case 6 for an illustration.

Generally, you specify only one index in the SORTED INDEXES clause, because data that is sorted for one index is not usually in the right order for another index. When the data is in the same order for multiple indexes, however, all of the indexes can be specified at once.

All indexes listed in the SORTED INDEXES clause must be created before you start the direct path load.

 Unsorted Data

If you specify an index in the SORTED INDEXES clause, and the data is not sorted for that index, then the index is left in direct load state at the end of the load. The data is present, but any attempt to use the index results in an error. Any index which is left in direct load state must be dropped and re-created after the load.

 Multiple Column Indexes

If you specify a multiple-column index in the SORTED INDEXES clause, the data should be sorted so that it is ordered first on the first column in the index, next on the second column in the index and so on.

For example, if the first column of the index is city, and the second column is last name; then the data should be ordered by name within each city, as in the following list:

Albuquerque	Adams

Albuquerque	Hartstein

Albuquerque	Klein

...	...

Boston	Andrews

Boston	Bobrowski

Boston	Heigham

...	...

 Choosing the Optimum Sort Order

For the best overall performance of direct path loads, you should presort the data based on the index that requires the most temporary segment space. For example, if the primary key is one numeric column, and the secondary key consists of three text columns, then you can minimize both sort time and storage requirements by presorting on the secondary key.

To determine the index that requires the most storage space, use the following procedure:

1.	For each index, add up the widths of all columns in that index.

2.	For a single-table load, pick the index with the largest overall width.

3.	For each table in a multiple table load, identify the index with the largest, overall width for each table. If the same number of rows are to be loaded into each table, then again pick the index with the largest overall width. Usually, the same number of rows are loaded into each table.

4.	If a different number of rows are to be loaded into the indexed tables in a multiple table load, then multiply the width of each index identified in step 3 by the number of rows that are to be loaded into that index. Multiply the number of rows to be loaded into each index by the width of that index and pick the index with the largest result.

 Infrequent Data Saves

Frequent data saves resulting from a small ROWS value adversely affect the performance of a direct path load. Because direct path loads can be many times faster than conventional loads, the value of ROWS should be considerably higher for a direct load than it would be for a conventional load.

During a data save, loading stops until all of SQL*Loader's buffers are successfully written. You should select the largest value for ROWS that is consistent with safety. It is a good idea to determine the average time to load a row by loading a few thousand rows. Then you can use that value to select a good value for ROWS.

For example, if you can load 20,000 rows per minute, and you do not want to repeat more than 10 minutes of work after an interruption, then set ROWS to be 200,000 (20,000 rows/minute * 10 minutes).

 Disabling MediaProtection

One way to speed a direct load dramatically is to disable media protection. There are two ways to do this. You can disable archiving, or you can specify that the load is UNRECOVERABLE. This section discusses both methods.

 Disabling Archiving

If a large volume of data is being loaded on a dedicated system, and redo log file archiving is normally enabled, then disabling archiving saves the time and space required to record data in the redo log file (see "Media Recovery with the Direct Path"). Perform the following steps:

1.	Shut down the database.

2.	Bring up the database without archiving (disables media protection).

3.	Load the data.

4.	Make a backup of the tablespace you loaded.

5.	Shutdown the database

6.	Bring up the database with archiving (re-enables media protection).

Note: This technique is not appropriate if other users are connected to Oracle and they need redo log file archiving for media protection.

 Specifying UNRECOVERABLE

Use UNRECOVERABLE to save time and space in the redo log file. An RECOVERABLE load does not record loaded data in the redo log file. Therefore, media recovery is disabled for the loaded table, although database changes by other users may continue to be logged.

Note: Because the loaded data is not archived, you may want to make a backup of the data after loading.

If media recovery becomes necessary on data that was loaded with the UNRECOVERABLE phrase, the data blocks that were loaded are marked as logically corrupted. To recover the data, drop and re-create the data. It is a good idea to do backups immediately after the load to preserve the otherwise unrecoverable data.

By default, a direct path load is UNRECOVERABLE. See "Control Syntax" for information on RECOVERABLE and UNRECOVERABLE.

If there are indexes on the table, then the index updates are logged, although the load is specified as UNRECOVERABLE. To avoid the index logging, either disable archiving the entire system, as described in the previous section, or drop the index before the load and re-create it afterwards, as described in the next section.

Note: You can specify UNRECOVERABLE only if the database is in ARCHIVELOG mode.

 Dropping Indexes

For both the conventional path and the direct path, SQL*Loader builds all existing indexes for a table. The only way to avoid building an index is to drop it prior to the load and re-create it afterwards.

Dropping and re-creating indexes is one way to save temporary storage while using the direct load facility. This action minimizes the amount of space required during the load, for the following reasons:

•	You can build multiple indexes one at a time, saving the temporary segment space that would otherwise be needed for each index.

•	Only one index segment exists when an index is built, instead of the three segments that temporarily exist when the new keys are merged into the old index to make the new index.

This approach is quite reasonable when the number of rows to be loaded is large compared to the size of the table. But if relatively few rows are added to a large table, then the time required to re-sort the indexes may be excessive. In such cases, it is usually better to make use of the space, if it is available.

 ________________________________________

Direct Loads, Integrity Constraints, and Triggers

With the conventional path, arrays of data are inserted with standard SQL statements -- integrity constraints and insert triggers are automatically applied. But when loading data on the direct path, some integrity constraints and all database triggers are disabled. This section discusses the implications of using direct path loads with respect to these features.

 Integrity Constraints

During a direct path load, some integrity constraints are automatically disabled. Others are not. For a description of the constraints, see Chapter 6 "Maintaining Data Integrity" of the Oracle7 Server Application Developer's Guide.

 Enabled Constraints

The constraints that remain in force are:

•	not null

•	unique

•	primary keys

Not Null constraints are checked at insertion time. Any row that violates this constraint is rejected. Unique constraints are verified when indexes are rebuilt at the end of the load. The index will be left in direct load state if a violation is detected. (Direct load state is explained.) A primary key constraint is merely a unique-constraint on a not-null column.

 Disabled Constraints

The following constraints are disabled:

•	check constraints

•	referential constraints (foreign keys)

 Rentable Constraints

When the load completes, the integrity constraints will be re-enabled automatically if the REENABLE clause is specified: The syntax for this clause is as follows:

The optional keyword DISABLED_CONSTRAINTS is provided for readability. If the EXCEPTIONS clause is included; the table must already exist and you must be able to insert into it. This table contains the rowids of all rows that violated one of the integrity constraints. It also contains constraint that was violated. See the Oracle7 Server SQL Language Reference Manual for instructions on how to create an exceptions table.

If the REENABLE clause is not used, then the constraints must be re-enabled manually. At that time, all rows in the table are verified. If Oracle finds any errors in the new data, error messages are produced. The names of violated constraints and the rowids of the bad data are placed in an exceptions table, if one is specified. See ENABLE in the Oracle7 Server SQL Language Reference Manual.

The SQL*Loader log file describes the constraints that were disabled, the ones that were re-enabled and what error, if any, prevented re-enabling of each constraint. It also contains the name of the exceptions table specified for each loaded table.

Warning: As long as bad data remains in the table, the integrity constraint cannot be successfully re-enabled.

Suggestion: Because referential integrity must be reverified for the entire table, performance may be improved by using the conventional path, instead of the direct path, when a small number of rows are to be loaded into a very large table.

 Database Insert Triggers

Table insert triggers are also disabled when a direct path load begins. After the rows are loaded and indexes rebuilt, any triggers that were disabled are automatically re-enabled. The log file lists all triggers that were disabled for the load. There should not be any errors re-enabling triggers.

Unlike integrity constraints, insert triggers are not reapplied to the whole table when they are enabled. As a result, insert triggers do not fire for any rows loaded on the direct path. When using the direct path, the application must ensure that any behavior associated with insert triggers is carried out for the new rows.

 Replacing Insert Triggers with Integrity Constraints

Applications commonly use insert triggers in order to implement integrity constraints. Most of these application insert triggers are simple enough that they can be replaced with Oracle's automatic integrity constraints.

 When Automatic Constraints Cannot Be Used

Sometimes an insert trigger cannot be replaced with Oracle's automatic integrity constraints. For example, if an integrity check is implemented with a table lookup in an insert trigger, then automatic check constraints cannot be used, because the automatic constraints can only reference constants and columns in the current row. This section describes two methods for duplicating the effects of such a trigger.

 Preparation

Before either method can be used, the table must be prepared. Use the following general guidelines to prepare the table:

1.	Before the load, add a one-character column to the table that marks rows as "old data" or "new data".

2.	Let the value of null for this column signify "old data", because null columns do not take up space

3.	When loading, flag all loaded rows as "new data"with SQL*Loader's CONSTANT clause.

After following this procedure, all newly loaded rows are identified, making it possible to operate on the new data without affecting the old rows.

 Using An Update Trigger

In most cases, you can use a database update trigger to duplicate the effects of an insert trigger. This method is the simplest. It can be used whenever the insert trigger does not raise any exceptions.

1.	Create an update trigger that duplicates the effects of the insert trigger.

Copy the trigger. Change all occurrences of "new.column_name" to "old.column_name".

2.	Replace the current update trigger, if it exists, with the new one

3.	Update the table, changing the "new data" flag to null, thereby firing the update trigger

4.	Restore the original update trigger, if there was one

Note: Depending on the behavior of the trigger, it may be necessary to have exclusive update access to the table during this operation, so that other users do not inadvertently apply the trigger to rows they modify.

 Duplicating the Effects of Exception Conditions

If the insert trigger can raise an exception, then more work is required to duplicate its effects. Raising an exception would prevent the row from being inserted into the table. To duplicate that effect with an update trigger, it is necessary to mark the loaded row for deletion.

The "new data" column cannot be used for a delete flag, because an update trigger cannot modify the column(s) that caused it to fire. So another column must be added to the table. This column marks the row for deletion. A null value means the row is valid. Whenever the insert trigger would raise an exception, the update trigger can mark the row as invalid by setting a flag in the additional column.

Summary:	When an insert trigger can raise an exception condition, its effects can be duplicated by an update trigger, provided:

•	two columns (which are usually null) are added to the table

•	the table can be updated exclusively (if necessary)

 Using a Stored Procedure

The following procedure always works, but it is more complex to implement. It can be used when the insert trigger raises exceptions. It does not require a second additional column; and, because it does not replace the update trigger, and it can be used without exclusive access to the table.

1.	Create a stored procedure that duplicates the effects of the insert trigger. Follow the general outline given below. (For implementation details, see the Cursor Management section of the PL/SQL User's Guide and Reference .)

•	declare a cursor for the table, selecting all the new rows

•	open it and fetch rows, one at a time, in a processing loop

•	perform the operations contained in the insert trigger

•	if the operations succeed, change the "new data" flag to null

•	if the operations fail, change the "new data" flag to "bad data"

2.	Run this procedure with the SQL*DBA EXECUTE command. (See the Oracle7 Server Administrator's Guide for details.)

3.	After running the procedure, check the table for any rows marked "bad data".

4.	Update or remove the bad rows.

5.	Re-enable the insert trigger.

 Permanently Disabled Triggers & Constraints

SQL*Loader needs to acquire several locks on the table to be loaded to disable triggers and constraints. If a competing process is enabling triggers or constraints at the same time that SQL*Loader is trying to disable them for that table, then SQL*Loader may not be able to acquire exclusive access to the table.

SQL*Loader attempts to handle this situation as gracefully as possible. It attempts to re-enable disabled triggers and constraints before exiting. However, the same table-locking problem that made it impossible for SQL*Loader to continue may also have made it impossible for SQL*Loader to finish enabling triggers and constraints. In such cases, triggers and constraints will remain permanently disabled until they are manually enabled.

Although such a situation is rare and unlikely, it is still possible. The best way to prevent it is to make sure that no applications are running that could enable triggers or constraints for the table, while the direct load is in progress.

If a direct load is aborted due to failure to acquire the proper locks, carefully check the log. It will show every trigger and constraint that was disabled, and each attempt to re-enable them. Any triggers or constraints that were not re-enabled by SQL*Loader should be manually enabled with the ENABLE clause described in the Oracle7 Server SQL Language Reference .

 Alternative: Partitioned Load

If triggers or integrity constraints pose a problem, but you want faster loading, you should consider a partitioned load. A partitioned load works on a multiple-CPU system. Divide the data set into separate partitions, and then load each part through different CPUs with the conventional path. The resulting load is faster than a single-CPU conventional load, although possibly not as fast as a direct load. But triggers fire, and integrity constraints are applied to the loaded rows.

 ________________________________________

Parallel Data Loading

SQL*Loader now permits multiple concurrent sessions to perform a direct path load into the same table. Multiple SQL*Loader sessions improve the performance of a direct path load given the available resources on your system.

 Restrictions

To load a table in parallel, the table must not be indexed.

 Initiating Multiple SQL*Loader Sessions

Each SQL*Loader session takes a different source file as input. In all sessions executing a direct load on the same table, you must specify the PARALLEL clause on the command line. The syntax of the PARALLEL clause is:

PARALLEL can be specified on the command line or in a parameter file. It can also be specified in the control file with the OPTIONS clause.

For example, to invoke three SQL*Loader direct path load sessions on the same table, you would execute the following commands at the operating system prompt:

SQLLOAD USERID=SCOTT/TIGER CONTROL=LOAD1.CTL DIRECT=TRUE PARALLEL=TRUE

SQLLOAD USERID=SCOTT/TIGER CONTROL=LOAD2.CTL DIRECT=TRUE PARALLEL=TRUE

SQLLOAD USERID=SCOTT/TIGER CONTROL=LOAD3.CTL DIRECT=TRUE PARALLEL=TRUE

The previous commands must be executed in separate sessions, or if permitted on your operating system, as separate background jobs. Note the use of multiple control files. This allows you to be flexible in specifying the files to use for the direct path load (see the example of one of the control files below).

Note: Indexes are not created during a parallel load. Any indexes must be created manually after the load completes. You can use the parallel index creation feature to speed the creation of large indexes after a parallel load.

When you use the PARALLEL clause, SQL*Loader creates temporary segments for each concurrent session and then merges the segments upon completion. The segment created from the merge is then added to the existing table in the database above the table's high water mark. The last extent used for each loader session is trimmed of any free space before being combined with the other extents of the SQL*Loader session. For a detailed description of direct path load with SQL*Loader, see the Oracle7 Server Utilities User's Guide.

Use of FILE Parameter

You can specify the database file from which the temporary segments are allocated with the FILE keyword in the OPTIONS clause for each table in the control file. You can also specify the FILE parameter on the command line of each concurrent SQL*Loader session, but then it will globally apply to all tables being loaded with that session.

 Use of OPTIONS Clause

It is recommended that each concurrent session use files located on different disks to allow for the maximum I/O throughput. You can specify the filename of any valid datafile in the table's tablespace with the FILE keyword of the OPTIONS clause. The following example illustrates a portion of one of the control files used for the SQL*Loader sessions in the previous example:

LOAD DATA

INFILE 'load1.dat'

INSERT INTO TABLE emp

OPTIONS(FILE='/dat/data1.dat')

(empno POSITION(01:04) INTEGER EXTERNAL NULLIF empno=BLANKS

...

Note: The FILE keyword is specified in a table-specific OPTIONS clause. That is, the OPTIONS clause is placed within an INTO TABLE statement, rather than before.

 Enabling Constraints After A Parallel Direct Path Load

Each SQL*Loader session attempts to re-enable constraints on a table after a direct path load. Each SQL*Loader session has a share lock on the table, however, so that another session cannot enable constraints before it is a finished. When the last session completes, its attempt to re-enable constraints succeeds.

Warning: There is a danger that some constraints may not be re-enabled after a direct path load, you should check the status of the constraint after completing the load to ensure that it was enabled properly.

 PRIMARY and UNIQUE KEY constraints

PRIMARY KEY and UNIQUE key constraints create indexes on a table when they are enabled, and subsequently can take a significantly long time to enable after a direct path loading session if the table is very large.

You should consider enabling these constraints manually after a load (and not specify the automatic enable feature). This allows you to manually create the required indexes in parallel to save time before enabling the constraint. See the section "Parallel Index Creation" in the Oracle7 Server Addendum, Release 7.1 for more information about creating indexes in parallel.


CHAPTER 10. INTRODUCTION TO SQL*DBA

The SQL*DBA utility helps database administrators manage and monitor a database. SQL*DBA performs the following tasks:

•	start and stop an Oracle instance

•	mount, dismount, open, and close an Oracle Server

•	monitor realtime use and performance of an Oracle Server

•	perform backup and recovery of database logs and data

•	execute SQL statements

•	execute PL/SQL statements

This chapter gives an overview of SQL*DBA's menu, command, and script-file interfaces.

Users with a graphical display device can also use the Oracle Server Manager instead of SQL*DBA to administer one or more local and remote databases. With Oracle Server Manager you "point-and-click" to manipulate database objects and carry out administrative tasks.

Oracle Server Manager is fully compatible with SQL*DBA. It supports the same commands, the same scripts, and the same monitors. For more information on Oracle Server Manager, see Appendix D, "Compatibility of SQL*DBA and Server Manger" and the Oracle Server Manager User's Guide.

 ________________________________________

Terminology

SQL*DBA is a powerful utility that allows you to perform many system administration tasks with menu choices, execute SQL and PL/SQL statements, and execute the special set of server and database administration commands supported by SQL*DBA and Server Manager. To clarify discussion of these features, the following terminology is used:

database operations	SQL*DBA's database operations are any database manipulations that can be performed with the SQL*DBA interface. Access to database operations is provided through menus, commands, and the operating system prompt.

interface operations	SQL*DBA's interface operations refer to the way you use the SQL*DBA interface to perform SQL*DBA database operations. This chapter describes the operation of the menu interface and the input window command editor.

operations	Where the context is clear, the term operations may mean either database operations or interface operations. A clear context is established by any description that discusses one or the other of these operations, but not both.

functions and operations	When both interface and database operations are discussed, the term functions is used for database operations, and the term operations is restricted to mean interface operations. This convention makes it possible to discuss "the menu operations required to perform a SQL*DBA function" without being unnecessarily wordy.

commands	Commands includes all the commands you can enter in SQL*DBA's input window. They include SQL commands, PL/SQL commands, and SQL*DBA commands. SQL*DBA commands are the special commands that are implemented in SQL*DBA. These commands typically access SQL*DBA functions that are not available in the SQL*DBA menus.

 ________________________________________

SQL*DBA Interfaces

This section discusses the methods for accessing SQL*DBA functions.

 Menu Interface and Input Window Editor

You invoke SQL*DBA by entering a command at the operating system prompt. (On a bit-mapped device, you may select an icon.) The parameter MODE=SCREEN puts SQL*DBA into screen mode. This is the default mode, so entering either of the following commands displays a menu of choices, an input window, and an output window:

SQLDBA

SQLDBA MODE=SCREEN

With this interface, SQL*DBA functions can either be selected from menus or invoked by issuing commands in the command window. Menu operations are described beginning. Instructions for using the input window begin.

Additional Information:  When running SQL*DBA in screen mode, your terminal has a default terminal type dependent upon your operating system. You may be able to override your default terminal type by setting an environment variable at the operating system prompt. For more information, see your operating system-specific Oracle7 documentation.

 Command Scripts

You can run a series of commands stored in a file. The file format and methods for doing so are described.

 Operating System Prompt

In addition, you may run scripts directly from the operating system prompt when you invoke SQL*DBA, bypassing the interactive interface. This method is described.

 Interactive Line Mode

If you enter

SQLDBA MODE=LINE

then SQL*DBA runs in line mode with the following prompt:

SQLDBA>

With this interface, all SQL and SQL*DBA commands are supported, except for monitor commands. (Commands are described in Chapter 12.) This interface exists only for backward compatibility. The use of the menu and command editor interface is recommended.

 ________________________________________

Using SQL*DBA

This section describes the basic methods for using SQL*DBA.

 Connecting to a Database

Regardless of which interface you use, most SQL*DBA functions require you first to connect to an Oracle Server with a username and password. (An obvious exception is the CONNECT function.)

The username INTERNAL is a special username that is supported only for backward compatibility. It is best to log in with the SYSOPER or SYSDBA privilege to perform special system operations.

 Privileged Operations

Some database operations available through SQL*DBA are privileged because they can have powerful effects on the database. For example, the commands STARTUP, SHUTDOWN, and CONNECT INTERNAL all require the appropriate system privileges.

These operations are limited to users who have been given both

•	access to use SQL*DBA and

•	the appropriate operating system privileges

These users should be limited in number and are assumed to be administrators.

Additional Information: See to your operating system-specific Oracle7 documentation for additional information about both types of access.

Any SQL*DBA function may be performed with SQL*DBA provided you have the necessary privileges. If you do not have the required system privileges, then the appropriate object privileges are needed. For example, if user SCOTT is using SQL*DBA and does not have the SELECT ANY TABLE privilege, then he must have SELECT access on the table NANCY.PAYROLL to query it.

 Using SQL*DBA in a Distributed Environment

If SQL*Net is also installed, SQL*DBA can connect to other databases on nodes of the communications network. Thus, you can use SQL*DBA to start an instance on a remote node. For more information on SQL*Net, see Understanding SQL*Net.

Use SET INSTANCE to give the database specification of the instance with which you want to work. This instance will be used for subsequent STARTUP, SHUTDOWN, MONITOR, and CONNECT commands, and all SQL statements that do not use explicit database specifications.

See the SET command and the SHOW command.

 ________________________________________

SQL*DBA Menus

This section describes general SQL*DBA menu operations. Detailed information on the menus that implement SQL and SQL*DBA commands are given in Chapter 11, "SQL*DBA Menus". SQL*DBA's commands are described in Chapter 12, "SQL*DBA Commands".

Additional Information:  You use the [Menu] operation to access the SQL*DBA menus. This operation is operating-system-dependent. If your terminal has a numeric keypad, the [Menu] operation is generally mapped to the zero-key. For more information, see your operating system-specific Oracle7 documentation.

 Help Menu

The help menu gives you current revision numbers, information on SQL*DBA functions, and a listing of SQL*DBA keyboard assignments.

Figure 10 - 1.  Help Menu

 About SQL*DBA      Shows current revisions of the Oracle server, SQL*DBA, and the windowing system (Oracle Toolkit) on which it runs.

 Help System      Provides an index of help topics that cover SQL*DBA functions.

 Show Keys      Gives a listing of SQL*DBA keyboard assignments.

 File Menu

Use the file menu to run SQL scripts, turn spooling on and off, and exit SQL*DBA.

Figure 10 - 2.  File Menu

 SQL Script      Lets you enter a filename for a script you want to run.

 Spool On      Enables output spooling. Lets you specify a file for SQL*DBA's output.

 Spool Off      Disables output spooling.

 Quit      Commits the current transaction, terminates the session, exits SQL*DBA, and returns control to the operating system.

Note: The Spool command does not show output on the monitor.

 Edit Menu

The edit menu provides access to SQL*DBA editing operations. All these commands work in the editing window. Some, like Copy, Previous Command, and Next Command, also work from the output window. The edit operations are discussed.

Figure 10 - 3.  Edit Menu

 Cut      Removes selected text and moves it to the clipboard.

 Copy      Copies selected text to the clipboard.

 Paste      Pastes the contents of the clipboard at the current cursor location.

 Clear      Erases the selected text. Does not affect the clipboard.

 Previous Command      Copies the previous command from the command history to the input window.

 Next Command      Copies the next command from the command history to the input window.

 Monitor Menu

The Monitor menu shown in Figure 10 - 4 lets you monitor the Oracle server and dynamically track the availability and use of resources. For a description of the monitors, see Chapter 13, "SQL*DBA Monitors".

Figure 10 - 4. Monitor Menu

 ________________________________________

Understanding the SQL*DBA Interface

Figure 10 - 5 shows the three major components of the SQL*DBA menu interface: the menu bar at the top of the screen, the output window in the middle, and the input window at the bottom. These components are discussed in the remainder of this section.

Figure 10 - 5. Major Interface Components

Menu Bar: The menu bar is the interface to SQL*DBA's menus. The main menu commands are listed at the top of the display. When a menu bar item is selected, a menu of choices appears.     Output Window: The next major segment of the display is the output window. This segment shows the results of all SQL*DBA operations, whether chosen from menus or given as commands in the input window. It also shows the submitted command, if entered from the input window, or the command-equivalent generated from a menu selection. Input lines are identified by a right angle bracket (>) in the first column.     Input Window: The bottom segment of the display is the input window. This window runs the command editor. You can enter any SQL*DBA, SQL, or PL/SQL commands in this window. Some commands are not available through menus and must be entered in this window.     The following SQL*DBA commands can only be entered through the input window:

DESCRIBE 	SET

EXECUTE 	SHOW

PRINT 	SPOOL

REMARK 	VARIABLE

See Chapter 12, "SQL*DBA Commands" for detailed descriptions of these SQL*DBA commands.

Scroll Bars: Vertical and horizontal scroll bars appear to the right and bottom of the windows. For instructions on using them, see "Using the Scroll Bars".      Menu Objects

This section describes the various objects you can manipulate as you use SQL*DBA's menus.

 Menu Bar

The main menu bar at the top of the display lists the major menus. When one of these items is selected, a pull-down menu appears with further choices, as shown in the following display:

Figure 10 - 6.  Pull Down Menu

 Menu Options

Menu options shown with a right-pointing triangle (>) bring up a submenu. For example, choosing the Shut Down option from the Instance menu shown above produces the following submenu:

Figure 10 - 7.  Submenu

Many menu choices bring up an alert box that lets you confirm your choice of actions, as shown in the following display:

Figure 10 - 8.  Alert Box

 Dialog Boxes and Fields

Many menu items bring up a dialog box so you can enter more information. Dialog boxes contain data entry fields. When the field you are entering must be filled in, the word MANDATORY will appear in the lower left-hand corner of the dialog. When a list box or list builder (described subsequently) is available, the word LIST appears in the lower left corner. These cues are shown in the following dialog box:

Figure 10 - 9.  Dialog Box

 Check Boxes

Dialog boxes also contain check boxes and radio buttons. Multiple options can be chosen from a set of check boxes like those shown below using [Select]. Check boxes are displayed with square brackets--"[ ]".

Figure 10 - 10.  Check Boxes

 Radio Buttons

Only one option can be selected from a set of radio buttons, as shown below. Using [Select] to choose one option deselects the others.Radio buttons are displayed with parentheses--"( )"

Figure 10 - 11.  Radio Buttons

 Data Entry Fields

Data entry fields allow you to type in a value. Many of them also allow you to select your items from a list of values by pressing [List] while in the field. For more information, see the "Key Mappings" and "Getting a List of Choices" under "Common Actions".

 ________________________________________

Using SQL*DBA

This section describes SQL*DBA's menu and command interface.

 SQL*DBA Operations

The operations listed below are assigned to physical keys for a particular display device. See your operating system-specific Oracle7 documentation to find out the usual mapping (that is, the table of assignments) for devices commonly in use on your system.

For information on how to change the key mapping, consult the Oracle7*Terminal User's Guide. The following operations are defined:

General Operations

[Show Keys] 	[Help]

[Menu]	[Cancel]

[Move Up] 	[Move Down]

[Move Left]	[Move Right]

[Page Up]	[Page Down]

[Refresh]	[Rotate Window]

Dialog Box Operations

[Previous Member]	[Next Member]

[Previous Group]	[Next Group]

[List]	[Accept]

[Select]

Text and Field Editing Operations

[Move Startline]	[Move Endline]

[Delete]	[Backspace]

[DeleteLine]	[Delete to Eol]

[Select Text]	[Cut]

[Copy]	[Paste]

[Clear]

Command Operations

[Previous Command]	[Next Command]

Special Operation

[Newline]

 Menu Shortcut Operations

Menu shortcuts provide fast, single-key access to SQL*DBA's most frequently-accessed menu functions. The keystrokes assigned to these operations are shown on the SQL*DBA menus.

 Special Operation: [Newline]

[Newline] is an all-purpose operation. This operation performs the most useful action in any given situation. In general, it does what you expect, but the actual execution depends on the current situation.

For example, in the input window, this operation:

•	starts a new line when you are entering a SQL command

•	executes the current command when you are entering a SQL*DBA command

•	reissues the current command when you are at the end of a command you retrieved from the command history

In the menu system, [Newline] activates the highlighted selection from the menu bar, pull-down menu, or submenu.

At the action keys in a dialog box, (OK, Cancel), the [Newline] operation performs the highlighted action

The best way to understand the [Newline] operation is to use it. It operates in a highly-intuitive manner that is easily understood  in practice.

Common Actions

This section describes the actions you commonly take in the menu system.

 Show Keys

The most important key is [Show Keys]. Once you know that key, you can easily learn the other keys. On most devices, control-K or escape-K shows the key-mapping for that device. (K stands for "KEYS".)

 Getting Help

For additional help on using SQL*DBA, use [Help]. This action takes you to an index of help topics.

 Getting to the Main Menu

Use [Menu] to activate the main menu or select a menu item with the mouse.

 Selecting a Menu Item

Press the underlined letter to select the menu item or move the cursor to the desired item and use [Select] or [Newline].

 Moving Around in a Dialog Box

Sometimes, entries in a dialog box are collected into groups. The [Next Group] operation moves from one group to the next, while the [Next Member] operation moves to the next item within the group. [Previous Group] and [Previous Member] perform similar operations in the reverse direction.

 Canceling Dialog Choices

You cancel an operation with [Cancel] or by selecting the Cancel button on the screen. This action leaves a window (menu, dialog box, list box, or list builder) as if you never entered it, discarding any choices you may have made.

 Acting on Dialog Choices

To perform an operation, use [Accept] or choose the OK button on the screen, either with a mouse or by moving the cursor to that position and using [Select] or [Newline]. In either case, you indicate that you have finished making choices or entering data, and that you want the current operation to continue.

 Entering Data in Fields

Some data entry fields allow multiple items to be specified, separated by commas. Those that allow multiple items have plural titles, such as "New Storage Parameters". Those that only permit a single entry have singular titles, such as "Override Preset Log Destination".  To move on to the next field, use [Next Group].

 Clearing a Field

To erase the contents of a field, use [DeleteLine] while the cursor is positioned in that field.

 Using Checkboxes and Radio Buttons

Use [Select] to mark a checkbox or to pick an item from a set of radio buttons.

 Viewing Multiple Monitors

When you have started up one or more monitors, you can use [Rotate Window] to cycle the display. The display moves from one monitor screen to the next each time you use [Rotate Window].

When the last monitor has been displayed, the initial SQL*DBA screen is displayed showing the command editor and output window. From this display, [Rotate Window] goes to the first monitor screen, starting the cycle all over.

For more information, see Chapter 13.

 Selecting an Item from a List Box

Most data entry fields allow you to bring up a list box. Data entry fields that support this option are indicated by the word "List" in the lower left-hand corner of the dialog.

Data entry fields that ask for names of existing objects usually have an associated list box that lets you select the objects, rather than typing them from memory. To select such a field, position to it and use [List].

For example, using [List] in the Default Tablespace field of the Create User dialog box shown in Figure 10 - 12 gets a list box like the one shown in Figure 10 - 13.

Figure 10 - 12. Field with List Option

Figure 10 - 13. List Box

 Creating a List with a List Builder

Data entry fields that allow you to specify several objects also have an associated list box, called a list builder. The following example shows a list builder. Specifications entered into the data entry fields in the list builder are added to the list when you choose Add. An item is deleted from the list when you select it and then choose Remove.

Figure 10 - 14.  List Builder

 Changing a Window Display

Use [Next Group] to move the cursor between the input window and the output window. Use [Move Up] and [Move Down] to move up or down one line at a time. Use [Page Up] or [Page Down] to move the entire display to an adjacent position, filling it with new information. [Move Left] and [Move Right] move one character at a time. You can also use scroll bars to change the display, as described in the next section.

 Using the Scroll Bars

Windows have horizontal and vertical scroll bars. The horizontal scroll bar is at the bottom of the display. It applies to whichever window is currently active. Vertical bars are at the right, as shown in the following illustration:

Figure 10 - 15.  Scroll Bars

The highlighted box at the right side of a windows represents current vertical position. Similarly, the small box along the bottom represents horizontal position of the currently active window. The position of the boxes in their respective scroll bars indicates the position of the window relative to the amount of information available for viewing. Although the appearance of the boxes may vary on different devices, their function is the same.

You can change the display location with the mouse in the following ways:

•	Click on the arrow at the end of the scroll bar to move the display one line (or one character) at a time.

Note: These arrows do not appear on all devices.

•	Click on the scroll bar to move the display to an adjacent location. For example, click above the display box to move the display up, or to the right of the display box to move it to the right.

•	Grab the display box with the cursor and reposition it. To grab the box, you move the mouse cursor to it and then press the mouse button without releasing it. You have now grabbed the display box. Move the mouse up or down (for a vertical scroll bar) or left and right (for a horizontal one) to move the display to a new location. Release the mouse button to drop the display in its new location.

For terminals that do not have a mouse, the scroll bar tracks the cursor to display your position.

 Refreshing the Screen

To redisplay the screen after it has been interrupted by a message, use [Refresh].

 ________________________________________

Using the Input Window

You can use SQL*DBA's input window to

•	issue SQL*DBA commands and SQL statements

•	enter and execute anonymous PL/SQL blocks

•	run commands that have been stored in a command file

 Editing Functions

The input editor operates in insert mode. Multiple-line commands can be entered and edited. Previously entered commands can be called back, edited, and reissued. Cursor operations and backspacing are supported so you can correct typing mistakes.

 Common Editing Actions

This section describes the editing procedures you commonly perform in the input window.

 Repeating a Command

[Previous Command] moves up the command history, copying a previously entered command to the input window. [Next Command] moves down the list. Use SET HISTORY to change the number of commands that can be recalled (see Chapter 12). By default, the command history stores the last ten commands.

Commands can be retrieved from the history and then edited. Multiple-line commands are recalled in their entirety, and all lines of the command can be edited. After editing, move the cursor to the end of the command and type the end-of-command syntax character (for example, semicolon (;)) for a SQL command, or else use [Newline].

 Positioning the Cursor

[Move Left], [Move Right], [Move Up], and [Move Down] move one character or line at time. [Move Startline] and [Move Endline] move to the beginning or end of a line. [Page Up] and [Page Down] move to the previous or next screen.

 Erasing Input Lines

[DeleteLine] deletes the line the cursor is on. [Delete to Eol] deletes from the current cursor position to the end of line.

 Other Editing Functions

[Cut], [Copy], and [Paste] let you rearrange text in the input window or use text from the output window. First, use [Select Text] to mark text. Then use [Cut] to move the selected text to the clipboard or [Copy] to make a copy of it on the clipboard. Move the cursor to the place where you want the text inserted and use [Paste].

 Command Syntax

This section describes the syntax for each of the commands that can be entered in SQL*DBA.

 SQL*DBA Commands

One-line SQL*DBA commands do not require punctuation or terminators. A SQL*DBA command may be longer than one line if a backslash (\) is used at the end of the line to indicate continuation. However, if you enter a SQL*DBA command on multiple lines, you need to terminate the command with a semicolon.

The following examples are valid SQL*DBA command:

CONNECT scott/tiger

RECOVER DATABASE \

  USING BACKUP CONTROLFILE \

  PARALLEL 4;

Chapter 12 contains descriptions of the SQL*DBA commands.

 SQL Commands

You can execute any SQL statement from within SQL*DBA once you are connected to a database. Many SQL statements can also be executed with menu choices, as described in Chapter 11, "SQL*DBA Menus".

You signal the end of a SQL statement and begin its execution in one of the following ways:

•	put a slash as the first and only character on an input line

•	put a semicolon as the last character on an input line

The following examples are valid SQL commands:

SELECT * FROM DICTIONARY

WHERE TABLE_NAME LIKE 'USER_%';   -- SQL command with ;

SELECT * FROM SCOTT.EMP

/ 	    -- SQL command with /

Continuation characters are not required for multi-line SQL commands, because SQL commands are terminated by a semicolon or slash, unlike SQL*DBA commands, which are terminated with a [Newline] only.

 PL/SQL Commands

All PL/SQL statements are supported by the SQL*DBA command editor. Use a period (.) to terminate entry of a PL/SQL or SQL statement to end entry without execution. Do not terminate lines beginning with DECLARE or BEGIN with a semicolon.

To execute a PL/SQL block, enter a slash on a line by itself.

Prepared Scripts

To run a script, type the filename in the input window after an at-sign. For example:

@beginday

If not specified, the file's extension or file type is assumed to be SQL. Do not follow the filename with a slash or a semicolon. The format of the command file is discussed in the next section.

 ________________________________________

Using the O/S Prompt and Script Files

This section describes how to run prepared scripts using SQL*DBA's command-line interface. It also describes the format of script files and gives tips for making scripts.

 Running Prepared Scripts from the Command Line

You can run prepared scripts directly from the operating system prompt by specifying a command string on the command line with the following syntax:

SQLDBA COMMAND="@command_file"

The default extension for the file is ".SQL". For example, the script BEGINDAY.SQL might contain all of the commands you regularly use at the start of the day. You could execute all of those commands at once with the following command:

SQLDBA COMMAND="@beginday"

Additional Information:   Some operating systems require extra quotation marks to get the quotation marks past the operating system's command-processing shell and into SQL*DBA. See your operating system-specific Oracle7 documentation for details.

When the command-line interface is used, SQL*DBA automatically executes in line mode. Because no screen is required, this mode is suitable for use with your operating system's batch-mode command files. When the script finishes, SQL*DBA automatically exits.

Note: With the command-line interface, SQL*DBA's MONITOR commands are not allowed. MONITOR commands are allowed in scripts that are executed interactively, however.

 Command File Format

The script can contain SQL, PL/SQL and SQL*DBA commands.

 SQL Statements in a Script

Terminate all SQL statements with a semicolon or a slash. For example, the following mixture of SQL and SQL*DBA statements could be contained in a script:

CONNECT scott/tiger

SELECT * FROM emp;

MONITOR PROCESS

Note: Because of the MONITOR command, this script must be executed interactively from the input window with a command such as the following :

@script_name

 PL/SQL Statements in a Script

To execute a PL/SQL statement, terminate it with a slash. To end a PL/SQL statement without executing it, terminate it with a period. This sample script file uses PL/SQL and SQL*DBA commands:

CONNECT scott/tiger

VARIABLE name VARCHAR2(20)

REMARK Use a PL/SQL block to select into the local variable

BEGIN

  SELECT ename INTO :name FROM emp WHERE empno = 7369;

END;

/

PRINT name

Executing this script produces the following result:

NAME

-------------------

SMITH

1 row selected.

 Nested Scripts

Scripts may call other scripts. For example, the following command could itself be contained in a script:

@script_name

Additional Information:  The depth to which scripts may be nested is operating system specific. See your operating system-specific Oracle7 documentation for details.

 Saving Commands in a Command Script

Whenever you select a menu function, the equivalent SQL*DBA command and the command output are listed. You can use this feature to create a script based on your interactive selections:

1.	Use the SPOOL function to capture SQL*DBA's command listing and command output in a file.

2.	Edit the file to remove the command output, leaving the commands.

The resulting script can either be run interactively or used with SQL*DBA's command-line interface.


CHAPTER 11. SQL*DBA MENUS

This chapter gives an overview of SQL*DBA's menu, command, and command-file interfaces. Menu commands appear in alphabetical order. For more information on SQL*DBA commands, see Chapter 12, "SQL*DBA Commands".

 ________________________________________

Main Menu Options

 Session Menu

This menu provides the session management commands available through SQL*DBA. For more information on the options in this menu, see Chapter 12.

 Instance Menu

This section describes the instance and database management commands available through SQL*DBA. For more information on the options in this menu, see Chapter 3, "Starting Up and Shutting Down" and Chapter 4, "Managing Oracle Processes"in the Oracle7 Server Administrator's Guide.

 Storage Menu, Tablespace Submenu

This menu provides the tablespace management commands available through SQL*DBA. For more information on the options in this menu, see Chapter 7, "Managing the Size and Files of the Database" in the Oracle7 Server Administrator's Guide.

 Storage Menu, Rollback Segments Submenu

This menu provides the rollback segment management commands available through SQL*DBA. For more information on the options in this menu, see Chapter 9, "Managing Rollback Segments" in the Oracle7 Server Administrator's Guide.

 Log Menu

This menu provides the redo log management commands available through SQL*DBA. For more information on the options in this menu, see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

 Backup Menu

This menu provides the backup and recovery options available through SQL*DBA. For more information on the options in this menu, see Chapter 18, "Backing Up a Database" in the Oracle7 Server Administrator's Guide.

 Security Menu

This menu provides the security options available through SQL*DBA. For more information on the options in this menu, see Chapter 18, "Privileges and Roles" in the Oracle7 Server Concepts Manual.

 ________________________________________

Menu Commands

 Add Datafiles

The tablespace Add Datafiles option is on the Tablespace submenu of the Storage menu. This option adds datafiles to a tablespace.

Figure 11 - 1.  Add Datafiles to Tablespace Dialog Box

Select the tablespace to which you wish to add a datafile.

 Specify Datafiles

Type in filenames. Filenames should be enclosed within single quotation marks and separated by commas. Alternatively, use [List] to display the following list builder.

Figure 11 - 2.  Filenames List Builder

Type in a new filename and specify the file's size or enter the name of an existing file. If the file already exists, specify Reuse Existing File, If Present to clear it of its current contents. If Reuse Existing File, If Present and the file's size are both specified, then the specified size must match the file's actual size. Choose Add to insert the file specification into the list of files to add. Use the same procedure to specify other files.

To remove a file from the list, select it and then choose Remove.

For more information see Chapter 7, "Managing the Size and Files of the Database", in the Oracle7 Server Administrator's Guide, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER TABLESPACE ADD DATAFILE (SQL)

Privilege required:	ALTER TABLESPACE

 Add Group

The Add Group option is on the Log menu. This option adds a new online redo log group.

Figure 11 - 3.  Add Redo Log Group Dialog Box

 Specify Thread

Specify the thread number or use [List] to display a dialog such as the following one.

Figure 11 - 4.  Thread Number List Box

Select a thread and choose OK to return to the Add Online Redo Log Group dialog.

 Specify Group

Specify the group number, or use [List] to display a dialog box such as the following one.

Figure 11 - 5.  Group Number List Box

Select a group and choose OK to return to the Add Online Redo Log Group dialog.

 Specify Redo Log Members

Enter the names of redo log files (that is, member names) in the Online Redo Log Members field. Filenames should be enclosed within single quotation marks and separated by commas. The size specified in the Log Member Size field applies to all files in the list. If Reuse is specified, then any size specification (if given) must match the existing file.

As an alternative to typing in the list, use [List] to display the following list builder.

Figure 11 - 6.  Redo Log Members List Builder

Type in a filename. Choose Add to add it to the group. All files specified in this manner have the size specified in the previous dialog. If you specify Reuse, then the file must exist and have the specified size. The file's contents are then erased.

To drop a file from the group, select it and then choose Remove. Choosing OK or Cancel returns to the Add Online Redo Log Group dialogue box.

For parallel instances accessing the same database, you can specify the thread (instance) to which the new group will belong by checking off Associate New Group with Thread# and filling in the appropriate thread number.

For more information see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE ADD LOGFILE GROUP (SQL)

Privilege required: 	ALTER DATABASE

 Add Member

The Add Member option is on the Log menu. This option adds a redo log file to a redo log group.

Figure 11 - 7.  Add Redo Log Member Dialog Box

 Specify Log Files

Specify a list of log files to add. Log file filenames should be enclosed within quotation marks and separated by commas. As an alternative to typing the list, use [List] in the Members to Add field to bring up the list builder.

Figure 11 - 8.  Redo Log Member List Builder

Type in a filename. Choose Add to add it to the list. If you specify Reuse Existing File, the file must exist. (Its contents are then erased.) To remove a file from the list, select it and then choose Remove.

Choose OK to return to the Add Online Redo Log Member dialog box.

 Specify Group

From this dialog, enter the number of the group to which you wish to add members or use [List] to display a list box such as the following one:

Figure 11 - 9.  Redo Log Group List Box

From this list box, you can select the redo log group to which to add the members.

For more information see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE ADD LOGFILE MEMBER (SQL)

Privilege required:	ALTER DATABASE

 Alter Default Storage

The tablespace Alter Default Storage option is on the Tablespace submenu of the Storage menu. This option changes default storage parameters for objects subsequently created in a tablespace.

Figure 11 - 10.  Alter Default Storage Dialog Box

Choose the tablespace you want to change, check off the desired parameters, and fill in the appropriate values.

For more information see Chapter 7, "Managing the Size and Files of the Database", in the Oracle7 Server Administrator's Guide, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER TABLESPACE ... DEFAULT STORAGE (SQL)

Privilege required:	ALTER TABLESPACE

 Alter Profile

The Alter Profile option is on the Security menu. This option modifies a profile that limits use of system resources.

Figure 11 - 11.  Alter Profile Dialog Box

Select the resource limits you want to change and fill in the appropriate values.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	ALTER PROFILE (SQL)

Privilege required:	ALTER PROFILE

 Alter Resource Cost

The Alter Resource Cost option is on the Security menu. This option specifies a formula for calculating the total cost of resources used in a session.

Figure 11 - 12.  Alter Resource Cost Dialog Box

Specify a numeric "weight" (zero or greater) for each of the resource cost factors:

•	CPU time, in hundredths of seconds

•	connect time, in minutes

•	logical reads, in number of database blocks

•	private SGA space, in bytes

The measurements for each session are multiplied by corresponding weights and added together to produce a composite measure of resource utilization that is compared with the COMPOSITE_LIMIT specified in a resource-limit profile.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	ALTER RESOURCE COST (SQL)

Privilege required:	ALTER RESOURCE COST

 Alter Role

The Alter Role option is on the Security menu. This option changes the authentication method for a role.

Figure 11 - 13.  Alter Role Dialog Box

Select the role you want to change, then choose the new authentication method. This is the only change you can make to a role from this menu. To change the privileges associated with a role, use the Grant and Revoke options from the Security menu.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	ALTER ROLE (SQL)

Privilege required:	ALTER ANY ROLE

 Alter Rollback Segment Storage

The rollback segment Alter Storage option is on the Rollback Segment submenu of the Storage menu. This option changes storage parameters for a rollback segment.

Figure 11 - 14.  Alter Rollback Segment Storage Dialog Box

Select the rollback segment you wish to alter. Check off the parameters you want to change and fill in the appropriate values.

For more information see Chapter 9, "Managing Rollback Segments", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER ROLLBACK SEGMENT ... STORAGE (SQL)

Privilege required:	ALTER ROLLBACK SEGMENT

 Alter User

The Alter User option is on the Security menu. This option changes a user definition.

Figure 11 - 15.  Alter User Dialog Box

Select the name of the user definition you want to change. Choose Change Password to to change an existing user's password or fill in a new user's initial password. Choose Change to OS Authentication to rely on the operating system's user authentication.

 Specify Default Tablespace

To change the user's default tablespace, enter the name of a tablespace or use [List] to select the tablespace from a list box.

Figure 11 - 16.  Default Tablespace List Box

 Specify Temporary Segment

To change the user's temporary segment, enter a name in the Temporary Segment Tablespace field or use [List] to select the tablespace from a list like the one shown in the previous display.

 Specify Quota

To change the user's quotas, enter a specification in the Quota field or use [List] to bring up a list builder such as the following one.

Figure 11 - 17.  Tablespace Quotas List Builder

 Specify Profile

To change the user's profile, fill in a profile name or use [List] to select from a list box such as the following one.

Figure 11 - 18.  User Profile List Box

 Specify Role

To set or change the user's list of default roles, check off the Default Roles option, then enter a list of roles separated by commas, or use [List] to display the following list box.

Figure 11 - 19.  User Role List Box

Make your choice of role assignments. Select the roles to assign. Press [Accept] or choose OK to indicate that you have finished making choices and return to the Alter User dialog.

When you are finished making changes at the Alter User dialog, press [Accept] or choose OK to make them effective. Press [Cancel] or choose the Cancel button to leave the user definition unchanged.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	ALTER USER (SQL)

Privilege required:	ALTER USER

 Begin Manual Archive

The Begin Manual Archive option is on the Log menu. This option performs a manual archive of one or more redo logs.

Figure 11 - 20.  Begin Manual Archive Dialog Box

 Specify a Thread

The default is to apply the options you choose to all threads in the database. (For single-instance Oracle, there is only one thread.)

For multiple instances, you can enter a thread number to restrict archiving to a single thread or use [List] in the Specific Thread Number field to select from a list of threads, as shown in the following list box.

Figure 11 - 21.  Thread Number List Box

Both OK and Cancel return to the Manual Archiving dialog.

 Specify a Group

To archive a specific unarchived group, enter the group number or use [List] to select from a list of unarchived groups, as shown in the following list box.

Figure 11 - 22.  Group Number List Box

 Specify a Member

To select a group for archiving by specifying a specific member, check Specific Group Including Member, then enter the member name or use [List] to select from a list of members, as shown in the following list box.

Figure 11 - 23.  Redo Log Group Member List Box

When you specify a specific log sequence number, only the log file you specify is archived. If you specify a System Change Number (SCN), then SQL*DBA archives all unarchived logs up to and including the one containing that SCN. If either the log sequence number or SCN cause the current log file to be selected, then a log switch is forced,  and the log file is archived. Choosing All Current Redo Information  is the same as specifying the current SCN, whatever it happens to be at the time.

 Specify Archive Destination

The default archive destination is specified by the initialization parameter LOG_ARCHIVE_DEST, unless that destination has been changed with the ALTER SYSTEM ARCHIVE LOG command.

To change the archive destination for the current archive operation, fill in the New Archive Destination field. The change is effective for this archive only. Any subsequent automatic archives will continue to go to the default destination.

For more information see Chapter 17, "Archiving Redo Information", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER SYSTEM ARCHIVE LOG ... (SQL) (where "..." is anything but STOP or START)

Privilege required:	ALTER SYSTEM

 Begin Online Tablespace Backup

The Begin Online Tablespace Backup option is on the Backup menu. This option marks a tablespace as "being backed up". Use this option before backing up a tablespace with an operating system command or with the backup utility. If data recovery becomes necessary, the server then knows that a backup was in progress and not complete.

Figure 11 - 24.  Begin Online Tablespace Backup Dialog Box

Choose the tablespace you want to back up and then press [Accept] or choose OK to get it ready for the backup. This step is necessary to create a usable backup. Otherwise, the database cannot be reliably restored from the backup -- even if recovery occurs without error, it may produce inconsistent data. Then use SQL*DBA's HOST command or use the Session menu's Enter System Command option to back up the tablespace with an operating system command or with the backup utility.

Additional Information:  See your operating-system-specific Oracle7 documentation for details on operating system backups.

Warning: When the backup is complete, use the End Online Tablespace Backup option to return the tablespace to its normal state. Otherwise, when the database is shut down, the Server will assume that tablespace recovery is necessary when the database is restarted.

For more information see Chapter 18, "Backing Up a Database", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER TABLESPACE BEGIN BACKUP (SQL)

Privilege required:	ALTER TABLESPACE

 Configure Dispatcher

Configure Dispatcher is on the Instance menu. Use this option to specify the number of dispatcher processes with specific protocols.

Figure 11 - 25.  Configure Dispatcher Dialog

Type in the protocol name and the total number of dispatchers that will use that protocol. Choose Add to insert that specification into the list of specifications to be implemented. Use the same procedure to specify the number of dispatchers using other protocols.

To remove a protocol from the list, select it and then choose Remove. The existing number of dispatchers using that protocol then remains unchanged. To eliminate dispatchers using a specific protocol, specify that protocol and then specify zero for the number of dispatchers.

For more information see Chapter 9, "Memory Structures and Processes", in the Oracle7 Server Concepts Manual, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER SYSTEM SET MTS_DISPATCHERS  (SQL)

Privilege required:	ALTER SYSTEM

 Configure Shared Server

Configure Shared Server is on the Instance menu. This option specifies the number of shared server processes.

Figure 11 - 26.  Configure Shared Server Dialog

Specify the total number of shared server processes that should exist and choose OK.

For more information see Chapter 9, "Memory Structures and Processes", in the Oracle7 Server Concepts Manual, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER SYSTEM SET MTS_SERVERS  (SQL)

Privilege required:	ALTER SYSTEM

 Connect

Connect is on the Session menu. This option connects to a database instance.

Figure 11 - 27.  Connect Dialog

For more information see Chapter 12.

Command equivalent:	CONNECT (SQL*DBA)

Privilege required:	CREATE SESSION

 Create Profile

The Create Profile option is on the Security menu. This option creates a profile that can be assigned to users to limit their use of system resources.

Figure 11 - 28.  Create Profile Dialog Box

Select the resources you want to limit and fill in the appropriate values.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	CREATE PROFILE (SQL)

Privilege required:	CREATE PROFILE

 Create Role

The Create Role option is on the Security menu. This option defines an abstract category of users so that you can grant or revoke privileges on all users in that category with one operation.

Figure 11 - 29.  Create Role Dialog Box

Fill in the name of the role you want to create. Choose the user authentication method. Then press [Accept] or choose OK to create the role. Press [Cancel] or choose the Cancel button to leave this menu without creating a role.

Note: To set the role's privileges, use the Grant and Revoke options from the Security menu.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	CREATE ROLE (SQL)

Privilege required:	CREATE ROLE

 Create Rollback Segment

The rollback segment Create option is on the Rollback Segment submenu of the Storage menu. This option creates a rollback segment.

Figure 11 - 30.  Create Rollback Segment Dialog Box

Choose Public or Private to specify the kind of rollback segment you want to create, then enter the name of the rollback segment.

 Specify Tablespace

Enter the name of the tablespace in which to create the rollback segment or use [List] to display the following dialog.

Figure 11 - 31.  Tablespace List Box

Select the tablespace and choose OK to return to the Create Rollback Segment dialog.

 Specify Storage Parameters

To change storage parameters, choose Override Default Storage Parameters and then specify the storage parameters or use [List] to display the following dialog box.

Figure 11 - 32.  Storage Parameters Dialog Box

Check off the parameter(s) you wish to set and fill in the appropriate value(s), then choose OK.

For more information see Chapter 9, "Managing Rollback Segments", in the Oracle7 Server Administrator's Guide.

Command equivalent:	CREATE ROLLBACK SEGMENT (SQL)

Privilege required:	CREATE ROLLBACK SEGMENT

 Create Tablespace

The tablespace Create option is on the Tablespace submenu of the Storage menu. This option creates a tablespace.

Figure 11 - 33.  Create Tablespace Dialog Box

This option lets you create a tablespace and specify datafiles, default storage parameters, and initial online/offline state. Begin by entering the name of the tablespace you want to create.

 Specify Datafiles

Type filenames separated by commas (filenames should be enclosed within single quotation marks if they contain any special characters) or use [List] to display the following pop-up window.

Figure 11 - 34.  Tablespace Datafiles List Builder

Type in the name of a new datafile and specify its size. Choose Reuse to use an existing file after erasing its contents. If size is specified along with Reuse, the size must match the existing file. If size is not specified, then Reuse is assumed.

Choose Add to add the file specification to the list of files to be included in the tablespace. To remove a file from the list, select the filename and then choose Remove. Use [Accept] or choose OK to return to the previous dialog with your specifications or [Cancel] to return to the previous dialog box without them.

 Specify Storage Parameters

Type in storage parameters separated by commas or use [List] to display the following pop-up dialog box.

Figure 11 - 35.  Tablespace Storage Parameters Dialog Box

Check off the options you want to specify and fill in their values. Your specifications are then included in the create tablespace dialog.

For more information see Chapter 7, "Managing the Size and Files of the Database", in the Oracle7 Server Administrator's Guide, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	CREATE TABLESPACE (SQL)

Privilege required:	CREATE TABLESPACE

 Create User

The Create User option is on the Security menu. This option creates a user definition.

Figure 11 - 36.  Create User Dialog Box

 Specify User and Authentication

Fill in the name of the user you want to establish on the system. If database authentication is desired, choose Use Password Authentication and fill in the user's initial password value. If the host operating system is to be used for authentication, choose Use OS Authentication.

 Specify Tablespaces

To specify a default tablespace or the user's temporary segment, enter a tablespace name or use [List] to select the tablespace from a list box such as the following one.

Figure 11 - 37.  Default Tablespace List Box

 Specify Quota

When specifying the user's quotas on various tablespaces, a list-builder can be used.

Figure 11 - 38.  Tablespace Quotas List Builder

 Specify Profile

To establish the user's profile, check off the Profile option, then fill in a profile name or use [List] to select from a list box such as the following one.

Figure 11 - 39.  User Profile List Box

When you are finished selecting your options, press [Accept] or choose OK to create the user.

Note: To set a user's default role, use the ALTER USER option, described next.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	CREATE USER (SQL)

Privilege required:	CREATE USER

 Disable Thread

The Disable Thread option is on the Log menu. This option disables a specified thread of redo log files.

Figure 11 - 40.  Disable Thread Dialog

Choose the thread you want to disable. Press [Accept] or choose OK to disable it. Press [Cancel] or choose the Cancel button to exit this window without disabling a thread.

For more information see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE DISABLE THREAD (SQL)

Privilege required:	ALTER DATABASE

 Disconnect

Disconnect from the instance.

For more information see Chapter 12.

Command equivalent:	DISCONNECT (SQL*DBA)

Privilege required:	None

 Drop Group

The Drop Group option is on the Log menu. This option drops an online redo log group.

Figure 11 - 41.  Drop Redo Log Group Dialog Box

Select the log file group you want to drop and then press [Accept] or choose OK to drop it. Press [Cancel] or choose the Cancel button to exit the window without dropping a log file group.

For more information see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE DROP LOGFILE GROUP (SQL)

Privilege required:	ALTER DATABASE

 Drop Member

The Drop Member option is on the Log menu. This option drops a redo log file from a redo log group.

Figure 11 - 42.  Drop Redo Log Member Dialog Box

Select the log file to drop and press [Accept] or choose OK to drop it. Press [Cancel] or choose the Cancel button to exit this window without dropping a log file.

For more information see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE DROP LOGFILE MEMBER (SQL)

Privilege required:	ALTER DATABASE

 Drop Profile

The Drop Profile option is on the Security menu. This option drops a resource-limit profile.

Figure 11 - 43.  Drop Profile Dialog Box

Select the profile you want to drop. If the profile is currently assigned to any users, you must specify Reassign Profile to drop it. Those users are then assigned the DEFAULT profile.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	DROP PROFILE (SQL)

Privilege required:	DROP PROFILE

 Drop Role

The Drop Role option is on the Security menu. This option drops a role.

Figure 11 - 44.  Drop Role Dialog Box

Select the role you want to drop. Press [Accept] or choose OK to perform the drop. Press [Cancel] or choose the Cancel button to leave this menu without dropping a role.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	DROP ROLE (SQL)

Privilege required:	DROP ANY ROLE

 Drop Rollback Segment

The rollback segment Drop option is on the Rollback Segment submenu of the Storage menu. This option drops a rollback segment.

Figure 11 - 45.  Drop Rollback Segment Dialog Box

Select the rollback segment you want to drop, then press [Accept] or choose OK to drop it. Press [Cancel] or choose the Cancel button to exit from the list without dropping a rollback segment.

For more information see Chapter 9, "Managing Rollback Segments", in the Oracle7 Server Administrator's Guide.

Command equivalent:	DROP ROLLBACK SEGMENT (SQL)

Privilege required:	DROP ROLLBACK SEGMENT

 Drop Tablespace

The tablespace Drop option is on the Tablespace submenu of the Storage menu. This option drops a tablespace.

Figure 11 - 46.  Drop Tablespace Dialog Box

Select the tablespace to drop. If the tablespace is empty, this selection is sufficient. If the tablespace is not empty, then you must also choose to Drop Contained Objects, If Present for the drop to succeed.

You may also choose to cascade the drop of integrity constraints. If any integrity constraints from tables in other tablespaces reference tables in the tablespace to be dropped, then the drop fails if Drop Dependent Referential Constraints is not specified. If this option is specified, then all integrity constraints that reference the tables in the dropped tablespace are removed from the tables that contain them.

For more information see Chapter 7, "Managing the Size and Files of the Database", in the Oracle7 Server Administrator's Guide, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	DROP TABLESPACE (SQL)

Privilege required:	DROP TABLESPACE

 Drop User

The Drop User option is on the Security menu. This option drops a user definition.

Figure 11 - 47.  Drop User Dialog Box

Select the user definition you want to drop. If you want to drop all of the objects in the user's schemas, choose Including Associated Schema Objects. If this option is not chosen and the associated schema is not empty, the user definition is not dropped.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	DROP USER (SQL)

Privilege required:	DROP USER

 Enable Thread

The Enable Thread option is on the Log menu. This option enables the specified thread of redo log files.

Figure 11 - 48.  Enable Thread Dialog Box

Choose the thread you want to enable. For parallel servers, you may also choose to make the thread available to any instance, instead of restricting it to the current instance. For single-instance Oracle, these options are equivalent.

For more information see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE ENABLE THREAD (SQL)

Privilege required:	ALTER DATABASE

 End Online Tablespace Backup

The End Online Tablespace Backup option is on the Backup menu. This option informs the Oracle Server that backup of a tablespace has completed. This step prevents unnecessary tablespace recovery the next time the database is started.

Figure 11 - 49.  End Online Tablespace Backup Dialog Box

After the backup is complete, select the tablespaces you backed up and mark them as ended.

For more information see Chapter 18, "Backing Up a Database", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER TABLESPACE END BACKUP (SQL)

Privilege required:	ALTER TABLESPACE

 Enter System Command

Enter System Command is on the Session menu. This option runs a single operating system command from within SQL*DBA.

Figure 11 - 50.  Enter System Command Dialog Box

For more information see Chapter 12.

Command equivalent:	HOST (SQL*DBA)

Privilege required:	None

 Force Checkpoint

Force Checkpoint is on the Instance menu. Force Checkpoint displays an options menu that gives you the choice of Local or Global. In single-instance Oracle, both options are equivalent.

Global	Checkpoint all instances accessing the current database. This option is only useful for the Oracle Parallel Server.    Local	Checkpoint only the instance to which you are currently connected.     For more information see Chapter 23 in the Oracle7 Server Concepts Manual, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER SYSTEM CHECKPOINT (SQL)

Privilege required:	ALTER SYSTEM

 Force Log Switch

Force Log Switch is on the Instance menu. This option forces a log switch from the currently active redo log group to the next group. After the log switch completes, the members of the previously active group are available for maintenance operations, such as archiving.

For more information see Chapter 23 in the Oracle7 Server Concepts Manual, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER SYSTEM SWITCH LOGFILE (SQL)

Privilege required:	ALTER SYSTEM

 Go to System

Go to System is on the Session menu. This option temporarily leaves SQL*DBA to execute a series of operating system commands.

Choosing Go To System allows you to execute a series of operating system commands.

For more information see Chapter 12.

Additional Information:  The method for returning to SQL*DBA when finished is specific to each operating system. Consult your operating-system-specific Oracle7 documentation for details.

Command equivalent:	HOST (SQL*DBA)

Privilege required:	None

 Grant

The Grant option is on the Security menu. This option grants system privileges and roles to a user or to a role.

Figure 11 - 51.  Grant System Privileges and Roles Dialog Box

 Specify System Privileges and Roles to Grant

Enter a list of system privileges separated by commas or use [List] to display the following list builder.

Figure 11 - 52.  System Privilege and Roles List Builder

Choose the system privileges and roles you want to grant. Press [Accept] or choose OK to accept this list and return to the Grant menu.

 Specify Users and Roles to Receive Grants

Enter a list of users and roles to receive the grants, separated by commas, or use [List] to bring up the following display:

Figure 11 - 53.  User and Role List Builder

Choose the users and roles you want to grant to. Press [Accept] or choose OK to accept this list and return to the Grant menu.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	GRANT (SQL)

Privilege required:	GRANT ANY ROLE or other privileges that include the ADMIN option

 Kill Session

Kill Session is on the Instance menu. This option terminates a user session.

Figure 11 - 54.  Kill Session Dialog Box

When you choose Kill Session a list appears showing all current users, their sessions, and the serial number for each session. Select the session you want to terminate, using session number and serial number to distinguish between multiple sessions that belong to the same user. Then use [Accept] or choose OK to terminate the session.

For more information see Chapter 9, "Memory Structures and Processes", in the Oracle7 Server Concepts Manual, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER SYSTEM KILL SESSION (SQL)

Privilege required:	ALTER SYSTEM

 List Archive Status

The List Archive Status option is on the Log menu. This option produces a display containing redo, including archive destination, the sequence number of the next group to be archived, the sequence number of the group currently being used, and the sequence number of the oldest unarchived group.

For more information see Appendix C.

Command equivalent:	ARCHIVE LOG LIST (SQL*DBA)

Privilege required:	You must be connected as INTERNAL, OSOPER, or OSDBA.

 Mount Database

Mount Database is on the Instance menu. When you choose Mount Database, a submenu is displayed that gives you the choice of Mount Exclusive or Mount Parallel.

Mount Exclusive opens the database for exclusive use by this instance. Mount Parallel allows it to be shared by other instances. After performing this operation, you can carry out the administrative functions that require the database to be mounted, but not open.

If the database has already been opened by another instance, then it must be opened in parallel mode.

Mount Parallel is available only if you have installed the Oracle Parallel Server. Consult the Oracle7 Parallel Server Administrator's Guide for more information.

For more information see Chapter 3, "Starting Up and Shutting Down", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE MOUNT (SQL)

Privilege required:	ALTER DATABASE

 Open Database

Open Database is on the Instance menu. This option opens a mounted database, allowing users to connect to it.

For more information see Chapter 3, "Starting Up and Shutting Down", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE OPEN (SQL)

Privilege required:	ALTER DATABASE

 Prevent and Allow Connection

Prevent Connection and Allow Connection are on the Instance menu. These options control enabling and disabling of Oracle's RESTRICTED SESSION access mode.

 Prevent Connection      Enables RESTRICTED SESSION. This option restricts database access to those users with the RESTRICTED SESSION system privilege. Any users currently connected to the database continue without interruption, until they disconnect or are terminated with the KILL SESSION option in the INSTANCE menu.

 Allow Connection      Disables RESTRICTED SESSIONS, opening database access to all users.

For more information see Chapter 3, "Starting Up and Shutting Down", in the Oracle7 Server Administrator's Guide.

Command equivalents:	ALTER SYSTEM ENABLE RESTRICTED SESSION, ALTER SYSTEM DISABLE RESTRICTED SESSION (SQL)

Privilege required:	ALTER SYSTEM

 Recover Database

The Recover Database option is on the Backup menu. This option performs media recovery on the entire database.

Figure 11 - 55.  Recover Database Dialog Box

Choose Complete Database Recovery or Incomplete Database Recovery and whether you want to use the backup version of the control file. A complete database recovery is necessary if a media failure occurred with the database running in NOARCHIVELOG mode. The backup control file must be used if the original control file is lost or damaged and cannot be restored. The choice of incomplete recovery depends on your runtime configuration and type of media failure.

For more information see Chapter 19, "Recovering a Database", in the Oracle7 Server Administrator's Guide.

Command equivalent:	RECOVER DATABASE (SQL*DBA)

Privilege required:	ALTER DATABASE

 Recover Datafile

The Recover Datafile option is on the Backup menu. This option performs media recovery on datafiles.

Figure 11 - 56.  Recover Datafile Dialog Box

Select a datafile for recovery. Press [Accept] or choose OK to perform the recovery. Press [Cancel] or choose the Cancel button to leave this menu without performing a recovery.

Note: When the SET AUTORECOVERY ON command has been issued in the input window, the recovery dialog remains available, allowing you to do another recovery. When AUTORECOVERY is OFF, the window disappears after the datafile is chosen: to recover other datafiles, you need to reselect the RECOVER DATAFILE option from the BACKUP menu.

For more information see Chapter 19, "Recovering a Database", in the Oracle7 Server Administrator's Guide.

Command equivalent:	RECOVER DATAFILE (SQL*DBA)

Privilege required:	ALTER DATABASE

 Recover Tablespace

The Recover Tablespace option is on the Backup menu. This option performs media recovery on tablespaces.

Figure 11 - 57.  Recover Tablespace Dialog

Select the tablespace you need to recover. Press [Accept] or choose OK to perform the recovery. Press [Cancel] or choose the Cancel button to leave this menu without performing a recovery.

Note: When the SET AUTORECOVERY ON command has been issued in the input window, the recovery dialog remains available, allowing you to do another recovery. When AUTORECOVERY is OFF, the window disappears after the tablespace is chosen. To recover other tablespaces, you need to reselect the RECOVER TABLESPACE option from the BACKUP menu.

For more information see Chapter 19, "Recovering a Database", in the Oracle7 Server Administrator's Guide.

Command equivalent:	RECOVER TABLESPACE (SQL*DBA)

Privilege required:	ALTER DATABASE

 Rename Datafiles

The tablespace Rename Datafiles option is on the Tablespace submenu of the Storage menu. This option renames datafiles in a tablespace.

Figure 11 - 58.  Rename Datafiles Dialog Box

Select the tablespace containing the files you want to rename.

 Specify Old Filename

Type in the old filename or use [List] to display the following list box.

Figure 11 - 59.  Datafile Filenames List Builder

Select one or more datafiles from this list and choose OK to return to the Rename Data File menu. The old filename field is then filled in with your choices.

Fill in the new filenames, then press [Accept] or choose OK to perform the rename.

For more information see Chapter 7, "Managing the Size and Files of the Database", in the Oracle7 Server Administrator's Guide, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER TABLESPACE RENAME DATAFILE (SQL)

Privilege required:	ALTER TABLESPACE

 Rename Member

The Rename Member option is on the Log menu. This option renames a redo log file in a redo log group.

Figure 11 - 60.  Rename Redo Log Member Dialog Box

 Specify Filename

Type in the log file to rename or use [List] to select the filename from a list.

Figure 11 - 61.  Redo Log Member List Box

After specifying the filename, fill in the new filename in the original dialog box. Then press [Accept] or choose OK to perform the rename.

For more information see Chapter 5, "Managing the Online Redo Log", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER DATABASE RENAME FILE (SQL)

Privilege required:	ALTER DATABASE

 Revoke

The Revoke option is on the Security menu. This option revokes system privileges and roles from users and from roles.

Figure 11 - 62.  Revoke System Privileges and Roles Dialog Box

 Specify System Privileges and Roles to Revoke

Enter a list of system privileges separated by commas or use [List] to display the following list builder.

Figure 11 - 63.  System Privileges and Roles List Builder

Choose the system privileges and roles you want to revoke. Press [Accept] or choose OK to accept this list and return to the Grant menu.

 Specify Users and Roles from Which to Revoke

Enter a list of users and roles from which to revoke, separated by commas, or use [List] to display the following list builder.

Figure 11 - 64.  User and Role List Builder

Choose the users and roles from which you want to revoke. Press [Accept] or choose OK to accept this list and return to the Grant menu.

For more information see Chapter 18, "Privileges and Roles", in the Oracle7 Server Concepts Manual.

Command equivalent:	REVOKE (SQL)

Privilege required:	GRANT ANY ROLE and/or other privileges that include the ADMIN option

 Set Rollback Segment Offline

The rollback segment Set Offline option is on the Rollback Segment submenu of the Storage menu. This option takes a rollback segment offline.

Figure 11 - 65.  Set Rollback Segment Offline Dialog Box

Select the rollback segment you want to take offline. Press [Accept] or choose OK to do so. Press [Cancel] or choose the Cancel button to exit without taking it offline.

For more information see Chapter 9, "Managing Rollback Segments", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER ROLLBACK SEGMENT ... OFFLINE (SQL)

Privilege required:	ALTER ROLLBACK SEGMENT

 Set Rollback Segment Online

The rollback segment Set Online option is on the Rollback Segment submenu of the Storage menu. This option brings a rollback segment online.

Figure 11 - 66.  Set Rollback Segment Online Dialog Box

Select the rollback segment you wish to bring online. Press [Accept] or choose OK to bring it online. Press [Cancel] or choose the Cancel button to exit without bringing it online.

For more information see Chapter 9, "Managing Rollback Segments", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER ROLLBACK SEGMENT ... ONLINE (SQL)

Privilege required:	ALTER ROLLBACK SEGMENT

 Set Server Output On, Set Server Output Off

Set Server Output On and Set Server Output Off are on the Session menu. These options determine whether output statements in stored functions and procedures are displayed in SQL*DBA`s output window.

 Set Server Output On      Enables output to SQL*DBA output window from stored procedures and functions that use DBMS_OUTPUT PUTLINE calls. This option brings up a dialog box that lets you specify the message buffer size (the total number of bytes from messages that can be accumulated at any one time). The default buffer size is 2000 bytes.

 Set Server Output Off      Disables output to SQL*DBA output window from stored procedures and functions that use DBMS_OUTPUT PUTLINE calls.

For more information see Chapter 12.

Command equivalent:	SET SERVEROUT (SQL*DBA)

Privilege required:	None

 Set Tablespace Offline

The tablespace Set Offline option is on the Tablespace submenu of the Storage menu. This option takes a tablespace offline.

Figure 11 - 67.  Set Tablespace Offline Dialog Box

Select a tablespace and choose OK to take it offline. You may choose to take it offline in one of three ways:

 After Checkpointing All Datafiles of Tablespace      Checkpoint all datafiles in the tablespace and ensure that the files can be written before taking the tablespace offline.

 After Checkpointing Online Datafiles of Tablespace      Checkpoint the online datafiles and ensure that they can be written. Then begin the checkpoint process. Continue without waiting for it to complete. Media recovery may be necessary when you bring the tablespace back online.

 Without Checkpointing Datafiles of Tablespace      Take the tablespace offline without checkpointing datafiles. Media recovery is required when you bring the tablespace back online. This option is only allowed if the database is archiving.

For more information see Chapter 7, "Managing the Size and Files of the Database", in the Oracle7 Server Administrator's Guide, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER TABLESPACE ... OFFLINE (SQL)

Privilege required:	ALTER TABLESPACE or MANAGE TABLESPACE

 Set Tablespace Online

The tablespace Set Online option is on the Tablespace submenu of the Storage menu. This option brings a tablespace online.

Figure 11 - 68.  Set Tablespace Online Dialog Box

All currently offline tablespaces are listed. Select a tablespace and choose OK to bring it online.

For more information see Chapter 7, "Managing the Size and Files of the Database", in the Oracle7 Server Administrator's Guide, and the Oracle7 Server SQL Language Reference Manual.

Command equivalent:	ALTER TABLESPACE ... ONLINE (SQL)

Privilege required:	ALTER TABLESPACE or MANAGE TABLESPACE

 Shut Down

Shut Down is on the Instance menu. This option shuts down a database. When you choose Shut Down, a submenu is displayed, allowing termination in one of three ways: Normal, Immediate, or Abort Instance.

Normal	Shuts down after all current users have disconnected from the database. New users are prevented from connecting, but current users can complete their work.     Immediate	     Immediately disconnect all users, roll back any uncommitted transactions, and shut down as soon as the rollbacks complete.     Abort Instance   Immediately shut down the database without waiting for transactions to roll back. This option is for use only in emergency situations. This option forces instance recovery on startup.     For more information see Chapter 3, "Starting Up and Shutting Down", in the Oracle7 Server Administrator's Guide.

Command equivalent:	SHUTDOWN (SQL*DBA)

Privilege required:	Connected as Internal

 Start Auto Archive

The Start Auto Archive option is on the Log menu. This option starts automatic archiving of redo logs.

Figure 11 - 69.  Start Auto Archive Dialog Box

Press [Accept] or choose OK to begin automatic archiving. Entering a destination overrides the one specified by the LOG_ARCHIVE_DEST parameter at startup.

For more information see Chapter 17, "Archiving Redo Information", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER SYSTEM ARCHIVE LOG START (SQL)

Privilege required:	ALTER SYSTEM

 Start Up

Start up is on the Instance menu. This option starts up a database.

Figure 11 - 70.  Startup Dialog Box

You can mount and open a database, mount a database without opening it, or start an instance. When you mount a database, you can choose to open it in exclusive or parallel mode.

Mount Exclusive opens the database for exclusive use by this instance. Mount Parallel allows it to be shared by other instances. If the database has already been opened by another instance, then it must be opened in parallel mode. For more information, consult the Oracle7 Parallel Server Administrator's Guide.

The database name is optional. If an initialization parameter file is specified in the Parameter File field, then the name of the database is given by the DB_NAME initialization parameter. If the database name is also specified in the Database Name field, then the specifications must match. For details on the DB_NAME parameter, see Appendix A, "Parameter Files and Initialization Parameters", in the Oracle7 Server Administrator's Guide.

Abort Current Instance Before Startup aborts the current instance and starts the new instance in one operation. This option should be used only when an existing database cannot be shut down, or when an instance will not start due to internal problems.

Enable Restricted Access restricts database access. In this mode, only users who have the RESTRICTED SESSION system privilege are allowed to connect to the database. By default, the menu allows open database access.

Recover Before Open does full database recovery. This option mounts the database without opening it.

For more information see Chapter 3, "Starting Up and Shutting Down", in the Oracle7 Server Administrator's Guide.

Command equivalent:	STARTUP (SQL*DBA)

Privilege required:	Connected as Internal

 Stop Auto Archive

The Stop Auto Archive option is on the Log menu. This option stops automatic archiving of redo logs.

For more information see Chapter 17, "Archiving Redo Information", in the Oracle7 Server Administrator's Guide.

Command equivalent:	ALTER SYSTEM ARCHIVE LOG STOP (SQL)

Privilege required:	ALTER SYSTEM


CHAPTER 12. SQL*DBA COMMANDS

This chapter describes SQL*DBA's commands. For information on SQL*DBA's menu interface, see Chapter 11.

 ________________________________________

ARCHIVE LOG

 Purpose

Start or stop automatic archiving of online redo log files, manually (explicitly) archive specified redo log files, or display information about redo log files.

Note: This command applies only to the current instance. To specify archiving for a different thread or for all threads in a multi-instance Oracle Server, use the SQL command ALTER SYSTEM.

 Prerequisites

You must be connected to an open Oracle database as SYSOPER or SYSDBA.

 Syntax

 Keywords and Parameters

LIST	Requests a display that shows range of redo log files to be archived, the current log file group's sequence number, and the current archive destination (specified by either the optional command text or by the initialization parameter LOG_ARCHIVE_DEST).

If you are using both ARCHIVELOG mode and automatic archiving, the display might appear like:

Database log mode	   ARCHIVELOG

Automatic archival	   ENABLED

Archive destination	   DISK9:ARCH

Oldest online log sequence	   30

Next log sequence to archive	   33

Current log sequence	   33

Because the log sequence number of the current log group and the next log group to archive are the same, automatic archival has archived all log groups up to the current one.

If you are using ARCHIVELOG but have disabled automatic archiving, the last three lines might look like:

Oldest online log sequence	30

Next log sequence to archive	30

Current log sequence	33

If you are using NOARCHIVELOG mode, the "next log sequence to archive" line is suppressed.

The log sequence increments every time LGWR begins to write to another redo log file group. It does not indicate the number of logs being used. Every time an online redo log file group is reused, the contents are assigned a new log sequence number.

To use the LIST option, you must be connected to a mounted or open database. The database may be running in either ARCHIVELOG or NOARCHIVELOG mode.

START	Enables automatic archiving. Starts the background process ARCH that performs automatic archiving as required. If ARCH is started and a filename is supplied, then the filename becomes the new default archive destination.

ARCH automatically starts on instance startup if the initialization parameter LOG_ARCHIVE_START is set to TRUE.

STOP	Disables automatic archival. If the instance is still in ARCHIVELOG mode and all redo log file groups fill, database operation is suspended until a redo log file is archived (for example, until you enter the command ARCHIVE LOG NEXT or ARCHIVE LOG ALL).

integer	Causes archival of online redo log file group with log sequence number n. You can specify any redo log file group that is still online. An error occurs if the log file cannot be found online or the sequence number is not valid. This option can rearchive a log file group.

NEXT	Manually archives the next online redo log file group that has been filled but not yet archived.

ALL	Manually archives all filled but not yet archived online log file groups.

'destination'  	Specifies the destination device or directory in an operating system. Specification of archive destination devices is installation specific. See your operating system-specific Oracle7 documentation for examples of specifying archive destinations. On many operating systems, multiple log files can be spooled to the same tape.

If not specified in the command line, the archive destination is derived from the initialization parameter LOG_ARCHIVE_DEST. The command ARCHIVE LOG START 'destination' causes the specified device or directory to become the new default archive destination for all future automatic or manual archives. A destination specified with any other option is a temporary destination that is in effect only for the current (manual) archive. It does not change the default archive destination for subsequent automatic archives.

 Usage Notes

If an online redo log file group fills and none are available for reuse, database operation is suspended. The condition can be resolved by archiving a log file group.

Examples	ARCHIVE LOG START

Starts up the archiver process and begins automatic archiving with the archive destination specified in LOG_ARCHIVE_DEST.

ARCHIVE LOG STOP

Stops automatic archiving.

ARCHIVE LOG 1001 'DISK9:/TEMPARCH/TEMP'

Archives the log file group with the sequence number 1001 to the destination specified. 'TEMP' specifies the prefix of the filename on the destination device. The remainder of the filename is dependent on the initialization parameter LOG_ARCHIVE_FORMAT that specifies the filename format for archived redo log files.

 ________________________________________

CONNECT

 Purpose

Connect to a database using the specified username.

 Prerequisites

Only valid username/password combinations can successfully connect. The option CONNECT INTERNAL is a system privileged command and requires certain operating system privileges.

 Syntax

 Keywords and Parameters

SYS	Connect as username SYS. It should be used rarely and only by the DBA for certain configuration purposes. It requires operating system privileges. For operations like startup, shutdown, and other normal maintenance functions, use SYSOPER or SYSDBA, described later in this section.

username	Any valid Oracle username for the current database or a null string. If neither username nor INTERNAL are specified, SQL*DBA prompts for a username.

password	The password corresponding to the specified username. Password can be a null string.

instance-path	A valid specification for an instance/database combination. If an instance is specified, it becomes the current instance for the duration of the connection. It does not become the default instance for subsequent connections.

SYSOPER, SYSDBA	When you connect with SYSOPER or SYSDBA privileges with a username and password, you connect to the SYS schema, not the schema that is generally associated with that username.

DBAs and system operators can use this facility for maintenance, configuration, and privileged operations like startup and shutdown. See Chapter 1, "Administering Oracle Databases" of the Oracle7 Server Administrator's Guide and the Oracle7 Server Addendum, Release 7.1 for more information on the SYSOPER and SYSDBA privileges.

INTERNAL	This option is provided for backwards compatibility only.

CONNECT scott/tiger

CREATE TABLE scott_test(name VARCHAR2(20));

Later, when SCOTT issues these commands:

CONNECT scott/tiger AS SYSDBA

SELECT * FROM scott_test;

He receives an error that SCOTT_TEST does not exist. That is because SCOTT is now connected to the SYS schema, whereas the table was created in the SCOTT schema.

 Usage Notes

If only the Oracle username is specified, the password is requested with the prompt "Password:". The entered password is not echoed.

CONNECT can be used without a DISCONNECT to connect to another username.

The connect is always accompanied by opening a cursor.

You can specify an instance path for a remote instance when you connect using the INTERNAL keyword. If you attempt a CONNECT INTERNAL to a remote instance, authentication occurs on the remote node. So you must have the appropriate privileges on the remote node.

Examples	To connect to an instance on the current default node, enter:

CONNECT

To connect to an instance on the current node as username SCOTT with password TIGER, enter:

CONNECT scott/tiger

To connect to an instance on the current node as the administrator with username SYSTEM, enter:

CONNECT system

To connect to an instance on current node as INTERNAL (does not request a password but requires the operating system privilege to connect as INTERNAL), enter:

CONNECT INTERNAL

To connect to an instance on a different node as username SCOTT with password TIGER, enter:

CONNECT scott/tiger@instance-path

 ________________________________________

DESCRIBE

 Purpose

Describe a table, view, stored procedure, function, or package.

 Prerequisites

You must currently be connected to a database.

 Syntax

 Keywords and Parameters

table_name	The name of the table to describe. The table's column names and datatypes are listed.

view_name	The name of the view to describe. The view's column names and datatypes are listed.

procedure_name	The name of the stored procedure or function to describe. Formal arguments and their datatypes are listed.

 Usage Notes

Procedures inside packages cannot be described with this command.

Example	A command such as

DESCRIBE scott.addemp

produces output similar to this:

PROCEDURE SCOTT.ADDEMP (EMPNO INTEGER, ENAME VARCHAR2, SAL NUMBER(9,2))

 ________________________________________

DISCONNECT

 Purpose

Disconnect from an Oracle server.

 Prerequisites

You must be currently connected to a database.

 Syntax

 Usage Notes

Upon disconnection, SQL*DBA reverts to the current default host machine after closing all open cursors and committing any uncommitted transactions.

Example	DISCONNECT

 ________________________________________

EXECUTE

 Purpose

Executes a one-line PL/SQL statement.

 Prerequisites

You must be currently connected to a database. You also must have privileges to use any stored procedures, packages, package variables, and functions referenced with this command.

 Syntax

 Usage Notes

You can execute only one line of PL/SQL code with the EXECUTE command. If you wish to execute a PL/SQL block with many lines, you cannot use the EXECUTE command. You must use the format:

BEGIN

[PL/SQL BLOCK]

END;

You can reference any SQL*DBA bind variables in PL/SQL statements by preceding the variable name with a colon. The following example illustrates the use of bind variables with the VARIABLE, EXECUTE, and PRINT commands:

Example	VARIABLE  temp NUMBER

 EXECUTE  :temp  :=  34056  PRINT  temp  BALANCE  ----------       34056

 ________________________________________

EXIT

 Purpose

Exit SQL*DBA.

 Prerequisites

None.

 Syntax

 Usage Notes

The EXIT command leaves SQL*DBA unconditionally--no matter what you are currently doing. It returns to the operating system prompt, if any, and commits the current transaction.

Example	EXIT

 ________________________________________

HOST

 Purpose

Execute an operating system command without exiting SQL*DBA.

 Prerequisites

None.

 Syntax

 Usage Notes

This command is useful for listing files that currently are of interest to the database administrator or for editing files to be run while in SQL*DBA. Your operating system may also support additional symbols or characters to invoke operating system commands.

If you omit the operating system command and enter "HOST", you temporarily exit SQL*DBA on the assumption you want to run multiple operating system commands

Additional Information:  To return to the current SQL*DBA session, you must use a operating system-specific entry. See your operating system-specific Oracle7 documentation to find that entry.

Example	HOST TYPE INIT.ORA

 ________________________________________

MONITOR

 Purpose

Display realtime information about locks, enqueues, processes, and other database entities.

 Prerequisites

You must be connected to the database with a username that has SELECT access to the dynamic performance tables.

 Syntax

These options can also be selected from SQL*DBA's Monitor menu. See Chapter 13, "The SQL*DBA Monitors" for descriptions and examples of the various displays.

 Keywords and Parameters

CIRCUIT	Displays information on virtual circuits in the shared server.

DISPATCHER	Displays information on the shared server's dispatcher processes.

FILEIO	Displays a screen with one row for every database file, showing read and write activity on those files.

LATCH	Displays a screen summarizing all current latches.

LCACHE	Displays information on the library cache.

LOCK	Displays a screen indicating current Oracle processes and the locks held or waited for. If the ALL keyword is specified, shows one screen at a time of all locks for the displayed process IDs

PROCESS	Displays one row of information for each process currently connected to the database.

QUEUE	Displays information on the shared server's message queues.

ROLLBACK	Displays information regarding the size, status, and activity against all active rollback segments--with one row per rollback segment.

SESSION	Displays information on one or more active processes. Displays for the background processes vary slightly from those for user processes.

SESSION STATISTIC	Displays statistics for user sessions. The statistics are described in Chapter 13.

SHARED	Displays information on the shared server.

SQLAREA	Displays information on the shared SQL area.

SYSTEMIO	Displays a histogram of the percent each Oracle process contributes to the total logical and physical I/O during the specified period. Relative distributions are displayed, not precise counts of I/O operations.

SYSTEM STATISTIC	Displays systemwide statistics regarding database use. The statistics are described in Chapter 13.

TABLE	Displays names of tables referenced in currently parsed SQL statements.

 Usage Notes

Although you can specify individual process numbers for some options, the screens display defaults for all processes. Specifying process ID 0 displays systemwide information. To explicitly request one screen summarizing all processes, use 0 after the process ID.

SQL*DBA lets you cycle forward and backward through multiple monitor screens and the input/output screen. You can move to the input/output screen and issue additional commands while monitors continue to run, then move back to the monitor(s) for the latest data.

Examples	MONITOR LATCH

 MONITOR LOCK 10 20  MONITOR LOCK ALL  MONITOR PROCESS 11  MONITOR STAT 0 6 0

 ________________________________________

PRINT

 Purpose

Print the value of a variable defined with the VARIABLE command.

 Prerequisites

None.

 Syntax

 Keywords and Parameters

variable	The name of a variable defined by the VARIABLE command.

 Usage Notes

SQL*DBA bind variables referenced with the print command do not need to be preceded by a colon. You can use the PRINT command to display variables defined only in the current SQL*DBA session. The SET CHARWIDTH and SET NUMWIDTH commands can affect the display of the PRINT command.

Examples	PRINT balance

 BALANCE  ----------  4687.24    SET CHARWIDTH 10  PRINT ename  ENAME  ----------  SCOTT

 ________________________________________

RECOVER

 Purpose

Performs media recovery on one or more tablespaces, database files, or the entire database.

 Prerequisites

You must be connected to the Oracle server as SYSOPER or SYSDBA. You cannot use the RECOVER command when connected via the multi-threaded server.

 Syntax

.

  Keywords and Parameters

DATABASE	Specifies restoring the entire database.

UNTIL TIME date	Specifies an incomplete, time-based recovery. Use single quotation marks in the following format:

'YYYY-MM-DD:HH24:MI:SS'.

UNTIL CHANGE integer	Specifies an incomplete, change-based recovery. The integer is the number of the SCN following the last change to which you wish to recover. For example, if you want to restore your database up to the transaction with an SCN of 9, you would specify UNTIL CHANGE 10.

UNTIL CANCEL	Specifies an incomplete, cancel-based recovery. Recovery proceeds by prompting you with the suggested filenames of archived redo log files, and recovery completes when you specify CANCEL instead of a filename.

USING BACKUP CONTROL FILE	Specifies that a backup of the control file is being used instead of the current control file.

PARALLEL integer	Specifies the degree of parallelism for a recovery session. The number specified with the PARALLEL keyword is the number of recovery processes that apply redo entries to datafiles. The value must be greater than one. This value overrides the RECOVERY_PARALLELISM initialization parameter.

NOPARALLEL	NOPARALLEL, the default, specifies that recovery is to proceed serially.

TABLESPACE tablespace	Specifies restoring a particular tablespace. Tablespace is the name of a tablespace in the current database. You may recover up to 16 tablespaces in one statement.

DATAFILE filename	Specifies restoring a particular database file. You can specify any number of datafiles.

 Usage Notes

To perform media recovery on an entire database (all tablespaces), the database must be mounted EXCLUSIVE and closed.

To perform media recovery on a tablespace, the database must be mounted and open and the tablespace must be offline.

To perform media recovery on a database file, the database can remain open and mounted with the damaged database files offline--unless the file is part of the SYSTEM tablespace.

Before using the RECOVER command, you must have restored good copies of the damaged database file(s) from a previous backup. Be sure you can access all archived and online redo log files dating back to when that backup was made.

When another log file is required during recovery, a prompt suggests the names of files that are needed. The name is derived from the values specified in the initialization parameters LOG_ARCHIVE_DEST and LOG_ARCHIVE_FORMAT. You should restore copies of the archived redo log files needed for recovery to the destination specified in LOG_ARCHIVE_DEST, if necessary.

During recovery you can accept the suggested log name by hitting return, cancel recovery by entering CANCEL instead of a log name, or enter AUTO for automatic file selection without further prompting.

If you have enabled autorecovery (described), recovery proceeds without prompting you with filenames. Status messages are displayed when each log file is applied.

When normal media recovery is done a completion status is returned.

For more information on recovery and the RECOVER command, see Chapter 19, "Recovering a Database" of the Oracle7 Server Administrator's Guide.

Additional Information: Additional options exist for parallel recovery. For details, see the Oracle7 Parallel Server Administrator's Guide and the Oracle7 Server Addendum.

Examples	RECOVER DATABASE

 RECOVER DATABASE UNTIL 30-AUG-90:04:32:00  RECOVER TABLESPACE ts_one, ts_two  RECOVER DATAFILE 'data1.db'

 ________________________________________

REMARK

 Purpose

Enter a comment, typically in SQL script files.

 Prerequisites

None.

 Syntax

 Usage Notes

Primarily for batch use of SQL*DBA. The comment is ignored by SQL*DBA and by Oracle. REMARK can be shortened to REM.

REM must be the first non-blank character string in the line.

Examples	Examples of valid comments embedded in a SQL file follow:

REM     This command file is creates a

REM     database. Edit it to fill in filenames

REM     and sizes, and invoke it from SQL*DBA.

REM

REM

CREATE DATABASE dbname ....

/* This is a SQL comment */ ...

...

;

REMARKs are recognized by SQL*Plus and by SQL*DBA. They put comments between SQL statements, while SQL comments (/*...*/) place comments within statements.

 ________________________________________

SET

 Purpose

Set or change characteristics of the current SQL*DBA session.

 Prerequisites

None.

 Syntax

  Keywords and Parameters

ARRAYSIZE integer	Sets the number of rows fetched at a time from the database. The default is 20 rows. The maximum is platform specific.

AUTO- RECOVERY	Specifying ON causes the RECOVER command to automatically apply the default filenames of archived redo log files needed during recovery. No interaction is needed when AUTORECOVERY is set to ON, provided the necessary files are in the expected location with the expected name. The filenames used when AUTORECOVERY is ON are derived from the values of the initialization parameters LOG_ARCHIVE_DEST and LOG_ARCHIVE_FORMAT.

OFF, the default option, requires that you enter the filenames manually or accept the suggested default filename given.

CHARWIDTH integer	Sets the column display width for CHAR data. If entered with no argument, returns the setting to the default. The default is 80; the range of values is operating system-specific.

COMPATIBILITY	Sets compatibility mode to V6 or V7. The compatibility mode setting affects the specification of character columns, integrity constraints, and rollback segment storage parameters.

CHAR Columns: When creating tables in Version 6 compatibility mode, CHAR columns are variable length. In Oracle7, such column definitions are fixed length.

Integrity Constraints: In Version 6 compatibility mode, the Version 6 syntax is still recognized, and the Oracle7 syntax is disabled. For mode V6, table constraints on CREATE TABLE statements are specified with V6 syntax:

CREATE TABLE {UNIQUE | PRIMARY KEY} CONSTRAINT ....

and specified constraints are disabled, by default. For mode V7, table constraints are specified with V7 syntax:

CREATE TABLE CONSTRAINT ....{UNIQUE | PRIMARY KEY}

and they are enabled.

Rollback Segment Parameters: Version 6 compatibility mode allows PCTINCREASE and MAXEXTENTS to be specified for rollback segments, and for other segments. Although the specifications are ignored, the syntax is allowed. (Use of these parameters is not recommended. They exist only for backward compatibility.)

Bind Variables: Bind variables of type VARCHAR2 are given type CHAR in Version 6 compatibility mode.

CYCLE integer	Sets the cycle time in seconds for the MONITOR command. Minimum time is 1 second; maximum is 3600. Normally, a cycle time of at least 5 seconds is preferred.

DATEWIDTH integer	Sets the column display width for DATE data. If entered with no argument, returns the setting to the default. The default is 9; the range of values is platform specific.

ECHO	ON enables echoing of commands entered from command files. OFF, the default, disables echoing of commands.

FETCHROWS integer	Limits the number of rows returned by a query. Useful with ordered queries for finding the "top ten" items in a category, for example. Also used with unordered queries to find the "first n" records that satisfy a given criteria.

If integer is not specified, SQL statement processing returns to the default method, returning all rows.

FLAGGER	Enables and disables FIPS flagging. When enabled, Oracle Server flags SQL statements that include extensions above and beyond the ANSI/ISO SQL 92 standard are flagged. Valid settings are:

ENTRY	--SQL92 Entry level

INTERMEDIATE	--SQL92 Intermediate level

FULL	--SQL92 Full level

OFF	--Turns off FIPS flagging

HISTORY integer	Determines the size of SQL*DBA's command history. This is the number of commands that can be recalled, edited, and reissued. The default value is 10. If integer is not specified, the default setting is used.

INSTANCE instance-path	Changes the default instance for your SQL*DBA session to the specified instance path. Does not connect to a database. The default instance is used for the STARTUP, SHUTDOWN, and CONNECT commands when no instance is specified.

Instance-path consists of a node name and a database name connected by a hyphen:

INSTANCE home_office-main_database

This option is not permitted when already connected to a database. Only a remote instance can be specified, not a local instance.

Any commands preceding first use of SET INSTANCE will communicate to the default instance.

To reset the instance to the default value for your operating system, you can either enter SET INSTANCE with no instance-name or SET INSTANCE LOCAL. For a description of how to set the initial default instance, see your operating system-specific Oracle7 documentation.

This command may be issued only when SQL*Net is running. You can use any valid SQL*Net connect string as the specified instance path. See your operating system-specific Oracle7 documentation for a complete description of how your operating system specifies SQL*Net connect strings. For more information on SQL*Net, see Understanding SQL*Net. The maximum length of the instance path is 64 characters.

LABWIDTH	This is a Trusted Oracle7 Server parameter. For more information, see the Trusted Oracle7 Server Administrator's Guide.

LINES integer	Specifies the number of lines of output that can be stored in SQL*DBA's output window. The default value is 1,000. If integer is not specified, the default setting is used.

LOGSOURCE pathname | DEFAULT	Specifies the location from which archive logs are retrieved during recovery. The default value is set by the LOG_ARCHIVE_DEST initialization parameter. Specifying the DEFAULT restores the setting for archive log location to this default value.

LONGWIDTH integer	Sets the column display width for LONG data. If entered with no argument, returns the setting to the default. The default is 80; the range of values is platform specific.

MAXDATA integer	Sets the maximum data size. Indicates the maximum data that can be received in a single fetch during a SELECT statement. The default is 20480 bytes (20K). The maximum is platform specific.

NUMWIDTH integer	Sets the column display width for NUMBER data. If entered with no argument, returns the setting to the default. The default is 10; the range of values is platform specific.

RETRIES integer | INFINITE	Sets the number of tries that will be attempted when the RETRY option is used with the STARTUP command (see page 12 - 29). INFINITE, the default, specifies an infinite number of retries.

SERVEROUTPUT	ON enables debugging output from stored procedures that use DBMS_OUTPUT PUT and PUT_LINE commands. OFF disables output.

You can specify the size in bytes of the message buffer using the syntax SIZE n. That is the total number of bytes of all messages sent that can be accumulated at one time. The minimum is 2,000 bytes. If the buffer fills before calls to the get-message routines make room for additional message bytes, an error is returned to the message-sending program.

SPOOL filename | OFF	Specifying a filename captures all future SQL*DBA output in the file, as well as in the output window. Specifying the default, OFF, disables output spooling.

STOPONERROR	Specifying ON indicates that if a command file is running and an error occurs, execution should terminate. OFF disables STOPONERROR.

TERM	Specifying PAGE causes one page of output to be displayed at a time in SQL*DBA's output window. An action is then required to get the next page of information. Specifying the default value, NOPAGE, causes all output to be displayed in the output window. If information scrolls off screen, you can use [Next Field] and [Previous Page] to go to the output window and view it, up to the limit set by the LINES parameter.

TERMOUT	ON, the default, enables terminal output for SQL commands. OFF disables terminal output. Useful for preventing output to terminal when spooling output to files. Note that nothing will appear on the terminal until SET TERMOUT ON is used.

TIMING	ON displays parse, execute, and fetch times (CPU and elapsed) for each SQL statement executed. OFF, the default, does not display timing information.

Examples	SET INSTANCE D:DEV-PROD

 SET TIMING ON  SET CYCLE 10  SET LONGWIDTH 132  SET NUMWIDTH 20  SET CHARWIDTH 5

Either of the following commands can revert to the initial default host:

SET INSTANCE

SET INSTANCE LOCAL

 ________________________________________

SHOW

 Purpose

 Show settings currently in effect.

 Prerequisites

None.

 Syntax

 Keywords and Parameters

ALL	Displays all settings except for ERRORS, PARAMETERS, and SGA.

ARRAYSIZE	Displays the number of rows fetched at a time from the database.

AUTORECOVERY	Displays the autorecovery setting.

CHARWIDTH	Displays the column display width for CHAR data.

COMPATIBILITY	Displays the sessions compatibility mode: V6 or V7.

CYCLE 	Displays the cycle time in seconds for the MONITOR command.

DATEWIDTH	Displays the column display width for DATE data.

ECHO	Displays the setting for echoing of commands from command files.

ERRORS	Displays the errors generated from the last compilation of a procedure, package, or function, if any. This option displays the line number, column number, and the error message generated. Use the SHOW ERRORS command if SQL*DBA error 72 is returned after compiling a package.

The SET CHARWIDTH command can expand or truncate the display from the SHOW ERRORS command.

FETCHROWS	Displays the limit on the number of records returned by a SELECT statement. If no limit is in effect, displays INFINITE.

FLAGGER	Displays the current setting of the FIPS flagger. When enabled, Oracle Server flags SQL statements that include extensions above and beyond the ANSI/ISO SQL 92 standard.

HISTORY	Displays the number of commands that can be recalled from SQL*DBA's command history buffer.

INSTANCE	Displays the connect string for the default instance. SHOW INSTANCE returns the local value if you have not used SET INSTANCE, or if you have used the LOCAL option of the SET INSTANCE command.

LABEL	This is a Trusted Oracle7 Server parameter. For more information, see the Trusted Oracle7 Server Administrator's Guide .

LABWIDTH	This is a Trusted Oracle7 Server parameter. For more information see the Trusted Oracle7 Server Administrator's Guide.

LINES	Shows the number of lines of output that can be recalled from the output window buffer.

LOGSOURCE	Shows the current setting for archive log location. Displays DEFAULT if the default setting is in effect, as specified by the LOG_ARCHIVE_DEST initialization parameter.

LONGWIDTH	Shows the column display width for LONG data.

MAXDATA	Displays the maximum data size.

NUMWIDTH	Shows column display width for NUMBER data.

PARAMETERS	Displays the current values for one or many initialization parameters. You can use a string after the command to see a subset of parameters whose names include that string. For example, if you enter:

SHOW PARAMETERS COUNT

you would see:

NAME                           TYPE  	   VALUE

-------------------            -------   -----

 	db_file_multiblock_read_count  integer    12

spin_count                     integer    0

The SHOW PARAMETERS command, without any string following the command, displays all initialization parameters.

RETRIES	Displays the number of retries that will be attempted when restarting an instance in parallel mode. See the RETRY option of the STARTUP command.

SERVEROUTPUT	Displays ON if output from stored procedures and functions is enabled. Otherwise, displays OFF.

SGA	Displays information about the current instance's System Global Area.

SPOOL	If spooling is enabled, displays the name of the output spool file. Otherwise, displays OFF.

STOPONERROR	Displays the setting for termination of command file execution when an error is encountered.

TERM	Shows the current terminal output setting: PAGE or NOPAGE (scroll).

TERMOUT	Shows if output to the terminal is enabled.

TIMING	Displays the setting for display of parse, execute, and fetch times (CPU and elapsed) for SQL statements.

VAR VARIABLES	Shows the names and datatypes of one bind variable, or for all bind variables declared in the current session.

Examples	SHOW ALL

returns a display like:

Instance           local

Spool              OFF

Timing             OFF

Termout            ON

Echo               ON

Stoponerror        OFF

Cycle              5

Autorecovery	OFF

Logsource	DEFAULT

Maxdata            20480

Arraysize          20

Fetchrows	INFINITE

Numwidth           10

Charwidth          80

Longwidth          80

Datewidth          9

Compatibility      V7

Flagger	off

Retries	infinite

Labwidth	32

History	10

Lines	1000

Term	nopage

ServerOutput	OFF

SHOW TIMING

returns a display such as:

Parse           2.94 (Elapsed)  0.20 (CPU)

Execute/Fetch  13.17 (Elapsed)  2.78 (CPU)

Total          16.11            2.98

SHOW SGA

returns a display like:

Total Shared Global Area          801280  bytes

Fixed Size                         13896  bytes

Variable Size                     369592  bytes

Database  Buffers                 409600  bytes

Redo Buffers                        8192  bytes

SHOW ERRORS PACKAGE BODY my_pkg

returns a display like:

ERRORS FOR PACKAGE BODY my_pkg:

LINE/COL	ERRORS

---------------------------------------------------------------

...

 ________________________________________

SHUTDOWN

 Purpose

Shut down a currently-running Oracle instance, optionally closing and dismounting a database.

 Prerequisites

System privileged command. You must be connected to a database as SYSOPER or SYSDBA. You cannot be connected via a multi-threaded server.

 Syntax

 Keywords and Parameters

ABORT	Proceeds with the fastest possible shutdown. Does not wait for calls to complete or users to disconnect. Does not close or dismount database, but does shut down instance. Requires instance recovery on next startup. You must use this option if a background process terminates abnormally.

IMMEDIATE	Does not wait for current calls to complete, prohibits further connects, and closes and dismounts the database. Finally, shuts down the instance. Does not wait for connected users to disconnect. Does not require instance recovery on next startup.

NORMAL	Waits for currently connected users to disconnect from the database, prohibits further connects, and closes and dismounts the database. Finally, shuts down the instance. Does not require instance recovery on next startup. NORMAL is the default option.

dbname	This is a Trusted Oracle7 Server parameter. For more information, see the Trusted Oracle7 Server Administrator's Guide.

 Usage Notes

SHUTDOWN with no arguments is equivalent to SHUTDOWN NORMAL. The instance that is shut down with this command is the default instance for your session specified with the SET INSTANCE command (see page 12 - 16).

Example	SHUTDOWN

 Database closed.  Database dismounted.  Oracle instance shut down.

 ________________________________________

SPOOL

 Purpose

Enable or disable spooling of output to a specified file.

 Prerequisites

None.

 Syntax

 Keywords and Parameters

filename	Any valid name for a spool file. If not specified, the file type or file extension is LOG. If a file by that name exists, an error is generated.

OFF	Closes the previously opened spool file.

 Usage Notes

Additional Information:  For the default filename on your system, see to your operating system-specific Oracle7 documentation. To see whether you are currently spooling, enter SHOW SPOOL.

Note: Monitor display output cannot be SPOOLed. All other forms of SQL*DBA output can.

Example	To create a file named JELLO.LOG, enter:

SPOOL JELLO

 ________________________________________

STARTUP

 Purpose

Start an Oracle instance, with several options, including mounting and opening a database.

 Prerequisites

System privileged command. You must be connected to a database as SYSOPER or SYSDBA. You cannot be connected via a multi-threaded server.

 Syntax

 Keywords and Parameters

database	Specifies the database name. If no database name is specified, then the database name is taken from the current initialization parameter DB_NAME.

EXCLUSIVE	Signifies that the database can only be mounted and opened by the current instance (it cannot be opened simultaneously by multiple instances). Cannot be used with SHARED, PARALLEL, or NOMOUNT. If no mounting option is specified, EXCLUSIVE is assigned by default.

FORCE	Shuts down the current Oracle instance (if it is running) with SHUTDOWN mode ABORT before restarting it. If the current instance is running and FORCE is not specified, an error results. FORCE is useful while debugging and under abnormal circumstances. It should not normally be used.

MOUNT	Mounts a database, but does not open it.

NOMOUNT	Causes the database not to be mounted upon instance startup. Cannot be used with SHARED, EXCLUSIVE, PARALLEL, MOUNT, or OPEN.

OPEN 	Mounts and opens the specified database.

PARALLEL	Must be specified if the database is to be mounted by multiple instances concurrently. Cannot be used with EXCLUSIVE or NOMOUNT. Invalid if the initialization parameter SINGLE_PROCESS is set to TRUE.

PFILE=filename   	Causes the specified parameter file to be used while starting up the instance.

RECOVER	Specifies that media recovery is to be performed, if necessary, before starting the instance. STARTUP RECOVER has the same effect as issuing the RECOVER DATABASE command and starting an instance. Only complete recovery is possible with the RECOVER option.

Recovery proceeds, if necessary, as if AUTORECOVERY were set to ON, even if AUTORECOVERY was not enabled. If a redo log file is not found in the expected location, recovery continues as if AUTORECOVERY is disabled by prompting you with the suggested location and name of the subsequent log files that need to be applied. See "Usage Notes" of the RECOVER command for a description of how to proceed with recovery when AUTORECOVERY is disabled.

If recovery fails using the RECOVER option, the database remains mounted and closed.

RESTRICT	Only allows Oracle users with the RESTRICTED SESSION system privilege to connect to the database. Later, you can use the ALTER SYSTEM command to disable the restricted session feature.

RETRY	Specifies that opening the database should be attempted every five seconds if the instance is busy being recovered by another instance. When an instance is being recovered by another instance, the down instance cannot open the database until recovery is complete. If the database cannot be opened for any other reason, RETRY will not attempt to open the database again. This option is only available for instances operating in PARALLEL mode. The number of times RETRY attempts to start the database can be set with the SET command (see page 12 - 16).

SHARED	Synonym for PARALLEL.

 Usage Notes

No option can be used twice, and some options are mutually exclusive. With no arguments, STARTUP starts the current instance with the default database, mounts the database, and opens it.

To start a remote instance, first use SET INSTANCE and then use the STARTUP command.

Examples	To start an instance with the standard parameter file, mount the default database in exclusive mode, and open the database, enter:

STARTUP

or enter:

STARTUP OPEN databasename EXCLUSIVE

To start an instance with the standard parameter file, mount the default database in parallel mode, and open the database, enter:

STARTUP PARALLEL

STARTUP OPEN databasename PARALLEL

If an instance went down in parallel mode, and you do not know if other instances have completed recovery, restart the instance using the RETRY option:

STARTUP PARALLEL RETRY

To shut down the current instance, immediately restart without mounting or opening, and allow only database administrators to connect, enter:

STARTUP FORCE NOMOUNT RESTRICT

To start an instance with the parameter file TESTPARM without mounting the database, enter:

STARTUP PFILE=testparm NOMOUNT

To shut down a particular database, immediately restart and open it in parallel mode, allow only database administrators access, and use the file MYINIT.ORA, enter:

STARTUP OPEN databasename PFILE=myinit.ora FORCE SHARED RESTRICT

To start up an instance and mount but not open a database, you must use the following sequence of commands (the system's response is also shown):

STARTUP NOMOUNT

Oracle instance started.

CONNECT scott/tiger AS SYSOPER

Connected.

ALTER DATABASE MOUNT;

Statement processed

At this point, you could run a maintenance command and then open the database, as shown in the following commands:

ALTER DATABASE ARCHIVELOG;

Statement processed.

ALTER DATABASE OPEN;

Statement processed.

 ________________________________________

VARIABLE

 Purpose

Declare a bind variable for use in the current session with the EXECUTE or PRINT command or for use with a PL/SQL block.

 Prerequisites

None.

 Syntax

 Keywords and Parameters

name	The name of the bind variable you wish to define.

type	The datatype of the bind variable. The valid datatypes are NUMBER, DATE, CHAR, and VARCHAR2. You can specify a length from 1 to 255 for CHAR, and from 1 to 2,000 for VARCHAR2. If you do not specify a length, CHAR and VARCHAR2 both default to a length of 1. Lengths specified as greater than the maximum default to the maximum.

 Usage Notes

Variables are referenced by preceding them with a colon (:). They can be set with the EXECUTE command defined.

Bind variables defined with the VARIABLE command exist until the end of the SQL*DBA session. Variables defined in your session cannot be accessed or changed by a different session.

Warning: CHAR variables are fixed length, padded with blanks. VARCHAR2 variables are variable length. You must use CHAR when passing a character variable to a PL/SQL procedure that defines a CHAR parameter. Otherwise, a conversion error results. A PL/SQL procedure that expects a VARCHAR2 variable, on the other hand, will automatically convert a CHAR parameter to the proper form. In general, it is a good idea to avoid the use of CHAR variables in PL/SQL procedures unless blank-padding is an absolute requirement.

Note: In V6 compatibility mode, a CHAR variable is variable length, rather than fixed.

Example	A stored function get_name can be defined with the following SQL statement:

CREATE OR REPLACE FUNCTION get_name(in_empno IN NUMBER)

RETURN VARCHAR2

IS

out_ename VARCHAR2(20);

BEGIN

SELECT ename INTO out_ename FROM emp

WHERE empno = in_empno;

RETURN(out_ename);

END;

The following commands can then look up an employee name from the EMP table:

VARIABLE  name VARCHAR2(20)

EXECUTE  :name := get_name(7369)

PRINT  name

ENAME

----------

SMITH


CHAPTER 13. THE SQL*DBA MONITORS

Using SQL*DBA's monitors, you can view ongoing use of the database. For example, you can see:

•	Oracle usernames of current database users

•	which programs they are running

•	which tables they are accessing

•	a summary of I/O

•	cumulative statistics about database usage

 ________________________________________

Using the Monitors

You can invoke a particular monitor with the menu interface described in Chapter 11, "SQL*DBA Monitors" or with a command. For example:

MONITOR LOCK

The monitors provide a continuously updated display of database activity. So you can monitor activity over time to spot patterns of normal or abnormal database use.

MONITOR displays are updated at intervals. The default interval is every five seconds. You can change the interval using the SQL*DBA command SET CYCLE. Although valid intervals may range from 1 to 3600 seconds, because some overhead is associated with refreshing the screen, a minimum interval of 5 seconds is recommended.

The monitor displays are described in the following sections.

Additional Information:  The format or content of a field may be operating system dependent. For more information, see your operating system-specific Oracle7 documentation.

Note:

•	The output of the monitor displays cannot be spooled with SQL*DBA's SPOOL command. This is an exception to the normal operation of the SPOOL command.

•	The displays on your operating system may vary somewhat from the samples shown in this chapter.

•	The monitors only operate in screen mode. They are not available in line mode.

 Troubleshooting

If you have trouble getting the MONITOR screens to display properly, check the following prerequisites:

•	Do you have access to SQL*DBA?

•	Do you have access to the underlying dynamic performance tables?

•	Is the INIT.ORA parameter TIMED_STATISTICS set to true? This setting is required for some statistics.

•	Are you running SQL*DBA in window mode? The monitors are not available in interactive line mode. See Chapter 11, "SQL*DBA Monitors" for details.

•	Has CATALOG.SQL been run to create the views that the monitor screens use?

 Displaying Multiple Monitors

You can run several monitors at once. For example, after starting one monitor, you can use [Menu], open the Monitor menu, and start up another monitor.

You can then use [Rotate Window] to cycle between the monitor displays and the initial command editor/output screen. Another way to initiate other monitors is to use [Rotate Window] to get back to the command editor and then issue another monitor command.

 Hiding Monitors

When you select Hide from the monitor window, the monitor display goes away, but it continues functioning. While hidden, the monitor screen is not included in the [Rotate Window] cycle. To reopen the display, reissue the command or reselect the menu choice.

 Terminating Monitors

To terminate a monitor, use [Cancel] or select the Quit button.

 Granting Other Users Access to Monitors

By default, only user SYS has access to the dynamic performance tables that provide the information shown in the monitor displays. To grant access to all other users, SYS can run the file CATMONTR.SQL. This file contains the necessary grants to allow all users to view the monitor screens. (They must also have access to SQL*DBA to use the SQL*DBA monitor functions.)

You may modify CATMONTR.SQL if you wish to grant access to these tables to a select group of users rather than to PUBLIC (all users).

 Dynamic Performance Tables Used by Monitors

In addition to using the monitor displays, you can directly access the data shown in the displays. The data is stored in pseudo-tables, called dynamic performance tables. These tables are stored only in memory. They are not physically on the disk, but they can be queried as if they were read-only tables stored in the database

These tables are created by CATALOG.SQL and are owned by SYS. Views created on these tables begin with "V$". Access these views to see the data in the tables. The views used by each monitor are listed on the next page. You can also use this list as a guide for granting selective access to monitors.

Monitor	Required Table(s)

CIRCUIT	V$CIRCUIT

V$DISPATCHER

V$SESSION

V$SHARED_SERVER

DISPATCHER	V$DISPATCHER

FILE I/O	V$DBFILE

V$FILESTAT

LATCH	V$LATCH

V$LATCHHOLDER

V$LATCHNAME

LIBRARY CACHE	V$LIBRARYCACHE

LOCK	V$LOCK

V$SESSION

PROCESS	V$PROCESS

QUEUE	V$QUEUE

ROLLBACK	V$ROLLNAME

V$ROLLSTAT

SESSION	V$PROCESS

V$SESSION

SESSION STATISTIC	V$SESSTAT

V$SYSSTAT

SHARED SERVER	V$SHARED_SERVER

SYSTEM STATISTIC	V$SYSSTAT

SQL AREA	V$SQLAREA

SYSTEM I/O	V$PROCESS

V$SESSION

V$SESSTAT

TABLE ACCESS	V$ACCESS

 ________________________________________

File I/O Monitor

The File I/O monitor shows the read and write activity on each file in the database.

Figure 13 - 1.  File I/O Monitor

Enter a filename template, or pattern, to determine which files are displayed. Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

The File I/O monitor contains one row for every database file and summarizes the read and write activity on those files. Reads are performed by user processes. All writes are performed by the background process DBWR. The figure above shows the display.

If database files are added or dropped while this display is on the screen, you should redisplay the screen for an update.

The second and third columns show the request rate of reads or writes per second. If one of these values is high for all files on a given drive, you should consider restructuring your database to allocate database files and tablespaces across additional disk drives.

The product of column 3 and column 5, batch size of blocks written, shows how much data was written to disk per second. If this value is high relative to the capacity of that disk, then you should consider changing the disk to one with a higher transfer rate.

To obtain the total of all physical reads or writes for a disk made by Oracle, add the relevant columns for all files located on the same disk. Note that this display does not show I/O to other files that may be on the same disk.

When an index is generated or a SELECT statement is issued, a temporary sort file may be created. Look for excessive I/O to such files. Consider increasing SORT_AREA_SIZE or assigning different tablespaces to different groups of users.

Warning: You will see values in column 6 and column 7 only if you set the INIT.ORA parameter TIMED_STATISTICS to TRUE. The default value for this parameter is false, because of the overhead associated with the collection of timing statistics.

Command equivalent:	MONITOR FILEIO (SQL*DBA)

 ________________________________________

Latch Monitor

The Latch monitor shows how internal data structure latches are  being used.

Figure 13 - 2.  Latch Monitor

Monitoring begins immediately with this display. Press [Accept] or select Restart to initiate a new display.

Latches protect shared data structures in the SGA. A user or background process acquires a latch when working with a structure and releases the latch when finished with the structure. Each latch protects a different set of data, identified by the latch name.

The latch monitor shows the process that is currently holding the latch and the ratios of waits and timeouts per request.

Additional Information:  Latching and timeout algorithms  are platform-dependent. For more information on these algorithms, see your platform-dependent Oracle7 documentation.

On some operating systems, processes timeout without waiting for a resource. On other systems, processes will make several attempts to obtain a latch before timing out. If the value for timeouts is high, it is more indicative of a problem in the latter type of system than in the former.

The values shown in the Gets columns indicate latches that were obtained without a wait. The Willing To Wait...Misses column shows the ratio for processes that were willing to wait and did so. Willing To Wait...Sleeps shows the ratio for processes that timed out while waiting. The No-Wait...Misses column shows the ratio for processes that were not willing to wait and failed to get the latch.

Command equivalent:	MONITOR LATCH (SQL*DBA)

 ________________________________________

Library Cache Monitor

The Library Cache monitor shows the activity in and effectiveness of the library cache.

Figure 13 - 3.  Library Cache Monitor

Fill in the name of the cache you want to monitor, or leave the default value intact to monitor all cache areas. Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

The Gets columns refer to object handles. The Pins columns refer to the objects. The Requests column shows the number of times a Get or Pin was attempted. A Hit occurs when the object or handle is already in the cache. Otherwise, it is a miss and the item must be retrieved from disk. Hit Ratios close to 1 indicate effective caching.

The Reloads column shows the number of times that objects have to be reinitialized and reloaded because they have aged out or been invalidated. The Invalidtns column shows the number of times that non-persistent library objects have been invalidated.

Command equivalent:	MONITOR LCACHE (SQL*DBA)

 ________________________________________

Lock Monitor

The Lock monitor shows database locks.

Figure 13 - 4.  Lock Monitor

Monitoring begins immediately with this display. Press [Accept] or select Restart to initiate a new display.

See the description of the V$LOCK table (upon which this monitor is based) in Appendix B, "Data Dictionary Reference", of the Oracle7 Server Administrator's Guide for a list of the Lock Types displayed in this screen. For a complete discussion of the types of locks, see Chapter 10, "Data Concurrency" of the Oracle7 Server Concepts Manual.

The combination of Session ID and Serial Number uniquely identifies a user session. Resource ID identifies the object affected by the lock.

The values in the Mode Held and Mode Requested columns have the following meanings:

Value	Mode Held	Mode Requested

------------------------------------------------------------------------

None	Lock not held	Lock not requested

Null	Lock ID obtained	Lock ID requested or

(but not the lock)	Lock released (transient)

RS	                        Row Share, Share Update

RX	                             Row Exclusive

S	                                 Share

SRX	                          Share Row Exclusive

X	                               Exclusive

Table 13 - 1.  Lock Modes

Note: The table with a lock can be identified by looking up the resource ID in the Table Access monitor. Locks on tables may continue to be shown on the Lock monitor, however, even when the resource ID for the table is no longer shown on the Table Access monitor. This situation occurs whenever the cursor has been closed, but a COMMIT has not been issued.

Command equivalent:	MONITOR LOCK (SQL*DBA)

 ________________________________________

Multi-Threaded Monitor

The Multi-threaded monitors show information on Oracle's management of multiple sessions on shared servers. The multi-threaded monitors are chosen from the Multi-threaded submenu. They include the following monitors:

•	Shared Server monitor

•	Dispatcher monitor

•	Circuit monitor

•	Queue monitor

 Shared Server Monitor

This monitor displays the server processes.

Figure 13 - 5.  Multi-Threaded Monitor: Shared Server

Enter a server name template, or pattern, to determine which servers are displayed. Select a status pattern or leave the default entry for all status values. The status values and column descriptions are given in the description of the V$SHARED_SERVERS table in the Data Dictionary appendix of the Oracle7 Server Administrator's Guide or Oracle7 Server Application Developer's Guide.

Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

Command equivalent:	MONITOR SHARED (SQL*DBA)

 Dispatcher Monitor

This monitor displays information on the shared server's dispatcher processes.

Figure 13 - 6.  Multi-Threaded Monitor: Dispatcher

Enter a template for the names of dispatcher process IDs you want to monitor. Select a status pattern or leave the default entry for all status values. The status values and column descriptions are given in the writeup of the V$DISPATCHERS table in the Data Dictionary appendix of the Oracle7 Server Administrator's Guide or Oracle7 Server Application Developer's Guide.

Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

Command equivalent:	MONITOR DISPATCHER (SQL*DBA)

 Circuit Monitor

This monitor displays information on the shared servers virtual circuits, through which users connect to the database.

Figure 13 - 7.  Multi-Threaded Monitor: Circuit

Monitoring begins immediately with this display. Press [Accept] or select Restart to initiate a new display. The first five columns specify a unique system path identified by circuit, server, dispatcher, session ID, and session serial number.

For each path, the monitor shows circuit status, currently active queue, number of messages, and total bytes transferred. For a description of these columns, including status values, see the V$CIRCUITS table in the Data Dictionary appendix of the Oracle7 Server Administrator's Guide or Oracle7 Server Application Developer's Guide.

Command equivalent:	MONITOR CIRCUIT (SQL*DBA)

 Queue Monitor

This monitor displays information on the multi-threaded server's message queues.

Figure 13 - 8.  Multi-Threaded Monitor: Queue

Monitoring begins immediately with this display. Press [Accept] or select Restart to initiate a new display. The first two columns identify a particular queue and the process that owns it. The next three columns identify the number of messages currently in the queue, the total number of messages that have ever been in the queue, and the average wait time for each message.

Command equivalent:	MONITOR QUEUE (SQL*DBA)

 ________________________________________

Process Monitor

The Process monitor shows all background and user processes currently accessing the database through the current instance.

Figure 13 - 9.  Process Monitor

Enter the range of Oracle process IDs that you want to monitor. Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

The Process monitor shows

•	the Oracle process ID's (PID's) of processes that are accessing the database from this instance

•	the operating system process ID's (PID's)

•	the system username associated with each process

•	latch the process is waiting on, if any

•	the terminal the process is running from (if the process is interactive)

•	the Oracle program each process is executing

To determine the last SQL statement executed by a process, use the Session monitor.

Process 1 is the PSEUDO process. It is not a real operating system process, but rather is a placeholder for sessions that are due to be recovered or migrated. For example, when KILL SESSION is executed, the session is moved to the PSEUDO process until it can be completely deleted.

Processes 2 through 5 are always present and represent the four background processes (DBWR, LGWR, SMON, and PMON). Process 6 represents ARCH, if it is enabled. These processes always appear in the same order, and they all run the same program.

The username shown in the third column is not the Oracle username, but the name of the operating system account or ID from which that user is accessing the database.

Command equivalent:	MONITOR PROCESS (SQL*DBA)

 ________________________________________

Rollback Segment Monitor

The Rollback Segment monitor shows the current status of rollback segments.

Figure 13 - 10.  Rollback Segment Monitor

Enter a filename template, or pattern, to determine which files are displayed. Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

Gets is the number of gets per second. When you have multiple rollback segments, these values should be similar for all rollback segments, indicating that they are being accessed evenly.

If the value in the column Extents is high, then you may wish to create additional rollback segments or increase the size of current segments.

Waits/s is the number of waits per second. A high value in this column shows contention for the headers of rollback segments. In this case, you should consider adding more rollback segments.

Command equivalent	MONITOR ROLLBACK (SQL*DBA)

 ________________________________________

Session Monitor

The Session monitor shows statistics and information for each user session in the current instance.

Figure 13 - 11.  Session Monitor

Monitoring begins immediately with this display. Press [Accept] or select Restart to initiate a new display.

This display shows the Session ID and session Serial Number currently assigned to the username, the Oracle Process ID (PID), the session's status (Active, Inactive, or Killed), Oracle Username, and the most recent SQL statement executed in that session.

Command equivalent:	MONITOR SESSION (SQL*DBA)

 ________________________________________

SQL Area Monitor

The SQL Area monitor shows the memory that processes SQL statements that have been or are being executed.

Figure 13 - 12.  SQL Area Monitor

You can specify a pattern in the Statement Filter to restrict the display. Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

The text of the SQL statement is shown, along with the number of separate executions of that statement (Version Count), the sharable memory used for the statement, and the Per-User Memory. Both Persistent and transient per-user memory are shown. Transient memory (Runtime) only exists while a SQL statement is executing. Persistent memory is retained between executions of the statement.

Command equivalent: 	MONITOR SQLAREA (SQL*DBA)

 ________________________________________

Statistics Monitors

The Session Statistic and System Statistic monitors show runtime statistics on system use and performance for the current instance. You can choose statistics for selected sessions or obtain systemwide statistics.

Figure 13 - 13.  Session Statistic Monitors

Both the Session Statistic and System Statistic monitors have similar displays and provide similar options. The session monitor is shown above. The system monitor is equivalent, except for the session-range fields.

Fill in the range of sessions you wish to monitor. The default is all sessions. Then select the types of statistics you want to display. Use [Accept] or choose Restart to initiate a new display.

Command equivalents:  	MONITOR SESSIONSTATISTIC and  MONITOR SYSTEMSTATISTIC (SQL*DBA)

 Column Headings

With some exceptions, all statistics are shown as rates per second. (The exceptions are noted in the descriptions in this section.) The following columns appear:

CURRENT	Current change in the value for this statistic. This value is the value as of the last cycle's update.

AVERAGE	Average change in the value of this statistic since the screen was displayed. If the screen is on a user process basis, the average is shown for that process. If the screen represents all processes, then the average is across all processes.

MINIMUM	Represents the lowest value in this cycle for a given statistic since the screen was displayed.

MAXIMUM	Represents the highest value in the cycle for a given statistic since the screen was displayed.

TOTAL	Represents the total value for each statistic since the screen was displayed, on either a process or global basis.

Note: Statistics that provide time durations are only available if the TIMED_STATISTICS parameter is enabled. For details, see Appendix A, "Parameter Files and Initialization Parameters", in the Oracle7 Server Administrator's Guide.

 Available Statistics

The following kinds of statistics are available:

USER	PARALLEL SERVER

REDO	SQL

ENQUEUE	INTERNAL

CACHE

The statistics in each category are discussed in the remainder of this section.

 User Statistics

These statistics provide information on CPU and resource use by Oracle users. These statistics also provide information on the calls, commits, and rollbacks that users initiate. The session monitor covers specified sessions. The system monitor covers all sessions.

CPU used by this session	Amount of CPU time used in 1/100's of a second.

cumulative logons	On a system-wide basis, the number in the CURRENT column is the number of new logons for this cycle. It always equals the corresponding number in current logons. On a per-process basis, this number is always 0 or 1.

The number in the TOTAL column is the number of processes that have ever logged on (including those that have since logged off). It is not reset to zero when the display is called, but is cumulative from the last warm start.

cumulative opened cursors	Total number of cursors that have ever been opened.

current logons	Number of current logons.

current open cursors	Number of cursors that are currently open.

cursor authentications	Number of times that cursor privileges have been verified, either for a SELECT or because privileges were revoked from an object, causing all users of the cursor to be re-authenticated.

logical reads per session	Number of logical disk reads that were satisfied from the cache or by a physical read from the disk.

max pga memory	Maximum amount of PGA memory ever used.

max session memory	Maximum amount of UGA memory ever used.

pga memory	Amount of PGA memory currently in use.

recursive calls	Number of recursive calls including data dictionary operations. A high value shows information is not being found often enough in the dictionary cache, either because parsing is occurring frequently or because the cache is not large enough.

recursive cpu usage	Amount of CPU time (in 1/100's of a second) that was spent updating internal tables while processing user SQL statements; for example, time spent doing space allocation. A high value shows a lot of data dictionary work.

session connect time	Total elapsed time that the session has been connected to the server in 1/100's of a second.

session memory	Amount of UGA memory used by the session.

session stored procedure space	Number of bytes allocated to stored procedures used in the session.

user calls	Number of user calls processed. A user call is made for each SQL statement processed.

user commits	Number of commits executed for this process or systemwide, both explicit (initiated by command) and implicit (initiated at the start of a DDL-change command, such as CREATE TABLE)

user rollbacks	Number of rollbacks for this process.

 Redo Statistics

These statistics provide information on the redo log files.

redo blocks written	Total number of redo blocks written.

redo buffer allocation retries	Total number of retries necessary to allocate space in the redo buffer. Retries are needed either because the redo writer has fallen behind or because an event such as a log switch is occurring.

redo entries	Number of redo entries generated.

redo entries linearized	Number of entries less than or equal to REDO_ENTRY_PREBUILD_THRESHOLD. Building these entries requires additional CPU but increases concurrency on multiple-user systems.

redo log space requests	Number of times LGWR was given a request to write a redo log buffer.

redo log space wait time	Time spent waiting for log space (in 1/100's of a second). A very high or rapidly increasing value may indicate a problem with log archiving.

redo log switch interrupts	Times an instance log switch was requested by another instance when running in parallel mode.

redo ordering marks	Number of extra SCN's allocated to maintain ordering of redo logs, as a result of blocks migrating from one instance's cache to another. The count of these pings is a measurement of cross-talk between instances when running in parallel mode. If this value is very high, it may indicate a need for a better separation of instance activities.

redo size	Amount of redo generated in bytes.

redo small copies	Total number of entries less than or equal to LOG_SMALL_ENTRY_MAX_SIZE. These entries are copied under the protection of the allocation latch, eliminating the necessity of the copy latch. This statistic generally is applicable to only multiple-processor systems.

redo wastage	Cumulative total of unused bytes written to the log. The redo buffer is flushed periodically even when not completely filled. So, this value may be nonzero.

redo write time	Cumulative elapsed time spent on log I/O.

redo writes	Total number of redo writes.

 Enqueue Statistics

These statistics provide information on the locks seen in the MONITOR LOCKS display.

enqueue requests	Number of times an enqueue (lock) was requested.

enqueue waits	Number of times an enqueue request resulted in a wait. Enqueue requests minus enqueue waits is the number of no-wait enqueue requests.

enqueue timeouts	Number of times an enqueue (lock) request was not granted within the allotted wait time and had to be resubmitted. A very large or rapidly increasing value shows a high degree of internal contention. Tuning may be required.

enqueue conversions	Number of enqueue locks converted to a different mode; for example, from shared to exclusive.

enqueue releases	Number of times an enqueue (lock) was released. This statistic should keep pace with enqueue requests.

enqueue deadlocks	Number of process deadlocks that occurred due to enqueues (locks) for DDL operations.

 Cache Statistics

These statistics provide information on I/O cache performance.

background checkpoints completed	Number of times DBWR completes a checkpoint.

background checkpoints started	Number of times DBWR starts a checkpoint.

buffer busy waits	Number of times that a user process wanted a buffer in a mode incompatible with the current use of that buffer. A high value shows block-level contention.

busy wait time	Amount of time spent in buffer busy waits in 1/100's of a second.

change write time	Amount of time waiting for redo buffer space, inserting redo information into the buffer, and allocating an SCN, if needed, in 1/100's of a second.

consistent changes 	Number of log changes to produce read-consistent blocks.

consistent gets	Number of logical reads in read-consistent mode. The sum of this number and db block gets equals logical reads.

cross instance CR read	Number of times the current instance did a consistent read in parallel mode. These tend to be slow, since every instance is told to write out the block. Instance functions should be arranged so that this value is kept small.

db block changes	Number of logical changes to current database blocks.

db block gets	Number of requests for the current copy of a block. This number plus consistent gets equals logical reads.

DBWR buffers scanned	Number of buffers in the Least Recently Used (LRU) buffer chain scanned by DBWR when looking for dirty buffers to flush to disk. This count includes both dirty and clean buffers. Divide by "DBWR lru scans" to get the average number of buffers scanned.

DBWR checkpoints	Number of times DBWR was notified to do a checkpoint.

DBWR cross instance writes	Number of blocks written for cross-instance calls so another instance could do a consistent read.

DBWR exchange waits	Used in multi-instance only. The number of times the DBWR was requested to exchange blocks between instances. Useful only when shown for the DBWR process.

DBWR free buffers found	Number of buffers that DBWR found already clean when requested to make free buffers. Divide by "DMWR make free requests" to find the average number of reusable buffers at the end of the lru. This value is only incremented when the lru is scanned in response to a make-free request.

DBWR lru scans	Number of times DBWR does a scan of the lru queue looking for more buffers to write. This includes times when the scan is made to fill out a batch being written for another purpose, such as a checkpoint. So it will always be equal to or greater than "DBWR make free requests".

DBWR make free requests	Number of requests received by DBWR to make more free buffers for the lru. This includes the times that DBWR sends such a request to itself.

DBWR summed scan depth	Sum of the current scan depth for each scan of the lru by DBWR when DBWR is looking for dirty buffers. The actual number of buffers scanned may be less than the scan depth, as a result of dirty buffers being placed in the dirty queue by foreground processes.

Divide by "DBWR lru scans" to find the average scan depth. Compare this value with the value calculated from "DBWR buffers scanned" to see how much scanning is actually performed.

DBWR timeouts	Number of timeouts at which DBWR had been idle since the last timeout. These are the times that DBWR looked for buffers to idle write.

dirty buffers inspected	Number of modified buffers found in the cache. If the value is large or increasing rapidly, DBWR is not working fast enough. Tuning may be required.

exchange deadlocks	Number of times a process detected a potential deadlock when exchanging two buffers, so raising an internal, restartable error. Index operations are the only operations that perform exchanges. If this number is high, increase the parameters GC_DB_LOCKS and DB_BLOCK_BUFFERS.

free buffer inspected	Number of buffers skipped in the buffer cache to find a free buffer. High values potentially indicate that user processes are doing too much work and DBWR not enough.

free buffer requested	Total number of free buffers needed.

free buffer waits	Number of times a process needed a free buffer (to read from the disk or to make a read-consistent block) and a free buffer was not available.

free wait time	Time spent waiting for a free buffer in 1/100's of a second. If this value is very large or rapidly increasing, then DBWR is not keeping pace with database activity, and tuning may be indicated.

hash latch wait gets	Number of times latches had to be obtained using waits rather than no-wait gets. If this value is large or rapidly increasing, you can increase the number of hash latches.

lock element waits	Number of waits for a parallel cache lock.

physical reads	Number of reads of database blocks from disk.

physical writes	Number of actual writes to disk made by DBWR. For multiple-user systems, this value is always 0, except for DBWR.

redo synch time	Amount of time waiting for redo logs to be written after a COMMIT in 1/100's of a second.

redo synch writes	Number of times the redo is forced to disk, usually for transaction commit.

remote instance undo requests	Number of times this instance acquired a lock (mode=SHARE) on undo from another instance to perform a consistent read.

remote instance undo writes	Number of times this instance wrote a dirty undo block so another instance could read it.

summed dirty queue length	Number of buffers pending for writing. If this value is large or increasing rapidly, then increase the write-batch size.

write complete waits	Number of times a process waited for DBWR to write a current block before making a change.

write requests	Number of multiblock writes performed.

write wait time	Amount of time spent waiting for DBWR to finish writing a block in the buffer cache before being allowed to change it.

 Parallel Server Statistics

These statistics provide information on the Parallel Server.

cross instance CR read	Number of times the current instance did a consistent read in parallel mode. These tend to be slow, because every instance is told to write out the block. Instance functions should be arranged so that this value is kept small.

DBWR cross instance writes	The number of blocks written for cross-instance calls so that another instance could do a consistent read.

global lock converts (async)	The number of instance locks that were converted from one mode to another during which other tasks were enabled.

global lock converts (non-async)	The number of instance locks that were converted from one mode to another during which no other tasks could run.

global lock convert time	The amount of time spent waiting for instance lock conversion in 1/100's of a second.

global lock gets (async)	The number of instance locks that were acquired when other tasks could be enabled during the wait.

global lock gets (non-async)	The number of instance locks that were acquired when other tasks could run during the wait.

global lock get time	The amount of time spent waiting to acquire instance locks in 1/100's of a second.

global lock releases (async)	The number of instance locks that were released when other tasks could be enabled during the wait.

global lock releases (non-async)	The number of instance locks that were released when other tasks could run during the wait.

global lock release time	The amount of time spent waiting to release instance locks in 1/100's of a second.

hash latch wait gets	The number of times latches had to be obtained using waits rather than no-wait gets. If this value is large or rapidly increasing, you can increase the number of hash latches.

lock element waits	Number of waits for a parallel cache lock.

next SCNs gotten without going to DLM	Number of SCNs obtained without Distributed Lock management. To measure the effectiveness of the Parallel Server's SCN cache, divide this value by the total number of SCN gets as given by the user statistic "user commits". This gives the percentage of SCN gets satisfied from the cache.

remote instance undo requests	Number of times this instance acquired an SS lock on undo from another instance to perform a consistent read.

remote instance undo writes	Number of times this instance wrote a dirty undo block so another instance could read it.

 SQL Tuning Statistics

These statistics provide information on SQL tuning and table characteristics. This kind of information can also be made available on a statement-by-statement basis with the ALTER SYSTEM SET SQL_TRACE command.

cluster key scans	Number of full table scans or clustered tables performed by fetching rows using the cluster key.

cluster key scan block gets	Number of blocks read while performing full table scans or clustered tables using the cluster key.

table fetch by rowid	Number of logical rows fetched from a table.

table fetch continued row	Number of additional physical fetches required to access broken rows. Divide this number by "table fetch by rowid" for a percentage of broken rows, where rows with multiple breaks count as multiple broken rows.

table scan rows gotten	Number of rows fetched during full table scans.

table scan blocks gotten	Number of logical block reads during table scans.

table scans (long tables)	Number of full table scans of long tables. A long table has more blocks than the value specified by the SMALL_TABLE_THRESHOLD parameter. (All blocks over this amount are reused immediately instead of aging out of the lru queue.)

table scans (short tables)	Number of full table scans of short tables. A short table is one in which all of the table's blocks are aged out of the lru queue in normal fashion, because the number of blocks in the table is smaller than the value of SMALL_TABLE_THRESHOLD.

parse count	Number of SQL statements parsed.

parse time cpu	Amount of CPU time spent parsing SQL statements in 1/100's of a second.

parse time elapsed	Amount of elapsed time spent parsing SQL statements in 1/100's of a second.

sorts (disk)	Number of disk sorts. Each disk sort requires the memory specified by the SORT_AREA_SIZE parameter.

sorts (rows)	Number of rows sorted.

sorts (memory)	Number of in-memory sorts. Sorts remain in memory when the total required sort space is less than the value specified by the SORT_AREA_RETAINED_SIZE parameter.

 Internal Statistics

These statistics are for internal use. At times, some of these statistics may be needed by Oracle personnel to assist in problem identification and resolution.

 ________________________________________

System I/O Distribution Monitor

The System I/O Distribution monitor shows the percentage of I/O activity generated by each background and user process that is accessing the database through the current instance. This information shows relative distributions, not precise counts of I/O operations.

Figure 13 - 14.  System I/O Distribution Monitor

Monitoring begins immediately with this display. Press [Accept] or select Restart to initiate a new display.

This display shows all currently connected processes (including the background processes) and the percent of I/O performed by each. The first two columns give the Oracle Process ID and Session ID.

The next three columns give the distribution of I/O in the last interval; that is, in the time since the monitor screen was last updated. The last three columns give cumulative statistics gathered since the last  warm start.

Note that the cumulative histogram's results may not add up to 100, because processes that were previously connected are also responsible for cumulative I/O.

 Cache Hit Ratio

One important figure that can be derived from this display is the cache hit ratio. This number shows the percentage of reads that were satisfied by blocks found in memory. The best possible value for the cache hit ratio is 100%. If the value is less than 80%, additional performance tuning may be desirable.

 System Cache Hit Ratio

The system cache hit ratio is calculated using the values at the bottom of the columns, as follows:

total logical reads

--------------------------------------------------------------------------------------------

( total logical reads + total physical reads )

For example, the cumulative system cache hit ratio in Figure 13 - 15 is

system cache hit ratio = 8,800,336 /(8,800,336 + 1,228,963)

                       = 87%

 Process Cache Hit Ratio

The cache hit ratio for a process is calculated in similar fashion using the percentages shown for the process. The formula for the process cache hit ratio is

   logical reads

-------------------------------------------------------------------

( logical reads + physical reads )

where:

logical reads = %logical reads * total logical reads

physical reads = %physical reads * total physical reads

For example, the cumulative cache hit ratio for process 17 would be calculated as follows:

logical reads   = %logical reads * total logical reads

                = .07 * 8,800,336

                = 616,023

physical reads  = %physical reads * total physical reads

                =.04 * 1,228,963

                = 49,158

cache hit ratio = logical reads / (logical reads + physical reads)

                = 616,023 / (616,023 + 49,158)

                = 92%

Command equivalent	MONITOR SYSTEMIO (SQL*DBA)

 ________________________________________

Table Access Monitor

The Table Access monitor shows tables that are in use and the users accessing them.

Figure 13 - 15. Table Access Monitor

You can control the display with entries in any of the following fields:

•	Minimum Session ID number: All sessions with an ID greater than or equal to this value are included in the display.

•	Maximum Session ID number: All sessions with an ID less than or equal to this value are included in the display.

•	Schema Filter: A pattern for Oracle schema names that determines which schema's tables are included in the display.

•	Table Filter: Only tables with names matching this pattern are included in the display.

Press [Accept] or select the Start button to begin monitoring. Once monitoring begins, this button's name becomes Restart. You can change the display criteria at any time and then press [Accept] or select Restart to initiate a new display.

This display shows all tables currently accessed by currently-parsed cursors. The schema named in column 2 owns the table named in the last column. The Process ID given in column 1 shows the process that is accessing that table. To find out if that PID is the owner of the table, refer to the Session monitor to see which Oracle username corresponds to the PID.

When the cursor is closed, the object is removed from the Table Access monitor. However, the lock on the table is held until a COMMIT is issued. The lock on the object continues to be displayed on the Lock monitor until the COMMIT occurs.

Command equivalent	MONITOR TABLE (SQL*DBA)


APPENDIX A. CHANGES IN THE ORACLE7 SERVER UTILITIES

This appendix describes changes in the Oracle7 Server utility programs. It covers:

•	Import/Export changes

•	SQL*Loader changes

•	SQL*DBA changes

 ________________________________________

Export/Import Changes

This section describes changes to the Oracle7 Import/Export utility.

 Release 7.1 Changes

These are the changes to Export in Release 7.1.

 Change in Export File Format

In Release 7.1, the export file format was changed to accommodate stored procedures, functions, and packages that have comments embedded among the creation-statement keywords. In some cases, a patch is required to successfully migrate these code objects between a Release 7.0 database and a Release 7.1 database. See page 3 - 9.

 Read-Only Tablespaces

Read-only tablespaces can be exported. See page 3 - 5.

 Trusted Oracle Label Mapping

Trusted Oracle7 Import allows you to list the labels in the export file and specify a mapping that converts them into the labels used by the target Trusted Oracle7 database. For details, see the Trusted Oracle7 Server Administrator's Guide.

 Version Incompatibility Error Message

When a higher level version of the Export utility is used with a lower level version of the Oracle7 Server with which it is incompatible, an ORA-37 error results. See page 3 - 9.

 New 7.1 Objects Supported

Release 7.1 of the Export/Import utilities supports these new Oracle7 objects:

•	job queues

•	refresh groups

•	resource costs

 Changes in Export for Release 7.0

The new features of Oracle7 export utility are described below.

 Oracle7 Objects

New objects in Oracle7 (roles, profiles, triggers, stored procedures, and snapshots) can be exported. See page 1 - 7.

 Log Files

Log files are supported in Oracle7. Systems that do not support I/O redirection can have a record of errors and warnings that occur during the export. See page 1 - 13.

 Final Message

In Version 6, any export that completed displayed the message  "Export completed successfully". In Oracle7, export ends with one of  three messages:

Export terminated successfully without warnings

Export terminated successfully with warnings

Export terminated unsuccessfully

See page 1 - 4 for more information.

 CONSISTENT

The Oracle7 parameter CONSISTENT allows the creation of read-consistent exports. A read-consistent export is guaranteed not to include any partially completed transactions. It is used when exports and database updates must occur simultaneously. See page 1 - 11.

 GRANTS=Y

The default for the GRANTS export parameter is Yes. In Version 6, it was No. See page 1 - 12.

 CONSTRAINTS=Y

The default for the CONSTRAINTS export parameter is Yes. In Version 6, it was No. See page 1 - 15.

 Setting Up Export Views

In Oracle7, the script EXPVEW.SQL must be run after CATALOG.SQL to establish the export views. In Version 6, the order made no difference. See page 1 - 2.

 Trusted Oracle7 Server Parameters

The Trusted Oracle7 Server parameters MLS and MLS_LABEL_FORMAT have been added. See page 1 - 13.

 Changes in Import for Release 7.0

The new features of Oracle7 Import are described below.

 Oracle7 Objects

New objects in Oracle7 (roles, profiles, triggers, stored procedures, and snapshots) can be imported. See pages 2 - 9 to 2 - 11.

 DESTROY Parameter

The ALTER TABLESPACE statement stored in the Oracle7 export file sets REUSE=NO so that the default action on import is not to reuse the datafiles defined for the database. In Version 6, the default was REUSE=YES. This change minimizes the chance that a database can be inadvertently replaced when attempting to create a copy of it for testing or other purposes. This change resulted from the fact that the full pathname of datafiles in the database is included in the export file.

A new import parameter allows you to specify DESTROY=YES, instructing Import to erase the existing datafiles and reuse them. This option allows you to re-create your database from backups, when necessary. The default value for DESTROY is NO. See page 2 - 18.

 Log Files

Log files are supported in Oracle7 so that systems that do not support I/O redirection can have a record of errors and warnings that occur during the import. See page 2 - 21.

 Final Message

In Version 6, any import that completed displayed the message "Import completed successfully". In Oracle7, import ends with one of three messages:

Import terminated successfully without warnings

Import terminated successfully with warnings

Import terminated unsuccessfully

See page 2 - 4 for more information.

 User Definitions

In Version 6, user definitions did not exist separately from their GRANTS. User definitions were therefore imported by importing GRANT statements. In Oracle7, importing a user definition does not automatically grant connect access. See page 2 - 10.

 Importing Objects for Other Users

Version 6 import adopted the target user's privileges when importing objects. If the user did not have CREATE TABLE privilege, for example, a DBA might find that a user's tables could not be imported--although the DBA had successfully exported them.

Oracle7 Import uses the importer's privileges to import objects into another user's schema. This method preserves the importer's privileges, allowing a fully privileged user to import objects for a limited-privilege user.

 IGNORE=N

In Oracle7, the default is to report all object creation errors. Previously they were ignored by default. To suppress the reporting of error messages that occur when tables and other objects already exist, specify IGNORE=Y. See page 2 - 20.

 INDEXFILE Parameter

The Oracle7 parameter INDEXFILE makes it possible to siphon off index-creation statements, so they are placed in a file instead of being applied to the database. This procedure is more efficient and makes it possible to change index storage attributes. See page 2 - 20.

 Character Set Conversion

In Version 6, Import/Export provided a limited capability to convert data between ASCII-based and EBCDIC-based systems. In Oracle7, that capacity has been extended to translate data between two systems using different character encoding schemes. See page 2 - 13.

 CHARSET parameter

In Version 6, the CHARSET parameter was used in limited ways to control the conversion from the character set used in the export file to the database character set. In Oracle7, the Export file records the character set used when the file was created. Oracle7 Import then automatically converts that character set to the database character set.

In Oracle7, this parameter is only checks that the Export file's character set matches the expected value. Use of the CHARSET parameter is no longer recommended as it will eventually become obsolete.

 Trusted Oracle7 Server Parameter

The Trusted Oracle7 Server parameter MLS has been added. For details. See page 2 - 21.

 Incremental Import and Export

In Oracle7, an incremental import or export can be performed by any user who has been granted the EXP_FULL_DATABASE role. Previously, only SYS or SYSTEM could do an incremental import or export. See page 1 - 25.

Similarly, any user who has been granted the IMP_FULL_DATABASE role can perform an incremental import. See page 2 - 27.

 ________________________________________

SQL*Loader Changes

This section describes the changes to SQL*Loader and the releases in which they became effective.

 Oracle7 Server Release 7.1

Changes for Release 7.1

•	Data can be loaded in parallel with the PARALLEL direct path load. See page 9 - 22.

•	Direct loads can load data into synonyms for tables (but not synonyms for views, or synonyms for synonyms). See page 9 - 7.

•	Direct loads can specify UNRECOVERABLE to improve performance by disabling redo logging. See page 9 - 17.

•	In Release 7.1, direct loads can specify a datafile character set which is different from the control file using the CHARACTERSET clause. In 7.0 this was possible for a conventional load, but not for a direct load. See page 6 - 22.

As before, the control file must be in the same character set as the session so that the session can interpret it. And, as before, the database character set can be different -- data conversion happens automatically.

•	The REPLACE option returns to using DELETE TABLE semantics. That was the standard behavior prior to Release 7.0. Release 7.1 returns to that standard, and no longer performs a table TRUNCATE when REPLACE is specified. With this change:

•	Integrity constraints on the table do not have to be disabled before the load.

•	Delete triggers that are defined on the table fire as rows are deleted.

•	DELETE privilege on the table is sufficient if the table is not in your own schema. See page 6 - 24 for more information.

•	A new option, TRUNCATE, uses fast table truncation for a load. This option does not fire delete triggers for the truncated rows. Integrity constraints on the table must be disabled before loading with TRUNCATE. Finally, if the table is not in your own schema, the DELETE ANY TABLE privilege is required. See page 6 - 23.

•	Previously, only one direct path load could be performed on any given table. With Oracle Server release 7.1, you can optionally specify a PARALLEL clause within the SQL*Loader control file or on the command line to indicate that multiple SQL*Loader direct path load sessions can share access to the table. See page 9 - 22.

•	The FILE parameter allows different parts of a parallel load to allocate extents from different database files. See page 9 - 23.

 Oracle7

In Oracle7, SQL*Loader is part of the standard Oracle Server release. As a result, its release number jumps from "1.1" to "7.0". New features include:

•	Direct loads bypass referential integrity constraints and database triggers. See page 9 - 18.

•	Input character conversion possible with the CHARACTERSET clause. See page 6 - 22.

•	Multi-byte (Asian language) characters supported. See page 6 - 22.

•	Fast table truncation used for REPLACE option. See page 6 - 23.

 Release 1.1

Changes for Direct Path Loads:

•	Maximum performance available with the direct path option. See Chapter 9.

•	Operating system sorts can be used for high-speed sorting, fast indexing, and reduced need for temporary storage. See page 9 - 14.

•	DIRECT command-line parameter added. See page 7 - 5.

•	Meaning of ROWS parameter extended for direct loads.  See page 9 - 9.

•	CONTINUE_LOAD and table-level SKIP clauses added to continue a multiple-table direct path load after an interruption. See page 6 - 26.

Changes in File Management:

•	The file processing string allows optimizing datafile reads. See page 6 - 16.

•	The keywords RECLEN, STREAM, RECORD, FIXED, BLOCKSIZE, and VARIABLE are now obsolete. They are still recognized for upward compatibility, but they have no effect.

•	Single quotation marks recommended for filenames. See page 6 - 11.

•	When loading records that contain only generated data, SQL*Loader skips reading of input file. See page 6 - 43.

•	The bad file is only created if it is needed. See page 6 - 17.

Changes in Data Management:

•	SQL string allows use of SQL operators on fields. See page A - 76 - 73.

•	RAW datatype added. See page 6 - 50.

•	Insert current date/time with SYSDATE keyword. See page 6 - 44.

•	Initial and trailing field delimiters can be different. See page 6 - 56.

•	Mismatches in field length specifications generate warning messages in native datatype fields and character datatype fields. See page 6 - 53 and page 6 - 58.

•	Default maximum field size for delimited fields is 255 bytes instead of 240 bytes. See page 6 - 56.

Changes in the Command Line:

•	Command-line specifications override control file options. See page 6 - 10 and page 7 - 3.

•	Bad file command-line specification overrides control-file specification. See page 6 - 17 and page 7 - 4.

•	Discard file command-line specification overrides control-file specification. See page 6 - 19 and page 7 - 5.

•	Arguments can be specified in a separate file with PARFILE command-line parameter. See page 7 - 6.

Obsolete Parameters:

Because it has been replaced by the file processing options string, the RECLEN parameter is obsolete.

In addition, the old syntax

[ STREAM | RECORD | FIXED len [BLOCKSIZE size] | VARIABLE [len] ]

does not affect the way SQL*Loader reads the datafile, although the syntax is recognized to maintain upward compatibility.

 Release 1.0.26

Changes in Release 1.0.26:

•	Load character fields with all whitespace intact, using the PRESERVE BLANKS option. See page 6 - 72.

•	Test to see if a field of undetermined length is all blank with the BLANKS keyword. See page 6 - 35.

•	All-blank numeric fields no longer automatically loaded as NULL. See page 6 - 66.

 Release 1.0.22

Changes in Release 1.0.22:

•	ZONED DECIMAL datatype added. See page 6 - 49.

•	Specifying how to handle missing fields at the end of a record with the TRAILING NULLCOLS keyword. See page 6 - 66.

•	Putting special characters into quoted strings with the quoted-string escape character. See page 6 - 12.

 ________________________________________

Changes to SQL*DBA

 SQLDBA Release 7.1

This section describes the changes in Oracle7 SQL*DBA, Release 7.1.

 FIPS Flagging

FIPS flagging can be enabled and disabled using the SQL*DBA SET command. See page 12 - 16.

 Connecting as SYSOPER and SYSDBA

A properly privileged user can connect to the SYS schema in the Oracle7 Server with the AS SYSOPER or AS SYSDBA clause. These privileges allow the privileged user to perform privileged operations such as instance startup and shutdown.

Because INTERNAL is an authorization and not an actual user, you are no longer considered to be connecting as INTERNAL. Rather, you are allowed to connect as a particular user with either the SYSOPER or SYSDBA system privilege. The CONNECT INTERNAL phrase is retained for backward compatibility only.

 See page 12 - 5 for more information.

 Parallel Recovery

Database recovery can now take place in parallel using the PARALLEL option on the RECOVERY command. See page 12 - 13.

 SQLDBA Release 7.0

This section describes the changes in Oracle7 SQL*DBA, Release 7.0.

 Menu Interface

SQL*DBA supports both a graphic and character-oriented menu interface. It includes drop-down menus, dialog boxes, and multiple windows. See page 10 - 5.

 Command Processing

SQL*DBA allows multiple-line commands to be entered and edited.

SQL*DBA also implements a command history, allowing previous commands to be retrieved. A command is retrieved in its entirety, even if it spans multiple lines. It can then be edited and reissued. See page 10 - 18.

 Flexible [Newline] Operation

SQL*DBA's menu and command interface features a flexible [Newline] operation that operates in an intuitive manner to perform the current default operation, depending on context. In the input window [Newline] operates like the <Return> key in a full-screen editor, while in menus and dialog boxes it operates like the [Accept] operation. See page 10 - 13.

 Line Mode

For compatibility with previous versions, SQL*DBA retains a single-line interactive mode. All SQL, PL/SQL, and SQL*DBA commands can be entered in line mode, except for monitor commands. See page 10 - 3.

 Script Required for Startup

In Version 6, it was possible to issue the startup command directly from the operating system command line. In Oracle7, you must CONNECT before you can issue the startup command.

To start your database from the command line, you need to put your startup command in a script and precede it with the appropriate CONNECT statement. This script can then be invoked from the O/S command line. See page 10 - 20 for information on creating and using scripts.

 Monitors

Monitors are now implemented in separate windows. This facility provides several capabilities:

•	You can hide monitor windows and bring them back into view.

•	Multiple monitors can be active at one time. You can move from one monitor window to the next, viewing each of the them in turn.

•	You can issue commands while monitors are running.

•	The monitor windows can be hidden and restored.

When you issue monitor commands in the input window, you only enter the name of the monitor. The monitor screens contain fields that control monitor operation.

The SQL*DBA monitors are not available in line mode, because they require the menu-system windows. For the same reasons, monitors cannot be SPOOLed to operating system files.

See Chapter 13 for more information.


APPENDIX B. RESERVED WORDS

This appendix lists the words reserved by the Oracle utilities and tells how to avoid problems that can arise when you use them as names for database objects.

It is generally a good idea to avoid naming your tables or columns with terms that are reserved by any of the languages or utilities you are likely to use at your installation. Refer to the various language and reference manuals (PL/SQL, SQL*Plus, and so on) and to this appendix for lists of reserved words.

Consult the SQL Language Reference Manual, Chapter 3, "Elements of the SQL Language", for a list of words that are reserved by SQL. Tables or columns that have these names must also be specified in double quotation marks.

 ________________________________________

SQL*Loader Reserved Words

With SQL*Loader, you must follow the usual rules for naming tables and columns. A table or column name cannot be a reserved word, a word having special meaning for SQL*Loader. The following words must be enclosed in double quotation marks if they are table or column names:

 ________________________________________

SQL*DBA Reserved Words

If any of the SQL*DBA reserved words are used as database object names, then those names should be enclosed in double quotation marks when they are included in SQL*DBA commands.

For example, if "v7" is the name of your database, then the following command fails with error DBA-00119  "illegal startup option".

STARTUP OPEN v7

But the following command succeeds:

STARTUP OPEN "v7"


APPENDIX C. NOTES FOR DB2/DXT USERS

This appendix describes differences between the syntax of SQL*Loader and DB2 Load Utility/DXT control files. The topics discussed include:

•	SQL*Loader extensions to the DB2 Load Utility

•	the DB2 RESUME option

•	options included for compatibility

•	SQL*Loader restrictions

•	DB2/DXT compatible syntax

 ________________________________________

SQL*Loader Extensions to the DB2 Load Utility

SQL*Loader can use any DB2 Load Utility control file. SQL*Loader also offers numerous extensions to the DB2 loader by supporting the following features:

•	the DATE datatype

•	the automatic generation of unique sequential keys

•	the ability to specify the record length explicitly

•	loading data from multiple datafiles of different file types

•	fixed-format, delimited-format, and variable-length records

•	the ability to treat a single physical record as multiple logical records

•	the ability to combine multiple physical records into one logical record via CONCATENATE, CONTINUEIF NEXT, and CONTINUEIF THIS (IBM supports only CONTINUEIF THIS)

•	more thorough error reporting

•	bad file (DB2 stops on first error)

•	control over the number of records to skip, the number to load, and the number of errors to allow

•	ANDed WHEN clause

•	FIELDS clause for default field characteristics

•	direct loads

•	parallel loads

 ________________________________________

Using the DB2 RESUME Option

You can use the DB2 syntax for RESUME, but you may prefer to use SQL*Loader's equivalent keywords. See "Loading into Non-Empty Database Tables" for more details about the SQL*Loader options summarized below.

DB2	SQL*Loader Options	Result

RESUME NO or no RE-	INSERT	Data loaded only if table is

SUME clause	empty. Otherwise an error is re-

turned.

RESUME YES	APPEND	New data is appended to exist-

ing data in the table, if any.

RESUME NO 	REPLACE	New data replaces existing

REPLACE	table data, if any.

Table C - 1.  DB2 Functions and Equivalent SQL*Loader Operations

A description of the DB2 syntax follows.

If the tables you are loading already contain data, you have three choices for the disposition of that data. Indicate your choice using the RESUME clause. The argument to RESUME can be enclosed in parentheses.

RESUME  { YES | NO [ REPLACE ] }

where:

YES	Appends the new rows to rows already in the table.

NO	Requires the table to be empty before loading. An error message results if the table contains rows and the run is terminated. This is the default.

NO REPLACE	Deletes any data in the table before loading new data. Thus, the new data will replace the old. This argument requires that the username invoking SQL*Loader have DELETE privilege on the table. You cannot recover the data that was in the table before the load, unless you saved it using Export or something comparable.

In SQL*Loader you can use one RESUME clause to apply to all loaded tables by placing the RESUME clause before any INTO TABLE clauses. Alternatively, you can specify your RESUME options on a table-by-table basis by putting a RESUME clause after the INTO TABLE specification. The RESUME option following a table name will override one placed earlier in the file. The earlier RESUME applies to all tables that do not have their own RESUME clause.

 ________________________________________

Inclusions for Compatibility

The IBM DB2 Load Utility contains certain elements that SQL*Loader does not use. In DB2, sorted indexes are created using external files, and specifications for these external files may be included in the load statement. For compatibility with the DB2 loader, SQL*Loader parses these options, but ignores them if they have no meaning for Oracle. The syntactical elements described below are allowed, but ignored, by SQL*Loader.

 LOG Statement

This statement is included for compatibility with DB2. It is parsed but ignored by SQL*Loader. (This LOG option has nothing to do with the log file that SQL*Loader writes.) DB2 uses the log file for error recovery, and it may or may not be written.

SQL*Loader relies on Oracle's automatic logging, which may or may not be enabled as a warm start option.

[ LOG { YES | NO } ]

 WORKDDN Statement

This statement is included for compatibility with DB2. It is parsed but ignored by SQL*Loader. In DB2, this statement specifies a temporary file for sorting.

[ WORKDDN filename ]

 SORTDEVT and SORTNUM Statements

SORTDEVT and SORTNUM are included for compatibility with DB2. These statements are parsed but ignored by SQL*Loader. In DB2, these statements specify the number and type of temporary data sets for sorting.

[ SORTDEVT device_type ]

[ SORTNUM n ]

 DISCARD Specification

Multiple file handling requires that the DISCARD clauses (DISCARDDN and DISCARDS) be in a different place in the control file -- next to the datafile specification. However, when loading a single DB2 compatible file, these clauses can be in their old position -- between the RESUME and RECLEN clauses. Note that while DB2 Load Utility DISCARDS option zero (0) means no maximum number of discards, for SQL*Loader, option zero means to stop on the first discard.

 ________________________________________

Restrictions

Some aspects of the DB2 loader are not duplicated by SQL*Loader. For example, SQL*Loader does not load data from SQL/DS files nor from DB2 UNLOAD files. SQL*Loader gives an error upon encountering the DB2 Load Utility commands described below.

 FORMAT Statement

The DB2 FORMAT statement must not be present in a control file to be processed by SQL*Loader. The DB2 loader will load DB2 UNLOAD format, SQL/DS format, and DB2 Load Utility format files. SQL*Loader does not support these formats. If this option is present in the command file, SQL*Loader will stop with an error. (IBM does not document the format of these files, so SQL*Loader cannot read them.)

FORMAT { UNLOAD | SQL/DS }

 PART Statement

The PART statement is included for compatibility with DB2. There is no Oracle concept that corresponds to a DB2 partitioned table.

In SQL*Loader, the entire table is read. A warning indicates that partitioned tables are not supported, and that the entire table has been loaded.

[ PART n ]

 SQL/DS Option

The option SQL/DS=tablename must not be used in the WHEN clause. SQL*Loader does not support the SQL/DS internal format. So if the SQL/DS option appears in this statement, SQL*Loader will terminate with an error.

 DBCS Graphic Strings

Because Oracle does not support the double-byte character set (DBCS), graphic strings of the form G'**' are not permitted.

 ________________________________________

SQL*Loader Syntax with DB2-compatible Statements

In the following listing, DB2-compatible statements are in bold type:

OPTIONS (options)

{ LOAD | CONTINUE_LOAD } [DATA]

[ CHARACTERSET character_set_name ]

[ { INFILE | INDDN } { filename | * }

   [ "OS-dependent file processing options string" ]

   [ { BADFILE | BADDN } filename ]

   [ { DISCARDFILE | DISCARDDN } filename ]

   [ { DISCARDS | DISCARDMAX } n ] ]

[ { INFILE | INDDN } ] ...

[ APPEND | REPLACE | INSERT |

    RESUME [(] { YES | NO [REPLACE] } [)]  ]

[ LOG { YES | NO } ]

[ WORKDDN filename ]

[ SORTDEVT device_type ]

[ SORTNUM n ]

[ { CONCATENATE [(] n [)] |

    CONTINUEIF { [ THIS | NEXT ]

                 [(] ( start [ { : | - } end ] ) | LAST }

                 operator  { 'char_str' | X'hex_str' } [)] } ]

[ PRESERVE BLANKS ]

INTO TABLE tablename

[ CHARACTERSET character_set_name ]

[ SORTED [ INDEXES ] ( index_name [ ,index_name... ] ) ]

[ PART n ]

[ APPEND | REPLACE | INSERT |

  RESUME [(] { YES | NO [REPLACE] } [)] ]

[ REENABLE [DISABLED_CONSTRAINTS] [EXCEPTIONS table_name] ]

[ WHEN field_condition [ AND field_condition ... ] ]

[ FIELDS  [ delimiter_spec ] ]

[ TRAILING [ NULLCOLS ] ]

[ SKIP n ]

(.column_name

  { [ RECNUM

      | SYSDATE

      | CONSTANT value

      | SEQUENCE ( { n | MAX | COUNT } [ , increment ] )

      | [[ POSITION ( { start [ {:|-} end ] | * [+n] } ) ]

         [ datatype_spec ]

         [ NULLIF field_condition ]

         [ DEFAULTIF field_condition ]

         [ "sql string" ] ] ]  }

  [ , column_name ] ...)

[ INTO TABLE ] ... [ BEGINDATA ]

[ BEGINDATA]


APPENDIX D. COMPATIBILITY OF SQL*DBA AND SERVER MANAGER

This appendix lists the differences between Oracle7 SQL*DBA and Server Manager/LineMode.

 ________________________________________

Functional Differences

Feature	SQL*DBA	Server Manager/LineMode

------------------------------------------------------------------------

DESCRIBE	DESCRIBE <object name>	DESCRIBE <object type> <ob-

ject name>

DESCRIBE for 	Lists information about the 	Lists the definition of the

PL/SQL	procedure's arguments in a 	procedure's arguments

tabular form

PRINT <no args>	Does nothing	Prints all defined variables

PRINT (before       	SQLDBA> print a         	SVRMGR> print a

connect)	DBA-00302: not.connected 	A

to a database	----------

   10

SET COMPATIBILITY 	Unsupported	Server Manager uses the native

NATIVE	SQL of the database to which

you are connected

SHOW <no args>	SQLDBA> show            	Prints current Server Manager

show                                	settings

        *

DBA-00115: unexpected end

of command

SPOOL <no args>	No prompt                                    	Prompts for filename

SQLDBA> spool            	SVRMGR> spool

File sqldba.log opened...	Name for the spool file:

(svrmgr.log)

STARTUP	If any step of STARTUP fails, 	If any step of STARTUP fails,

SQL*DBA backs out and leaves 	Server Manager leaves the

the database in a shutdown 	database in its current state.

state.	For example, if an error is en-

countered after the mount

stage, Server Manager leaves

the database mounted.

VARIABLE a CHAR	Default size is 1	Default size is CHARWIDTH

@<no args>	Prints an error                               	Prompts for the name of the

SQLDBA> @              	file

ORA-07225: ...	SVRMGR> @

Name of script file:

Empty line	SQLDBA> garbage	SVRMGR> garbage

     2>                 	    2>

SQLDBA>;                	     3>;

SQLDBA>	garbage

*

ORA-00900: invalid SQL

statement

SVRMGR>

Table D - 1.  Functional Differences

 ________________________________________

Cosmetic Differences

Feature	SQL*DBA	Server Manager/LineMode

------------------------------------------------------------------------

Prompt	SQLDBA>	SVRMGR>

Product Banner	SQL*DBA	Server Manager

Connect to idle 	SQLDBA> connect internal  	SVRMGR> connect internal

instance	Connected.	Connected to an idle

instance.

PRINT a	A                  	A

----------                   	----------

        10                  	        10

1 row selected.                     	The variable name is not space

The variable name is space 	padded: "A". Also, no feedback

padded: "A         ".	is listed.

SET	                                                      	Server Manager echoes the

SQLDBA> set echo on    	new value:

SQLDBA>	SVRMGR> set echo on

Echo          ON

SVRMGR>

Error Message Prefix	DBA-xxxxx: ...	MGR-xxxxx: ...

HOST	Adds return after HOST results  	No extra return after results

SQLDBA> host whoami     	SVRMGR> host whoami

barthur                   	barthur

               	SVRMGR>

SQLDBA>

Wrapping text	Writes 80 characters and then 	Writes the entire width and

wraps	relies on the display device to

deal with wrapping. This is

better for wide terminals.

Table D - 2.  Cosmetic Differences

 ________________________________________

Obsolete Functionality

Feature	SQL*DBA	Server Manager/LineMode

------------------------------------------------------------------------

SET ARRAYSIZE	Changes the size of each fetch 	No longer used: Server

call	Manager automatically chooses

optimum fetch size.

SET CYCLE	Sets the monitor interval	No longer used

SET HISTORY	Screen mode	No longer used

SET LINES	Screen mode	No longer used

SET TERM	Screen mode	No longer used

Table D - 3.  Obsolete Functionality

 ________________________________________

Unsupported Options

Feature	SQL*DBA	Server Manager/LineMode

------------------------------------------------------------------------

RECOVERY prompt	FROM <logsource>

unsupported

SET FETCHROWS	Limits the total number of 	Unsupported

rows to fetch

SET FLAGGER...	SET FLAGGER ENTRY	Unsupported: Use the ALTER

SESSION SET FLAGGER

statement

SHOW FLAGGER	Shows FLAGGER value	Unsupported

SET LABELWIDTH	Unsupported

SET RETRIES	Unsupported

SHOW VARIABLES     	Shows all defined variables	Unsupported: Use

SHOW VAR	PRINT <no args>

SHUTDOWN dbname	Unsupported

VARIABLE a DATE	Unsupported

Table D - 4.  Unsupported Options


APPENDIX E. OPERATING SYSTEM DEPENDENCIES

This Guide occasionally refers to other Oracle manuals that contain detailed information for using Oracle on a operating system-specific system. These Oracle manuals are often called installation or user's guides, although the exact name may vary on different operating systems.

Additional Information:  Throughout this Guide, references to these manuals are given in paragraphs like this one.

This appendix lists all references made in this Guide to operating-system-dependent behavior for the Oracle utilities. Use this appendix as a guide when moving data between operating systems or when designing operating-system independent applications.

Operating-system-specific topics are listed alphabetically with page numbers of sections that discuss these topics.

 ________________________________________

General

Installing the utilities	Preface- ii

README filename	Preface- ix

 ________________________________________

Export/Import

Default buffer size	1 - 11, 2 - 18

Default record length	1 - 14, 2 - 22

Error Messages	1 - 5, 2 - 5

Installing export views	1 - 3

Quotes on command line when using # sign	1 - 10, 2 - 16

Size of Export Parameter File	1 - 9

Sixe of Import Parameter File	2 - 16

Redirecting I/O	1 - 4, 2 - 5

 ________________________________________

SQL*Loader

Allocating direct path I/O buffers	9 - 13

Backslash escape character in non-portable strings	6 - 12

Bad file overwritten or new version created	6 - 17

Command to start SQL*Loader	5 - 4, 7 - 2

Names of SQL*Loader demo files	5 - 2

Sizes

INTEGER, SMALLINT, FLOAT, and DOUBLE data	6 - 48

SMALLINT data type	6 - 48

length subfield in VARCHAR data	6 - 52

length subfield in VARGRAPHIC data	6 - 51

specifying file processing options	6 - 16

 ________________________________________

SQL*DBA

Backups	11 - 16

Default spool filename	12 - 29

Extra quotes required on command line	10 - 20

File locations, specifying	12 - 4

Initial default instance	12 - 20

Key mappings	10 - 5, 10 - 12

Latch and timeout algorithms	13 - 7

Maximum data size	12 - 21

Monitor fields, content of	13 - 2

Number of records fetched at one time (ARRAYSIZE)	12 - 18

Privileges required for connect INTERNAL	10 - 4

Range for width of

character columns (CHARWIDTH)	12 - 18

DATE columns (DATEWIDTH)	12 - 19

LONG data columns (LONGWIDTH)	12 - 21

NUMBER data (NUMWIDTH)	12 - 21

Returning from the operating system	11 - 32, 12 - 9

Script nesting limit	10 - 21

SQL*Net: specifying connect strings	12 - 20

Terminal type default	10 - 3