< Previous Section: utGen Package | Next Section: utRecEq Package >

utOutput Package

This package contains the following procedures and functions:

utOutput.save	Turn on the 'save' flag
utOutput.nosave	Turn off the 'save' flag
utOutput.saving	Return the 'save' flag
utOutput.extract	Pull text from the DBMS_OUTPUT buffer
utOutput.replace	Replace saved output in the DBMS_OUTPUT buffer
utOutput.nextLine	Pull the next line from the DBMS_OUTPUT buffer
utOutput.count	Count the lines in the DBMS_OUTPUT buffer

Outline of Usage

The problem with attempting to test output in PL/SQL is that there is a single DBMS_OUTPUT buffer. When your test is run, there may already be output in the buffer from other tests, or from the tested code. So what state should you leave it in once you have finished? Perhaps you want all the output created by your tested code to end up in the buffer as if it had been run normally (i.e. not from within utPLSQL), or maybe you want only the text that was in the buffer before you started to be left.

This package attempts to allow to do any of these. There is a flag in the package to determine whether text pulled from the output buffer should be saved. This is set with 'save' and 'nosave' and returned by 'saving'. Data is pulled from the buffer using 'extract', while the procedure 'replace' puts any saved data back into the output buffer.

The intent is that it is used like this:

PROCEDURE ut_my_test IS
BEGIN

  --Pull out any text already in the output buffer
  utoutput.save;
  utoutput.extract;

  --Your testing code here, with saving turned on or off as you see fit

  --Put text back in the output buffer 
  utoutput.replace;

END;

So to start with, we save any text already in the buffer. We then carry out our testing. If we want the output generated by the testing to end up back in the output buffer, we turn on saving. Finally, we put the saved text back.

Warning

In the current version of utPLSQL (2.0.9.1) use of this package is virtually impossible with utPLSQL tracing turned on. The reason for this is that this facility writes output using DBMS_OUTPUT every time an assertion is called.

Saving Output

The three routines for handling the save flag are:

PROCEDURE save;

PROCEDURE nosave;

FUNCTION saving RETURN BOOLEAN;

Quite simply, 'save' turns the flag on, 'nosave' turns it off and 'saving' returns its current value.

Extracting Output

There are 4 versions of the extract routine to get text from the output buffer:

FUNCTION extract (
   buffer_out    OUT DBMS_OUTPUT.CHARARR,
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
) RETURN INTEGER;

PROCEDURE extract (
   buffer_out    OUT DBMS_OUTPUT.CHARARR,
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
);

FUNCTION extract(
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
) RETURN INTEGER;

PROCEDURE extract(
   max_lines_in  IN INTEGER := NULL,
   save_in       IN BOOLEAN := saving
);

The function versions return the number of lines extracted from the DBMS_OUTPUT buffer. The other parameters are used as follows:

buffer_out - This is a buffer in which to put the extracted text.
max_lines_in - This is the maximum number of lines to be extracted. If NULL is passed in (the default) then all the lines are extracted.
save_in - This specifies if the extracted output should be saved. It overrides the global save flag.

Replacing Output

The replace procedure takes no parameters:

PROCEDURE replace;

It simply puts the saved text back into the DBMS_OUTPUT buffer. Note that the buffer is emptied at this point.

Checking Output Line-by-Line

The nextLine function makes it easy to check output line-by-line as it simply extracts and returns the next line of output:

FUNCTION nextLine(
  raise_exc_in BOOLEAN := TRUE, 
  save_in BOOLEAN := saving
) RETURN VARCHAR2;

The raise_exc_in flag determines if the function should throw the exception utOutput.EMPTY_OUTPUT_BUFFER when asked for the next line from an empty buffer. If no exception is thrown, NULL is returned. As with extract, the save_in flag simply overrides the global save flag setting.

Size of Output

This function simply counts the number of lines present in the output buffer:

FUNCTION count RETURN INTEGER;

Note that the output itself is left untouched.

< Previous Section: utGen Package | Next Section: utRecEq Package >