Oracle SQL Plus The Definitive Guide- P17 pps

< previous page page_137 next page > Page 137 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 < previous page page_137 next page > < previous page page_138 next page > Page 138 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. < previous page page_138 next page > < previous page page_139 next page > Page 139 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 < previous page page_139 next page > < previous page page_140 next page > Page 140 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. < previous page page_140 next page > < previous page page_141 next page > Page 141 Table 4-2. Commands to Start SQL*Plus and Execute a Script Command Result 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 < previous page page_141 next page > < previous page page_142 next page > Page 142 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. < previous page page_142 next page > < previous page page_143 next page > Page 143 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. < previous page page_143 next page > < previous page page_144 next page > Page 144 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. < previous page page_144 next page > < previous page page_145 next page > Page 145 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 < previous page page_145 next page > . 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. 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. 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