Xisam, bibliothèque de gestion de fichiers
- Khouloud Achouri (Unlicensed)
- Bertrand Littel
1. INTRODUCTION
La DLL (Dynamic Link Library) DhXisam permet d'accéder aux fichiers de Divalto. Elle comporte un ensemble de fonctions permettant à un programme C, C++ ou VISUAL BASIC d'utiliser ces fichiers.
REMARQUES :
L'utilisation de la DLL nécessite l'installation du run-time Divalto.
De manière générale, les chaînes de caractères utilisées dans la gestion de fichiers (par exemple le nom d'un fichier) ne se terminent pas par \0.Elle seront donc généralement manipulées par les fonctions memory (memcpy etc.).
Les fonctions de la DLL permettent d'accéder aux fichiers d'autres ordinateurs à travers le réseau XLAN pour WINDOWS.
2. DETAIL DE LA FOURNITURE ET INSTALLATION
Les fichiers fournis sont les suivants :
testxis.exe: programme de démonstration Windows en C
defxisam.txt: prototypes des fonctions de DhXisam.dll pour VISUAL BASIC
xisam.h: interface entre le programme en C et XISAM
DhXisam.lib: définitions des fonctions de DhXisam.dll
testxis.c: source de testxis.exe
testxis.rc: ressources de testxis.exe
testxis.def : déclarations pour le linker
testxis.bmp: image du fond de la fenêtre principale de testxis
testxis.ico: icône de testxis.exe
clixis.dhfi:fichier pour la demo
clixis.dhfd
3. REGLES D'ECRITURE
Tout programme utilisant Divalto doit avoir un numéro de tâche qui permet de l'identifier.
La fonction d'initialisation de la DLL (xisam_begin) affecte un numéro de tâche Divalto au programme appelant, il sert de "ticket" et doit être passé à l'appel des fonctions.
Le fichier xisam.h doit être inclus dans les sources faisant appel à la dll.
Les programmes en Visual Basic doivent inclure le fichier defxisam.bas dans leur projet.
3.1 PROGRAMME PRINCIPAL
Début du programme :
Avant tout accès à la gestion de fichier, le programme principal doit faire appel à la fonction xisam_begin.
Syntaxe :
#include "xisam.h"
short xisam_begin (ushort tache)
Description :
La fonction xisam_begin réserve un numéro de tâche pour le programme appelant.
Le paramètre tâche permet de forcer ce numéro, dans ce cas il doit être compris entre 2 et 1999 sinon il faut mettre la tâche à 0. Dans ce DhXisam prendra le premier numéro de tâche disponible.
Compte-rendu :
La fonction renvoie un numéro de tâche en cas de succès sinon elle renvoie la valeur:
E_XISAMBEGIN_MEM : il n'y a pas assez de mémoire disponible dans Windows.
E_XISAMBEGIN_TACHE : le numéro de tâche est déjà pris (si variable tache différente de 0) ou s'il n'y a plus de tâche disponible.
E_XISAMBEGIN_XMU : le programme DhsDivalto0 n'est pas chargé (voir remarque 1).
E_XISAM_TACHE : le paramètre "tâche" est en dehors des limites de 2 et 1999 et différent de 0.
E_XISAMBEGIN_PROTECT : s'il y a une erreur de protection. Dans ce cas charger DivaltoLicence pour voir le code d'erreur.
Remarque 1 :
Si votre programme utilisant la DLL est lancé depuis le groupe de démarrage, il se peut que DhSession soit chargé après votre programme. Dans ce cas, la fonction xisam_begin renvoie la valeur -2. Il convient donc de boucler sur l'appel de cette fonction (sans omettre de rendre la main au système) pour laisser le temps à WINDOWS de charger DhSession.
Remarque 2 Contrôle de la version :
La fonction xisam_version() renvoie le numéro de version de la DLL. Ce numéro vous permet de contrôler que votre programme est compatible avec la DLL. Cette fonction retourne un entier court (short).
3.2 DEMANDE DU CODE UTILISATEUR
Puis il faut vous connecter selon un code utilisateur pour charger les chemins implicites de cet utilisateur avec la fonction :
extern unsigned short xisam_LoadUtil(unsigned short ntache,
unsigned char * util4,
unsigned short lgutil4,
unsigned char * enrxlogf,
unsigned short lgenrxlogf,
unsigned char * motdepasse,
unsigned short lgmotdepasse);
avec :
ntache : numéro de la tâche
util4: code utilisateur sur 4 caractères maximum
lgutil4: longueur de util4
enrxlogf: pt sur une zone de 256 caractères si on veut récupérer l'enregistrement
xlogf , par exemple pour connaître le nom complet de l'utilisateur
nota : la zone mot de passe est toujours effacée
cette zone n'est plus utiliser en 6.1
lgenrxlogf: taille de la zone enrxlogf
motdepasse : mot de passe sur 24 caractères maximum
lgmotdepasse :longueur de la zone motdepasse
typedef struct /* structure de la zone enrxlogf */
{
uchar interne1[2];
uchar nom[4];/* code utilisateur */
ucharcomm[24]; /* nom de l'utilisateur */
} exlogf;
exemple :
char szUser[4+1];
char szPwd[24+1];
strcpy(szUser,"");
strcpy(szPwd,"");
saisie de szUser et de szPwd ( voir le programme testxis.c )
status = isam_LoadUtil( Tache ,
(uchar*)szUser , (ushort)strlen(szUser) ,
NULL , 0 ,
(uchar*)szPwd , (ushort)strlen(szPwd) );
if ( status != 0 )
{
switch ( status )
{
case 2:
wsprintf(MsgErreur,"Utilisateur %s inconu",szUser);
break;
case -1:
wsprintf(MsgErreur,"Le mot de passe pour l'utilisateur %s est faux",szUser);
break;
default:
wsprintf(MsgErreur,"Erreur %4x lors du chargement de l'utilisateur %s",status,szUser);
break;
}
MessageBox(GetFocus(),MsgErreur,"Programme TESTXIS",MB_OK);
xisam_end(Tache);
FaireLeMenage();
return(FALSE);
}
strcpy(szPwd,""); // il ne faut pas laisser le mot de passe en mémoire
wsprintf(TexteMessage,"TESTXIS Test de DHXISAM.DLL - Tâche %d Util. %s",Tache,szUser);
SetWindowText(hWnd,TexteMessage);
3.3 FIN DU PROGRAMME
La fonction xisam_end(tache) permet de libérer toutes les
ressources qui ont étés allouées par DhXisam.
4. STRUCTURE DE LA TDF
La structure permettant de dialoguer avec la gestion de fichiers de Divalto est une chaîne de caractères de 1024 octets dont la description est :
typedef struct tdf51 {
union {
uchar tdf[1024];
struct {
uchar interne0[4];//0.4
uchar NAME[256];//4.256
uchar PROT[1];//260.1
uchar KEY[256];//261.256
uchar interne1[17];//517.17
ushort SIZELAST;//534.2
uchar interne2[143]; //536.143
uchar READONLY;//679.1
};
};
} TDF51;
Cette chaîne de caractères se nomme TDF (table de définition de fichier). Elle est passée comme paramètre de toutes les fonctions de gestion de fichiers.
NAME = c'est le nom du fichier
PROT = "W" si le fichier est protégé en écriture
KEY = la clé
SIZELAST = taille du dernier enregistrement lu
READONLY = flag , si = 1 alors le fichier est en lecture seule
5. LES FONCTIONS DE GESTION DE FICHIERS
5.1 xisam_topenlong
Syntaxe :
#include "xisam.h"
ushort xisam_topenlong(ushort ntache, TDF51 * tdf,uchar * cp)
Description :
La fonction xisam_topenlong ouvre un fichier existant.
ntache est le numéro de tâche Divalto affecté au programme.
Le nom du fichier à ouvrir doit être dans tdf.name.
Le code de partage (cp) peut prendre une des valeurs suivantes : espace "F" "P" ou "R".
"P" ouverture du fichier en mode partagé.
"R" ouverture du fichier en mode réservé.
"F" ouverture du fichier en lecture seule.
Compte-rendu :
0 : pas d'erreur.
E_FILNAME: nom de fichier incorrect.
E_ABSENT: fichier absent.
E_SHARE : erreur de partage.
autres : code d'erreur système.
Remarque :
Si le chemin n'est pas renseigné, la fonction xisam_topenlong tente d'ouvrir le fichier avec les chemins implicites
Exemple :
#include "xisam.h"
TDF51 tdf;
ushort st;
memset(tdf.name,' ',sizeof(tdf.name));
memcpy(tdf.name,nom du fichier,lg du nom du fichier);
st = xisam_topenlong(tache,tdf,"P");
if (st != 0)
affiche_erreur(st);
5.2 xisam_tcloselong
Syntaxe :
#include "xisam.h"
ushort xisam_tcloselong(ushort ntache, TDF51 * tdf)
Description :
Fermeture d'un fichier précédemment ouvert par la fonction xisam_topenlong.
Compte-rendu :
0: pas d'erreur.
Autres: Code d'erreur système.
5.3 xisam_tpcloselong
Syntaxe :
#include "xisam.h"
ushort xisam_tpcloselong(ushort ntache, TDF51 * tdf)
Description :
Fermeture partielle d'un fichier précédemment ouvert par la fonction xisam_topen.
Cette fonction demande au système d'exploitation d'écrire sur le disque tous les blocs modifiés qui se trouvent en mémoire cache.
Tous les enregistrements réservés dans le fichier sont automatiquement libérés.
Compte-rendu :
0: pas d'erreur.
Autres: Code d'erreur système.
5.4 xisam_teraselong
Syntaxe :
#include "xisam.h"
ushort xisam_teraselong(ushort ntache, TDF51 * tdf)
Description :
Effacement d'un fichier précédemment ouvert par la fonction xisam_topenlong.
S'il s'agit d'un fichier séquentiel indexé, le fichier des données est effacé et le fichier paramètres et clés est réinitialisé.
Compte-rendu :
0: pas d'erreur.
Autres: Code d'erreur système.
5.5 xisam_treadlong
Syntaxe :
#include "xisam.h"
ushort xisam_treadlong(ushort ntache, TDF51 * tdf,uchar * article, ushort taille,uchar * mode )
Description :
xisam_treadlong permet de lire l'enregistrement suivant ou de lire le premier enregistrement du fichier si aucune lecture n'a été effectuée.
Les données lues sont placées dans la zone mémoire pointée par article sur une longueur maximale de taille.
mode indique le mode de partage de l'enregistrement (P R ou F).
Pour les fichiers de type U, les tabulations ($09) sont décondensées en espaces. La taille des tabulations est fixée à 8 caractères.
Si le fichier est de type séquentiel-indexé, la lecture se fait d'après la clé courante et la fin de fichier est provoquée par la fin de la clé en cours.
Il est possible de modifier la clé avant d'utiliser la fonction xisam_treadlong pour se positionner directement sur un enregistrement. L'enregistrement lu est alors celui dont la clé est supérieure ou égale à la clé placée dans la TDF.
Compte-rendu :
0: pas d'erreur.
E_EOF: fin de fichier.
E_SHARE : enregistrement réservé.
Autres: Code d'erreur système.
5.6 xisam_tpreadlong
Syntaxe :
#include "xisam.h"
ushort xisam_tpreadlong(ushort ntache, TDF51 * tdf,uchar * article,ushort taille, uchar * mode)
Description :
xisam_tpreadlong permet de lire l'enregistrement précédant le dernier enregistrement lu.
Les données lues sont placées dans la zone mémoire pointée par article sur une longueur maximale de taille.
mode indique le mode de partage de l'enregistrement (P R ou F).
Si le fichier est de type séquentiel-indexé, la lecture se fait d'après la clé courante et la fin de fichier est provoquée par la fin de la clé en cours.
Il est possible de modifier la clé avant d'utiliser la fonction xisam_tpreadlong pour se positionner directement sur un enregistrement. L'enregistrement lu est alors celui dont la clé est inférieure ou égale à la clé placée dans la TDF.
Compte-rendu :
0: pas d'erreur.
E_EOF: début de fichier.
E_SHARE: enregistrement réservé.
Autres: Code d'erreur système.
5.7 xisam_tseeklong / xisam_tseek2long
Syntaxe :
#include "xisam.h"
ushort xisam_tseeklong(ushort ntache, TDF51 * tdf,uchar * article,ushort taille, uchar * mode)
ushort xisam_tseek2long(ushort ntache, TDF51 * tdf,uchar * article,ushort taille, uchar * mode)
Description :
xisam_tseeklong et xisam_tseek2long ne sont utilisables qu'avec les fichiers normaux avec enregistrements de taille fixe ou avec les fichiers séquentiels indexés.
Les données lues sont placées dans la zone mémoire pointée par article sur une longueur maximale de taille.
mode indique le mode de partage de l'enregistrement (P R ou F).Pour les Fichier séquentiel Indexé.*
xisam_tseeklong permet de lire un enregistrement à partir d'une clé. La clé de recherche doit avoir été positionnée par le programme dans la tdf.
S'il existe au moins un enregistrement correspondant à la clé, le premier enregistrement correspondant est lu.
S'il n'existe pas d'enregistrement correspondant à la clé, l'enregistrement suivant est lu, mais la fonction renvoie l'erreur E_RECABS. S'il n'y avait pas d'enregistrement suivant, le premier caractère de la clé est positionnée à espace et la fonction renvoie E_RECABS.
xisam_tseek2long permet de lire un enregistrement à partir d'une clé. La clé de recherche doit avoir été positionnée par le programme dans la tdf.
S'il existe au moins un enregistrement correspondant à la clé, aucun enregistrement est lu et la fonction renvoie E_RECABS.Fichier normal avec taille d'enregistrement fixe :*
xisam_tseeklong / xisam_tseek2long permet de lire un enregistrement à partir de son numéro relatif en décimal.
Avant l'utilisation de la fonction, le numéro d'enregistrement à lire doit être positionné dans la TDF (les 8 premiers caractères de la clé). Il se produit une erreur si cet enregistrement n'existe pas.
La numérotation des enregistrements commence à 1.
Attention : le numéro doit être en décimal et cadré à droite sur 8 caractères.
Exemple : memcpy(tdf.key," 10",8);
Compte-rendu :
0: pas d'erreur.
E_RECABS: enregistrement non trouvé.
E_SHARE: enregistrement réservé.
Autres : Code d'erreur système.
5.8 xisam_twritelong
Syntaxe :
#include "xisam.h"
ushort xisam_twritelong(ushort ntache, TDF51 * tdf,uchar * article,ushort taille, uchar * mode)
Description :
xisam_twritelong permet d'écrire un enregistrement dans un fichier.
L'enregistrement à écrire est dans la zone mémoire pointée par article sur une longueur de taille.
mode ("R" ou "P") permet de réserver l'enregistrement immédiatement après son écriture.Fichiers condensés (type U).*
Les caractères $0D $0A sont rajoutés à la fin de l'enregistrement.
Les espaces de fin ne sont pas écrits.Fichier normaux (type N) avec taille d'enregistrement variable.*
L'enregistrement est écrit avec la longueur exacte indiquée par taille.Fichier normaux (N) avec taille d'enregistrement fixe.*
L'enregistrement est écrit avec la taille prévue pour le fichier en effectuant une éventuelle troncature ou complémentation à droite par des espaces.Fichier séquentiels-indexés (I).*
L'enregistrement est écrit à la fin du fichier des données et les clés sont générées.
Compte-rendu :
0: pas d'erreur.
E_OVF: Fichier ou disque plein.
Autres: Code d'erreur système.
5.9 xisam_trewritelong
Syntaxe :
#include "xisam.h"
ushort xisam_trewritelong(ushort ntache, TDF51 * tdf,uchar * article,ushort taille)
Description :
xisam_trewritelong permet de réécrire un enregistrement dans un fichier. La réécriture n'est possible que pour les fichiers normaux et pour les fichiers séquentiels-indexés dont le fichier des données est de type normal (N).
L'enregistrement à écrire est dans la zone mémoire pointée par article sur une longueur de taille.
Dans tous les cas, la taille prise est celle du dernier enregistrement lu.
Pour les fichiers de type I, les clés sont automatiquement mises à jour.
Compte-rendu :
0: pas d'erreur.
E_OVF: Fichier ou disque plein.
Autres: Codes d'erreur système.
5.10 xisam_tdeletelong
Syntaxe :
#include "xisam.h"
ushort xisam_tdeletelong(ushort ntache, TDF51 * tdf,uchar * article,ushort taille)
Description :
xisam_tdeletelong permet de supprimer le dernier enregistrement lu. La suppression n'est possible que pour les fichiers séquentiels-indexés dont le fichier des données est de type normal (N).
L'enregistrement à supprimer est dans la zone mémoire pointée par article sur une longueur de taille.
Toutes les clés de l'enregistrement sont supprimées du fichier des clés et les données sont mises à espace dans le fichier des données. La place des enregistrements supprimés n'est pas récupérée.
Compte-rendu :
0: pas d'erreur.
Autres: Code d'erreur système.
5.11 xisam_trecord_libt
Syntaxe :
#include "xisam.h"
ushort xisam_trecord_libt (ushort ntache,uchar * ticket )
Description :
La fonction libère tous les enregistrements réservés avec le ticket spécifié.
Cette fonction n'est pas liée à un fichier en particulier.
Compte-rendu :
0: pas d'erreur.
Autres: Code d'erreur système.
5.12 xisam_trecord_liball
Syntaxe :
#include "xisam.h"
ushort xisam_trecord_liball (ushort ntache)
Description :
La fonction libère tous les enregistrements réservés par une tâche.
Compte-rendu :
0: Pas d'erreur.
Autres: Code d'erreur système.
5.13 xisam_pack
Syntaxe :
#include "xisam.h"
ushort xisam_pack(ushort ntache,uchar * destination,ushort ld,uchar * depart)
Description :
La fonction compresse les caractères de la chaîne numérique de départ dans la chaîne destination. La longueur ld indique la taille de la chaîne packée.
Compte-rendu :
0: Pas d'erreur.
Autres: Code d'erreur système.
5.14 xisam_unpack
Syntaxe :
#include "xisam.h"
ushort xisam_unpack(ushort ntache,uchar * destination,ushort lgdest,uchar * depart, ushort ldep)
Description :
La fonction décompresse les caractères de la chaîne numérique départ dans la chaîne destination. La longueur ldep indique la taille de la chaîne packée. Normalement la valeur de ldest doit être le double de ldep.Attention, la fonction ne fait pas de vérification de la cohérence des longueurs.
Compte-rendu :
0: Pas d'erreur.
Autres: Code d'erreur système.
6. LES FONCTIONS DE RESERVATIONS D'ENTITES
La fonction de réservation d'entité SHAREM en DIVA est incluse dans la bibliothèque xisam.
6.1 xisam_obj_tsharelong
Syntaxe :
#include "xisam.h"
ushort xisam_obj_tsharemlong(unsigned short ntache,
TDF51 * tdflong,
unsigned char * art,
unsigned short l,
unsigned char * mode);
Description :
La fonction xisam_obj_tsharemlong libère ou réserve l'entité contenue dans art.
mode peut valeur les valeurs suivantes:
"R": réservation exclusive de l'entité, aucun autre programme ne peut réserver cette
entité même en mode "P"
( mode 1 seul programme écrit)
"L" : libération de l'entité
"P": réservation partagée de l'entité , d'autres programmes peuvent réserver cette
entité en mode "P" mais pas en mode "R". Un programme qui réserverait cette entité en
mode "R" aurait une erreur
Ce mode indique que l'on veut réservé une entité mais
( mode n programmes peuvent lire mais pas écrire)
"F": réservation "forcée" de l'entité. Un programme peut réserver en mode "P" une
entité puis passer de façon provisoire en mode "F" un court instant , le temps
de mettre à jour une information puis revenir en mode "P" sur cette même
entité. Ainsi une autre programme peut réserver cette entité en mode "P" mais s'il cherche
à passer en mode "F" , il aura une erreur indiquant qu'un autre programme est passé en
mode "F" sur cette entité.
( mode n programmes peuvent lire mais 1 seul peut écrire)
La libération ou la réservation se fait sur la machine où se trouve le fichier préalablement ouvert dans tdf.
La taille des entités est limitée à 260 caractères.
Le premier caractère doit être à espaces.
Compte-rendu :
0: Pas d'erreur.
E_SHARE: entité déjà réservée.
Autres: Code d'erreur système.
7. EXEMPLE DE PROGRAMME EN C
Vous trouverez dans le source "testxis.c" un exemple réel de programme écrit pour Windows utilisant les fonctions de lecture et d'écriture d'un fichier Divalto.
8. INTERFACE AVEC VISUAL BASIC
Les fonctions de la DLL dhXisam peuvent également être appelées depuis un programme écrit en VISUAL BASIC.
8.1 STRUCTURE DE LA TDF
La TDF est une chaîne de caractères de 1024 octets. Elle doit être déclarée comme suit :
Dim Tdf As String * 1024
Le "découpage" de cette chaîne est identique à celle du C.
8.2 LES PARAMETRES
Les paramètres utilisés par les fonctions DhXisam sont de deux natures :
des chaînes de caractères de TAILLE FIXE (String * n),
des entiers courts sur 16 bits (Integer).
Toutes les chaînes de caractères utilisées comme argument des fonctions DhXisam doivent donc être déclarées avec une taille fixe.
8.3 INCLUSION DE SOURCES
Le fichier "defxisam.txt" doit être inclus dans le projet du programme Visual Basic. Il contient la déclaration des fonctions de la DLL, celles-ci sont strictement identiques aux fonctions C. Elles sont simplement définies en Visual Basic dans le fichier desxisam.txt
8.4 FONCTIONS DE LA DLL
Le fichier defxisam.txt contient les prototypes des fonctions de la DLL.
Pour la description de la fonction, reportez-vous aux chapitres précédents.