Oracle SQL Plus The Definitive Guide- P21 ppt

When used on a stored function, the DESCRIBE command tells you the data type of the return value, and also gives you a list of arguments that the function expects.. --- --- --- --- EMP_I

Syntax for DESCRIBE

The syntax for the DESCRIBE command looks like this:

DESC[RIBE] [schema ]object_name[@database_link_name]

where:

DESC[RIBE]

Is the command, which may be abbreviated to DESC

schema

Is the name of the object's owner This defaults to your username

object_name

Is the name of the object, often a table or a view, that you want to describe You can describe any of the following: a table, a view, a stored procedure, a stored function, a stored package, or an Oracle8 object type

database_link_name

Is the name of a database link pointing to the database where the object exists You only need to use this if the object you want to describe exists in a database other than the one to which you are currently connected Your DBA can help create a database link if you need one

Describing a Table

DESCRIBE is most often used to view the definition of a table or a view Simply enter the command DESCRIBE, followed by the name of the table or view you are interested in, as the following example shows:

SQL> DESCRIBE employee

Name Null? Type

- -

EMPLOYEE_ID NOT NULL NUMBER

EMPLOYEE_NAME VARCHAR2 (40)

EMPLOYEE_HIRE_DATE DATE

EMPLOYEE_TERMINATION_DATE DATE

EMPLOYEE_BILLING_RATE NUMBER

If you aren't the owner of the table, you can qualify the table or view name using the standardowner.table_name

notation This next example describes the ALL_ USERS view, which is owned by the user SYS

SQL> DESCRIBE sys.all_users

Name Null? Type

- -

USERNAME NOT NULL VARCHAR2(30)

USER_ID NOT NULL NUMBER

CREATED NOT NULL DATE

As you can see, DESCRIBE just gives you a list of columns in the table or view, along with their resulting datatypes, lengths, and nullability If you need to know more, such as whether or not a column has a default value, you will need to query the data dictionary directly You will see how to do this later in the chapter

In early releases of Oracle8, in particular the 8.0.3 release, the DESCRIBE command does not function correctly when used with a public synonym Thus, DESCRIBE ALL_TABLES will fail because ALL_TABLE is

a public synonym DESCRIBE SYS.ALL_TABLES will succeed because the view name is fully qualified You can also create private synonyms that match public synonyms for objects you frequently look at Create a private synonym named ALL_TABLES that refers to SYS.ALL_TABLES, and DESCRIBE will correctly interpret it

Describing Stored Functions and Procedures

DESCRIBE may also be used on stored procedures and functions When used on a stored function, the DESCRIBE command tells you the data type of the return value, and also gives you a list of arguments that the function expects For example:

SQL> DESCRIBE terminate_employee

FUNCTION terminate_employee RETURNS NUMBER(38)

Argument Name Type In/Out Default?

- - - -

EMP_ID NUMBER IN

EMP_HIRE_DATE DATE OUT

EMP_TERM_DATE DATE IN

As you can see, DESCRIBE returns the following information for each argument:

The datatype

Whether it is an input, output, or both

The default value, if there is one

The order in which the arguments are listed is also the order in which they should be passed into the function when you call it The DESCRIBE command does not show you the source code for a function To see that, you need to query the ALL_ SOURCE data dictionary view The following example shows how to get the source for the

TERMINATE_EMPLOYEE function:

SQL> SELECT text

2 FROM all_source

3 WHERE owner = USER

4 AND name = TERMINATE_EMPLOYEE

5 ORDER BY LINE;

TEXT

-

FUNCTION terminate_employee

(emp_id IN employee employee_id%TYPE,

emp_hire_date OUT employee.employee_hire_date%TYPE,

emp_term_date IN employee employee_termination_date%TYPE)

RETURN INTEGER AS

BEGIN

UPDATE employee

SET employee_termination_date = emp_term_date

WHERE employee_id = emp_id;

SELECT employee_hire_date INTO emp_hire_date

FROM employee

WHERE employee_id = emp_id;

RETURN 1;

EXCEPTION

WHEN OTHERS THEN

RETURN 0;

END;

19 rows selected

Describing a procedure works the same way as describing a function The only difference is that procedures do not have

a return type

Describing Packages and Object Types

With the release of Oracle8, the SQL*Plus DESCRIBE command was enhanced to return information about Oracle8 object types The following example shows how this works:

SQL> DESCRIBE employee_type

Name Null? Type

- -

EMPLOYEE_NAME VARCHAR2 (40)

EMPLOYEE_HIRE_DATE DATE

EMPLOYEE_SALARY NUMBER (9,2)

METHOD

-

MEMBER FUNCTION TERMINATE_EMPLOYEE RETURNS NUMBER

Argument Name Type In/Out Default?

- - - -

EMP_ID NUMBER IN

EMP_TERM_DATE DATE IN

Another Oracle8 enhancement provides the ability to describe a stored package and get back a list of all functions and procedures that make up the package This

is not surprising, because objects and packages are very similar in nature For example, you can get a list of all the entry points in the DBMS_OUTPUT package by using DESCRIBE as shown here:

SQL> DESCRIBE sys.dbms_ output

PROCEDURE DISABLE

PROCEDURE ENABLE

Argument Name Type In/Out Default?

- - - -

BUFFER_SIZE NUMBER(38) IN DEFAULT

PROCEDURE GET_LINE

Argument Name: Type In/Out Default?

- - - -

LINE VARCHAR2 OUT

STATUS NUMBER(38) OUT

PROCEDURE GET_LINES

Argument Name Type In/Out Default?

- - - -

LINES TABLE OF VARCHAR2(255) OUT

NUMLINES NUMBER(38) IN/OUT

PROCEDURE NEW_LINE

As with functions and procedures, you can get at the source for a package, or for an Oracle8 object type, by querying the ALL_SOURCE view See the previous section for an example of how this is done

There have been some problems with the enhancements to DESCRIBE Compatibility between different versions of SQL*Plus and different versions of the Oracle server has sometimes suffered For example, if you use the 8.0.3 version of SQL*Plus, connect to a 7.x database and issue the DESCRIBE command on a table, it will fail This particular problem was fixed

in SQL*Plus 8.0.4

Why DESCRIBE Is Not Enough

Handy as DESCRIBE is, it just doesn't return enough information While it shows you all the columns in a table, there are a lot of important details it leaves out If you need to know the primary key for a table, DESCRIBE won't tell you If you need to know the foreign key constraints defined on a table, DESCRIBE won't tell you that, either DESCRIBE won't show you the indexes DESCRIBE won't show you the default values DESCRIBE won't show you the triggers, and DESCRIBE won't tell you anything about the table's security

How then do you get at this other information? One way is to install Oracle's Enterprise Manager software Enterprise Manager has a GUI-based schema browser

that will show you everything there is to see about tables, indexes, views, triggers, and other objects There are also several third-party software packages on the market that provide the same functionality However, for many people, SQL*Plus is the only option available, or at least the only one conveniently available If this is the case for you, you can still get the information you need by querying Oracle's data dictionary

Oracle's Data Dictionary Views

Oracle has to keep track of all the tables, views, constraints, indexes, triggers, and other objects you create In order to

do that, Oracle needs a place to store the information This repository of information about your database is referred to

as the data dictionary Whenever you create a new object, such as a table, Oracle stores all the information about that

object in the data dictionary Modify the object, and Oracle modifies the data dictionary It follows, then, that if you want to know anything about your database, the data dictionary is the place to go

The data dictionary is a set of tables owned by the user SYS The structure of these tables ends up being fairly complex, and much of the information is not stored in a very user-friendly form You probably do not want to query these tables directly, and unless you have been given access to log in as user SYS, you won't be able to see them anyway To help

you out, Oracle provides a set of data dictionary views These views have names that are easy to remember The column

names used in the views are also easy to remember and use a consistent naming convention There are data dictionary views for each different type of schema object, and they present information in an easy-to-understand form For

example, if you are looking at a date column, the DBA_TAB_COLUMNS view will tell you it is of type DATE The underlying data dictionary table, which happens to be SYS.COL $ , will simply tell you the type is 12

Oracle has a large number of data dictionary views This chapter concentrates only on the views that are used to return information about the structure of a table, its constraints, indexes, columns, triggers, and security This is the most common type of information needed by application developers and other database users I encourage you to dig deeper

If you want, or need, to know more, then the Oracle Server Reference manual would be a good place to start The

Oracle Server Reference manual contains a chapter titled Static Data Dictionary Views, which gives a comprehensive

list of all the views available

The View Types: ALL, DBA, and USER

There are three different types of data dictionary views you need to be aware of These control the scope of the

information you can look at The three view types are:

USER

The USER views show you information only about objects that you own There is a USER_TABLES view, for example, that will list only tables you own.

ALL

The ALL views show you information about all objects you are able to access Anything you own will be included in an ALL view, as well as anything owned by other users, but to which you have been granted access.

DBA

The DBA views show you information about all objectsperiod Usually only database administrators will have access to these views, and they could be considered a superset of the ALL views DBA_TABLES, for example, will list every single table that exists The typical way to gain access to the DBA views is to be granted the DBA role However, the SELECT ANY TABLE privilege will also let you see them.

Generally speaking, for any given object type, one view of each type will exist It's up to you to choose the one you want to look

at Table 6-1 shows how this works in terms of the views discussed in this chapter.

Table 6-1 Correspondence Between USER, ALL, and DBA Views

As you delve more deeply into Oracle's data dictionary, you will occasionally find instances when corresponding views do not exist in all three categories When a view is omitted it's either for security reasons, because it doesn't make sense in the context

of a particular object, or because it would be redundant The USER_JOBS and DBA_JOBS views provide a good example of this A user can own a job, hence the USER_JOBS view The database administrator needs to see everything, hence the

DBA_JOBS view There is no ALL_JOBS view, because there is no mechanism to grant another user access to your jobs ALL_JOBS would be redundant with USER_JOBS, because the only jobs you can ever see are your own anyway.

When you write scripts, avoid the DBA views if at all possible Using the DBA views limits your ability to share your scripts, because most users don't have access to them

Which view should you use? The USER views limit you to seeing information only about objects that you own If I'm working interactively, I'll frequently use the USER views to save myself some typing, because I don't need to enter a WHERE clause to restrict the results to my objects When writing scripts, I try to use the ALL views in order to make the scripts more flexible It's not unusual, for example, to need to see the definition for a table owned by another user The ALL views allow this I save the DBA views for database administrationrelated tasks

The following sections show you how to get information about various types of schema objects First I'll show how to list the tables you own and how to look at the column definitions for those tables Next you will see how to look at the constraints, indexes, triggers, synonyms, and security for a table Finally, you will see how to write one script that will give you a pretty complete dump of all this information just by issuing one command

Dictionary Views Used in This Chapter.

A number of data dictionary views are referenced by the examples and scripts shown in this chapter For your

convenience, they are all shown together in this section As you scan through these, it's not necessary to understand every single column of each view Many of the view columns, particularly in ALL_TABLES and ALL_INDEXES, relate to the physical implementation of the objects, and aren't discussed in this chapter The more experienced you become with Oracle, the more you will come to understand the information these columns contain

The ALL_TABLES View

The ALL_TABLES view contains one record for every table to which you have access Table 6-2 lists the columns in this view and explains what information they contain Many of the columns contain information about the physical implementation of the table, and if you are not the DBA, you may not be too interested in them Some columns,

beginning with NUM_ROWS and going through NUM_FREELIST_BLOCKS, are set only when you use the

ANALYZE TABLE command to compute statistics for the table

Table 6-2 Columns in the ALL_TABLES View

Column Name Contents

OWNER Username of the table's owner.

TABLE_NAME Name of the table.

TABLESPACE_NAME Name of the tablespace where the table is stored This is a foreign key to the

DBA_TABLESPACES view.

CLUSTER_NAME A cluster name, if the table belongs to a cluster This is a foreign key to the ALL_CLUSTERS

view.

IOT_NAME An index-organized table name.

PCT_FREE Minimum percentage of free space in a block When free space drops to this level, Oracle stops

adding new rows to the block.

PCT_USED Minimum percentage of used space in a block When used space drops to this level, Oracle will

again add new rows to the block.

INI_TRANS Initial number of transactions that can concurrently touch this block.

INITIAL_EXTENT The size, in bytes, of the initial extent for the table This is how much space is allocated when the

table is first created.

NEXT_EXTENT The size, in bytes, of the next extent for the table The next time the table needs to be expanded,

this is how much space will be allocated.

MIN_EXTENTS The minimum number of extents to be allocated for the table This value affects the amount of

space that is initially allocated for the table See INITIAL_EXTENT and NEXT_EXTENT.

MAX_EXTENTS The maximum number of extents allowed for the table When these are used up, you won't be able

to insert any more data into the table.

PCT_INCREASE A percentage that controls growth of the NEXT_EXTENT value Each time an extent is allocated,

NEXT_EXTENT is recomputed to be NEXT_EXTENT + (NEXT_EXTENT*

(PCT_INCREASE/100)) This value is then rounded up to the blocksize, or a multiple of the blocksize.

FREELISTS The number of freelists allocated to the table.

FREELIST_GROUPS The number of freelist groups allocated to the table.

LOGGING The logging attribute for the table.

BACKED_UP A Y/N flag that indicates whether or not the table has been backed up since the last change.

NUM_ROWS The number of rows in the table.a

BLOCKS The number of data blocks used by the table.a

(table continued on next page)

Table 6-2 Columns in the ALL_TABLES View (continued)

EMPTY_BLOCKS The number of data blocks allocated to the table that have never been used.a

AVG_SPACE The average amount of free space in all blocks allocated to this table This value is in

bytes.

CHAIN_CNT The number of rows in the table that have had to be chained across more than one

block, possibly because the row has been expanded This also includes rows that have been moved entirely out of the block in which they were originally created.

AVG_ROW_LEN The average length, in bytes, of the rows in the table.

AVG_SPACE_FREELIST_BLOCKS The average freespace in all table blocks that are currently in the freelist.

NUM_FREELIST_BLOCKS The number of blocks allocated to the table that still contain space for more rows.

DEGREE The number of threads per instance for scanning the table.

INSTANCES The number of instances allowed to scan the table at one time.

CACHE A Y/N flag indicating whether or not the table should be cached in the buffer.

TABLE_LOCK Either ENABLED or DISABLED, indicating whether or not users are allowed to lock

the entire table.

SAMPLE_SIZE The sample size used when analyzing the table and computing statistics.

LAST_ANALYZED The date on which the table was most recently analyzed.

PARTITIONED Either YES or NO, indicating whether or not the table is partitioned.

IOT_TYPE Indicates whether or not the table is an index-only table A null value indicates a

normal table A value of IOT or IOT_OVERFLOW is used for index-only tables.

TEMPORARY Either Y or N, indicating whether or not the table is a temporary table.

NESTED Either YES or NO, indicating whether or not the table is a nested table.

BUFFER_POOL The name of the default buffer pool for the table.

a Not maintained automatically by Oracle This column is set when you use the ANALYZE TABLE command with the

COMPUTE STATISTICS option.

The ALL_TAB_COLUMNS view

The ALL_TAB_COLUMNS view contains one record for every column in a table This is the view used by the DESCRIBE command to get column names, lengths,

and datatypes Table 6-3 lists the columns in this view and explains the information they contain.

Table 6-3 Columns in the ALL_TAB_COLUMNS View

OWNER Username of the table's owner.

TABLE_NAME Name of the table.

COLUMN_NAME The column name.

DATA_TYPE The column's datatype (e.g., VARCHAR2, NUMBER, etc).

DATA_TYPE_MOD The datatype modifier for the column.

DATA_TYPE_OWNER The datatype owner This is used in Oracle8 and above when you create a column based

on an object type owned by another user.

DATA_LENGTH The length of the column in bytes.

DATA_PRECISION The decimal precision, or the number of significant digits, the column will hold, if the

column is type NUMBER If the column is type FLOAT, then this is the binary precision, or the number of significant bits For all other datatypes, this will be NULL.

DATA_SCALE The number of digits allowed to the right of the decimal point in a NUMBER column

Remember, NUMBER columns are defined as NUMBER (precision, scale).

NULLABLE Y = the column may contain null values

N = the column may not contain null values This may be because of a NOT NULL constraint, or because the column is part of the table's primary key.

COLUMN_ID The sequence number, indicating the column's position within each record When you

create a table, the first column in the list will have a COLUMN_ID of 1 The next column will have a COLUMN_ID of 2, and so on.

DEFAULT_LENGTH The length of the default value for the column, if there is a default value.

DATA_DEFAULT The default value for the column.

NUM_DISTINCT The number of distinct values in the column.a

LOW_VALUE The lowest value, up to the first 32 bytes of that value, in the column.a

HIGH_VALUE The highest value, up to the first 32 bytes of that value, in the column.a

DENSITY The density of the column.a

NUM_NULLS The number of records with a null value for this column.b

NUM_BUCKETS The number of buckets in the column's histogram.b

LAST_ANALYZED The date on which the data in the column was last analyzed with an ANALYZE TABLE

COMPUTE STATISTICS command.b