Installation de la librairie Forms9i WEBUTIL

SheikYerbouti

Interagissez avec votre poste client depuis Forms9i ♪

- Titre : Installation de la librairie Forms9i WEBUTIL

- Auteur : SheikYerbouti

- Parution : 1 avril 2004

- Mise à jour : 1 décembre 2004

- Licence :

Sommaire

- Introduction

- I. Description du paquetage

- II. Configuration des éléments

- II-A. Signature des fichiers archives .jar

- II-B. Configuration de la base

- II-C. Configuration du serveur HTTP

- II-D. Adaptation du fichier de configuration $ORACLE_HOME/forms90/server/formsweb.cfg

- II-E. Adaptation du fichier de configuration $ORACLE_HOME/forms90/server/default.env

- II-F. Adaptation du fichier de configuration $ORACLE_HOME/forms90/server/webutil.cfg

- II-G. Mise en place et compilation de la librairie Forms webutil.pll

- III. Mise en place d'une nouvelle forme

- IV. Forme d'exemple livrée dans cet article

- IV-A. L'onglet Infos locales

- IV-B. L'onglet Fichiers

- IV-C. L'onglet Host

- IV-D. L'onglet Image

- V. Matériel à télécharger

- Remerciements

Introduction

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

I - Description du paquetage

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 :
https://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écessaires à 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)

II - Configuration des éléments

II-A - Signature des fichiers archives .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).

Éditez 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écutez 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.

II-B - Configuration de la base

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éé.

II-C - Configuration du serveur HTTP

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 »

II-D - Adaptation du fichier de configuration $ORACLE_HOME/forms90/server/formsweb.cfg

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 où 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

II-E - Adaptation du fichier de configuration $ORACLE_HOME/forms90/server/default.env

- 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;…….

II-F - Adaptation du fichier de configuration $ORACLE_HOME/forms90/server/webutil.cfg

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 à 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

II-G - Mise en place et compilation de la librairie Forms webutil.pll

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)

III - Mise en place d'une nouvelle forme

- 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és par la variable FORMS90_PATH du fichier forms90.conf

IV - Forme d'exemple livrée dans cet article

Elle est constituée de quatre 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.

IV-A - L'onglet Infos locales

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.

IV-B - L'onglet Fichiers

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 champ Fichier source via la fonction WEBUTIL_FILE.FILE_OPEN_DIALOG

Le champ 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.

À 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é dans le champ Liste de fichiers

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

IV-C - L'onglet Host

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

Le bouton « host bloquant » exécute la commande saisie dans le champ 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 champ 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.

IV-D - L'onglet Image

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

V - Matériel à télécharger

- La forme d'exemple TEST_WEBUTIL.FMB (9i)

- Cadeau ! Webutil.pll et Webutil.olb version 6i

Remerciements

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