< previous page page_462 next page > Page 462 script_file Is the name of the file you want to execute, and may include the path and the extension. The default extension is SQL. If you do not specify a path, SQL*Plus will look for the file first in the current working directory, then search each directory listed in the SQLPATH environment variable. See Chapter 11 for information about customizing the search path. argument Is an argument you wish to pass to the script. You may pass as many arguments as you like. Arguments must be separated from each other by at least one space. Arguments may be enclosed in quotes, and should be if they contain spaces. Either single or double quotes may be used, at your discretion. Your script may reference the first argument as &1, the second as &2, and so forth. Startup The STARTUP command allows you to start an Oracle instance and open a database. Chapter 10 discusses this command. In order to use STARTUP, you must be connected as SYSDBA, SYSOPER, or INTERNAL. STARTUP [FORCE] [RESTRICT] [PFILE_parameter_filename] [MOUNT [OPEN [RECOVER]] [database_name]] [[EXCULSIVE ¦PARALLEL¦SHARED] ¦ [NOMOUNT] where: STARTUP Is the command, which may not be abbreviated. FORCE Forces the instance to start. If the instance is currently running, then FORCE will cause the equivalent of a SHUTDOWN ABORT to be done first; then the instance will be restarted. RESTRICT Opens the database in restricted session mode. Only users with the RESTRICTED SESSION system privilege will be allowed to connect. PFILE=parameter_filename Tells SQL*Plus to use the specified parameter file (initialization file) when starting the instance. You may specify a path with the filename. < previous page page_462 next page > < previous page page_463 next page > Page 463 SQL*Plus reads the parameter file, not the Oracle instance. The path to the parameter file must be relative to the machine running SQL*Plus. This matters, for example, if you are using SQL*Plus on a PC and connecting remotely to an instance on a server in order to start it. MOUNT Causes the database to be mounted, but not opened. The instance will be started. The control file will be opened, but none of the other database files will be opened. The MOUNT stage is the one between NOMOUNT and OPEN. OPEN Causes the database to be mounted, then opened for normal operation. RECOVER Tells Oracle to perform media recovery, if necessary. If no recovery is necessary, the database is opened as normal. If recovery is necessary, it proceeds automatically. You will be prompted for any needed log files that cannot be found. A failed recovery leaves the database mounted, but not opened. database_name Is a name you specify, which becomes the name of the database. This value overrides the DB_NAME parameter in the initialization file. EXCLUSIVE Causes the database to be opened, or mounted, exclusively by the current instance. No other instances may share it. This is the default setting, and is used if neither SHARE nor PARALLEL is specified. PARALLEL Causes the database to be opened, or mounted, in such a way as to allow multiple instances to access it simultaneously. This option cannot be used if the SINGLE_PROCESS parameter in the initialization file is set to TRUE. SHARED SHARED has the same effect as PARALLEL. RETRY Is provided for use when opening a database in parallel mode. RETRY affects the behavior of the instance when the database open fails because some other instance is performing recovery operations. When RETRY is specified, the instance will retry the open every five seconds until recovery is complete and the database is opened. NOMOUNT Causes an instance to be started, but no database is mounted or opened. < previous page page_463 next page > < previous page page_464 next page > Page 464 STORE STORE is a relatively new addition to the SQL*Plus command set. It generates a file of SET commands based on the current state of those settings. This file can be used after those settings have been changed to reset everything back to a known state. STORE SET filaname [CRE[ATE]¦REP[LACE]¦APP[END]] where: STORE Is the command. SET Is an option indicating what you want to store. Currently, the only option available is SET. filename Is the name of the file, including the path and extension, to which you want to write the SET commands. CRE[ATE] Causes the command to fail if the file already exists. REP[LACE] Causes SQL*Plus to overwrite any existing file with the same name. APP[END] Causes the SET commands to be appended to an existing file. Timing The TIMING command lets you start, stop, or display the value of a timer. Timers let you measure elapsed time, and are described in Chapter 8, Tuning and Timing. TIMI[NG] [START [timer_name] ¦ SHOW ¦ STOP] where: TIMI[NG] Is the command, and may be abbreviated to TIMI. START [timer_name] Starts a new timer, and optionally gives it the name you provide. SHOW Shows the current value of the most recently started timer. STOP Stops the most recently started timer, shows its current value, then deletes it. < previous page page_464 next page > < previous page page_465 next page > Page 465 Ttitle Use the TTITLE command to define page titles for a report. Chapter 3 discusses TTITLE, and has several examples. Also see the BTITLE command. TTITLE and BTITLE work the same way. TTI[TLE] {OFF¦ON] ¦ [COL X ¦ [S[KIP] x] TAB x¦ LE[FT] ¦ CE[NTER] ¦ R[IGHT] ¦ BOLD ¦ FOR[MAT] format_spec ¦ text ¦ variable ¦ where: TTI[TLE] May be abbreviated TTI. Issuing the TTITLE command with no parameters causes SQL*Plus to display the current top title setting. OFF Turns the page title off, but does not erase its definition. You can turn it back on again with ON. ON Turns on printing of page titles. The default title, if you do not specify another, will be the current date, the page number, and all or part of the SELECT statement. COLx Causes any title text following this parameter to print at the specified column position. S[KIP]x May be abbreviated to S, and inserts the specified number of line breaks before printing any subsequent title text. TAB x TAB is similar to COL, but moves you the specified number of columns relative to the current position. Negative numbers move you backwards. TAB has nothing whatsoever to do with tab characters. LE[FT] May be abbreviated LE, and causes subsequent title text to be printed beginning at the leftmost column of the current title line. < previous page page_465 next page > < previous page page_466 next page > Page 466 CE[NTER] May be abbreviated CE, and causes subsequent title text to be centered within the current line. The LINESIZE setting controls the line width. R[IGHT] May be abbreviated R, and causes subsequent title text to be printed flush right. The LINESIZE setting controls where SQL*Plus thinks the right end of the line is. BOLD Makes your title bold by printing it three times. Only title text following the BOLD command is repeated on each line. There is no NOBOLD parameter. FOR[MAT] May be abbreviated to FOR, and allows you to control how subsequent numeric data in the title is displayed. format_spec Is a string that specifies the display format to use for subsequent numeric data in the title. The format elements you can use here are the same as for the COLUMN command, and are described in Appendix B. It is possible to specify a character format, such as A20, but that has no effect on subsequent character strings. text Is any text you want to have in the title. To be safe, you should enclose this in quotes, but you don't have to as long as your title text doesn't include any keywords like BOLD or TAB that have meaning to TTITLE. Either single or double quotes may be used. If you need to include a quote as part of your text, use two quote characters back to back. variable May be one of the system variables maintained by SQL*Plus. See Table A-1, in the section on the BTITLE command, for a list of these variables. When using TTITLE, you should start off with one of the keywords such as LEFT, RIGHT, or CENTER. Otherwise, if the first parameter after the command is just text, SQL*Plus will assume you have used a now obsolete syntax for this command, and you won't get the results you want. UNDEFINE. UndefineUNDEFINE is the opposite of DEFINE, and erases a user variable definition. UNDEFINE is discussed in Chapter 4. UNDEF[INE] variable_name ( variable_name] < previous page page_466 next page > < previous page page_467 next page > Page 467 where: UNDEF[INE] Is the command, which may be abbreviated to UNDEF. variable_name Is the name of a user variable to delete. You can delete several variables with one command by listing them out separated by spaces. Variable The VARIABLE command is used to declare bind variables. Bind variables are discussed in Chapter 7. They are real variables that can be used within a PL/SQL block or SQL statement. VAR[IABLE] var_name data_type where: VAR[IABLE] Is the command, which may be abbreviated to VAR. var_name Is whatever name you want to give the variable. A variable name must start with a letter, but after that, the name may contain any combination of letters, digits, underscores, pound signs, and dollar signs. 30 characters is the maximum length for a variable name. data_type Is the datatype of the variable. The following datatypes are allowed: NUMBER This results in a floating-point number, and is the same as a NUMBER variable in PL/SQL or a NUMBER column in a table. Unlike PL/SQL, SQL*Plus does not let you specify a length or a precision, so a declaration like NUMBER (9,2) would not be allowed. CHAR [(length)] Results in a fixed-length character string. Length is optional. If it's omitted, you get a one-character string. NCHAR [(length)] Results in a fixed-length character string in the national character set. Length is optional. If it's omitted, you get a one- character string. VARCHAR2 (length) Results in a variable-length character string. < previous page page_467 next page > < previous page page_468 next page > Page 468 NVARCHAR2 (length) Results in a variable-length character string using the national language character set. CLOB Results in a character large object variable. NCLOB Results in a character large object variable using the national language character set. REFCURSOR Gives you a cursor variable you can use to return the results of a SQL query from PL/SQL to SQL*Plus. Whenever The WHENEVER command controls the behavior of SQL*Plus when an operatingsystem or SQL error occurs, and is discussed in Chapter 7. You can choose between having SQL*Plus exit immediately or continue on whenever an error occurs. You can also choose whether to automatically COMMIT or ROLLBACK in the event of an error. Finally, if you decide to abort in the event of an error, you can pass a value back to the operating system. If you are calling SQL*Plus from an operating-system script, you can use this return value to determine that script's next course of action. WHENEVER {OSERROR ¦ SQLERROR} {EXIT [SUCCESS ¦ FAILURE ¦ value ¦ bind_variable ¦] [COMMIT ¦ ROLLBACK] ¦ CONTINUE [COMMIT ¦ ROLLBACK ¦NONE]} where: WHENEVER OSERROR Use this form of the command to tell SQL*Plus what to do in the event of an operating-system error. WHENEVER SQLERROR Use this form of the command to tell SQL*Plus what to do in the event that an error is returned from a SQL statement or PL/SQL block. EXITSUCCESS Exit with a success status. The exact value of success is operating-systemdependent. This is the default setting, and it applies if the EXIT keyword is used without specifying any return value. EXITFAILURE Exit with a failure status. The value of failure is operating-system-dependent. < previous page page_468 next page > < previous page page_469 next page > Page 469 EXIT value Exit, and return the value specified as the status. EXIT :bind_variable Exit, and return the value of the specified bind variable as the status. CONTINUE Do not exit if an error occurs. This is the default behavior when you first start SQL*Plus. COMMIT This keyword may be used in conjunction with both EXIT and CONTINUE. It causes SQL*Plus to automatically COMMIT the current transaction when an error occurs. This is the default behavior when you use the EXIT keyword. ROLLBACK May also be used in conjunction with EXIT and CONTINUE, and causes SQL*Plus to roll back the current transaction when an error occurs. NONE May only be used in conjunction with CONTINUE, and causes SQL*Plus to neither COMMIT nor ROLLBACK when an error occurs. This is the default behavior when you use the CONTINUE keyword. < previous page page_469 next page > < previous page page_470 next page > Page 470 B SQL*Plus Format Elements Several SQL*Plus commands allow you to control data formats using what is called a format specification. A format specification is a string of characters that tells SQL*Plus exactly how to format a number, date, or text string when it is displayed. The most notable of these commands is the COLUMN command, which is used to format columns of output from a SELECT query. There are other commands as well. The complete list of SQL*Plus commands that accept format specification strings is shown here: ACCEPT Prompts the user to enter a value from the keyboard. COLUMN Controls various aspects of the way a column of data is displayed. SET NUMBER Defines the default display format for numbers. TTITTE, BTITLE, REPHEADER, REPFOOTER These commands all allow number format specifications to control the way numbers are formatted in page headers, page footers, report headers, and report footers. There are three different, broad types of values SQL*Plus can format: numbers, character strings, and dates. Not all commands can handle each type. With most commands, you can only specify number and date formats. The COLUMN command is a good example. The ACCEPT command is the only one that allows you to specify a date format string. Format specification strings are made up of special characters that have meaning to SQL*Plus in the context of formatting a value for display. Numeric format strings, for example, tend to have lots of 0s, 9s, decimal points, and dollar signs. < previous page page_470 next page > < previous page page_471 next page > Page 471 Date format strings tend to include things like MM, DD, YYYY, and so forth. Character string formats are the simplest of all, because you basically have only one thing you can influence: length. Formatting Numbers SQL*Plus offers the most options when it comes to formatting numbers. Numeric format strings may contain any of the elements shown in Table B-1. Table B-1. Numeric Format Elements Format Element Function 9 9s are used to control the number of significant digits to be displayed. 0 A 0 is used to mark the spot in the result where you want to begin displaying leading zeros. It replaces one of the 9s. The most common location for a 0 is at the extreme left of the format string, but you can place it elsewhere. $ Causes a number to be displayed with a leading dollar sign. , Places a comma in the output. . Marks the location of the decimal point. B Forces zero values to be displayed as blanks. MI Used at the end of a format string to cause a trailing negative sign to be displayed for negative values. S May be used at either the beginning or end of a format string, and causes a sign to be displayed. The + sign is used to mark positive numbers, and the - sign marks negative numbers. When you use S, a sign will always be displayed. PR Causes negative values to be displayed within angle brackets. For example, -123.99 will be displayed as <123.99>. Positive values will be displayed with one leading and one trailing space in place of the angle brackets. D Marks the location of the decimal point. G Places a group separator (usually a comma) in the output. C Marks the place where you want the ISO currency indicator to appear. For US dollars, this will be USD. L Marks the place where you want the local currency indicator to appear. For US dollars, this will be the dollar sign character. You cannot use L and C in the same format specification. V Used to display scaled values. The number of digits to the right of the V indicates how many places to the right the decimal point is shifted before the number is displayed. EEEE Causes SQL*Plus to use scientific notation to display a value. You must use exactly four Es, and they must appear at the right end of the format string. (table continued on next page) < previous page page_471 next page > . 463 SQL* Plus reads the parameter file, not the Oracle instance. The path to the parameter file must be relative to the machine running SQL* Plus. This matters, for example, if you are using SQL* Plus. Is the name of the file you want to execute, and may include the path and the extension. The default extension is SQL. If you do not specify a path, SQL* Plus will look for the file first in the. variable you can use to return the results of a SQL query from PL /SQL to SQL* Plus. Whenever The WHENEVER command controls the behavior of SQL* Plus when an operatingsystem or SQL error occurs, and is