Présentation des documents système

Tous les documents et applications que vous utilisez sur votre ordinateur sont stockés en tant que fichiers sur le ou les disques durs connectés ou montés sur votre ordinateur, ou encore sur des disquettes et autres supports de stockage permanent. Dans cette documentation ainsi que dans 4D, les termes fichier ou document sont indifféremment employés pour désigner ces documents et applications. Cependant, la plupart des commandes de ce thème utilisent le mot document car, généralement, vous les utiliserez pour accéder à des documents (par opposition à des fichiers d'application ou des fichiers système) sur disque.

Un disque dur peut être formaté de manière à comporter une ou plusieurs partitions. Chaque partition s'appelle un volume. Peu importe que ces volumes soient des partitions physiquement présentes sur le même disque dur ou non, au niveau de 4D, ces volumes sont considérés comme des entités séparées et équivalentes.

Un volume peut être situé sur un disque dur physiquement connecté à votre machine ou monté par le réseau par l'intermédiaire d'un protocole de partage de fichiers tel que TCP/IP, AFP ou SMB (Macintosh). Quel que soit le cas, au niveau de 4D, ces volumes sont considérés de la même façon lorsque vous utilisez les commandes du thème Documents Système (à moins que vous n'en décidiez autrement et utilisiez des plug-ins 4D pour étendre les capacités de votre application dans ce domaine).

Chaque volume a un nom de volume. Sous Windows, les volumes sont désignés par une lettre suivie de deux points. Généralement, C: et D: désignent les volumes que vous utilisez pour lancer votre système (à moins que vous n'ayez configuré votre PC différemment). Ensuite, les lettres E: à Z: sont utilisées pour les volumes supplémentaires connectés à votre PC (lecteurs DVD, autres lecteurs, lecteurs réseau, etc.). Sous Mac OS, les volumes ont des noms communs (ces noms sont ceux que vous visualisez sur le bureau au niveau du Finder).

Normalement, vous classez vos documents dans des dossiers qui peuvent eux-mêmes contenir d'autres dossiers. Il n'est pas conseillé d'accumuler des centaines ou des milliers de fichiers au même niveau d'un volume. C'est un fouillis, qui de plus qui ralentit votre système. Sous Windows, un dossier est parfois encore appelé un “répertoire”.

Pour identifier un document de manière certaine, vous avez besoin de connaître le nom du volume, le nom du ou des dossiers(s) dans le(s)quel(s) se trouve le document, ainsi que le nom du document lui-même. Si vous concaténez tous ces noms, vous obtenez le chemin d'accès à ce document. Dans le nom de ce chemin, les noms de dossiers sont séparés par un caractère spécial appelé séparateur de dossier. Sous Windows, ce caractère est la barre oblique inversée \, sous Mac OS ce sont les deux-points :

Examinons un exemple. Vous disposez d'un document Important situé dans le dossier Mémos, lui-même situé dans le dossier Documents, lui-même situé dans le dossier EnCours.

Si, sous Windows, l'ensemble est situé sur le volume C: , le chemin d'accès au document est donc :
C:\EnCours\Documents\Mémos\Important.TXT

Note : Le caractère \ est également utilisé par l'éditeur de méthodes de 4D pour désigner des séquences d'échappement. Pour éviter tout problème d'interprétation, l'éditeur transforme automatiquement les chemins d'accès du type C:\Disque en C:\\Disque. Pour plus d'informations, reportez-vous ci-dessous au paragraphe “Spécification des noms et chemins d'accès des documents”.

Si, sous Mac OS, l'ensemble est situé sur le volume Interne, le chemin d'accès au document est donc :
Interne:EnCours:Documents:Mémos:Important

Notez que, sous Windows, avec cet exemple, le nom du document contient le suffixe .TXT. Nous verrons pourquoi plus loin dans cette section.

Quelle que soit la plate-forme, le chemin d'accès à un document peut être exprimé sous la forme suivante : VolNom DosSep { DosNom DosSep { DosNom DosSep { ... } } } DocNom.

Tous les documents (fichiers) situés sur des volumes ont plusieurs caractéristiques généralement appelées attributs ou propriétés : par exemple le nom du document lui-même.

Un document est ouvert en mode lecture/écriture, ouvert en mode lecture ou fermé. Avec les commandes 4D, un document ne peut être ouvert en mode lecture/écriture que par un process à la fois. Un process peut ouvrir plusieurs documents, plusieurs process peuvent ouvrir de multiples documents, vous pouvez ouvrir un même document en mode lecture autant de fois que nécessaire, mais vous ne pouvez pas ouvrir le même document en mode lecture/écriture deux fois en même temps.

Vous ouvrez un document à l'aide des fonctions Open document, Create document et Append document. Les fonctions Create document et Append document ouvrent automatiquement les documents en mode lecture/écriture. Seule la fonction Open document permet de choisir le mode d'ouverture.
Une fois que le document est ouvert en lecture/écriture, vous pouvez lire et écrire des caractères dans ce document (cf. les commandes RECEIVE PACKET et SEND PACKET). Lorsque vous en avez terminé avec un document, il est préférable de le fermer — avec la commande CLOSE DOCUMENT.

Tous les documents ouverts sont désignés au moyen de l'expression RefDoc, retournée par les commandes Open document, Create document et Append document. Une RefDoc identifie de façon unique un document ouvert. C'est une expression de type Heure. Toutes les commandes fonctionnant avec des documents ouverts attendent une RefDoc comme paramètre. Si vous passez une RefDoc incorrecte à l'une de ces commandes, une erreur du gestionnaire de fichiers est générée.

Note : Lorsqu'elle est appelée depuis un process préemptif, une référence RefDoc est utilisable uniquement depuis ce process préemptif. Lorsqu'elle est appelée depuis un process coopératif, une référence RefDoc est utilisable depuis n'importe quel autre process coopératif.

Quand vous accédez à des documents (ouverture, fermeture, suppression, changement de nom, copie), quand vous modifiez les propriétés d'un document ou quand vous lisez et écrivez des caractères dans un document, des erreurs d'entrée/sortie (E/S) peuvent se produire. Un document peut ne pas avoir été trouvé ; il peut être verrouillé ; il peut être déjà ouvert en écriture. Vous pouvez repérer ces erreurs grâce à une méthode de gestion des erreurs installée par la commande ON ERR CALL. La plupart des erreurs qui peuvent se produire lors de l'utilisation des commandes du thème documents système est décrite dans la section Erreurs du gestionnaire de fichiers du système (-124 -> -33).

Les commandes Open document, Create document, Append document et Select document vous permettent d'accéder à un document par les boîtes de dialogue standard d'ouverture ou d'enregistrement de fichiers. Quand vous accédez à un document par ces boîtes de dialogue standard, 4D retourne le chemin d'accès complet du document dans la variable système Document. Ne confondez pas cette variable système avec le paramètre document qui apparaît dans la liste des paramètres des commandes.

Vous trouverez des informations supplémentaires concernant la variable système Document dans la section Variables système.

La plupart des routines de cette section attendant un nom de document acceptent à la fois un nom et un chemin d'accès au document (*). Si vous passez un nom, la commande cherche le document dans le dossier de la base. Si vous passez un chemin d'accès, il doit être valide.

Si vous passez un nom ou un chemin d'accès incorrect, la commande génère une erreur du gestionnaire de fichiers que vous pouvez intercepter avec une méthode d'ON ERR CALL.

(*) sauf cas contraire spécifié explicitement.

L’éditeur de méthodes de 4D permet d’utiliser des séquences d’échappement. Une séquence d’échappement est une suite de caractères permettant de remplacer un caractère “spécial”. La séquence débute par le caractère barre oblique inversée (antislash) \, suivi d’un caractère. Par exemple, \t est une séquence d’échappement pour le caractère Tabulation.
Le caractère \ est aussi utilisé comme séparateur dans les chemins d’accès sous Windows. En général, 4D interprétera correctement les chemins d’accès Windows saisis dans l’éditeur de méthodes en remplaçant automatiquement les barres simples \ par des doubles barres \\. Par exemple, C:\Dossier deviendra C:\\Dossier.
Toutefois, si vous écrivez C:\MesDocuments\Nouveaux, 4D affichera C:\\MesDocuments\Nouveaux. Dans ce cas, le second \ est incorrectement interprété \N (séquence d’échappement existante). Vous devez donc saisir un double \\ lorsque vous souhaitez insérer une barre oblique inversée devant un caractère utilisé dans une des séquences d’échappement reconnues par 4D.

Les séquences d’échappement reconnues par 4D sont les suivantes :

La plupart des commandes 4D de gestion des documents et des dossiers acceptent des chemins d'accès relatifs ou absolus :

• Les chemins d'accès relatifs définissent un emplacement par rapport à un dossier présent sur le disque. Dans 4D, les chemins d'accès relatifs sont généralement exprimés par rapport au dossier de la base, c'est-à-dire au dossier contenant le fichier de structure. Les chemins d'accès relatifs sont particulièrement utiles pour le déploiement d'applications en environnement hétérogène. 
• Les chemins d'accès absolus définissent un emplacement à partir de la racine d'un volume. Ils ne dépendent pas de la position courante du dossier de la base.

Pour déterminer si un chemin d'accès passé à une commande doit être interprété en tant que chemin relatif ou absolu, 4D applique un algorithme spécifique pour chaque plate-forme.

Si le paramètre contient seulement deux caractères et si le deuxième est un ':',
    ou si le texte contient ':' et '\' comme deuxième et troisième caractère,
    ou si le texte débute par "\\",
alors le chemin d'accès est absolu.       

Dans tous les autres cas, le chemin d'accès est relatif.

Exemples avec la commande CREATE FOLDER :

Si le texte débute par un séparateur de dossier ':',
    ou s'il n'en contient aucun,
alors le chemin est relatif.

Dans tous les autres cas, il est absolu.

Exemples avec la commande CREATE FOLDER :

• Détecter sur quelle plate-forme vous opérez

Bien que 4D fournisse des commandes telles que MAP FILE TYPES destinées à éliminer les modifications de code liées aux particularités des plates-formes, lorsque vous commencez à travailler à un plus bas niveau en manipulant des documents sur disque, par exemple lorsque vous obtenez les chemins d'accès par programmation, vous avez besoin de savoir si vous fonctionnez sous Windows ou Mac OS.

La méthode projet Sous Windows listée ci-dessous vous permet de savoir si votre base tourne sous Windows :

• Extraire le nom de fichier d'un chemin d'accès complet (ou "nom long")

Une fois que vous avez récupéré le "nom long" d'un fichier (c'est-à-dire le chemin d'accès+le nom du fichier), vous pouvez avoir besoin d'en extraire le nom du fichier seul, par exemple pour l'afficher comme titre d'une fenêtre. La méthode projet Nom long vers nom de fichier vous le permet, sous Windows et Mac OS.

• Extraire le chemin d'accès seul du chemin d'accès complet (ou "nom long")

Une fois que vous avez récupéré le "nom long" d'un fichier (c'est-à-dire le chemin d'accès+le nom du fichier), vous pouvez avoir besoin d'en extraire uniquement le chemin d'accès au fichier, par exemple pour sauvegarder d'autres documents au même endroit. La méthode projet Nom long vers chemin accès vous le permet, sous Windows et Mac OS.