/* If there is a second part, display that. */ IF part2 IS NOT NULL THEN DBMS_OUTPUT.PUT_LINE ('Name: ' || part2); END IF; ELSE /* No first part of name. Just display second part. */ DBMS_OUTPUT.PUT_LINE (object_type (part1_type) || ': ' || part2); END IF; /* Display the database link if it is present. */ IF dblink IS NOT NULL THEN DBMS_OUTPUT.PUT_LINE ('Database Link:' || dblink); END IF; END IF; END; / 10.1.2.18 The DBMS_UTILITY.NAME_TOKENIZE procedure This procedure calls the PL/SQL parser to parse the given name that is in the following format, a [ . b [. c]] [@dblink ] where dblink is the name of a database link. Here's the header for the procedure: PROCEDURE DBMS_UTILITY.NAME_TOKENIZE (name IN VARCHAR2, a OUT VARCHAR2, b OUT VARCHAR2, c OUT VARCHAR2, dblink OUT VARCHAR2, nextpos OUT BINARY_INTEGER); Parameters are summarized in the following table. Parameter Description name Name being parsed a, b, c Components of name, if present dblink Name of database link nextpos Position where next token starts NAME_TOKENIZE follows these rules: • Strips off all double quotes • Converts to uppercase if there are no quotes • [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 491 Ignores any inline comments • Does no semantic analysis • Leaves any missing values as NULL 10.1.2.19 The DBMS_UTILITY.PORT_STRING function The PORT_STRING function returns a string that uniquely identifies the version of Oracle Server and the platform or operating system of the current database instance. The specification for this function follows: FUNCTION DBMS_UTILITY.PORT_STRING RETURN VARCHAR2; Running the PORT_STRING function in Oracle8 on Windows NT, for example, returns the following string: IBMPC/WINNT−8.0.0 The maximum length of the string returned by this function is operating system−specific. 10.1.2.20 The DBMS_UTILITY.TABLE_TO_COMMA procedure The TABLE_TO_COMMA procedure converts a PL/SQL table into a comma−delimited list. Here's the header for this procedure: PROCEDURE DBMS_UTILITY.TABLE_TO_COMMA (tab IN UNCL_ARRAY, tablen OUT BINARY_INTEGER, list OUT VARCHAR2); Parameters are summarized in the following table. Parameter Description tab A PL/SQL table declared using the package's TABLE type tablen The number of rows defined in the PL/SQL table (assumed to be densely packed, all rows contiguously defined) list The string that will contain a comma−delimited list of the names for the PL/SQL table 9.2 UTL_RAW: Manipulating Raw Data 10.2 DBMS_DESCRIBE: Describing PL/SQL Program Headers Copyright (c) 2000 O'Reilly & Associates. All rights reserved. [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 492 Chapter 10 Miscellaneous Packages 10.2 DBMS_DESCRIBE: Describing PL/SQL Program Headers The DBMS_DESCRIBE package contains a single procedure used to describe the arguments of a stored PL/SQL object. 10.2.1 Getting Started with DBMS_DESCRIBE The DBMS_DESCRIBE package is created when the Oracle database is installed. The dbmsdesc.sql script (found in the built−in packages source code directory, as described in Chapter 1) contains the source code for this package's specification. This script is called by catproc.sql, which is normally run immediately after database creation. The script creates the public synonym DMS_DESCRIBE for the package and grants EXECUTE privilege on the package to public. All Oracle users can reference and make use of this package. 10.2.1.1 DBMS_DESCRIBE program Table 10.2 summarizes the single procedure available through DBMS_DESCRIBE. Table 10.2: DBMS_DESCRIBE Program Name Description Use in SQL DESCRIBE_PROCEDURE Describes the specified PL/SQL object by returning all of the information for the object in a set of scalar and PL/SQL table parameters. No 10.2.1.2 DBMS_DESCRIBE nonprogram elements In addition to the DESCRIBE_PROCEDURE procedure, DBMS_DESCRIBE defines two PL/SQL table types you can use when calling or describing a PL/SQL object. These are described in the following table. Name/Type Description DBMS_DESCRIBE.VARCHAR2_TABLE Table TYPE of 30−character strings; used to declare PL/SQL tables to hold string information returned by DBMS_DESCRIBE.DESCRIBE_PROCEDURE. DBMS_DESCRIBE.NUMBER_TABLE Table TYPE of numbers; used to declare PL/SQL tables to hold numeric information returned by DBMS_DESCRIBE.DESCRIBE_PROCEDURE. The two table TYPES are defined as follows: TYPE DBMS_DESCRIBE.VARCHAR2_TABLE IS 493 TABLE OF VARCHAR2(30) INDEX BY BINARY_INTEGER; TYPE DBMS_DESCRIBE.NUMBER_TABLE IS TABLE OF NUMBER INDEX BY BINARY_INTEGER; 10.2.1.3 The DBMS_DESCRIBE.DESCRIBE_PROCEDURE procedure The DESCRIBE_PROCEDURE procedure describes the specified PL/SQL object (currently only procedures and functions are supported). It returns information about the parameters of the program in a series of PL/SQL tables. The header for this procedure follows: PROCEDURE DBMS_DESCRIBE.DESCRIBE_PROCEDURE (object_name IN VARCHAR2 ,reserved1 IN VARCHAR2 ,reserved2 IN VARCHAR2 ,overload OUT NUMBER_TABLE ,position OUT NUMBER_TABLE ,level OUT NUMBER_TABLE ,argument_name OUT VARCHAR2_TABLE ,datatype OUT NUMBER_TABLE ,default_value OUT NUMBER_TABLE ,in_out OUT NUMBER_TABLE ,length OUT NUMBER_TABLE ,precision OUT NUMBER_TABLE ,scale OUT NUMBER_TABLE ,radix OUT NUMBER_TABLE ,spare OUT NUMBER_TABLE); Paremeters are summarized in the following table. Parameter Description object_name The name of the program being described. The form of the name is [[part1.]part2.]part3. The syntax for this name follows the rules for identifiers in SQL. This name can be a synonym and may also contain delimited identifiers (double−quoted strings). This parameter is required and may not be NULL. The total length of the name is limited to 197 bytes. reserved1 Reserved for future use. Must be set to NULL or an empty string, as in ``. reserved2 Reserved for future use. Must be set to NULL or an empty string, as in ``. overload An array of integers containing the unique number assigned to the program "signature." If the program is overloaded, the value in this array will indicate the specific overloading to which the argument belongs. position An array of integers showing the position of the argument in the parameter list. The first argument is always in position 1. A value of 0 indicates that the "argument" is actually the RETURN value of the function. level An array of integers describing the level of the argument. This is relevant when describing a procedure with a composite datatype, such as a record or PL/SQL table. For specific level values, see "Section 10.2.2.2, "The DESCRIBE level"" later in this chapter. argument_name An array of strings containing the names of the arguments. This entry is NULL if the argument is the RETURN value of a function. datatype An array of integers describing the datatypes of the arguments. For specific datatype values, see the next table. default_value An array of integers indicating whether the argument has a default value. If 1, then a default value is present; if 0, then no default value. in_out An array of integers indicating the parameter mode: [Appendix A] What's on the Companion Disk? 10.2.1 Getting Started with DBMS_DESCRIBE 494 0 = IN mode 1 = OUT mode 2 = IN OUT mode length An array of integers indicating the length of the argument. For string types, the length is the "N" in CHAR(N) or VARCHAR2(N). Currently, this value represents the number of bytes (not characters) on the server−side. (For a multibyte datatype, this may be different from the number of bytes on the client side.) precision An array of integers containing the precisions of the arguments. Relevant only for numeric arguments. scale An array of integers containing the scales of the arguments. Relevant only for numeric arguments. radix An array of integers containing the radixes of the arguments. Relevant only for numeric arguments. spare Reserved for future usage (but you still have to declare a PL/SQl table to hold it!). The values for parameter datatypes are listed in the following table. Datatype Number VARCHAR2 1 NVARCHAR2 1 NUMBER 2 INTEGER 2 BINARY_INTEGER 3 PLS_INTEGER 3 LONG 8 ROWID 11 DATE 12 RAW 23 LONGRAW 24 CHAR 96 NCHAR 96 MLSLABEL 106 CLOB 112 NCLOB 112 BLOB 113 BFILE 114 Object type (Oracle8) 121 Nested table type (Oracle8) 122 Variable array (Oracle8) 123 Record type 250 [Appendix A] What's on the Companion Disk? 10.2.1 Getting Started with DBMS_DESCRIBE 495 . 96 MLSLABEL 106 CLOB 112 NCLOB 112 BLOB 113 BFILE 114 Object type (Oracle8 ) 121 Nested table type (Oracle8 ) 122 Variable array (Oracle8 ) 123 Record type 250 [Appendix A] What's on the Companion. with DBMS_DESCRIBE The DBMS_DESCRIBE package is created when the Oracle database is installed. The dbmsdesc.sql script (found in the built−in packages source code directory, as described in Chapter. DBMS_UTILITY.PORT_STRING function The PORT_STRING function returns a string that uniquely identifies the version of Oracle Server and the platform or operating system of the current database instance. The specification