Oracle SQL Plus The Definitive Guide- P17 pps

Both of these decisions affect the command used by the shortcut to invoke SQL*Plus and start the script.. Commands to Start SQL*Plus and Execute a ScriptPLUS80W username/password@connect

INDEX: PROJECT_HOURS_EMP_DATE

TABLESPACE: USER_DATA

COLUMNS: EMPLOYEE_ID

TIME_LOG_DATE

UNIQUE INDEX: PROJECT_HOURS_PK

TABLESPACE: USER_DATA

COLUMNS: PROJECT_ID

EMPLOYEE_ID

TIME_LOG_DATE

6 rows selected

Commit complete

Cleaning Up the Display

As you've followed the development of the LIST_INDEXES script, you no doubt saw the following lines interspersed

in the output:

old 9: AND ui.table_name = UPPER(&table_name)

new 9: AND ui.table_name = UPPER(project_hours)

6 rows selected

Commit complete

These lines add no value to the script and serve only to clutter up the output It would be nice to get rid of them, and it is possible to do that by turning verification and feedback off The commands to do that are described next

Turning Verification Off

Verification refers to what SQL*Plus does when it encounters a line of script containing substitution variables By

default, SQL*Plus verifies the substitution by displaying both the old and the new versions of the line involved The output from verification looks like this:

old 9: AND ui.table_name = UPPER(&table_name)

new 9: AND ui.table_name = UPPER(project_hours)

Sometimes this verification is useful, especially when you are first developing a script, because it allows you to see for sure whether or not your substitutions are being made correctly Once you've developed a script, though, it's nice to be able to turn this output off

You can turn verification off by adding the following command to your script:

SET VERIFY OFF

Turning verification off makes your output a lot cleaner, and is especially helpful if the script is a report that may be run

by an end user

Turning Feedback Off

Feedback refers to the short messages that SQL*Plus displays after executing a SQL statement such as SELECT or

COMMIT Feedback looks like this:

6 rows selected

Commit complete

As with verification, feedback often clutters up the output from a script The extra lines added by feedback are

sometimes just enough to scroll output that you want to see off the top of the display, which can be a bit annoying You can turn feedback off by adding the following line to your scripts:

SET FEEDBACK OFF

You may want to turn it back on at the end of the script Use SET FEEDBACK ON for this purpose, so that you get the normal feedback messages when executing interactive commands

Turning Command Echoing Off

The echo setting controls whether or not commands from script files are displayed to the screen as they are executed

Normally off by default, command echoing can be a useful debugging tool To turn echo on, use the following

command:

SET ECHO ON

Now when you execute a script, such as LIST_INDEXES, all the commands are echoed to the display as they are

executed Here's how that would look:

SQL> set echo on

SQL> @C:\jonathan\sql_plus_book\xe_ch_5\list_indexes_H

SQL> SET HEADING OFF

SQL> SET RECSEP OFF

SQL> SET NEWPAGE 1

SQL> SET FEEDBACK OFF

SQL> SET VERIFY OFF

SQL>

SQL> PROMPT

SQL> PROMPT This script will first DESCRIBE a table, then

This script will first DESCRIBE a table, then

SQL> PROMPT it will list the definitions for all indexes

it will list the definitions for all indexes

SQL> PROMPT on that table

on that table

SQL> PROMPT

SQL>

SQL> Get the table name from the user

SQL> ACCEPT table_name CHAR PROMPT Enter the table name >

Enter the table name >

As you can see, echoing is something you usually want turned off As a safety measure, I often include SET ECHO OFF in my script files in order to avoid accidentally being deluged by output The one case where I always turn echoing

on is when I build a script file containing DDL commands If I run a script to create tables, indexes, or some other object, I like to see exactly what is happening when I run it

Turning Off All Terminal Output

Sometimes it's helpful to turn off the display output completely You've already seen this done in Chapter 3 when the script to produce the Project Hours and Dollars Report was modified to spool the output to a file Usually you want to turn off the display when you are spooling a report to a file, or when you are extracting data to a file You may not want

to look at all the data scrolling by on the screen, and turning off the display can speed things up quite a bit The

command to turn off terminal output is SET TERMOUT OFF To turn output back on again, use SET TERMOUT ON When using these commands, you usually want to bracket the SQL query that produces the report, as shown here:

SET TERMOUT OFF

SELECT P.PROJECT_ID,

P.PROJECT_NAME

FROM PROJECT P;

SET TERMOUT ON

The more output a report produces, the more turning off the display will make it run faster That's because updating and scrolling the display is one of the most time-consuming tasks SQL*Plus must perform

Packaging your Script

For most scripts you write, you will be satisfied just invoking them from the SQL*Plus prompt Sooner or later,

however, you are going to write a script that you want to share with an end user who may not be familiar with

SQL*Plus, or you may end up implementing a complex batch process as a SQL*Plus script In either of these cases you may find it convenient to create a command or icon that can easily be used to execute the script in question In the Microsoft Windows

environment, for example, you could easily create an icon on which an end user could double-click in order to produce

a report or extract data

Creating a Windows Shortcut

There are two decisions you need to make if you are going to create an icon or shortcut to execute a script One is

whether to embed the Oracle username and password into the shortcut or to prompt the user for this information The second is to decide which version of SQL*Plus you want to usethe GUI version or the DOS version

Both of these decisions affect the command used by the shortcut to invoke SQL*Plus and start the script Your job is easiest if you can embed the Oracle username and password, or at least the username, into the shortcut If you need to prompt for both username and password at runtime, then you will need to make some minor additions to your script For purposes of example, let's assume you are going to create a Windows shortcut to run the Project Hours and Dollars Report shown earlier in this chapter This section will show you how to do that both for the case where you can

hardcode the Oracle username in the shortcut, and for the case where you can't

Starting the SQL*Plus executable

The Windows version of Oracle contains two SQL*Plus executables One starts the command-line version while the other starts the GUI version The exact executable names vary slightly from one release of Oracle to the next because the SQL*Plus version number is embedded in the last two characters of the filename The locations of these executables vary as well, because the Oracle home directory is named differently under Windows 95 and NT

Beginning with version 8.1, Oracle has changed the naming convention used for the Windows

and command-line implementations of SQL*Plus SQLPLUS.EXE runs the command-line

version, while SQLPLUSW.EXE starts the GUI version.

Before you can create the shortcut, you need to decide on the exact command you will use to start SQL*Plus Table 4-2 shows three commands Each starts the GUI version of SQL*Plus under Windows 95, and executes the SQL script to produce the report The difference is in whether or not the user is to be prompted for an Oracle username, a username and password, or not prompted at all

Table 4-2 Commands to Start SQL*Plus and Execute a Script

PLUS80W username/password@connect

@hours_dollars_d

Username and password embedded in the command; user not prompted.

PLUS80W username@connect @hours_

dollars_d

Username embeded in the command; SQL*Plus prompts for the password.

PLUS80W /NOLOG @hours_dollars_d Your script must prompt for both username and password.

The @ sign is used both to mark the connect string and to start a script file You must have at least one space

between the login string and the command that starts the script; otherwise, SQL*Plus will become confused and

try to interpret the script file name as a connect string.

With the first command shown in Table 4-2, your script will simply run SQL*Plus will connect to Oracle with the username and

password provided The second command supplies only a username, so SQL*Plus will prompt for the password, and then run your script The third command deserves more explanation If you leave off both the username and password entirely, yet specify a script file on the SQL*Plus command line, SQL*Plus gets confused If you want to prompt the user for both his username and password, you have to do it from within your script In order to allow for that, the /NOLOG option is used to tell SQL*Plus to start up without first attempting to connect to a database.

The implementation of SQL*Plus that ships with Oracle8 Personal Edition doesn't seem to handle PLUS80

username®connect properly Even though your connect string specifies a remote database, that implementation

of SQL*Plus will still attempt to connect you to the local database.

When you start up SQL*Plus with the /NOLOG option, your script must log into a database before it executes any SQL statements The CONNECT command is used to do this, and you can use substitution variables to allow the user to enter the required values at runtime The following commands, for example, prompt for a username and password, then use that information to connect to Oracle.

ACCEPT username CHAR PROMPT Enter your Oracle username >

ACCEPT password CHAR PROMPT Enter your password >

CONNECT &username/&password

Once you have decided how to start SQL*Plus and which version to run, you are ready to create a Windows shortcut to run your script

Creating the shortcut

To create a Windows shortcut, right-click on the Windows 95 or NT desktop, and select New→ Shortcut from the popup menu Type the command to start SQL*Plus and execute your script in the Command line: field For example, if your command is PLUS80W /NOLOG @hours_dollars_d, the resulting screen should look like that shown in Figure 4-1

Figure 4-1

The Windows shortcut wizard Press the Next button to advance to the next step, where you select a name for the shortcut Be sure to pick a name that makes senseone that will remind you later of what the script does For this example, use the name Project Hours and Dollars Report Figure 4-2 shows this screen after the name has been entered

Finally, press the Finish button The shortcut will be created, and will appear on your desktop The icon will come from the SQL*Plus executable, and will be the familiar disk platter with a plus on top if you've chosen to use the GUI

version This is shown in Figure 4-3

Now you can run the script Double-click the icon and give it a try

Figure 4-2

Naming the shortcut

Figure 4-3

The shortcut icon

Creating a Unix Command

If you are running under Unix, you can write a simple shell script to invoke SQL*Plus and run a SQL*Plus script The command you need to place in your script file is pretty much the same as the one used in the previous Windows 95 shortcut example For example, if you are running the Korn shell, the following command is all you need to run the Project Hours and Dollars Report:

sqlplus username @hours_dollars_d

Unlike with Windows, the Unix command to invoke SQL*Plus is almost always sqlplus Note that the above command

does not include a password It's always best to avoid hardcoding passwords in script files In this case, SQL*Plus will prompt you for a password when you execute the script

The DEFINE and UNDEFINE Commands

The DEFINE and UNDEFINE commands allow you to explicitly create and delete user variables DEFINE creates a variable and assigns it an initial value DEFINE also lets you list all currently defined user variables with their values The UNDEFINE command allows you to delete a user variable so it can no longer be referenced

The DEFINE Command

The DEFINE command is used to define a new user variable and assign it a value DEFINE may also be used to display the value of a specific user variable or to display the values of all user variables

Syntax for the DEFINE command

The syntax for the DEFINE command is:

DEF[INE] [variable_name [= text]]

where:

DEF[INE]

Is the command, which may be abbreviated to DEF

variable_name

Is the name of the variable you want to create

text

Is the text you want to assign to that variable This may optionally be enclosed by single or double quotes, which you should use any time the value contains spaces or any other nonalphabetic character

Defining a variable

The first form of the DEFINE command is used to create a variable Here are some examples:

SQL> DEFINE fiscal_year = 1998

SQL> DEFINE my_publisher = O'Reilly

SQL> DEFINE my_editor = Debby Russell

The last command is a good example of where quotes should have been used The command will appear to execute correctly, but because of the space between the first and last name, my_editor will contain just Debby The remaining portion of the line is ignored

Examining a variable

The second form of the DEFINE command, where you specify only a variable name as an argument, shows you the contents of that variable Here are some that examine the variables just created previously:

SQL> DEFINE fiscal_year

DEFINE FISCAL_YEAR = 1998 (CHAR)

SQL> DEFINE my_publisher

DEFINE MY_PUBLISHER = O'Reilly (CHAR)

SQL> DEFINE my_editor

DEFINE MY_EDITOR = Debby (CHAR)

As you can see, because double quotes weren't used in the original DEFINE command, Debby's last name has been lost

Listing all variables

Issuing the DEFINE command with no arguments at all tells SQL*Plus to display all defined variables with their

contents; for example:

SQL> DEFINE

DEFINE _SQLPLUS_RELEASE = 800040000 (CHAR)

DEFINE _EDITOR = Notepad(CHAR)

DEFINE _O_VERSION = Oracle8 Enterprise Edition Release 8.1.3.0.0

With the Partitioning and Objects options

PL/SQL Release 8.1.3.0.0 -Beta (CHAR)

DEFINE _O_RELEASE = 801030000 (CHAR)

DEFINE FISCAL_YEAR = 1998 (CHAR)

DEFINE MY_PUBLISHER = O'Reilly (CHAR)

DEFINE MY_EDITOR = Debby (CHAR)

SQL>

Not only are the variables just defined in the above list, but there are a number of others as well That's because

SQL*Plus automatically defines these at startup You can define your own variables automatically as well, by taking

advantage of the LOGIN.SQL file See The Site and User Profiles in Chapter 11, Customizing Your SQL*Plus

Environment, for more information on this.

Usage notes

If you need to get a value from a user, DEFINE doesn't buy you much because you still have to use the ACCEPT

command to get the user's input However, using the DEFINE command to explicitly create all your variables at the beginning of a script can serve as a useful form of documentation This is especially helpful in very long scripts, or when you have a chain of tightly coupled script files that call one another

The DEFINE command can also be used to define certain magic constants, such as a company name, that may need to

be used more than once in a script Storing