FilePut, fonction

Article
09/12/2008

Mise à jour : novembre 2007

Écrit les données d'une variable dans un fichier disque.

La fonctionnalité My permet une meilleure productivité et de meilleures performances dans les opérations d'E/S sur fichier que FilePut. Pour plus d'informations, consultez My.Computer.FileSystem, objet.

Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Short, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Integer, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Single, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Double, _
      RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Decimal, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Byte, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Boolean, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As Date, _
   Optional RecordNumber As Integer = -1 _
)
' -or-
Public Overloads Sub FilePut( _
      FileNumber As Integer, _
      Value As System.Array, _
   Optional RecordNumber As Integer = -1, _
   Optional ArrayIsDynamic As Boolean = False _
)
' -or-
Public Overloads Sub FilePut (
      FileNumber As Integer, 
      Value As String, _
   Optional RecordNumber As Integer = -1, 
   Optional StringIsFixedLength As Boolean = False
)

Paramètres

FileNumber
Requis. Tout numéro de fichier valide.
Value
Requis. Nom de variable valide contenant les données écrites sur le disque.
RecordNumber
Facultatif. Numéro de l'enregistrement (fichiers ouverts en mode Random) ou de l'octet (fichiers ouverts en mode Binary) qui marque le débute de l'écriture.
ArrayIsDynamic
Facultatif. S'applique uniquement à l'écriture d'un tableau. Spécifie si le tableau doit être considéré comme dynamique et s'il est nécessaire d'écrire un descripteur de tableau pour la chaîne décrivant la longueur.
StringIsFixedLength
Facultatif. S'applique uniquement lors de l'écriture d'une chaîne. Spécifie s'il est nécessaire d'écrire dans le fichier un descripteur à deux octets pour la chaîne décrivant la longueur. La valeur par défaut est False.

Exceptions

Type d'exception	Numéro de l'erreur	Condition
ArgumentException	63	RecordNumber est inférieur à 1 et différent de -1.
IOExceptio	52	FileNumber n'existe pas.
IOException	54	Le mode de fichier est non valide.

Consultez la colonne « Numéro d'erreur » si vous mettez à niveau des applications Visual Basic 6.0 qui utilisent la gestion des erreurs non structurée. (Vous pouvez comparer le numéro d'erreur par rapport à Number, propriété (objet Err).) Toutefois, lorsque cela est possible, vous devez envisager de remplacer un tel contrôle d'erreur par Vue d'ensemble de la gestion structurée des exceptions pour Visual Basic.

Notes

FilePut est seulement valide en mode Random et Binary.

Les données écrites avec FilePut sont généralement lues à partir d'un fichier à l'aide de FileGet.

Le premier enregistrement ou octet d'un fichier occupe la position 1, le deuxième enregistrement ou octet la position 2, et ainsi de suite. Si l'argument RecordNumber est omis, l'écriture commence à partir de l'enregistrement ou de l'octet suivant la dernière fonction FileGet ou FilePut (ou à partir de celui désigné par la dernière fonction Seek).

L'argument StringIsFixedLength contrôle si la fonction interprète des chaînes comme variable ou à longueur fixe. FilePut n'écrit pas le descripteur de longueur lorsque l'argument est True. Si vous utilisez StringIsFixedLength = True avec FilePut, vous devez en faire de même avec FileGet et vous devez en outre vous assurer que la chaîne est initialisée à la longueur attendue.

Mode Random

Les règles suivantes s'appliquent aux fichiers ouverts en mode Random :

Si la longueur des données écrites est inférieure à la longueur spécifiée dans la clause RecordLength de la fonction FileOpen, la fonction FilePut poursuit l'écriture des enregistrements suivants conformément aux limites de longueur des enregistrements. L'espace compris entre la fin d'un enregistrement et le début de l'enregistrement suivant est rempli par le contenu de la mémoire tampon du fichier. Comme il est impossible de déterminer avec certitude le volume des données de remplissage, il est généralement préférable que la longueur des enregistrements corresponde à la longueur des données écrites. Une exception est levée si la longueur des données écrites est supérieure à celle spécifiée dans la clause RecordLength de la fonction FileOpen.
Si la variable écrite est une chaîne, la fonction FilePut écrit d'abord un descripteur à deux octets contenant la longueur de la chaîne, puis les données qui sont placées dans la variable. La longueur d'enregistrement spécifiée par la clause RecordLength de la fonction FileOpen doit donc être supérieure d'au moins deux octets à la longueur réelle de la chaîne.
Si la variable écrite est un objet contenant un type numérique, la fonction FilePut écrit d'abord deux octets qui identifient le VarType de l'objet puis la variable. Par exemple, lorsque vous écrivez un objet contenant un entier, FilePut écrit six octets : deux octets identifiant l'objet comme VarType(3) (Integer) et quatre octets contenant les données. La longueur d'enregistrement spécifiée par le paramètre RecordLength dans la fonction FileOpen doit être supérieure d'au moins deux octets au nombre réel d'octets requis pour stocker la variable.
Si la variable écrite est un objet contenant une chaîne, FilePut écrit un descripteur à deux octets identifiant le VarType(8) de l'objet, un descripteur à deux octets indiquant la longueur de la chaîne, puis la chaîne de données. La longueur d'enregistrement spécifiée par le paramètre RecordLength dans la fonction FileOpen doit être supérieure d'au moins quatre octets à la longueur réelle de la chaîne. Si vous souhaitez placer une chaîne sans descripteur, vous devez passer la valeur True au paramètre StringIsFixedLength de sorte que la chaîne lue soit de la longueur voulue.
Si la variable écrite est un tableau, vous avez la possibilité d'écrire ou non un descripteur pour la taille et les dimensions du tableau. Visual Basic 6.0 et les versions antérieures écrivent le descripteur de fichier pour un tableau dynamique, mais pas pour un tableau de taille fixe. Par défaut, Visual Basic 2005 n'écrit pas le descripteur. Pour écrire le descripteur, affectez la valeur True au paramètre ArrayIsDynamic. Lorsque vous écrivez le tableau, vous devez faire correspondre le mode de lecture du tableau ; s'il est lu par le descripteur, vous devez écrire ce dernier. Le descripteur spécifie le rang du tableau, la taille et les limites inférieures de chaque rang. Sa longueur est égale à 2 plus 8 fois le nombre de dimensions : (2 + 8 * NumberOfDimensions). La longueur d'enregistrement spécifiée par la clause RecordLength dans la fonction FileOpen doit être supérieure ou égale à la somme de tous les octets nécessaires à l'écriture des données et du descripteur du tableau. Par exemple, la déclaration de tableau suivante nécessite 118 octets pour l'écriture du tableau sur le disque.
```
Dim MyArray(4,9) As Integer
```
Si la variable écrite est d'un type différent (ni une chaîne de longueur variable ni un objet), la fonction FilePut n'écrit que les données variables. La longueur d'enregistrement spécifiée par la clause RecordLength dans la fonction FileOpen doit être supérieure ou égale à la longueur des données écrites.
FilePut écrit les éléments de structures comme si chacun d'entre eux était écrit individuellement, sauf qu'il n'y a pas de remplissage entre les éléments. L'attribut VBFixedString peut être appliqué aux champs de type chaîne dans les structures pour indiquer la taille de la chaîne lors de l'écriture sur le disque.

Remarque :

Les champs de chaîne dont le nombre d'octets est supérieur au nombre spécifié par l'attribut VBFixedString sont tronqués lors de l'écriture sur le disque,

Remarque :
Les champs de chaîne dont le nombre d'octets est supérieur au nombre spécifié par l'attribut VBFixedString sont tronqués lors de l'écriture sur le disque,

Mode Binary

Pour les fichiers ouverts en mode Binary, la plupart des règles du mode Random s'appliquent, à quelques exceptions près. Les règles suivantes pour les fichiers ouverts en mode Binary diffèrent des règles appliquées au mode Random :

La clause RecordLength de la fonction FileOpen n'a aucun effet. La fonction FilePut écrit toutes les variables sur le disque de manière contiguë, c'est-à-dire sans remplissage entre les enregistrements.
Pour tout tableau autre que ceux d'une structure, la fonction FilePut n'écrit que les données. Elle n'écrit aucun descripteur.
La fonction FilePut écrit les chaînes de longueur variable qui ne sont pas des éléments de structure, sans le descripteur à deux octets. Le nombre d'octets écrits est égal au nombre de caractères de la chaîne. Par exemple, les instructions suivantes écrivent 11 octets dans le fichier numéro 1 :
```
Dim hellow As String = "Hello World"
FilePut(1,hellow)
```
L'écriture sur fichier à l'aide de la fonction FilePut requiert l'accès Write à partir de l'énumération FileIOPermissionAccess.

Exemple

Cet exemple utilise la fonction FilePut pour écrire des données dans un fichier. Cinq enregistrements de la structure Person sont écrits dans le fichier.

Structure Person 
   Public ID As Integer
   Public Name As String
End Structure

Sub WriteData()
   Dim PatientRecord As Person
   Dim recordNumber As Integer    
'    Open file for random access.
   FileOpen(1, "C:\TESTFILE.txt", OpenMode.Binary)
   ' Loop 5 times.
   For recordNumber = 1 To 5 
      ' Define ID.
      PatientRecord.ID = recordNumber   
      ' Create a string.
      PatientRecord.Name = "Name " & recordNumber
      ' Write record to file.
      FilePut(1, PatientRecord)
   Next recordNumber
   FileClose(1)
End Sub