Chapter 9 : SQL*PLUS REPORTS Bordoloi and Bock A SQL*Plus PROGRAM COMMAND File • • • Interactive commands can be used to specify report headings, report footers, report titles, page numbers, and other common report features that managers tend to request. Unfortunately, if you exit SQL*Plus, all of the information about a report's features is lost unless you save your commands in a file. For this reason, we will also focus on creating files that will store SQL*Plus commands. We'll refer to this type of file as a SQL*Plus program command file, or simply a SQL program. The filename extension used for these files is .sql. Bordoloi and Bock Example • • • Following program gives a sample SQL*Plus program command file. This SQL program will produce the report shown in Figures 9.1a and 9.1b. All of the data for the report is selected from the assignment table of the Company database. The SQL program has numerous commands. Bordoloi and Bock Example REM Program: ch9-1.sql REM Programmer: dbock; 3-20-2003 REM Description: A program to list employee work history REM on projects. TTITLE 'Project Information' BTITLE SKIP 1 CENTER 'Not for external dissemination.' REPHEADER 'Project Report #1 –- prepared by D. Bock' SKIP 2 REPFOOTER SKIP 3 '-- Last Page of Report --' SET LINESIZE 55 SET PAGESIZE 24 SET NEWPAGE 1 Bordoloi and Bock Example Cont’d COLUMN "Emp. Soc. Sec. #" FORMAT A16 COLUMN "Hours Worked" FORMAT 999.99 SELECT work_emp_ssn "Emp. Soc. Sec. #", work_pro_number "Project #", work_hours "Hours Worked" FROM assignment ORDER BY work_emp_ssn, work_pro_number; • The report produced is shown next. Bordoloi and Bock Sun Apr 14 page Project Information Project Report #1 - prepared by D. Bock Emp. Soc. Sec. # Project # Hours Worked ---------------- ---------- -----------999111111 1 31.40 999111111 2 8.50 999222222 10 34.50 999222222 30 5.10 999333333 3 42.10 999444444 1 999444444 2 12.20 999444444 3 10.50 999444444 10 10.10 999444444 20 11.80 999555555 20 14.80 999555555 30 19.20 999666666 20 999887777 10 10.20 Not for external dissemination. Bordoloi and Bock 1 Sun Apr 14 page Project Information Emp. Soc. Sec. # Project # Hours Worked ---------------- ---------- -----------999887777 30 30.80 999888888 1 21.00 999888888 2 22.00 -- Last Page of Report -- Not for external dissemination. Bordoloi and Bock 2 Remarks • • • Optional remarks are typically entered at the beginning of a command file program that identify the filename, programmer name, and date of program creation. A brief description of the program is also provided. You may also list modifications made by programmer name, date and description here. Remarks and blank lines are used throughout a program to enhance the understandability and readability of programming code. Bordoloi and Bock Top and Bottom Titles • • • 1. 2. 3. 4. Titles and footers on reports enhance the meaning of reports for managerial system users. Reports are rarely disseminated to managers without appropriate title and footers. SQL*Plus supports the programming of four types of titles and footers: Top title, Bottom title, Report header and Report footer. Bordoloi and Bock Top and Bottom Titles • • The TTITLE command (short for top title) prints a title on each page of a report. When a simple TTITLE command like the one shown below is used, the report will automatically display the report date and page number. TTITLE 'Project Information' Bordoloi and Bock Top and Bottom Titles • • • You can also issue the TTITLE command interactively at the SQL> prompt. The first TTITLE command shown below will turn the report title off. The second one will change the report title interactively when followed by a slash (/) command. TTITLE OFF TTITLE 'Project and Employee Information' / Bordoloi and Bock Top and Bottom Titles • • The BTITLE command prints a bottom title with the specified information at the bottom of each page of a report. For example, your organization may want each page of a report marked as not for external dissemination as is shown in the BTITLE command here. BTITLE SKIP 1 CENTER 'Not for external dissemination.' Bordoloi and Bock Top and Bottom Titles • • • • The SKIP clause is optional. SKIP 1 will insert one blank line into the report. You can specify the number of lines to skip. If the SKIP option is specified prior to the bottom title, as is done above, then one line is skipped prior to printing the bottom title. The CENTER option centers the bottom title output. Bordoloi and Bock Top and Bottom Titles • • In addition to CENTER, you can also use the keywords RIGHT and LEFT within both the TTITLE and BTITLE commands to control the display of report information. An example multi-lined TTITLE command is shown below. TTITLE LEFT date_var – RIGHT 'Page: ' FORMAT 99 sql.pno SKIP 1 CENTER 'Project and Employee Information' Bordoloi and Bock Top and Bottom Titles • • • A dash ( - ) at the end of a line continues the TTITLE command. The date_var entry is a variable name that stores the date. When a complex TTITLE command is used, Oracle does not automatically print the date and page number information as was done earlier . Bordoloi and Bock Report Headers and Footers • • • A report header can be used to add meaningful information to the top of the first page of a report. You should use the REPHEADER command whenever you want information to be displayed on only the first page. The REPHEADER command shown below uses the SKIP 2 option to insert two blank lines immediately after the report header is printed. You'll also notice that the report header prints after the top title line. REPHEADER 'Project Report #1 -- prepared by D. Bock' SKIP 2 Bordoloi and Bock Report Headers and Footers • • • Report footers add meaningful information to the bottom of the last page of a report. In the command shown here, the SKIP 3 option provides for three skipped blank lines prior to printing the report footer. You will also note that the report footer prints prior to the bottom title line. REPFOOTER SKIP 3 '-- Last Page of Report --' • The OFF option also applies to report headers and footers, and will turn the report header and/or footer off. Bordoloi and Bock Setting the Line and Page Size • • The SET LINESIZE command specifies the size of an output line in characters. The example report shown before has a line size of 55 characters. SET LINESIZE 55 • • • Similarly, the SET PAGESIZE command specifies the number of lines to be printed per page. A typical setting is 50 to 55 lines of output per page for 10-point or 12-point printer fonts. The command shown below sets the page size to 50 lines. SET PAGESIZE 50 Bordoloi and Bock Setting the Line and Page Size • • • • The SET NEWPAGE command specifies the number of blank lines to print before the top title line of a report, that is, the line that displays the report date and page number. This is useful for aligning reports produced by various types of printers. The SET NEWPAGE command does not affect the PAGESIZE value. The command shown below specifies 6 blank lines at the top of each page. If the page size is set to 55, this will leave 49 lines for displaying output. SET NEWPAGE 6 Bordoloi and Bock Output to the Computer Monitor Screen • • When you are testing a SQL program that will be produce a printed report, it is sometimes useful to specify values for the LINESIZE, PAGESIZE, and NEWPAGE values so that report output will fit on a computer monitor screen. Typical values for screen output are shown below. SET LINESIZE 79 SET PAGESIZE 24 SET NEWPAGE 0 Bordoloi and Bock Output to the Computer Monitor Screen • • You will probably want the computer monitor screen output to pause between pages so that you can review the report. This can be accomplished by the SET PAUSE commands shown below. SET PAUSE 'More . . .' SET PAUSE ON SET PAUSE OFF Bordoloi and Bock CONTROL BREAK REPORTS • • • • A control break report organizes information into meaningful groups. We will organize the new report into groups according to each employee's social security number. The modified example program is listed below. The additional lines of code required to produce the control break report are highlighted in bold text. Additionally, the decision was made to remove the report header and report footer. Bordoloi and Bock Example Modified REM Program: ch9-2.sql REM Programmer: dbock; 3-20-2003 REM Description: A sample program control break report. TTITLE 'Project Information' BTITLE SKIP 1 CENTER 'Not for external dissemination.' SET LINESIZE 55 SET PAGESIZE 24 SET NEWPAGE 1 COLUMN "Emp. Soc. Sec. #" FORMAT A16 COLUMN "Hours Worked" FORMAT 999.99 Bordoloi and Bock Example Cont’d CLEAR BREAKS BREAK ON "Emp. Soc. Sec. #" SKIP 2 ON REPORT COMPUTE SUM OF "Hours Worked" ON "Emp. Soc. Sec. #“ COMPUTE SUM OF "Hours Worked" ON REPORT SPOOL report92.lst SELECT work_emp_ssn "Emp. Soc. Sec. #", work_pro_number "Project #", work_hours "Hours Worked" FROM assignment ORDER BY work_emp_ssn, work_pro_number; SPOOL OFF Bordoloi and Bock Sun Apr 14 page Project Information Project Report #1 - prepared by D. Bock Emp. Soc. Sec. # Project # Hours Worked ---------------- ---------- -----------999111111 1 31.40 2 8.50 **************** -----------sum 39.90 999222222 10 30 34.50 5.10 -----------39.60 3 42.10 ------------ **************** sum 999333333 **************** Bordoloi and Bock Not for external dissemination. 1 The BREAK Command • The BREAK command groups data rows for a control break report. The syntax of the BREAK command is: BREAK ON (expression1, ON expression2, … \row\page\report) … [SKIP n | [SKIP] PAGE] [NODUPLICATES | DUPLICATES]; • The BREAK command can be used to break on an expression, row, page, report, or more than one of these at a time. The BREAK command used in example program is shown below. CLEAR BREAKS BREAK ON "Emp. Soc. Sec. #" SKIP 2 ON REPORT • The CLEAR BREAKS command clears any previously established breaks. Bordoloi and Bock Output Style • The style of output shown in the example report is called NONDUPLICATES, or NODUP because each group value (employee social security number) is shown only once. • This is the default BREAK output method so there is no need to specify it. While this form of output diverges from the relational, two-dimensional, matrix format, it is much easier for managers to read. • The NODUP default can be overwritten by specifying the keyword DUP with the BREAK command as is shown here. This will yield the purely relational, twodimensional, matrix format for output. Bordoloi and Bock BREAK ON "Emp. Soc. Sec. #" DUP SKIP 2 SKIP and PAGE Keywords • To enhance the readability of a report, one or more blank rows can be inserted after each social security number grouping. As we noted earlier, the SKIP keyword inserts the blank rows. Our program specified to skip two lines prior to beginning the next report group. • Replacing the keyword SKIP with PAGE will cause a page eject to occur after each grouping. • This will produce a report with each social security number beginning on a new page. This will also cause each group to be preceded by new column headings. Bordoloi and Bock The COMPUTE Command • In order for a COMPUTE command to compute subtotals and totals properly it must be used in conjunction with a BREAK command. • If you have not specified a BREAK command, then a COMPUTE command will not produce any results! • When used with BREAK, a COMPUTE command displays values that are computed for the BREAK expression. The syntax of the COMPUTE command is shown here. COMPUTE {group function} OF {column_name | column_name_alias,. . .} ON {break_column_name | ROW | PAGE | REPORT}; Bordoloi and Bock The SPOOL Command • The SPOOL command routes the output from a SQL*Plus program to the specified filename. • The SPOOL command shown below routes output to a file named report9-2.lst. • The "lst" filename extension is short for listing; however, you can specify any filename extension that you desire. • The SPOOL OFF command terminates writing to the output file. SPOOL report9-2.lst SPOOL OFF Bordoloi and Bock Additional BREAK Command Details • The BREAK command in the example program specifies a break on a column as well as on a report. You can also break on any kind of expression, on rows, and on pages. • The BREAK ON ROW command can be used to change report spacing. The BREAK command shown below will insert a blank line between each row of the assignment report. BREAK ON ROW SKIP 1 • A column break and a row break can be used together. In conjunction, these two breaks create a double-spaced report that is still separated by column values. The command shown here will produce a double-spaced report that also breaks at the end of the report. BREAK ON "Emp. Soc. Sec. #" SKIP 1 ON REPORT ON ROW SKIP 1 Bordoloi and Bock Viewing Current BREAK and COMPUTE Command Settings • Only one BREAK command can be active at a time. • You can interactively replace the current BREAK command by typing a new command at the SQL> prompt. • If you forget which BREAK command is active, simply type the command BREAK on a line by itself and SQL*Plus will display the break status. • Note that the default for the BREAK command is no duplicates (NODUP). BREAK break on report nodup on Emp. Soc. Sec. # skip 2 nodup Bordoloi and Bock Viewing Current BREAK and COMPUTE Command Settings • Unlike BREAK, the COMPUTE command is cumulative. • While you are testing a program, you may accumulate quite a number of COMPUTE settings. You can display the current settings by simply typing the COMPUTE command at the SQL> prompt. COMPUTE COMPUTE sum LABEL 'sum' OF Hours Worked ON Emp. Soc. Sec. # COMPUTE sum LABEL 'sum' OF Hours Worked ON REPORT • You can clear COMPUTE settings by typing CLEAR COMPUTE at the SQL> prompt or by placing the command within a program. • When the command is used interactively, Oracle will respond as shown below. CLEAR COMPUTE computes cleared Bordoloi and Bock CREATING MASTER-DETAIL REPORTS • A master-detail report is a form of control break report because the report presents information that is "grouped.“ • The report typically displays data rows from more than one table. • Consider the one-to-many relationship between the department and project tables for the Company as described in Appendix A. • Each department controls numerous projects, and a project belongs to a single department. • In this situation, the rows in the department table are "master" rows because the department table is on the "one" side of the one-to-many relationship. • The associated project table rows provide the "detail" information. Bordoloi and Bock • Example • Program ch9-3.sql will produce the master-detail report for the department-project relationship. REM Program: ch9-3.sql REM Programmer: dbock; Date: 3-20-2003 REM Description: A sample Master-Detail report REM set page size, line size, new page spacing for screen display. SET LINESIZE 65 SET PAGESIZE 12 SET NEWPAGE 1 REM define department variable COLUMN pro_dept_number NEW_VALUE dept_number_var NOPRINT REM set column sizes based on alias column names COLUMN dpt_name FORMAT A18 COLUMN pro_name FORMAT A15 COLUMN pro_location FORMAT A15 TTITLE CENTER 'Department Number:' dept_number_var SKIP 2 BTITLE SKIP 1 CENTER 'Not for external dissemination.' Bordoloi and Bock • Example cont’d BREAK ON pro_dept_number SKIP PAGE SELECT pro_dept_number, dpt_name, pro_name, pro_location FROM department d, project p WHERE d.dpt_no = p.pro_dept_number AND pro_dept_number IN (3, 7) ORDER BY pro_dept_number; • The report produced is shown next. Bordoloi and Bock Department Number: DPT_NAME -----------------Admin and Records Admin and Records PRO_NAME ----------------Inventory Pay Benefits 3 PRO_LOCATION --------------Marina Marina Not for external dissemination. More . . . Department Number: DPT_NAME -----------------Production Production Production PRO_NAME --------------Order Entry Payroll Receivables PRO_LOCATION --------------St. Louis Collinsville Edwardsville Not for external dissemination. Bordoloi and Bock 7 MASTER-DETAIL REPORTS • A typical master-detail report format includes information in the top title report line that identifies the "master column" that controls the page breaks. • You can reference a column value in a top title by first storing the column value to a program variable. • You then specify the program variable name in the TTITLE command. • A special form of the COLUMN command is used to define a program variable as shown below. • The actual COLUMN command from program ch9-3.sql is also shown below. • The NEW_VALUE clause defines the variable name. You must follow Oracle's naming rules when naming program variables. COLUMN column_name NEW_VALUE variable_name [options] COLUMN pro_dept_number NEW_VALUE dept_number_var NOPRINT Bordoloi and Bock Using Views in Master-Detail Reports REM Program: ch9-4.sql REM Programmer: dbock; 3-20-2003 REM Description: The revised Master-Detail program with a View. REM SET SET SET set page size, line size, new page for screen display. LINESIZE 75; PAGESIZE 12; NEWPAGE 1; REM Create a view to be used in the SELECT command later. CREATE OR REPLACE VIEW project_department (project_no, dept_name, project_name, location) AS SELECT pro_dept_number, dpt_name, pro_name, pro_location FROM department d, project p WHERE d.dpt_no = p.pro_dept_number AND pro_dept_number IN (3, 7) ORDER BY pro_dept_number; Bordoloi and Bock Using Views in Master-Detail Reports COLUMN dept_name NEW_VALUE dpt_name_var NOPRINT COLUMN dept_name FORMAT A18 COLUMN project_name FORMAT A15 COLUMN location FORMAT A15 TTITLE CENTER 'Department Name: ' dpt_name_var SKIP 2 BTITLE SKIP 1 CENTER 'Not for external dissemination.' BREAK ON project_no SKIP PAGE; SELECT project_no, dept_name, project_name, location FROM project_department; • The program creates a view named project-department. This view assigns meaningful names to the selected columns, joins the department and project tables, and orders the output of rows by department number of the department controlling Bordoloi and Bock each project. Using Views in Master-Detail Reports • • • • • The revised COLUMN command uses a NEW_VALUE clause to store the value of the dept_name column of the view to a variable named dpt_name_var. This variable is used in the TTITLE command to display the department name at the top of each page. The BREAK command still breaks on the project_no column as the master column. Finally, the SELECT statement is greatly simplified because the program is now selecting information from the view. If the view had been previously created, then the code to create the view could be deleted from program ch9-4.sql. Bordoloi and Bock Department Name: Admin and Records PROJECT_NO PROJECT_NAME ---------- --------------3 Inventory Pay Benefits LOCATION --------------Marina Marina Not for external dissemination. More . . . Department Name: Production PROJECT_NO PROJECT_NAME ---------- --------------7 Order Entry Payroll Receivables Bordoloi and Bock LOCATION --------------St. Louis Collinsville Edwardsville Not for external dissemination. USING VARIABLES FOR INTERACTIVE REPORTING REM Program: ch9-5.sql REM Programmer: dbock; 3-20-2003 REM Description: Program with interactive variables. SET LINESIZE 60; SET PAGESIZE 12; SET NEWPAGE 1; COLUMN today NEW_VALUE date_var SELECT TO_CHAR(SYSDATE, 'MM/DD/YY') today FROM dual; COLUMN pro_name NEW_VALUE pro_name_var NOPRINT COLUMN pro_number NEW_VALUE pro_number_var NOPRINT COLUMN "Department" FORMAT A18 Bordoloi and Bock USING VARIABLES FOR INTERACTIVE REPORTING COLUMN "SSN" FORMAT A12 COLUMN "Employee Name" FORMAT A20 COLUMN "Hours" FORMAT 999.99 CLEAR BREAKS CLEAR COMPUTES BREAK ON "Department" ON REPORT COMPUTE SUM OF "Hours" ON REPORT ACCEPT project_no_var PROMPT 'Enter a project number: ' PAUSE Press the Enter Key to continue. TTITLE LEFT date_var CENTER 'Project Name: ' pro_name_var RIGHT 'Page:' FORMAT 999 sql.pno SKIP 1 CENTER 'Project Number:' pro_number_var SKIP 2 Bordoloi and Bock USING VARIABLES FOR INTERACTIVE REPORTING SPOOL project.lst SELECT pro_number, pro_name, dpt_name "Department", SUBSTR(work_emp_ssn,1,3)||'-'||SUBSTR(work_emp_ssn,4,2)||''||SUBSTR(work_emp_ssn,6,4) "SSN", emp_last_name||', '|| emp_first_name "Employee Name", work_hours "Hours" FROM project p, assignment a, employee e, department d WHERE p.pro_number = a.work_pro_number AND a.work_emp_ssn = e.emp_ssn AND d.dpt_no = p.pro_dept_number AND p.pro_number = '&project_no_var‘ ORDER BY pro_number, emp_last_name, emp_first_name; SPOOL OFF Bordoloi and Bock Executing Program Ch9-5.Sql SQL> start ch9-5.sql More . . . TODAY -------04/14/02 Enter a project number: 30 Press the Enter Key to continue. old 9: new 9: More . . . p.pro_number = '&project_no_var' p.pro_number = '30' 04/14/02 Project Name: Pay Benefits Project Number: 30 Department SSN ------------------ -----------Admin and Records 999-22-2222 999-55-5555 999-88-7777 ****************** Bordoloi and Bock Page: 1 Employee Name Hours -------------------- ------Amin, Hyder 5.10 Joyner, Suzanne 19.20 Markis, Marcia 30.80 ------55.10 Defining User Variables • You can define variables with the SQL*Plus DEFINE command. • The command shown here defines a variable name_var, and assigns it the value "Bordoloi." DEFINE name_var = Bordoloi • If you need to know what variables have been defined for your working session, enter the DEFINE command by itself at the SQL> prompt and all current variable definitions will be displayed. • You can also delete a variable with the UNDEFINE <variable_name> command. Bordoloi and Bock Defining User Variables DEFINE name_var = Bordoloi SELECT emp_last_name, emp_first_name, emp_date_of_birth FROM employee WHERE emp_last_name = '&name_var' / EMP_LAST_NAME EMP_FIRST_NAME EMP_DATE_ ------------------------- -------------------------- ----------------Bordoloi Bijoy 10-NOV-67 Bordoloi and Bock Passing Parameter Values Through the START Command • You can pass a value to a program at run time as a parameter of the START command. • Use an ampersand (&) followed by a numeral in the command file; for example, &1 in place of the substitution variable. • Each time you run the command file, the START command replaces the &1 parameter in the file with the first value (called an argument) listed after a START filename command. • You can use as many ampersand-parameter variables as is needed in the program. • The arguments of the START command are separated by commas. Bordoloi and Bock Example REM ch9-6.sql – Example passing arguments SELECT emp_last_name, emp_ssn, emp_dpt_number FROM employee WHERE emp_last_name = '&1' OR emp_dpt_number = '&2'; REM end of program SQL> start ch9-6.sql Bock 1 old 3: WHERE emp_last_name = '&1' OR emp_dpt_number = '&2' new 3: WHERE emp_last_name = 'Bock' OR emp_dpt_number = '1' More . . . EMP_LAST_NAME ------------------------Bordoloi Bock Bordoloi and Bock EMP_SSN EMP_DPT_NUMBER --------- -------------999666666 1 999111111 7 Clearing the Computer Monitor Screen • If you need to clear the computer monitor screen before displaying a report (or at any other time), include the CLEAR command with its SCREEN clause at the appropriate point in your command file, using the format shown here. CLEAR SCREEN Bordoloi and Bock Formatting Aggregate Function Titles • • • • • The COMPUTE command produces a standard title of 'sum' as a label for the column that is aggregated. This also applies to the other aggregate functions; each function has its own standard title. SQL*Plus allows you to change the aggregate function title to a more meaningful title. The COMPUTE commands shown below revise those used earlier in program ch9-2.sql (run program ch92a.sql). Each employee's sum of total hours worked is labeled as 'Employee Hours,' and the report sum of total hours is labeled as 'Total Hours.' Bordoloi and Bock COMPUTE SUM LABEL 'Employee Hours' OF "Hours Worked" ON "Emp. Soc. Sec. #" COMPUTE SUM LABEL 'Total Hours' OF "Hours Worked" ON REPORT Following Figure gives pages #1 and #4 of the report Bordoloi and Bock Sun Apr 14 page Project Information Emp. Soc. Sec. # Project # Hours Worked ---------------- ---------- -----------999111111 1 31.40 2 8.50 **************** -----------Employee Hours 39.90 999222222 10 30 34.50 5.10 -----------39.60 3 42.10 -----------42.10 **************** Employee Hours 999333333 **************** Employee Hours Not for external dissemination. Bordoloi and Bock 1 --------- pages 2 and 3 would be printed here --------Sun Apr 14 page Project Information Emp. Soc. Sec. # Project # Hours Worked ---------------- ---------- ----------------------284.20 Total Hours Not for external dissemination. Bordoloi and Bock 4 Changing Column Headings • When displaying column headings, you can either use the default heading which is the column name, or you can change the heading with the COLUMN command. • The COLUMN command's HEADING clause can be used to assign meaningful column headings. • If the new heading is a single word, the heading can be typed as is done for the emp_ssn column heading of SSN. • If the heading is more than one word, the heading must be enclosed in single or double-quotes as is shown for the emp_last_name heading of "Last Name." • If you want to display a column heading on more than one line, use a vertical bar (|) where you want to begin a new line as is done for the emp_first_name column. Bordoloi and Bock Example COLUMN emp_ssn HEADING SSN; COLUMN emp_last_name HEADING "Last Name"; COLUMN emp_first_name HEADING "First|Name"; • The new headings will remain in effect until you enter different headings, reset each column's format, or exit SQL*Plus. Bordoloi and Bock