Le paquetage WEBUTIL contient les objets nécessaires à l'exécution de fonctions sur le poste client pour les applications Forms Web.
Ces fonctions permettent une interaction entre l'application exécutée sur le serveur et la machine locale via le browser, en utilisant les fonctions PL/SQL d'une librairie Forms .

En effet, depuis les versions Web (Forms6i et Forms9i), le runtime Forms n'est plus installé sur le poste client mais sur le serveur d'application et toute commande adressée depuis l'application Forms est donc exécutée sur le serveur, avec les surprises que cela occasionne aux habitués des versions client-serveur !

Pour utiliser ces fonctions, il suffit d'attacher cette librairie à la forme et d'y incorporer le contenu de la librairie d'objets également fournie.

Dans sa version 9i, ce paquetage n'est pas supporté par Oracle. Les questions concernant la mise en place et l'utilisation doivent être posées sur le site OTN (http://www.oracle.com/forums/forum.jsp?forum=82)

Cette librairie reprend la plupart des fonctionnalités offertes par l'ancienne version client/server (D2KWUTIL.PLL) et en apporte de nouvelles spécifiques au mode web

Sa version actuelle (10g) est désormais supportée par Oracle. (webutil_105.zip)

L'objet de cet article est de décrire l'installation et l'utilisation de la librairie Webutil, mais en aucun cas de décrire en détail chaque fonction de cette librairie

L'archive contenant le matériel nécessaire est disponible en téléchargement à l'url suivante :
http://otn.oracle.com/software/products/forms/index.html

Le fichier compressé webutil_102.zip est également accessible ici :
http://sheikyerbouti.developpez.com/webutil/fichiers/webutil_102.zip

Voici le contenu de l'archive webutil_102.zip

Il est également nécessaire de télécharger l'archive jacobBin_17.zip à l'url suivante :
http://danadler.com/jacob/jacobBin_17.zip

Voici la raison invoquée par Oracle pour justifier l'absence de ces éléments dans le fichier webutil_102.zip :

"For legal reasons some code has been deliberately omitted from the WebUtil distribution and you will have to manually install it"

La documentation indique que la librairie Jacob.jar n'est nécessaire que pour exécuter les fonctions OLE, mais en réalité, Webutil ne fonctionne pas sans ce fichier

Depuis ce fichier archive, il faut extraire les fichiers jacob.dll et jacob.jar

La décompression de l'archive webutil_102.zip génère 5 sous-répertoires
Doc\ readme.html
webutil_manual.pdf

Ce répertoire contient le manuel d'installation en anglais ainsi que le fichier readme.html de complément d'installation (jacobBin_17.zip) Forms\ create_webutil_db.sql
webutil.olb
webutil.pll

Ce répertoire contient la librairie PL/SQL webutil.pll, la librairie d'objets webutil.olb ainsi qu'un script de création de paquetage create_webutil_db.sql Lib\ d2kwut60.dll
JNIsharedstubs.dll
webutil.jar


Ce répertoire contient les classes Java ainsi que les librairies système téléchargées sur le poste client Server\ sample_formsweb_cfg_entry.txt
webutil.cfg
webutil.env
webutiljini.htm

Ce répertoire contient le fichier de configuration webutil.cfg ainsi qu'un exemple de déclaration de section à ajouter au fichier formsweb.cfg Util\ makecert.bat
sign.bat
signer.properties

Ce répertoire contient les commandes nécessaire à la signature des fichiers .jar



Il est préférable de créer un répertoire Webutil\ sous le répertoire $ORACLE_HOME\forms90 et d'y copier l'ensemble des fichiers (y compris jacob.dll et jacob.jar)

Il est nécessaire de signer les fichiers webutil.jar et jacob.jar et cette opération nécessite d'installer sur le poste local le SDK Java Standard Edition 1.3.1 téléchargeable à l'url suivante : http://java.sun.com/j2se/1.3/download.html

Déplacez-vous dans le répertoire $ORACLE_HOME\forms90\webutil
(d:\forms9i\forms90\webutil pour cet exemple)

Editez le fichier signer.properties

La variable JDK_HOME doit pointer sur votre répertoire d'installation du Java Development Kit
JDK_HOME=D:\tools\jdk1.3.1

La variable JINIT_HOME doit pointer sur votre répertoire d'installation de Jinitiator
JINIT_HOME=d:\Program Files\Oracle\JInitiator 1.3.1.9

Ouvrez une fenêtre de commande (cmd)

Exécuter le fichier de commande makecert.bat

Signez le fichier webutil.jar avec la commande sign d:\forms9i\forms90\webutil \webutil.jar

Signez le fichier jacob.jar avec la commande sign d:\forms9i\forms90\webutil \jacob.jar


Si, pour une raison particulière vous ne disposez pas ou ne pouvez télécharger le Java SDK, je peux envoyer sur demande les fichiers pré-signés par mail

Certaines fonctions de transfert de fichiers nécessitent la présence d'un paquetage compilé sur la base.
Le script de création de ce paquetage est livré dans le sous-répertoire \webutil\forms\create_webutil_db.sql
L'exécution de ce paquetage nécessite elle-même le droit d'exécution des paquetages systèmes suivants : DBMS_LOB UTL_ENCODE UTL_RAW Il est conseillé de créer un schéma spécial pour webutil.
Ce schéma ne stocke qu'un seul paquetage et ne nécessite que très peu de place dans le tablespace.

Connexion sous SYSTEM

				
SQL> CREATE USER "WEBUTIL" IDENTIFIED BY "WEBUTIL"
  2   DEFAULT TABLESPACE USERS
  3   TEMPORARY TABLESPACE TEMP
  4   QUOTA  UNLIMITED  ON USERS;

Utilisateur créé.

SQL> 
SQL> GRANT CONNECT TO "WEBUTIL";

Autorisation de privilèges (GRANT) acceptée.

SQL> GRANT RESOURCE TO "WEBUTIL";

Autorisation de privilèges (GRANT) acceptée.

Connexion sous webutil

				
SQL> conn webutil/webutil@test
Connecté.
SQL> @D:\Forms9i\webutil\forms\create_webutil_db.sql

Package créé.

Corps de package créé.

Une fois le paquetage créé dans ce nouveau schéma, il ne reste plus qu'à créer des droits d'exécution pour les autres schémas ainsi qu'un synonyme pointant sur ce paquetage

				
SQL> GRANT EXECUTE ON WEBUTIL_DB TO PUBLIC ;

Autorisation de privilèges (GRANT) acceptée.

Connexion sous SYSTEM

				
SQL>  CREATE PUBLIC SYNONYM WEBUTIL_DB FOR WEBUTIL.WEBUTIL_DB ;

Synonyme créé.

Webutil nécessite la déclaration d'un répertoire virtuel pour localiser le fichier webutil.jar ainsi que les DLL à télécharger sur les postes clients.
Ce répertoire virtuel doit pointer sur le répertoire physique d'installation du paquetage Webutil

Admettons que vous avez copié tous les fichiers de l'archive webutil.zip dans le répertoire : D:\Forms9i\forms90\webutil
et que la variable d'environnement $ORACLE_HOME$ pointe sur le répertoire D:\Forms9i

Sous Oracle 9iDS, il faut mettre à jour le fichier : $ORACLE_HOME$\j2ee\Oracle9iDS\application-deployments\forms\forms90web\orion-web.xml

en ajoutant la ligne suivante :

<virtual-directory virtual-path="/webutil" real-path="D:\Forms9i\forms90\webutil" />

Sous Oracle 9iAS, il faut mettre à jour le fichier : …/9iAS/forms90/server/forms90.conf

en ajoutant la ligne suivante :

AliasMatch ^/forms90/webutil/(..*) "D:\Forms9i\forms90\webutil/$1"

Votre fichier de configuration Forms formsweb.cfg permet la création de sections propres et indépendantes pour configurer et exécuter des applications différentes.
Cela veut dire qu'il est possible d'adapter une section pour qu'elle utilise les fonctionnalités Webutil sans altérer les autres sections.

Définition de la page de lancement pour Jinitiator et le plug-in Java

Ajout de la ligne suivante au niveau de votre section :

baseHTMLjinitiator=D:\Forms9i\forms90\webutil\webutiljini.htm

Définition du nom et du répertoire ou se trouve le fichier webutil.jar

Ajout de la ligne suivante au niveau de votre section :

webUtilArchive=/forms90/webutil/webutil.jar, /forms90/webutil/jacob.jar


exemple d'une section du fichier formsweb.cfg :
(en gras, les ajouts spécifiques à Webutil)

#
# Configuration XX
#
[XX]
webUtilArchive=/forms90/webutil/webutil.jar,/forms90/webutil/jacob.jar
# Traces Webutil :
# off
# console (message dans la JVM du client )
# server (message sur le server, dans le web log file )
# all (les deux a la fois ..)
webUtilLogging=all
# Traces Webutil :
# Normal
# Detailed
WebUtilLoggingDetail=Normal
# Traces Webutil :
# alert (message pop up)
# console (message dans la JVM du client )
# server (message sur le server, dans le web log file )
# all (les deux a la fois ..)
WebUtilErrorMode=Alert
baseHTMLjinitiator=D:\Forms9i\forms90\webutil\webutiljini.htm
HTMLbodyAttrs=onLoad='javascript:self.moveTo(1601,1201)'
form=START.fmx
userid=user/password@base
serverURL=/forms90/l90servlet
codebase=/forms90/java
imageBase=DocumentBase
width=1000
height=750
separateFrame=true
splashScreen=
background=/forms90/icons/FOND_ECRAN.gif
lookAndFeel=Oracle
colorScheme=blue
logo=/forms90/icons/LOGO.gif

La variable FORMS90_PATH doit être adaptée pour inclure le chemin d'accès à la librairie webutil.pll FORMS90_PATH=D:\Forms9i/forms90;D:\Forms9i\forms90\webutil

(vous pouvez également éviter cette modification en copiant le fichier webutil.pll dans un des répertoires déjà mappés dans le FORMS90_PATH) La variable d'environnement WEBUTIL_CONFIG doit être ajoutée pour pointer le chemin contenant le fichier webutil.cfg WEBUTIL_CONFIG=D:\Forms9i\forms90\webutil\webutil.cfg La variable d'environnement CLASSPATH doit être adaptée pour inclure le chemin d'accès au fichier webutil.jar CLASSPATH=D:\Forms9i\forms90\webutil\webutil.jar;D:\Forms9i\jlib\debugger.jar;.......

Ce fichier de configuration de webutil permet d'autoriser ou interdire les accès en lecture/écriture sur le serveur

Certaines fonctions ( READ_IMAGE_FILE ) nécessitent un transfert temporaire de fichier sur le serveur. Il est donc indispensable de configurer webutil.cfg pour autoriser les accès sur le serveur


Extrait du fichier webutil.cfg

# 3. Upload / Download options
# For the file upload and download options you can define the default
# locations on the server that webutil can use as a work area
# Optionally you can switch upload and download off
#
# Details
# -------
# transfer.database.enabled: Can be TRUE or FALSE - allows you to disable
# upload and download direct from the database
# server.
# transfer.appsrv.enabled: Can be TRUE or FALSE - allows you to disable
# upload and download direct from the application
# server.
# transfer.appsrv.workAreaRoot: The root of the location in which WebUtil can
# store temporary files uploaded from the client.
# This location is always readable and writable
# no matter what the settings in appsrv.read and
# appsrv.write are.
# This setting is required if you need the
# Client side READ /WRITE_IMAGE_FILE procs
# transfer.appsrv.accessControl:Can be TRUE or FALSE - allows you to indicate
# that uploads and downloads can only occur from
# the directories named in the
# transfer.appsrv.read.n and transfer.appsrv.write.n
# entries and their subdirecories. If this setting
# is FALSE transfers can happen anywhere.
# transfer.appsrv.read.<n>: List of directory names that downloads can read
# from.
# transfer.appsrv.write.<n>: List of directory names that uploads can write
# to.
#NOTE: By default the file transfer is disabled as a security measure
transfer.database.enabled=TRUE
transfer.appsrv.enabled=TRUE
transfer.appsrv.workAreaRoot=D:\
transfer.appsrv.accessControl=TRUE
#List transfer.appsrv.read.<n> directories
transfer.appsrv.read.1=D:\
#List transfer.appsrv.write.<n> directories
transfer.appsrv.write.1=D:\


Par défaut ces variables sont positionnées à FALSE, interdisant tout transfert

Pour autoriser l'utilisateur a exécuter ces fonctions, il faut positionner la variable transfer.appsrv.enabled à TRUE et indiquer le répertoire de travail dans la variable transfer.appsrv.workAreaRoot comme dans l'exemple ci-dessus

Vous devez copier et compiler la librairie webutil.pll dans un des répertoires mappés par la variable de registre FORMS90_PATH (pour la partie Design) et par la variable FORMS90_PATH du fichier de configuration forms90.conf (pour l'exécution)

attacher la librairie webutil.pll glisser le groupe webutil depuis la librairie d'objet webtil.olb dans la section groupe d'objet de la forme Veillez à copier une version exécutable de chacun de vos modules (fmx, mmx, plx) dans un des répertoires pointé par la variable FORMS90_PATH du fichier forms90.conf

Elle est constituée de 4 onglets distincts présentant chacun quelques fonctionnalités de la librairie

Cette forme n'est pas basée et ne demande donc aucune création d'objet dans la base de données

Le bouton "Afficher les infos du poste client" permet de lire à partir des fonctions de la librairie, certaines propriétés du poste client (via la procédure Affiche_infos()) et met en œuvre les fonctions suivantes : Webutil_clientinfo.get_date_time Webutil_clientinfo.get_file_seperator Webutil_clientinfo.get_host_name Webutil_clientinfo.get_ip_address Webutil_clientinfo.get_java_version Webutil_clientinfo.get_operating_system Webutil_clientinfo.get_system_property Webutil_clientinfo.get_user_name Le bouton "Afficher les infos Webutil" permet de visualiser les numéros de version des différents éléments de la librairie webutil

Il permet de mettre en œuvre certaines fonctions sur les fichiers

Pour les manipulations, deux champs de saisie sont proposés afin de spécifier un fichier source et un fichier destination

Le bouton "Sélection" ouvre une boite de dialogue de sélection de fichier et permet d'alimenter le champs Fichier source via la fonction WEBUTIL_FILE.FILE_OPEN_DIALOG

Le champs Fichier destination, utile pour les fonctions copie et renommage doit être valorisé à la main.

Le bouton "Copier" permet de faire une copie du fichier source vers le fichier destination via la fonction WEBUTIL_FILE.COPY_FILE

Le bouton "Renommer" permet de renommer le fichier source en fichier destination via la fonction WEBUTIL_FILE.RENAME_FILE

Le bouton "Supprimer" permet de supprimer le fichier source via la fonction WEBUTIL_FILE.DELETE_FILE

A tous moments vous pouvez visualiser le résultat de ces commandes via le bouton "Sélection"


Le bouton "Sélection multiple" permet l'ouverture d'une boite de dialogue dans laquelle il est possible de sélectionner plusieurs fichiers via la fonction WEBUTIL_FILE.FILE_MULTI_SELECTION_DIALOG

Le résultat de cette sélection est affichée dans le champs Liste de fichiers

Ces fonctions sont regroupées dans le paquetage de la forme PKG_FICHIERS

Il permet d'exécuter des commandes transmises au système d'exploitation

Le bouton "host bloquant" exécute la commande saisie dans le champs Commande à exécuter et attend la sortie de la commande pour rendre la main à l'application Forms via la fonction WEBUTIL_HOST.blocking

Le bouton "host non bloquant" exécute la commande saisie dans le champs Commande à exécuter rend immédiatement la main à l'application Forms via la fonction WEBUTIL_HOST.nonblocking

Le bouton "Host avec rappel" permet d'exécuter une commande non bloquante et de transmettre un trigger utilisateur qui est déclenché dès que la commande se termine via la fonction WEBUTIL_HOST.nonblocking_with_callback (voir le trigger TERMINE du bloc HOST)


Ces fonctions sont regroupées dans le paquetage de la forme PKG_HOST

permet de lire un fichier image stocké sur le poste client et de le charger dans un item de type image via la fonction CLIENT_IMAGE.Read_Image_File

Le code de gestion de la sélection et du chargement de l'image se trouve dans la procédure Charge_image

La forme d'exemple TEST_WEBUTIL.FMB (9i) Cadeau ! Webutil.pll et Webutil.olb version 6i

Chaleureux remerciements à Developpez.com et l'équipe SGBD