Le package DBMS_UTILITY

Dernière mise à jour le

Introduction

Le package DBMS_UTILITY fournit des fonctions et procédures plus ou moins complexes qui peuvent parfois aider lors de l’élaboration d’applications.
Nous allons traiter dans cet article quelques-unes des routines qu’il fournit.

Ce package existe depuis la version 7.3.4 d’Oracle Database et a subit de multiples modifications. On peut retrouver les entêtes de ce package dans le fichier suivant :

$ORACLE_HOME/rdbms/admin/dbmsutil.sql

Pour certains exemples, nous travaillerons avec le schéma HR, fournit par Oracle. D’autres nécessitant des privilèges plus importants, nous travaillerons avec SYS.

Dépendances

Exécutez le code suivant entant que SYS pour afficher la liste des objets dépendants du package DBMS_UTILITY et les objets qui y sont référencés.

SELECT name, type, ’Dépendant’ direction
FROM dba_dependencies
WHERE referenced_name = ’DBMS_UTILITY’
UNION
SELECT referenced_name, referenced_type, ’Référencé’
FROM dba_dependencies
WHERE name = ’DBMS_UTILITY’ ;

On peut y retrouver, entre autres, les packages DBMS_ALERT, DBMS_DATAPUMP, DBMS_DDL, DBMS_DESCRIBE, DBMS_STATS, OWA_UTIL qui sont dépendants de DBMS_UTILITY.

Procédure COMPILE_SCHEMA

Cette procédure permet de recompiler toutes les procédures, fonctions, packages et triggers d’un schéma spécifié.

dbms_utility.compile_schema(
schema         IN VARCHAR2,
compile_all    IN BOOLEAN DEFAULT TRUE) ;

schema est le nom du schéma sur lequel on souhaite travailler
compile_all spécifie que tous les objets valides ou non doivent être recompilés (TRUE) ou non (FALSE)

Exemple :

EXECUTE DBMS_UTILITY.COMPILE_SCHEMA(’HR’)

Après avoir exécuté cette procédure vous pouvez faire un SELECT sur la vue ALL_OBJECTS en recherchant les objets invalides.

SELECT object_name, object_type
FROM all_objects
WHERE status = ’invalid’ ;
Pour les objets restants invalides, vous pouvez utiliser la commande suivante :
SHOW ERRORS  
Vous pourrez ainsi corriger les erreurs associées à vos objets.

Attention, cette procédure est exécutée avec une limite sur le nombre d’objets pouvant être traités. Dans ce cas, une exception est levée (ORA-20002 : Maximum iterations exceeded. Some objects may not have been recompiled). Dans ce cas, vous n’avez qu’à relancer la procédure une nouvelle fois.

Fonction CURRENT_INSTANCE

Retourne le numéro de l’instance à laquelle nous sommes connectés. Retourne NULL quand l’instance est tombée.

dbms_utility.current_instance RETURN NUMBER

Exemple :

SELECT dbms_utility.current_instance
FROM dual ;

Pour retrouver plus d’informations sur cette instance :

SELECT *
FROM v$instance
WHERE instance_number = dbms_utility.current_instance ;

Procédure DB_VERSION

Retourne des informations sur la version de la base de données.

dbms_utility.db_version (
version       OUT VARCHAR2,
compatibility OUT VARCHAR2) ;

Exemple :

DECLARE
 ver    VARCHAR2(100) ;
 compat VARCHAR2(100) ;
BEGIN
  dbms_utility.db_version(ver, compat) ;
  dbms_output.put_line(’Version : ’ || ver ||’ Compatible : ’ || compat) ;
END ;

Le paramètre de compatibilité est déterminé dans le fichier init.ora (« compatible »). S’il ne l’est pas, cette procédure retourne NULL en deuxième argument.

Procédure EXEC_DDL_STATEMENT

Exécute l’ordre DDL envoyé en argument.

dbms_utility.exec_ddl_statement(parse_string IN VARCHAR2) ;

Fonction GET_CPU_TIME

Cette fonction retourne le temps CPU actuel en centième de secondes.

dbms_utility.get_cpu_time RETURN NUMBER ;

Exemple :

DECLARE 
 t1 NUMBER ;
 t2 NUMBER ;
 i  NUMBER ;
BEGIN
  t1 := dbms_utility.get_cpu_time ;
  SELECT COUNT(*) INTO i
  FROM all_tables t, all_indexes i
  WHERE t.tablespace_name = i.tablespace_name ;
  t2 := dbms_utility.get_cpu_time ;
  dbms_output.put_line(t2-t1) ;
END ;

Procédure GET_DEPENDENCY

Cette procédure retourne toutes les dépendances sur l’objet passé en paramètre. On précisera le type de l’objet, le schéma et son nom.

dbms_utility.get_dependency(
type   IN VARCHAR2,
schema IN VARCHAR2,
name   IN VARCHAR2) ;

Exemple :

EXEC dbms_utility.get_dependency(’TABLE’, ’ORACLE’, ’EMPLOYEES’)

Fonction GET_TIME

Retourne le nombre de centièmes de secondes écoulés depuis un instant, choisi arbitrairement.

dbms_utility.get_time RETURN NUMBER ;

Exemple :

DECLARE 
 t1 NUMBER ;
 t2 NUMBER ; 
BEGIN
  t1 := dbms_utility.get_time ;
  dbms_lock.sleep(2.4) ;
  t2 := dbms_utility.get_time ;
  dbms_output.put_line(t2-t1) ;
END ;

Fonction IS_CLUSTER_DATABASE

Retourne TRUE si la base de données fonctionne en mode cluster. Retourne FALSE sinon.

dbms_utility.is_cluster_database RETURN BOOLEAN ;

Exemple :

BEGIN
  IF dbms_utility.is_cluster_database THEN
    dbms_output.put_line(’You’’re running in cluster database mode.’) ;
  ELSE
    dbms_output.put_line(’You’’re not running in cluster database mode.’) ;
  END IF ;
END ;

Procédure NAME_RESOLVE

Résolution d’un nom d’objet, avec transposition des synonymes si nécessaire et contrôle des autorisations.

dbms_utility.name_resolve (
name          IN  VARCHAR2, 
context       IN  NUMBER,
schema        OUT VARCHAR2, 
part1         OUT VARCHAR2, 
part2         OUT VARCHAR2,
dblink        OUT VARCHAR2, 
part1_type    OUT NUMBER, 
object_number OUT NUMBER) ;

Le contexte est un entier entre 0 et 9 :
- 0 = table
- 1 = fonction, procédure, package
- 2 = séquence
- 3 = trigger
- 4 = java store
- 5 = java resource
- 6 = java class
- 7 = type
- 8 = java shared data
- 9 = index

Si aucun schéma n’est spécifié dans le nom de l’objet, alors il sera déterminé par la procédure.
L’argument part1 contient la première partie du nom de l’objet. On pourra récupérer le type avec part1_type :
- 5 = synonyme
- 7 = procédure
- 8 = fonction
- 9 = package
L’argument object_number est l’identifiant unique de l’objet sur la base de données.

Exemple :

DECLARE
 s  VARCHAR2(30) ;
 p1 VARCHAR2(30) ;
 p2 VARCHAR2(30) ;
 d  VARCHAR2(30) ;
 o  NUMBER(10) ;
 ob NUMBER(10) ; 
BEGIN
  dbms_utility.name_resolve(’GET_EMPLOYEE’, 1, s, p1, p2, d, o, ob) ;
  dbms_output.put_line(’Owner :  ’ || s) ;
  dbms_output.put_line(’Table :  ’ || p1) ;
  dbms_output.put_line(’Column : ’ || p2) ;
  dbms_output.put_line(’Link :   ’ || d) ;
  dbms_output.put_line(’Type :   ’ || o) ;
  dbms_output.put_line(’ID :   ’ || ob) ;
END ;

Procédure VALIDATE

Cette procédure permet de changer le statut des objets de « invalid » à « valid ».

dbms_utility.validate(
object_id      IN NUMBER) ;

object_id est l’identifiant unique de l’objet sur la base de données.

SELECT object_id, object_name
FROM user_objects
WHERE status = ’INVALID’ ;

Cette procédure valide un objet de la base de données en utilisant le même mécanisme que celui utilisé par la re-validation automatique. Aucun exception n’est retournée si l’objet n’existe pas, est déjà valide ou ne peut être validé. Les exceptions devront donc être levées manuellement.

Conclusion

Ce package appartenant au schéma de SYS a un synonyme public nous permettant de l’utiliser directement avec son nom plutôt qu’avec SYS.DBMS_UTILITY. Des droits ont également été donnés à public pour exécuter ce package. Cependant, certaines routines à l’intérieur nécessiteront des privilèges de DBA.

Ce package contient encore d’autres procédures et fonctions, souvent plus complexes, mais qu’il peut-être intéressant de découvrir.