home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1996 February / PCWK0296.iso / po7_win / db / rdbms71 / dbmsotpt.sql < prev    next >
Text File  |  1994-08-07  |  9KB  |  185 lines
  1. rem 
  2. rem $Header: dbmsotpt.sql 7010400.1 94/06/04 18:23:57 cli Generic<base> $ 
  3. rem $Header: dbmsotpt.sql,v 1.9.710.1 94/02/04 11:18:46 adowning: Exp $ 
  4. rem 
  5. Rem  Copyright (c) 1991 by Oracle Corporation 
  6. Rem    NAME
  7. Rem      dbmsotpt.sql - used by sql*dba 'set serveroutput on' cmd
  8. Rem    DESCRIPTION
  9. Rem    NOTES
  10. Rem      SQL*DBA and SQL*PLUS depend on this package.
  11. Rem    RETURNS
  12. Rem 
  13. Rem    MODIFIED   (MM/DD/YY)
  14. Rem     adowning   02/02/94 -  split file into public / private binary files
  15. Rem     rkooi      04/20/93 -  merge changes from branch 1.8.312.1 
  16. Rem     rkooi      01/20/93 -  up default to 20000 
  17. Rem     rkooi      11/27/92 -  change error handling overflow case 
  18. Rem     rkooi      10/09/92 -  add some comments 
  19. Rem     rkooi      10/08/92 -  change newline to new_line 
  20. Rem     rkooi      09/29/92 -  more comments 
  21. Rem     rkooi      09/28/92 -  change some comments 
  22. Rem     rkooi      09/26/92 -  Creation 
  23.  
  24. Rem This script must be run as user SYS.
  25.  
  26. create or replace package dbms_output as
  27.  
  28.   ------------
  29.   --  OVERVIEW
  30.   --
  31.   --  These procedures accumulate information in a buffer (via "put" and
  32.   --  "put_line") so that it can be retrieved out later (via "get_line" or
  33.   --  "get_lines").  If this package is disabled then all
  34.   --  calls to this package are simply ignored.  This way, these routines
  35.   --  are only active when the client is one that is able to deal with the
  36.   --  information.  This is good for debugging, or SP's that want to want
  37.   --  to display messages or reports to sql*dba or plus (like 'describing
  38.   --  procedures', etc.).  The default buffer size is 20000 bytes.  The 
  39.   --  minimum is 2000 and the maximum is 1,000,000.
  40.  
  41.   -----------
  42.   --  EXAMPLE
  43.   --
  44.   --  A trigger might want to print out some debugging information.  To do
  45.   --  do this the trigger would do 
  46.   --    dbms_output.put_line('I got here:'||:new.col||' is the new value');
  47.   --  If the client had enabled the dbms_output package then this put_line
  48.   --  would be buffered and the client could, after executing the statement
  49.   --  (presumably some insert, delete or update that caused the trigger to
  50.   --  fire) execute
  51.   --    begin dbms_output.get_line(:buffer, :status); end;
  52.   --  to get the line of information back.  It could then display the
  53.   --  buffer on the screen.  The client would repeat calls to get_line
  54.   --  until status came back as non-zero.  For better performance, the
  55.   --  client would use calls to get_lines which can return an array of
  56.   --  lines.
  57.   --
  58.   --  SQL*DBA and SQL*PLUS, for instance, implement a 'SET SERVER OUTPUT
  59.   --  ON' command so that they know whether to make calls to get_line(s)
  60.   --  after issuing insert, update, delete or anonymous PL/SQL calls 
  61.   --  (these are the only ones that can cause triggers or stored procedures
  62.   --  to be executed).
  63.  
  64.   ------------
  65.   --  SECURITY
  66.   --
  67.   --  At the end of this script, a public synonym (dbms_output) is created
  68.   --  and execute permission on this package is granted to public.
  69.  
  70.   ----------------------------
  71.   --  PROCEDURES AND FUNCTIONS
  72.   --
  73.   procedure enable (buffer_size in integer default 20000);
  74.   --  Enable calls to put, put_line, new_line, get_line and get_lines.
  75.   --    Calls to these procedures are noops if the package has
  76.   --    not been enabled.  Set default amount of information to buffer.
  77.   --    Cleanup data buffered from any dead sessions.  Multiple calls to
  78.   --    enable are allowed.
  79.   --  Input parameters:
  80.   --    buffer_size
  81.   --      Amount of information, in bytes, to buffer.  Varchar2, number and
  82.   --      date items are stored in their internal representation.  The 
  83.   --      information is stored in the SGA. An error is raised if the 
  84.   --      buffer size is exceeded.  If there are multiple calls to enable,
  85.   --      then the buffer_size is generally the largest of the values
  86.   --      specified, and will always be >= than the smallest value
  87.   --      specified.  Currently a more accurate determination is not
  88.   --      possible.  The maximum size is 1,000,000, the minimum is 2000.
  89.  
  90.   procedure disable;
  91.   --  Disable calls to put, put_line, new_line, get_line and get_lines.
  92.   --    Also purge the buffer of any remaining information.
  93.  
  94.   procedure put(a varchar2);
  95.   procedure put(a number);
  96.   procedure put(a date);
  97.   --  Put a piece of information in the buffer.  When retrieved by
  98.   --    get_line(s), the number and date items will be formated with
  99.   --    to_char using the default formats.  If you want another format
  100.   --    then format it explicitly and use the put(<varchar2>) call.
  101.   --    Note that this routine is overloaded on the type of its argument.
  102.   --    The proper version will be used depending on argument type.
  103.   --  Input parameters:
  104.   --    a
  105.   --      Item to buffer
  106.  
  107.   procedure put_line(a varchar2);
  108.   procedure put_line(a number);
  109.   procedure put_line(a date);
  110.   --  Put a piece of information in the buffer followed by an end-of-line
  111.   --    marker.  When retrieved by get_line(s), the number and date items
  112.   --    will be formated with to_char using the default formats.  If you
  113.   --    want another format then format it explicitly and use the
  114.   --    put_line(<varchar2>) call.  Note that this routine is overloaded on
  115.   --    the type of its argument.  The proper version will be used depending
  116.   --    on argument type.  get_line(s) return "lines" as delimited by
  117.   --    "newlines".  So every call to put_line or new_line will generate a
  118.   --    line that will be returned by get_line(s).
  119.   --  Input parameters:
  120.   --    a
  121.   --      Item to buffer
  122.   --  Errors raised:
  123.   --    -20000, ORU-10027: buffer overflow, limit of <buf_limit> bytes.
  124.   --    -20000, ORU-10028: line length overflow, limit of 255 bytes per line.
  125.  
  126.   procedure new_line;
  127.   --  Put an end-of-line marker.  get_line(s) return "lines" as delimited
  128.   --    by "newlines".  So every call to put_line or new_line will generate
  129.   --    a line that will be returned by get_line(s).
  130.   --  Errors raised:
  131.   --    -20000, ORU-10027: buffer overflow, limit of <buf_limit> bytes.
  132.   --    -20000, ORU-10028: line length overflow, limit of 255 bytes per line.
  133.  
  134.   procedure get_line(line out varchar2, status out integer);
  135.   --  Get a single line back that has been buffered.  The lines are
  136.   --    delimited by calls to put_line or new_line.  The line will be
  137.   --    constructed taking all the items up to a newline, converting all 
  138.   --    the items to varchar2, and concatenating them into a single line.
  139.   --    If the client fails to retrieve all lines before the next put,
  140.   --    put_line or new_line, the non-retrieved lines will be discarded.
  141.   --    This is so if the client is interrupted while selecting back 
  142.   --    the information, there will not be junk left over which would 
  143.   --    look like it was part of the NEXT set of lines.
  144.   --  Output parameters:
  145.   --    line
  146.   --      This line will hold the line - it may be up to 255 bytes long.
  147.   --    status
  148.   --      This will be 0 upon successful completion of the call.  1 means
  149.   --      that there are no more lines.
  150.  
  151.   type chararr is table of varchar2(255) index by binary_integer;
  152.   procedure get_lines(lines out chararr, numlines in out integer);
  153.   --  Get multiple lines back that have been buffered.  The lines are
  154.   --    delimited by calls to put_line or new_line.  The line will be
  155.   --    constructed taking all the items up to a newline, converting all 
  156.   --    the items to varchar2, and concatenating them into a single line.
  157.   --    Once get_lines is executed, the client should continue to retrieve
  158.   --    all lines because the next put, put_line or new_line will first
  159.   --    purge the buffer of leftover data.  This is so if the client is
  160.   --    interrupted while selecting back the information, there will not
  161.   --    be junk left over.
  162.   --  Input parameters:
  163.   --    numlines
  164.   --      This is the maximum number of lines that the caller is prepared
  165.   --      to accept.  This procedure will not return more than this number
  166.   --      of lines.
  167.   --  Output parameters:
  168.   --    lines
  169.   --      This array will line will hold the lines - they may be up to 255
  170.   --      bytes long each.  The array is indexed beginning with 0 and
  171.   --      increases sequentially.  From a 3GL host program the array begins
  172.   --      with whatever is the convention for that language.
  173.   --    numlines
  174.   --      This will be the number of lines actually returned.  If it is
  175.   --      less than the value passed in, then there are no more lines.
  176. end;
  177. /
  178.  
  179. drop public synonym dbms_output
  180. /
  181. create public synonym dbms_output for dbms_output
  182. /
  183. grant execute on dbms_output to public
  184. /
  185.