Oracle Built−in Packages- P100 doc

10.1.2.13 The DBMS_UTILITY.GET_PARAMETER_VALUE function Available first in PL/SQL8, this function allows you to retrieve the value of a database initialization parameter (set in the INIT.ORA initialization file). Here's the header: FUNCTION DBMS_UTILITY.GET_PARAMETER_VALUE (parnam IN VARCHAR2 ,intval IN OUT BINARY_INTEGER ,strval IN OUT VARCHAR2) RETURN BINARY_INTEGER; The value returned by the function is either of the following: 0 Indicating a numeric or Boolean parameter value 1 Indicating a string parameter value Parameters are summarized in the following table. Parameter Description parnam The name of the initialization parameter (case−insensitive). intval The parameter value if that value is numeric. If the value is a Boolean (i.e., the value in the initialization file is TRUE or FALSE), then intval is set to 0 for FALSE and 1 for TRUE. If the value is a string, then this argument contains the length of that string value. strval The parameter value if that value is a string. Otherwise it is NULL. Long desired by Oracle developers, the GET_PARAMETER_VALUE function now allows you to get critical information about the current database instance, including the default date format and lots of information about the way shared memory is configured. And you don't have to use UTL_FILE to read the initialization file. (Chances are your DBA would not enable the database directory holding this file for UTL_FILE access anyway!). Note that if you have more than one entry for the same parameter (certainly a possibility with a parameter such as UTL_FILE_DIR), then this built−in will retrieve only the value associated with the first occurrence of the parameter. You will probably want to build a wrapper around GET_PARAMETER_VALUE to make it easier to retrieve and interpret the results. Why? Whenever you call this built−in function, you must declare two variables to retrieve the OUT arguments. You must then interpret the results. Rather than write all this code and have to remember all these rules, you can build it into a package once and then simply call the appropriate program as needed. A prototype of such a package is shown later in this section. My package specification contains these three sections: • Generic interfaces to the built−in, by datatype: return a string value, integer value, or Boolean value. You have to know which type of value should be returned for the name you provide. • Functions returning the values of specific named (by the name of the function) entries in the initialization file. You should expand this section to make it easy to retrieve values for parameters you work with. • A display procedure to show the different values returned by the built−in for a particular parameter. [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 486 /* Filename on companion disk: dbparm.spp */ CREATE OR REPLACE PACKAGE dbparm IS /* Generic (by datatype) interfaces to built−in. */ FUNCTION strval (nm IN VARCHAR2) RETURN VARCHAR2; FUNCTION intval (nm IN VARCHAR2) RETURN INTEGER; FUNCTION boolval (nm IN VARCHAR2) RETURN BOOLEAN; /* Encapsulation for specific parameter retrieval */ FUNCTION nls_date_format RETURN VARCHAR2; FUNCTION utl_file_dir RETURN VARCHAR2; FUNCTION db_block_buffers RETURN INTEGER; PROCEDURE showval (nm IN VARCHAR2); END; / Rather than show the entire package body (also found in dbparm.spp), I will show you the two levels of encapsulation around DBMS_UTILITY.GET_PARAMETER_VALUE found in the package. You can then apply that technique to other parameters of interest. Here is the dbparm.intval function. It calls the built−in procedure and then returns the integer value. You might want to enhance this procedure to check the datatype of the parameter and only return a value if it is in fact a numeric (or Boolean) type. FUNCTION intval (nm IN VARCHAR2) RETURN INTEGER IS valtype PLS_INTEGER; ival PLS_INTEGER; sval VARCHAR2(2000); BEGIN valtype := DBMS_UTILITY.GET_PARAMETER_VALUE (nm, ival, sval); RETURN ival; END; Now I build my dbparm.db_block_buffers package on top of that one as follows: FUNCTION db_block_buffers RETURN INTEGER IS BEGIN RETURN intval ('db_block_buffers'); END; 10.1.2.14 The DBMS_UTILITY.GET_TIME function This function returns the number of 100ths of seconds that have elapsed from an arbitrary time. The header for the function follows: FUNCTION DBMS_UTILITY.GET_TIME RETURN NUMBER; You are probably wondering what this "arbitrary time" is and why I don't tell you about what that starting point is. Two reasons: I don't know and it doesn't matter. You should not use GET_TIME to establish the current time, but only to calculate the elapsed time between two events. The following example calculates the number of 100ths of elapsed seconds since the calc_totals procedure was executed: DECLARE time_before BINARY_INTEGER; time_after BINARY_INTEGER; BEGIN [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 487 time_before := DBMS_UTILITY.GET_TIME; calc_totals; time_after := DBMS_UTILITY.GET_TIME; DBMS_OUTPUT.PUT_LINE (time_after − time_before); END; Without GET_TIME, Oracle functions can only record and provide elapsed time in second intervals, which is a very coarse granularity in today's world of computing. With GET_TIME, you can get a much finer understanding of the processing times of lines in your program. Notice that in my anonymous block I had to declare two local variables, make my calls to GET_TIME, and then compute the difference. I will probably need to perform those actions over and over again in my programs. I might even want to perform timings that cross product lines (e.g., start my timing in a form and then check elapsed time from inside a report module). To make it easier to use GET_TIME in these various ways, I built a package called sptimer ("stored package timer" mechanism), which you can find in the sptimer.sps and sptimer.spb files on the companion disk.[2] [2] PL/Vision also offers the PLVtmr package, a much more fully−realized timing utility. See the Preface ("About PL/Vision") for more information. 10.1.2.15 The DBMS_UTILITY.IS_PARALLEL_SERVER function This function helps determine whether the database is running in parallel server mode. The specification follows: FUNCTION DBMS_UTILITY.IS_PARALLEL_SERVER RETURN BOOLEAN; The function returns TRUE if the database is running in parallel server mode; otherwise, it returns FALSE. 10.1.2.16 The DBMS_UTILITY.MAKE_DATA_BLOCK_ADDRESS function Use this function to obtain a valid data block address from a file number and block number. The header follows: FUNCTION DBMS_UTILITY.MAKE_DATA_BLOCK_ADDRESS (file IN NUMBER ,block IN NUMBER) RETURN NUMBER; 10.1.2.16.1 Example Here is an example of calling this function and displaying the resulting value: SQL> BEGIN 2 DBMS_OUTPUT.PUT_LINE 3 (DBMS_UTILITY.MAKE_DATA_BLOCK_ADDRESS (10000, 20000)); 4 END; 5 / 268455456 10.1.2.17 The DBMS_UTILITY.NAME_RESOLVE procedure This procedure resolves the name of an object into its component parts, performing synonym translations as necessary. Here's the header for the procedure: PROCEDURE DBMS_UTILITY.NAME_RESOLVE (name IN VARCHAR2, context IN NUMBER, [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 488 schema OUT VARCHAR2, part1 OUT VARCHAR2, part2 OUT VARCHAR2, dblink OUT VARCHAR2, part1_type OUT NUMBER, object_number OUT NUMBER); Parameters are summarized in the following table. Parameter Description name The name of the object to be resolved. context Present for future compatibility; must be set to the value 1. schema Name of the object's schema. part1 The first part of the object's name. part2 The second part of the object's name (NULL unless the object is a package module, and then part1 is the package name). dblink Name of the database link for the object, if any. part1_type Indicates the type of object returned in part1. object_number The object number for the named object. When object_number is returned NOT NULL, the name was successfully resolved. An object type may have one of the following values: 5 Synonym 7 Standalone procedure 8 Standalone function 9 Package The NAME_RESOLVE procedure has six OUT parameters, which means that in order to use this module you will have to declare six variables −− an annoying task that creates an obstacle to casual use of the procedure. I built a procedure called show_name_components precisely to make it easier to take advantage of NAME_RESOLVE. The show_name_components accepts an object name, and then calls DBMS_OUTPUT.PUT_LINE to display the different components of the name. It shows information only if it is relevant; in other words, if there is no part2, then part2 is not displayed. The name of the database link is displayed only if there is a database link associated with that object. Here are some examples of calls to show_name_components: SQL> execute show_name_components('do.pl'); Schema: BOOK Package: DO Name: PL SQL> execute show_name_components('do'); Schema: BOOK Package: DO [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 489 SQL> execute show_name_components('show_name_components'); Schema: BOOK Procedure: SHOW_NAME_COMPONENTS Here is the show_name_components procedure in its entirety: /* Filename on companion disk: showcomp.sp */* CREATE OR REPLACE PROCEDURE show_name_components (name_in IN VARCHAR2) IS /* variables to hold components of the name */ schema VARCHAR2(100); part1 VARCHAR2(100); part2 VARCHAR2(100); dblink VARCHAR2(100); part1_type NUMBER; object_number NUMBER; /*−−−−−−−−−−−−−−−−−−−−− Local Module −−−−−−−−−−−−−−−−−−−−−−−*/ FUNCTION object_type (type_in IN INTEGER) RETURN VARCHAR2 /* Return name for integer type */ IS synonym_type CONSTANT INTEGER := 5; procedure_type CONSTANT INTEGER := 7; function_type CONSTANT INTEGER := 8; package_type CONSTANT INTEGER := 9; BEGIN IF type_in = synonym_type THEN RETURN 'Synonym'; ELSIF type_in = procedure_type THEN RETURN 'Procedure'; ELSIF type_in = function_type THEN RETURN 'Function'; ELSIF type_in = package_type THEN RETURN 'Package'; END IF; END; BEGIN /* Break down the name into its components */ DBMS_UTILITY.NAME_RESOLVE (name_in, 1, schema, part1, part2, dblink , part1_type, object_number); /* If the object number is NULL, name resolution failed. */ IF object_number IS NULL THEN DBMS_OUTPUT.PUT_LINE ('Name "' || name_in || '" does not identify a valid object.'); ELSE /* Display the schema, which is always available. */ DBMS_OUTPUT.PUT_LINE ('Schema: ' || schema); /* If there is a first part to name, have a package module */ IF part1 IS NOT NULL THEN /* Display the first part of the name */ DBMS_OUTPUT.PUT_LINE (object_type (part1_type) || ': ' || part1); [Appendix A] What's on the Companion Disk? 10.1.2 The DBMS_UTILITY Interface 490 . value. strval The parameter value if that value is a string. Otherwise it is NULL. Long desired by Oracle developers, the GET_PARAMETER_VALUE function now allows you to get critical information about. for the same parameter (certainly a possibility with a parameter such as UTL_FILE_DIR), then this built−in will retrieve only the value associated with the first occurrence of the parameter. You. GET_PARAMETER_VALUE to make it easier to retrieve and interpret the results. Why? Whenever you call this built−in function, you must declare two variables to retrieve the OUT arguments. You must then interpret