[Appendix C] C.9 DBMS

C.9 DBMS_OUTPUT

Of all the packages in this appendix, the DBMS_OUTPUT package is the one you will find yourself using most frequently. This package allows you to display information to your session's output device in a buffer as your PL/SQL program executes. As such, it serves as just about the only easily accessible means of debugging your PL/SQL Version 2 programs. DBMS_OUTPUT is also the package you will use to generate reports from PL/SQL scripts run in SQL*Plus.

C.9.1 The DISABLE procedure

The DISABLE procedure disables all calls to the DBMS_OUTPUT package (except for ENABLE, described next). It also purges the buffer of any remaining lines of information. After you execute this command, any calls to PUT_LINE and other modules will be ignored and you will not see any output. The specification is:

PROCEDURE DBMS_OUTPUT.DISABLE;

C.9.2 The ENABLE procedure

The ENABLE procedure enables calls to the other DBMS_OUTPUT modules. If you do not first call ENABLE, then any other calls to the package modules are ignored. The specification is:

PROCEDURE DBMS_OUTPUT.ENABLE (buffer_size IN INTEGER DEFAULT 2000);

C.9.3 The GET_LINE procedure

The GET_LINE procedure retrieves one line of information from the buffer. The specification is:

PROCEDURE DBMS_OUTPUT.GET_LINE
  (line OUT VARCHAR2,
   status OUT INTEGER);

C.9.4 The GET_LINES procedure

The GET_LINES procedure retrieves multiple lines from the buffer with one call. It reads the buffer into a PL/SQL string table. The specification is:

PROCEDURE DBMS_OUTPUT.GET_LINES
  (lines OUT CHARARR,
   numlines IN OUT INTEGER);

C.9.5 The NEW_LINE procedure

The NEW_LINE procedure inserts an end-of-line marker in the buffer. Use NEW_LINE after one or more calls to PUT in order to terminate those entries in the buffer with a newline marker. The specification is:

PROCEDURE DBMS_OUTPUT.NEW_LINE;

C.9.6 The PUT procedure

The PUT procedure puts information into the buffer, but does not append a newline marker into the buffer. Use PUT if you want to place information in the buffer (usually with more than one call to PUT), but not also automatically issue a newline marker. The specifications are:

PROCEDURE DBMS_OUTPUT.PUT (A VARCHAR2);
PROCEDURE DBMS_OUTPUT.PUT (A NUMBER);
PROCEDURE DBMS_OUTPUT.PUT (A DATE);

C.9.7 The PUT_LINE procedure

The PUT_LINE procedure puts information into the buffer and then appends a newline marker into the buffer. The specifications are:

PROCEDURE DBMS_OUTPUT.PUT_LINE (A VARCHAR2);
PROCEDURE DBMS_OUTPUT.PUT_LINE (A NUMBER);
PROCEDURE DBMS_OUTPUT.PUT_LINE (A DATE);