home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1996 February / PCWK0296.iso / po7_win / db / rdbms71 / dbmsdesc.sql < prev    next >
Text File  |  1994-08-07  |  10KB  |  244 lines
  1. rem 
  2. rem $Header: dbmsdesc.sql 7010300.1 94/02/24 18:24:41 snataraj Generic<base> $ 
  3. rem 
  4. Rem  Copyright (c) 1991 by Oracle Corporation 
  5. Rem    NAME
  6. Rem      dbmsdesc.sql - describe stored procedures and functions
  7. Rem    DESCRIPTION
  8. Rem      Given a stored procedure, return a description of the 
  9. Rem      arguments required to call that procedure.
  10. Rem    RETURNS
  11. Rem 
  12. Rem    NOTES
  13. Rem      The procedural option is needed to use this facility.
  14. Rem      
  15. Rem    MODIFIED   (MM/DD/YY)
  16. Rem     adowning   02/02/94 -  split file into public / private binary files
  17. Rem     rkooi      11/26/92 -  change some comment 
  18. Rem     rkooi      11/21/92 -  check for top level functions 
  19. Rem     rkooi      11/17/92 -  get rid of database name 
  20. Rem     rkooi      11/12/92 -  change name res stuff 
  21. Rem     mmoore     11/01/92 -  Creation 
  22.  
  23. REM ********************************************************************
  24. REM THIS PACKAGE MUST NOT BE MODIFIED BY THE CUSTOMER.  DOING SO
  25. REM COULD CAUSE INTERNAL ERRORS AND SECURITY VIOLATIONS IN THE
  26. REM RDBMS.  SPECIFICALLY, THE PSD* ROUTINES MUST NOT BE CALLED
  27. REM DIRECTLY BY ANY CLIENT AND MUST REMAIN PRIVATE TO THE PACKAGE BODY.
  28. REM ********************************************************************
  29. create or replace package dbms_describe is
  30.  
  31.   ------------
  32.   --  OVERVIEW
  33.   --
  34.   -- This package is used to describe the arguments of a stored 
  35.   -- procedure.  The client specifies an object name and describe returns 
  36.   -- a set of indexed tables with the results.  Full name 
  37.   -- translation is performed and security checking is also
  38.   -- checked on the final object.
  39.  
  40.   --------
  41.   --  USES
  42.   --
  43.   -- The primary client of this package is ODESSP (Oracle Call 
  44.   -- Interface Describe PRocedure).
  45.  
  46.   ---------------
  47.   --  LIMITATIONS
  48.   --
  49.   --  Currently describes of remote objects are not supported.  It is
  50.   --  intended to support this at some point in the future.
  51.   -- 
  52.   --  Currently descibes of all procedures/functions within a package
  53.   --  is not supported. We could add a 'describe_package' procedure
  54.   --  that returns the names of all procedures/functions for the named
  55.   --  package and then the client could call 'describe_procedure' for
  56.   --  those in which it has an interest.
  57.  
  58.   ------------
  59.   --  SECURITY
  60.   --
  61.   -- Describe is available to PUBLIC and performs it's own
  62.   -- security checking based on the object being described.
  63.  
  64.   -----------------------
  65.   --  TYPES AND CONSTANTS
  66.   --
  67.   type varchar2_table is table of varchar2(30) index by binary_integer;
  68.   -- Indexed table type which is used to return the argument names.
  69.  
  70.   type number_table   is table of number       index by binary_integer;
  71.   -- Indexed table type which is used to return various argument fields.
  72.  
  73.   ------------
  74.   --  EXAMPLES
  75.   --
  76.   --  External service interface
  77.   ------------------------------
  78.   --
  79.   -- The ODESSP OCI call may be used to call this routine from a user 
  80.   -- program.  (See the Oracle Call Interface guide for a description)  
  81.   -- Also, this routine could be called from other stored procedures 
  82.   -- using the varchar2_table and number_table types.
  83.   --
  84.   --   EXAMPLE :
  85.   --
  86.   --   Client provides -
  87.   --
  88.   --   object_name - SCOTT.ACCOUNTING.ACCOUNT_UPDATE
  89.   --   total_elements - 100
  90.   --   
  91.   --   ACCOUNT_UPDATE is an overloaded function in package ACCOUNTING
  92.   --   with specification :
  93.   --
  94.   --     type number_table is table of number index by binary_integer
  95.   --     table account (account_no number, person_id number,
  96.   --                    balance number(7,2))
  97.   --     table person  (person_id number(4), person_nm varchar2(10))
  98.   --
  99.   --     function ACCOUNT_UPDATE (account number, 
  100.   --       person person%rowtype, amounts number_table,
  101.   --       trans_date date) return account.balance%type;
  102.   --
  103.   --     function ACCOUNT_UPDATE (account number, 
  104.   --       person person%rowtype, amounts number_table,
  105.   --       trans_no number) return account.balance%type;
  106.   --
  107.   --
  108.   --   Values returned -
  109.   --
  110.   --   overload position   argument  level  datatype length prec scale rad
  111.   --   -------------------------------------------------------------------
  112.   --          1        0                0   NUMBER      7    2     0    0
  113.   --          1        1   ACCOUNT      0   NUMBER     22    0     0    0
  114.   --          1        2   PERSON       0   RECORD
  115.   --          1        2     PERSON_ID  1   NUMBER      4    0     0    0
  116.   --          1        2     PERSON_NM  1   VARCHAR2   10
  117.   --          1        3   AMOUNTS      0   TABLE
  118.   --          1        3                1   NUMBER     22    0     0    0
  119.   --          1        4   TRANS_NO     0   NUMBER     22    0     0    0
  120.   --
  121.   --          0        0                0   NUMBER      7    2     0    0
  122.   --          0        1   ACCOUNT      0   NUMBER     22    0     0    0
  123.   --          0        2   PERSON       0   RECORD
  124.   --          0        2    PERSON_ID   1   NUMBER      4    0     0    0
  125.   --          0        2    PERSON_NM   1   VARCHAR2   10
  126.   --          0        3   AMOUNTS      0   TABLE
  127.   --          0        3                1   NUMBER     22    0     0    0
  128.   --          0        4   TRANS_DATE   0   DATE
  129.   --
  130.  
  131.   ----------------------------
  132.   --  PROCEDURES AND FUNCTIONS
  133.   --
  134.   procedure describe_procedure (object_name in varchar2,
  135.     reserved1 in varchar2, reserved2 in varchar2,
  136.     overload out number_table, position out number_table,
  137.     level out number_table, argument_name out varchar2_table,
  138.     datatype out number_table, default_value out number_table,
  139.     in_out out number_table, length out number_table,
  140.     precision out number_table, scale out number_table,
  141.     radix out number_table, spare out number_table);
  142.   --  
  143.   --  Describe pl/sql object with the given name.  Returns the arguments
  144.   --    ordered by overload, position.  The name resolution follows the
  145.   --    rules for SQL.  Top level procedures and functions, as well as
  146.   --    packaged procedures and functions, may be described.  Procedures
  147.   --    and functions in package STANDARD must be prefixed by "STANDARD"
  148.   --    (e.g., 'standard.greatest' will describe function "GREATEST" in
  149.   --    package "STANDARD").
  150.   --  Input parameters:
  151.   --    object_name 
  152.   --      The name of the procedure being described. The form is
  153.   --        [[part1.]part2.]part3[@dblink]
  154.   --      The syntax follows the rules for identifiers in SQL.  The name may
  155.   --      be a synonym and may contain delimited identifiers (double quoted
  156.   --      strings). This parameter is required and may not be null.
  157.   --      The total length of the name is limited to 197 bytes.
  158.   --    reserved1, reserved2
  159.   --      Reserved for future use.  Must be set to null or empty string.
  160.   --  Output parameters:
  161.   --    overload
  162.   --       A unique number assigned to the procedure signature.  If a 
  163.   --       procedure is overloaded, this field will hold a different
  164.   --       value for each version of the procedure.
  165.   --    position
  166.   --       Position of the argument in the parameter list beginning with 1.
  167.   --       Position 0 indicates a function return value.
  168.   --    level
  169.   --       If the argument is a composite type (like record), this
  170.   --       parameter returns the level of datatype.  See example
  171.   --       section for a usage example.
  172.   --    argument_name
  173.   --       The name of the argument.
  174.   --    datatype
  175.   --       Oracle datatype of the parameter. These are:
  176.   --           0 - This row is a placeholder for a procedure with
  177.   --               no arguments.
  178.   --           1 - VARCHAR2
  179.   --           2 - NUMBER
  180.   --           3 - NATIVE INTEGER (for PL/SQL's BINARY_INTEGER)
  181.   --           8 - LONG
  182.   --          11 - ROWID
  183.   --          12 - DATE
  184.   --          23 - RAW
  185.   --          24 - LONG RAW
  186.   --          96 - CHAR (ANSI FIXED CHAR)
  187.   --         106 - MLSLABEL
  188.   --         250 - PL/SQL RECORD (see "Notes:" below)
  189.   --         251 - PL/SQL TABLE
  190.   --         252 - PL/SQL BOOLEAN (see "Notes:" below)
  191.   --    default_value
  192.   --       1 if the parameter has a default value.  0, otherwise.
  193.   --    in_out
  194.   --       0 = IN param, 1 = OUT param, 2 = IN/OUT param
  195.   --    length
  196.   --       The data length of the argument.  For string types, length is
  197.   --       the "N" in CHAR/VARCHAR2(N);  N is today bytes ON THE SERVER
  198.   --       SIDE (for multi-byte it may differ on the client side) and 
  199.   --       may someday be the number of characters rather than bytes.
  200.   --    precision
  201.   --       Precision of the argument (if the datatype is number).
  202.   --    scale
  203.   --       Scale of the argument (if the datatype is number).
  204.   --    radix
  205.   --       Radix of the argument (if the datatype is number).
  206.   --    spare
  207.   --       Reserved for future functionality.
  208.   --  Exceptions:
  209.   --    ORA-20000 - A package was specified.  Can only specify top-level
  210.   --      procedure/functions or procedures/functions within a package.
  211.   --    ORA-20001 - The procedure/function does not exist within the package.
  212.   --    ORA-20002 - The object is remote.  This procedure cannot currently 
  213.   --      describe remote objects.
  214.   --    ORA-20003 - The object is invalid.  Invalid objects cannot be
  215.   --      described.
  216.   --    ORA-20004 - A syntax error in the specification of the object's name.
  217.   --  Notes:
  218.   --    There is currently no way from a 3gl to directly bind to an
  219.   --    argument of type 'record' or 'boolean'.  For booleans, there are
  220.   --    the following work-arounds.  Assume function F returns a boolean, G
  221.   --    is a procedure with one IN boolean argument, and H is a procedure
  222.   --    which has one OUT boolean argument. 
  223.   --    Then you can execute these functions, binding in DTYINTs (native
  224.   --    integer) as follows, where 0=>FALSE and 1=>TRUE:
  225.   --
  226.   --      begin :dtyint_bind_var := to_number(f); end;
  227.   --
  228.   --      begin g(to_boolean(:dtyint_bind_var)); end;
  229.   -- 
  230.   --      declare b boolean; begin h(b); if b then :dtyint_bind_var := 1;
  231.   --        else :dtyint_bind_var := 0; end if; end;
  232.   --
  233.   --    Access to procedures with arguments of type 'record' would require 
  234.   --    writting a wrapper similar to that in the 3rd example above (see
  235.   --    funciton H).
  236. end;
  237. /
  238. drop public synonym dbms_describe
  239. /
  240. create public synonym dbms_describe for sys.dbms_describe
  241. /
  242. grant execute on dbms_describe to public
  243. /
  244.