DBE_OUTPUT

When DBE_OUTPUT.PUT_LINE is used to print the result obtained by the DBE_FILE.READ_LINE_NCHAR API, ensure that the UTF-8 character set encoding can be converted to the current database character set encoding. If the preceding conditions are met, the result can be properly output. DBE_OUTPUT.PRINT_LINE does not support this function.

API Description

Table 1 provides all APIs supported by the DBE_OUTPUT package.

**Table 1** DBE_OUTPUT
API	Description
DBE_OUTPUT.PRINT_LINE	Outputs the specified text with newline characters.
DBE_OUTPUT.PRINT	Outputs the specified text without newline characters.
DBE_OUTPUT.SET_BUFFER_SIZE	Sets the size of the output buffer. If the size is not specified, the buffer can contain a maximum of 20000 bytes. If the size is set to a value less than or equal to 2000 bytes, the buffer can contain a maximum of 2000 bytes.
DBE_OUTPUT.DISABLE	Disables the calling of PUT, PUT_LINE, NEW_LINE, GET_LINE and GET_LINES, and clears the output buffer.
DBE_OUTPUT.ENABLE	Enables the buffer, allows the calling of PUT, PUT_LINE, NEW_LINE, GET_LINE, and GET_LINES, and sets the buffer size.
DBE_OUTPUT.GET_LINE	Obtains a line of data from the buffer with a newline character as the boundary. The obtained data is not output to the client.
DBE_OUTPUT.GET_LINES	Obtains the character string of a specified number of lines in the buffer as a VARCHAR array. The obtained content is cleared from the buffer and is not output to the client.
DBE_OUTPUT.NEW_LINE	Places a line at the end of the buffer, places an end-of-line marker, and leaves a new line empty.
DBE_OUTPUT.PUT	Places an input string in the buffer without a newline character at the end. After the anonymous block is executed, the line ending with the newline character is displayed.
DBE_OUTPUT.PUT_LINE	Places an input string in the buffer with a newline character at the end. After the anonymous block is executed, the line ending with the newline character is displayed.

DBE_OUTPUT.PRINT_LINE

Outputs the specified text and adds a newline character. The function prototype of DBE_OUTPUT.PRINT_LINE is as follows:

      
           DBE_OUTPUT.PRINT_LINE (
format IN VARCHAR2);

**Table 2** DBE_OUTPUT.PRINT_LINE parameters
Parameter	Description
format	Output text.

DBE_OUTPUT.PRINT

Outputs the specified text without adding a newline character. The function prototype of DBE_OUTPUT.PRINT is as follows:

      
           DBE_OUTPUT.PRINT (
format IN VARCHAR2);

**Table 3** DBE_OUTPUT.PRINT parameters
Parameter	Description
format	Output text.

DBE_OUTPUT.SET_BUFFER_SIZE

The stored procedure SET_BUFFER_SIZE sets the output buffer size. If the size is not specified, it contains a maximum of 20000 bytes. The function prototype of DBE_OUTPUT.SET_BUFFER_SIZE is as follows:

      
           DBE_OUTPUT.SET_BUFFER_SIZE (
size IN INTEGER default 20000);

**Table 4** DBE_OUTPUT.SET_BUFFER_SIZE parameters
Parameter	Description
size	Sets the output buffer size.

DBE_OUTPUT.DISABLE
Disables the calling of PUT, PUT_LINE, NEW_LINE, GET_LINE, and GET_LINES, and clears the output buffer. The prototype of the DBE_OUTPUT.DISABLE function is as follows:
1

DBE_OUTPUT.DISABLE;

DBE_OUTPUT.ENABLE

Enables the buffer, allows the calling of PUT, PUT_LINE, NEW_LINE, GET_LINE, and GET_LINES, and sets the buffer size. If the buffer size is not specified, 20,000 bytes are allowed by default. The prototype of the DBE_OUTPUT.ENABLE function is as follows:

      
           DBE_OUTPUT.ENABLE (
    buffer_size IN INTEGER DEFAULT 20000
);

**Table 5** DBE_OUTPUT.ENABLE parameters
Parameter	Description
buffer_size	Upper limit of the buffer size, in bytes. If buffer_size is set to NULL, the default value (20000 bytes) is used.

DBE_OUTPUT.GET_LINE

The stored procedure GET_LINE obtains a line of data from the buffer with a newline character as the boundary. The obtained data is not output to the client. The prototype of the DBE_OUTPUT.GET_LINE function is as follows:

     
          DBE_OUTPUT.GET_LINE (
    line   OUT VARCHAR2,
    status OUT INTEGER
);

**Table 6** DBE_OUTPUT.GET_LINE parameters
Parameter	Description
line	Indicates the obtained character string.
status	Specifies whether the calling is normal. If a character string is obtained, the value is 0. Otherwise, the value is 1.

DBE_OUTPUT.GET_LINES

The stored procedure GET_LINES obtains the character string of a specified number of lines in the buffer as a VARCHAR array. The obtained content is cleared from the buffer and is not output to the client. The prototype of the DBE_OUTPUT.GET_LINES function is as follows:

     
          DBE_OUTPUT.GET_LINES (
    lines    OUT   VARCHAR[],
    numlines IN OUT INTEGER
);

**Table 7** DBE_OUTPUT.GET_LINES parameters
Parameter	Description
lines	Outputs an array of multi-line strings read from the buffer.
numlines	Inputs the number of lines to be retrieved from the buffer. The output value is the number of lines actually retrieved. If the output value is less than the input value, there are no more lines in the buffer.

DBE_OUTPUT.NEW_LINE
The stored procedure NEW_LINE places a line at the end of the buffer, places an end-of-line marker, and leaves a new line empty. The prototype of the DBE_OUTPUT.NEW_LINE function is as follows:
1

DBE_OUTPUT.NEW_LINE;

DBE_OUTPUT.PUT

The stored procedure PUT places an input string in the buffer without a newline character at the end. When the stored procedure ends, the line ending with the newline character is displayed. The prototype of the DBE_OUTPUT.PUT function is as follows:

     
          DBE_OUTPUT.PUT (
    item IN VARCHAR2);

**Table 8** DBE_OUTPUT.PUT parameters
Parameter	Description
item	Character or character string to be placed in the buffer.

DBE_OUTPUT.PUT_LINE

The stored procedure PUT_LINE places an input string in the buffer with a newline character at the end. When the stored procedure ends, the line ending with the newline character is displayed. The prototype of the DBE_OUTPUT.PUT_LINE function is as follows:

     
          DBE_OUTPUT.PUT_LINE (
    item IN VARCHAR2);

**Table 9** DBE_OUTPUT.PUT_LINE parameters
Parameter	Description
item	Character or character string to be placed in the buffer.

Examples

    
     
       
       
         BEGIN
    DBE_OUTPUT.SET_BUFFER_SIZE(50);
    DBE_OUTPUT.PRINT('hello, ');
    DBE_OUTPUT.PRINT_LINE('database!');-- Output "hello, database!"
END;
/
-- The expected result is as follows:
hello, database!
ANONYMOUS BLOCK EXECUTE

-- Test DISABLE: Disable the calling of PUT, PUT_LINE, NEW_LINE, GET_LINE, and GET_LINES. The PUT_LINE has no output.
BEGIN
 dbe_output.disable();
        dbe_output.put_line('1');
END; 
/
-- The expected result is as follows:
ANONYMOUS BLOCK EXECUTE

-- Test ENABLE: Enable the calling of PUT, PUT_LINE, NEW_LINE, GET_LINE, and GET_LINES. The output of PUT_LINE is 1.
BEGIN
 dbe_output.enable();
        dbe_output.put_line('1');
END; 
/
-- The expected result is as follows:
1
ANONYMOUS BLOCK EXECUTE

-- Test PUT: Place the input character string a in the buffer without adding a newline character at the end. a has no output.
BEGIN
 dbe_output.enable();
 dbe_output.put('a');
END; 
/
-- The expected result is as follows:
ANONYMOUS BLOCK EXECUTE

-- Test NEW_LINE. Add a new line. The output is a.
BEGIN
 dbe_output.enable();
 dbe_output.put('a');
        dbe_output.new_line;
END; 
/
-- The expected result is as follows:
a
ANONYMOUS BLOCK EXECUTE

-- Test GET_LINE: Obtain buffer data and save the data to variables and use PUT_LINE to output the data.
DECLARE
 line VARCHAR(32672);
 status INTEGER := 0;
BEGIN
 dbe_output.put_line('hello');
 dbe_output.get_line(line, status);
 dbe_output.put_line('-----------');
 dbe_output.put_line(line);
 dbe_output.put_line(status);
END; 
/
-- The expected result is as follows:
-----------
hello
0
ANONYMOUS BLOCK EXECUTE

-- Test get_lines: Obtain multiple lines of content in the buffer and use PUT_LINE to output the content.
DECLARE
    lines varchar[];
    linenum integer;
BEGIN
    dbe_output.put_line('line 1');
    dbe_output.put_line('line 2');
    dbe_output.put_line('line 3');
    linenum := 100;
    dbe_output.get_lines(lines, linenum);
    dbe_output.put_line('num: ' || linenum);
    FOR i IN 1 .. linenum LOOP
        dbe_output.put_line(lines[i]);
    END LOOP;
END;
/
-- The expected result is as follows:
num: 3
line 1
line 2
line 3
ANONYMOUS BLOCK EXECUTE

        

      

    
   

When the character encoding type server_encoding of the server is not UTF-8, if the character encoding in the data is valid UTF-8 encoding, when processing the character encoding, the DBE_OUTPUT.PUTLINE and DBE_OUTPUT.PUT functions convert the character encoding into the server_encoding encoding format based on the UTF8 encoding logic before performing subsequent operations, as a result, the return values of the functions may not meet the expectation or an error may be reported. After the GUC parameter enable_convert_illegal_char is enabled, the DBE_OUTPUT.PUTLINE and DBE_OUTPUT.PUT functions process such codes in the same way as when the parameter is disabled. Special characters are not output as placeholders, therefore, you are advised not to use the DBE_OUTPUT.PUTLINE and DBE_OUTPUT.PUT functions for data containing special characters.

Parent topic: Secondary Encapsulation APIs (Recommended)

Previous topic: DBE_MATCH

Next topic: DBE_PROFILER