XC. SESAM

Notes de configuration�: Il n'y a pas de support pour l'interface SESAM si PHP est un CGI : elle ne fonctionne que comme module Apache. En module Apache, l'interface SESAM peut �tre configur�e avec les directives Apache.

Tableau 1. Directives de configuration SESAM

Directive	Signification
php3_sesam_oml	Nom de la librairie BS2000 PLAM contenant le module du pilote SESAM. Ceci est obligatoire pour utiliser les fonctions SESAM. Exemple: php3_sesam_oml $.SYSLNK.SESAM-SQL.030
php3_sesam_configfile	Nom du fichier de configuration de l'application SESAM. Ceci est obligatoire pour utiliser les fonctions SESAM. Exemple: php3_sesam_configfile $SESAM.SESAM.CONF.AW Ce fichier contient g�n�ralement une configuration comme celle ci (voir dans le manuel de r�f�rence SESAM): CNF=B NAM=K NOTYPE
php3_sesam_messagecatalog	Nom du fichier de messages SESAM. Dans la plus part des cas, cette directive n'est pas n�cessaire. Uniquement si le fichier de messages SESAM n'es pas install� dans la table de messages BS2000. Il peut alors �tre choisi avec cette directive. Exemple: php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030

En plus de la configuration de l'interface PHP/SESAM, vous devez aussi configurer le serveur SESAM-Database sur votre mainframe, comme d'habitude. Cela signifie notamment qu'il faut :

• d�marrer le gestionnaire de base SESAM (DBH)

• connecter les bases avec le gestionnaire de bases SESAM

Pour connecter un script PHP au serveur de bases SESAM, les param�tres CNF et NAM de la configuration SESAM selectionn�e doivent correspondre � l'id du gestionnaire de base d�marr�.

Dans le cas des bases de donn�es distribu�es, vous devez d�marrer un agent SESAM/SQL-DCN, avec la table de distribution incluant le nom de l'h�te et de la base de donn�es.

La communication entre PHP (fonctionnant sur le sous-syst�me POSIX) et le gestionnaire de base (fonctionnant hors du sous-syst�me POSIX) est r�alis�e par un pilote sp�cial appel� SQLSCI et le module de connexion SESAM, qui utilise la m�moire partag�e. A cause de la m�moire partag�e, et parce que PHP est une partie statique du serveur web, les acc�s � la base de donn�es sont extr�mement rapide, car il ne requi�rent pas de connexion distante via ODBC, JDBC ou UTM.

Seul un chargeur de stub (stub loader, SESMOD) est compil� dans PHP. Les modules de connexion SESAM proviennent de la librairie OML PLAM. Dans la configuration, vous devez indiquer � PHP le nom de la librairie PALM, et le fichier de lien � utiliser pour la configuration de SESAM (En SESAM V3.0, SQLSCI est disponible dans la librairie d'outils SESAM (SESAM Tool Library), qui fait partie de la distribution standard).

Les commandes SQL imposent que les guillemets simples soient doubl�s pour �tre interpr�t� lit�ralement (contrairement � d'autres bases de donn�es qui utilisent un guillemet simple, pr�c�d� d'un antislash), il est recommand� d'activer les directives PHP php3_magic_quotes_gpc et php3_magic_quotes_sybase.

Ex�cutions�: A cause des limitations du mod�le de processus BS2000, le pilote peut �tre charg� uniquement apr�s que le serveur Apache ait g�n�r� le processus fils. Cela ralentit l�g�rement le traitement de la premi�re requ�te, mais toutes les requ�tes suivantes seront effecut�e � pleine vitesse.

Lorsque vous d�finissez explicitement le catalogue de messages SESAM, ce catalogue ser charg� � chaque fois que le pilote est charg� (i.e., au moment de la requ�te initiale). Le syst�me d'exploitation BS2000 affiche un message apr�s avoir correctement charg� le catalogue de messages, qui sera envoy� au fichier d'erreurs Apache. BS2000 ne permet pas la suppression de ce message, qui va remplir progressivement ce fichier.

Assurez vous que la librairie SESAM OML PLAM et le fichier de configuration SESAM sont accessibles par l'utilisateur qui fait tourner le serveur web. Sinon, le serveur ne sera pas capable de charger le pilote, ou d'appeler les fonctions SESAM. L'acc�s � la base doit �tre donn� � cet utilisateur. Sinon, les connexions SESAM �choueront.

Types de curseurs�: Les curseurs de r�sultat sont allou�s pour les requ�tes SQL de selection, peuvent �tre soit "s�quentiels", soit "� d�filement" ("scrollable"). Les curseurs � d�filement sont beaucoup plus gourmands en m�moire, et le mode par d�faut est s�quentiel.

Lorsque vous utilisez les curseurs � d�filement, le curseur peut �tre positionn� librement dans le r�sultat. Pour chaque requ�te � d�filement, il existe des valeurs globales de types de d�filement (initialis�e � :SESAM_SEEK_NEXT) et la position peut �tre fix�e une seule fois par sesam_seek_row() ou bien � chaque appel, avec la fonction sesam_fetch_row(). Lorsque vous lisez une ligne avec un curseur � d�filement, le traitement suivant est effectu� � partir des valeurs globales de type de d�filement et de position :

Tableau 2. Scrolled Cursor Post-Processing

Type de d�filement	Action
SESAM_SEEK_NEXT	aucun
SESAM_SEEK_PRIOR	aucun
SESAM_SEEK_FIRST	le type de d�filement devient SESAM_SEEK_NEXT
SESAM_SEEK_LAST	le type de d�filement devient SESAM_SEEK_PRIOR
SESAM_SEEK_ABSOLUTE	incr�mente automatiquement la valeur interne de position
SESAM_SEEK_RELATIVE	aucune. conserve les valeurs globales par d�faut de position, ce qui permet, par exemple de lire toutes les 10 lignes, en arri�re.

Porting note�: En PHP, il est naturel de commencer les index � z�ro (plut�t que 1), et quelques adaptations ont �t� faite pour l'interface SESAM : � chaque fois qu'un tableau index� commence � l'index 1 en SESAM natif, l'interface PHP utilisera l'index 0 comme point de d�part. Par exemple, lorsque vous lisez des donn�es avec sesam_fetch_row(), la premi�re colonne sera � l'index 0, et les suivantes suivront juqu'au nombre de colonne (exclus) du r�sultat ($array["count"]). Lors du portage d'applications depuis d'autres langage �volu�s vers le PHP, soyez attentifs � ce changement. A chaque fois que c'est n�cessaire, la description d'une fonction PHP SESAM indique que l'index du tableau commence � 0.

S�curit�: Lorsque vous autorisez l'acc�s � une base de donn�es SESAM, le serveur web doit avoir le minimum de privil�ges possible. Pour la plus part des bases de donn�es, seul le droit de lecture doit �tre fourni. Suivant votre utilisation, ajoutez d'autres droits d'acc�s au fur et � mesure de vos besoins. Ne donnez jamais le contr�le total de vos bases � un utilisateur du web! Limitez l'acc�s aux scripts PHP qui doivent administrer la base en utilisant un mot de passe et/ou une s�curisation SSL.

Migration d'une autre base SQL�: Deux langage SQL ne sont jamais 100% compatibles. Lorsque vous portez une application SQL depuis une autre interface vers SESAM, certaines adaptation doivent �tre fa�tes. Les diff�rences suivantes sont les plus courantes :

• Types de donn�es sp�cifiques

  Certains types de donn�es sp�cifiques � une base doivent �tre remplac�s par les types de donn�es standard SQL. (i.e., TEXT doit �tre remplac� par VARCHAR(taille max)).

• Mots reserv�s comme identifiants SQL.

  En SESAM (comme dans le standard SQL), les mots reserv�s utilis�s comme identifiants doivent �tre entour�s de guillemets doubles (ou renomm�s).

• Taille d'affichage des donn�es.

  Les types de donn�es SESAM ont une taille de stockage, mais par de taille d'affichage. A la place de int(4) (c'est � dire : les entiers jusqu'� '9999'), SESAM requiert simplement int, pour une taille implicite de 31 bits. De m�me, les seuls types de date disponible dans SESAM sont : DATE, TIME(3) et TIMESTAMP(3).

• Les types de donn�es unsigned (non sign�), zerofill (compl�t� avec des z�ros), ou auto_increment

  Unsigned et zerofill ne sont pas support�s. Auto_increment est automatique (utilisez "INSERT ... VALUES(*, ...)" au lieu de "... VALUES(0,...)" pour profiter des auto-increment implicites de SESAM.

• int ... DEFAULT '0000'

  Les variables num�riques ne doivent pas �tre initialis�es avec des constantes de type cha�ne de caract�res. Utilisez DEFAULT 0 � la place. Pour initialiser une date, la cha�ne doit �tre pr�fix�e avec le type de date adapt�, tel que : CREATE TABLE exmpl (xtime timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT NULL);

• $count = xxxx_num_rows();

  Certaines bases de donn�es essaient d'estimer le nombre de lignes d'un r�sultat, m�me grossi�rement approximativement. SESAM ne connait pas le nombre de lignes avant de les avoir lues lui-m�me. Si vous avez vraiment besoin de les compter, utilisez la commande SELECT COUNT(...) WHERE ..., qui vous dira combien de lignes sont disponibles. Une deuxi�me requ�te devrait vous retourner tous ces r�sultats.

• DROP TABLE lenom;

  Avec SESAM, dans la commande DROP TABLE, le nom de la table doit �tre suivi du mot cl� RESTRICT ou CASCADE. Avec RESTRICT, une erreur est retounr�e si il y a des objets d�pendant (par exemple, des vues), tandis qu'avec CASCADE, les objets d�pendants seront supprim�s en m�me temps que la table.

Notes sur l'utilisation de types SQL divers�: SESAM ne supporte pas le type BLOB. Une future version de SESAM devra le faire.

L'interface PHP effectue automatiquement les conversions suivantes lors de la lecture de lignes de r�sultats SQL :

Tableau 3. Conversion de type SQL vers PHP

Type SQL	Type PHP
SMALLINT, INTEGER	"integer" (entier)
NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE	"double" (nombre � virgule flottante)
DATE, TIME, TIMESTAMP	"string"(cha�ne de caract�res)
VARCHAR, CHARACTER	"string"(cha�ne de caract�res)

Lorsque vous lisez une ligne enti�re, le r�sultat est retourn� sous la forme d'un tableau. Les champs vides ne sont pas remplis, et vous aurez � v�rifier vous m�me l'existence des champs ( (utilisez isset() ou empty() pour tester les champs vides). Cela donne plus de contr�le � l'utilisateur sur l'apparence des champs que si les champs vides �taient repr�sent� par des cha�nes vides).

Support des "champs multiples" de SESAM�: La fonctionnalit� sp�ciale des "champs multiples" de SESAM permet � une colonne de contenir un tableau de champs. Un tel "champs multiple" peut �tre cr�� comme ceci :

Exemple 1. Cr�ation d'une colonne de champs multiples CREATE TABLE multi_field_test ( pkey CHAR(20) PRIMARY KEY, multi(3) CHAR(12) )

et peut �tre remplie avec :

Exemple 2. Affectation d'une colonne de type "champs multiple" INSERT INTO multi_field_test ( pkey, multi(2..3) ) VALUES ( 'Second', <'first_val','second_val>)

Notez que (comme c'est le cas ci-dessus), les sous-champs vides initiaux sont ignor�s, et que le tableau est alors compact�, ce qui fait que l'exemple ci-dessus conduit � un tableau multi(1..2) au lieu de multi(2..3).

Lors de la lecture d'une ligne, les "champs multiples" sont mis en colonne. Dans l'exemple ci-dessu, "pkey" prend l'index 0, et les trois colonnes "multi(1..3)" sont accessibles depuis les index 1 � 3.