| “php3_sesam_configfile” | Nom du fichier de configuration de l’application SESAM. Elle est nécessaire pour utiliser les fonctions SESAM. | Exemple 3. Configuration de “php3_sesam_configfile” | php3_sesam_configfile $SESAM.SESAM.CONF.AW | | Ce fichier va généralement contenir une configuration comme celle-ci. (reportez-vous au manuel de référence SESAM). | Exemple 4. Configuration SESAM | CNF=B NAM=K NOTYPE | | |
| “php3_sesam_messagecatalog” | Nom du catalogue de messages SESAM. Dans la plupart des cas, cette directive n’est pas nécessaire. Uniquement dans les cas où le fichier de message n’est pas installé dans la table de message du système BS2000, vous pouvez utiliser cette directive : | Exemple 5. Nom du catalogue de messages SESAM | php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030 | | |
En plus de la configuration de l’interface PHP/SESAM, vous devez configurer le serveur SESAM-Database lui-même, sur votre mainframe habituel. Cela signifie :
* 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. À 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 rapides ; car ils ne requièrent pas de connexion distante via ODBC, JDBC ou UTM.
====== Considérations à l’exécution ======
À 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ées à pleine vitesse.
Lorsque vous définissez explicitement le catalogue de messages SESAM, ce catalogue sera 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 bibliothèque 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ésultats sont alloués pour les requêtes SQL de sélection ; ils 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. |
====== Portage ======
En PHP, il est naturel de commencer les index à zéro (plutôt que 1), et quelques adaptations ont été faites 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 colonnes (exclus) du résultat ($array[”count”]). Lors du portage d’applications depuis d’autres langages évolués vers PHP, soyez attentifs à ce changement. À 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 plupart 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 langages SQL ne sont jamais 100 % compatibles. Lorsque vous portez une application SQL depuis une autre interface vers SESAM, certaines adaptations doivent être faites. 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. À 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 dates 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 connaît 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 retournée s’il y a des objets dépendants (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 leur existence ( (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és 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 multiples” peut être créé comme ceci :
| Exemple 6. 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 7. Affectation d’une colonne de type “champs multiples” | INSERT INTO multi_field_test (pkey, multi(2..3) ) VALUES (’Second’, <’first_val’, ‘second_val’>) | |