Sie sind auf Seite 1von 11

libdoc_d.dot / V1.0

libdoc_d.dot / V1.0 Bibliotheksbeschreibung: CoDeSys V 3.x SysFile.library Dokument Version 2.0  3S - Smart Software
libdoc_d.dot / V1.0 Bibliotheksbeschreibung: CoDeSys V 3.x SysFile.library Dokument Version 2.0  3S - Smart Software

Bibliotheksbeschreibung:

CoDeSys V 3.x SysFile.library

Dokument Version 2.0

Bibliothek SysFile.library

libdoc_d.dot / V1.0

INHALT

1 ÜBERBLICK

3

2 BIBLIOTHEKSBAUSTEINE

4

2.1 SysFileClose

4

2.2 SysFileCopy

4

2.3 SysFileDelete

4

2.4 SysFileDeleteByHandle

5

2.5 SysFileEOF

5

2.6 SysFileGetName

5

2.7 SysFileGetName2

5

2.8 SysFileGetPath

6

2.9 SysFileGetPos

6

2.10 SysFileGetSize

6

2.11 SysFileGetSizeByHandle

7

2.12 SysFileGetStatus

7

2.13 SysFileGetStatus2

7

2.14 SysFileGetTime

7

2.15 SysFileOpen

8

2.16 SysFileRead

8

2.17 SysFileRename

8

2.18 SysFileSetPos

9

2.19 SysFileWrite

9

2.20 Enumeration AccessMode

9

2.21 Struktur FileInfo

10

2.22 Enumeration FileStatus

10

2.23 Struktur FileTime

10

ÄNDERUNGSHISTORIE

11

Bibliothek SysFile.library

libdoc_d.dot / V1.0

1

Überblick

Hinweis: Es hängt vom verwendeten Zielsystem ab, welche Systembibliotheken im Steuerungsprogramm verwendet werden können.

Diese Bibliothek unterstützt synchrone Dateizugriffe auf dem Zielrechner. Wenn das Zielsystem die Funktionalität beinhaltet, können die Bibliotheksfunktionen verwendet werden, um Dateien zu öffnen, zu schließen, zu löschen, umzubenennen und Daten in Dateien zu schreiben oder auszulesen. Weitere Funktionen dienen dem Ermitteln der Dateigröße oder des Zeitpunkts des letzten Zugriffs, wie auch dem Feststellen bzw. Verändern des aktuellen Offsets.

Achtung: Bitte beachten Sie, dass Dateizugriffe das Echtzeitverhalten beeinträchtigen können!

SysFileClose

SysFileCopy

SysFileDelete

SysFileDeleteByHandle

SysFileEOF

SysFileGetName

SysFileGetName2

SysFileGetPath

SysFileGetPos

SysFileGetSize

SysFileGetSizeByHandle

SysFileGetStatus

SysFileGetStatus2

SysFileGetTime

SysFileOpen

SysFileRead

SysFileRename

SysFileSetPos

SysFileWrite

Die Funktionen verwenden folgende Strukturen und Enumerationen:

AccessMode

FileInfo

FileStatus

FileTime

Bibliothek SysFile.library

libdoc_d.dot / V1.0

2

Bibliotheksbausteine

 

2.1

SysFileClose

 

Diese Funktion dient dem Schließen einer Datei, die mit SysFileOpen geöffnet wurde. Die Datei wird über ihre Dateinummer (Handle) identifiziert, die von SysFileOpen zurückgegeben wird.

Der Rückgabewert ist vom Typ UDINT und liefert einen Fehler-Code, der über den Erfolg der Operation Auskunft gibt. Siehe hierzu das Dokument „Runtime Error Codes“.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Datei-Nummer (siehe SysFileOpen)

2.2

SysFileCopy

 
 

Diese Funktion dient dazu, den Inhalt einer Quelldatei in eine Datei mit anderem Namen (Zieldatei) zu kopieren.

Der Rückgabewert ist ein Fehler-Code, der Auskunft über Erfolg (=1) oder Misserfolg (=0) der Operation gibt.

Input-Variable

Datentyp

Beschreibung

szDestFileName

REFERENCE TO

Name der Zieldatei, in die kopiert werden soll. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Verzeichnisse müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

STRING

szSourceFileName

REFERENCE TO

Name der Quelldatei, aus der kopiert werden soll. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Verzeichnisse müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

STRING

puiCopied

POINTER TO

Zeiger auf eine Variable. In diese Variable wird die Anzahl der tatsächlich kopierten Bytes geschrieben.

UDINT

2.3

SysFileDelete

 

Diese Funktion dient dem Löschen einer Datei, die über ihren Namen identifiziert wird.

Der Rückgabewert ist ein Fehler-Code, der Auskunft über Erfolg oder Misserfolg der Operation gibt.

Input-Variable

Datentyp

Beschreibung

szFileName

REFERENCE TO

Name der Datei, die gelöscht werden soll. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Verzeichnisse müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

STRING

Bibliothek SysFile.library

libdoc_d.dot / V1.0

2.4 SysFileDeleteByHandle

Diese Funktion dient dem Löschen einer Datei, welche über ihre Dateinummer (Handle) identifiziert wird.

Der Rückgabewert ist ein Fehler-Code, der Auskunft über Erfolg oder Misserfolg der Operation gibt.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, die gelöscht werden soll (siehe SysFileOpen).

2.5 SysFileEOF

Diese Funktion gibt Auskunft darüber, ob der Dateizeiger am Ende der angegebenen Datei steht. Dazu wird die Datei über ihre Dateinummer (Handle) identifiziert.

Der Rückgabewert ist ein Fehler-Code, der Auskunft über Erfolg oder Misserfolg der Operation gibt.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, die untersucht werden soll (siehe SysFileOpen).

2.6 SysFileGetName

Diese Funktion gibt Auskunft über den Namen einer Datei, die dazu über ihre Dateinummer (Handle) identifiziert wird.

Der Rückgabewert vom Typ REFERENCE TO STRING enthält den Dateinamen.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, deren Name ausgegeben werden soll (siehe SysFileOpen).

2.7 SysFileGetName2

Diese Funktion gibt Auskunft über den Namen einer Datei, die dazu über ihre Dateinummer (Handle) identifiziert wird.

Der Rückgabewert vom Typ REFERENCE TO STRING enthält den Dateinamen.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, deren Name ausgegeben werden soll (siehe SysFileOpen).

pResult

POINTER TO

Zeiger auf Fehler-Code, siehe Dokument „Runtime Error Codes“.

UDINT

Bibliothek SysFile.library

libdoc_d.dot / V1.0

2.8 SysFileGetPath

Diese Funktion extrahiert den Dateipfad aus dem Dateinamen. Ist kein expliziter Pfad im Namen angegeben, so wird der Standardpfad zurückgegeben. Wenn ein Dateipfad im Namen enthalten ist, müssen die einzelnen Verzeichnisse mit „/“ getrennt sein, z.B.:

/CoDeSys/CoDeSys_SP_3.0/Test.txt

In diesem Beispiel würde die Funktion den Dateipfad „/CoDeSys/CoDeSys_SP_3.0/“ zurückliefern.

Der Rückgabewert vom Typ RTS_IEC_RESULT liefert einen Fehler-Code, der über den Erfolg der Operation Auskunft gibt. Siehe hierzu das Dokument „Runtime Error Codes“.

Input-Variable

Datentyp

Beschreibung

szFileName

REFERENCE TO

Name der Datei, deren Dateipfad extrahiert werden soll

STRING

szPath

REFERENCE TO

Extrahierter Pfad aus dem Dateinamen

STRING

diMaxLen

DINT

Maximale Länge, die der Pfad haben darf.

2.9 SysFileGetPos

Diese Funktion ermittelt die aktuelle Position des Dateizeigers (Offset) in einer Datei, die über ihre Dateinummer (Handle) identifiziert wird.

Der Rückgabewert ist ein Fehler-Code, der Auskunft über Erfolg oder Misserfolg der Operation gibt.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, in der Position des Zeigers ermittelt werden soll (siehe SysFileOpen).

puiPos

POINTER TO

Zeiger auf eine Variable, welche die aktuelle Position des Dateizeigers (gezählt vom Dateianfang an) enthält

UDINT

2.10 SysFileGetSize

Diese Funktion gibt Auskunft über die Größe einer Datei. Dazu wird die Datei wird über ihren Namen identifiziert.

Der Rückgabewert vom Typ UDINT enthält die Dateigröße in Bytes.

Input-Variable

Datentyp

Beschreibung

szFileName

UDINT

Name der Datei, deren Größe ermittelt werden soll. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Directories müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

pResult

POINTER TO

Zeiger auf Fehler-Code, siehe Dokument „Runtime Error Codes“.

UDINT

Bibliothek SysFile.library

libdoc_d.dot / V1.0

2.11 SysFileGetSizeByHandle

Diese Funktion gibt Auskunft über die Größe einer Datei. Dazu wird die Datei wird über ihre Dateinummer (Handle) identifiziert.

Der Rückgabewert vom Typ UDINT enthält die Dateigröße in Bytes.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, deren Größe ermittelt werden soll (siehe SysFileOpen).

pResult

POINTER TO UDINT

Zeiger auf Fehler-Code, siehe Dokument „Runtime Error Codes“.

2.12 SysFileGetStatus

Diese Funktion gibt Auskunft über den Status einer Datei. Dazu wird die Datei wird über ihre Dateinummer (Handle) identifiziert.

Der Rückgabewert ist vom Typ FileStatus, einer Enumeration zur Verwaltung der möglichen Status-Werte (siehe Kap. 2.22).

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, deren Status ermittelt werden soll (siehe SysFileOpen).

2.13 SysFileGetStatus2

Diese Funktion gibt Auskunft über den Status einer Datei. Dazu wird die Datei wird über ihre Dateinummer (Handle) identifiziert.

Der Rückgabewert ist vom Typ FileStatus, einer Enumeration zur Verwaltung der möglichen Status-Werte (siehe Kap. 2.22).

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der Datei, deren Status ermittelt werden soll (siehe SysFileOpen).

pResult

POINTER TO

Zeiger auf Fehler-Code, siehe Dokument „Runtime Error Codes“.

UDINT

2.14 SysFileGetTime

Diese Funktion liefert den Zeitpunkt der Erstellung, des letzten Zugriffs oder der letzten Modifikation einer Datei. Dazu wird die Datei über ihren Namen angegeben und der gewünschte Datumstyp über die Enumeration FileTime.

Der Rückgabewert vom Typ UDINT enthält das angeforderte Datum im TIME Format.

Input-Variable

Datentyp

Beschreibung

szFileName

REFERENCE

Name der Datei, für die das gewünschte Datum ermittelt werden soll. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Directories müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

TO STRING

ptFileTime

POINTER TO

Zeiger auf die Struktur FileTime. Diese Struktur enthält die abgefragten Daten (siehe Kap. 0).

FileTime

3S - Smart Software Solutions GmbH

SysFile_V3x_D.doc

Seite 7 von 11

Bibliothek SysFile.library

libdoc_d.dot / V1.0

2.15 SysFileOpen

Diese Funktion dient dem Öffnen einer bereits bestehenden oder neu zu generierenden Datei.

Der Rückgabewert ist eine 'Datei-Nummer' (Handle), die in anderen Bibliotheksfunktionen SysFileWrite, SysFileRead, SysFileClose, usw. als Eingabe ('hFile') benötigt wird. Konnte die Datei nicht geöffnet bzw. erzeugt werden, wird ein ungültiges Handle zurückgegeben (16#FFFFFFFF). Der Parameter pResult enthält einen entsprechenden Fehler-Code.

Input-Variable

Datentyp

Beschreibung

szFile

REFERENCE TO

Name der zu öffnenden Datei. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Directories müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

STRING

am

AccessMode

Gewünschte Zugriffsart, siehe Enumeration AccessMode (2.20).

pResult

POINTER TO

Pointer auf Fehler-Code, siehe Dokument „Runtime Error Codes“

UDINT

2.16 SysFileRead

Diese Funktion dient zum Lesen einer Datei, die zuvor mit SysFileOpen geöffnet wurde.

Der Rückgabewert vom Typ UDINT enthält die Anzahl der erfolgreich gelesenen Bytes.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der zu lesenden Datei (siehe SysFileOpen).

pbyBuffer

POINTER TO BYTE

Adresse des Buffers, an den die gelesenen Daten geschrieben werden sollen (ermittelbar mit Hilfe des Operators ADR).

uiSize

UDINT

Anzahl der Bytes, die aus der Datei gelesen werden sollen. Die Anzahl darf die Größe des Buffers nicht überschreiten.

pResult

POINTER TO

Pointer auf Fehler-Code, siehe Dokument „Runtime Error Codes“.

UDINT

2.17 SysFileRename

Diese Funktion dient dem Umbenennen einer Datei.Der Rückgabewert ist ein Fehler-Code, der Auskunft über Erfolg oder Misserfolg der Operation gibt.

Input-Variable

Datentyp

Beschreibung

szOldFileName

REFERENCE TO

Bisheriger Name der Datei. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Directories müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

STRING

szNewFileName

REFERENCE TO

Neuer Name der Datei. Der Dateinamen kann den absoluten oder relativen Pfad enthalten. Die Directories müssen dabei durch ‚/’ getrennt werden (und nicht durch ‚\’).

STRING

Bibliothek SysFile.library

libdoc_d.dot / V1.0

2.18 SysFileSetPos

Diese Funktion dient dazu, den aktuellen Offset (der über SysFileGetPos gelesen werden kann) für einen Dateizugriff zu verändern. Die Datei wird dazu über ihre Dateinummer (Handle) identifiziert.

Der Rückgabewert ist ein Fehler-Code, der Auskunft über Erfolg oder Misserfolg der Operation gibt.

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der zu öffnenden Datei (siehe SysFileOpen).

uiOffset

UDINT

Offset innerhalb der Datei, der für Zugriffe gilt.

2.19 SysFileWrite

Diese Funktion dient zum Schreiben von Daten in eine Datei, die dazu vorher über die Funktion SysFileOpen geöffnet wurde.

Der Rückgabewert vom Typ UDINT enthält die Anzahl der erfolgreich geschriebenen Bytes (=0, falls Schreiben nicht erfolgreich war).

Input-Variable

Datentyp

Beschreibung

hFile

UDINT

Dateinummer (Handle) der zu öffnenden Datei (siehe SysFileOpen).

pbyBuffer

POINTER TO

Adresse des Puffers (ermittelbar mit dem Hilfe des Operators ADR), der die zu schreibenden Daten enthält.

BYTE

uiSize

UDINT

Anzahl der Bytes, die in die Datei geschrieben werden sollen (ermittelbar mit Hilfe des Operators SIZEOF). Die Anzahl darf die Puffer-Größe nicht überschreiten-

pResult

POINTER TO

Pointer auf Fehler-Code, siehe Dokument „Runtime Error Codes“.

UDINT

2.20 Enumeration AccessMode

Diese Enumeration vom Typ UDINT enthält die möglichen Zugriffsmodi für eine Datei. Sie wird von der Struktur FileInfo verwendet (siehe Kap.2.21).

Komponente

Bedeutung

AM_READ

Öffnen einer bestehenden Datei zum Lesen. Wenn die Datei nicht existiert, wird ein Fehler zurückgegeben.

AM_WRITE

Öffnen einer neuen Datei zum Schreiben. Wenn die Datei bereits existiert, wird der alte Inhalt überschrieben.

AM_APPEND

Eine bestehende Datei wird mit Schreibrecht geöffnet. Wenn die Datei noch nicht existiert, wird ein Fehler zurückgegeben.

AM_READ_PLUS

Öffnen einer bestehenden Datei zum Lesen und Schreiben. Wenn die Datei nicht existiert, wird ein Fehler zurückgegeben.

AM_WRITE_PLUS

Öffnen einer neuen Datei zum Lesen und Schreiben. Wenn die Datei bereits existiert, wird der alte Inhalt überschrieben.

AM_APPEND_PLUS

Eine bestehende Datei wird mit Lese- und Schreibrecht geöffnet. Wenn die Datei noch nicht existiert, wird die Datei neu angelegt.

Bibliothek SysFile.library

libdoc_d.dot / V1.0

2.21 Struktur FileInfo

Diese Struktur enthält den Namen, das Zugriffsrecht, den Status und die Datei-Nummer (Handle) einer Datei.

Struktur-Komponente

Datentyp

Bedeutung

szFileName

REFERENCE

Dateiname

TO STRING

tAccessMode

AccessMode

Zugriffsrecht auf die Datei, siehe Enumeration AccessMode (Kap.2.20)

tFileStatus

FileStatus

Aktueller Datei-Status, siehe Enumeration FileStatus (Kap. 2.22)

ulFileHandle

UDINT

Dateinummer (Handle) der zu öffnenden Datei (siehe SysFileOpen).

2.22 Enumeration FileStatus

Diese Enumeration enthält die möglichen Zustandsmodi einer Datei. Sie wird von der Struktur FileInfo (siehe Kap. 2.21) verwendet.

Komponente

Bedeutung

FS_OK

Datei ok

FS_NO_FILE

Datei existiert nicht

FS_ILLEGAL_POS

Illegale Position in der Datei (Position liegt außerhalb der Datei), wird meist durch SysFileSetPos() gesetzt

FS_FULL

Dateisystem voll, Datei kann nicht gespeichert werden

FS_EMPTY

Datei ist leer.

FS_BUFFER_FULL

Datei kann nicht in Buffer geladen werden.

2.23 Struktur FileTime

Diese Struktur enthält Angaben zum Erstelldatum, Datum des letzten Zugriffs und Datum der letzten Änderung einer Datei. Die Daten werden im DT-Format behandelt. Sie wird von Funktion SysFileGetTime verwendet.

Struktur-Komponente

Datentyp

Bedeutung

ulCreation

UDINT

Erstelldatum

ulLastAccess

UDINT

Datum des letzten Zugriffs, Achtung: bei VxWorks- Systemen ggf. nur Tag ohne Uhrzeit!

ulLastModification

UDINT

Datum der letzten Änderung

Bibliothek SysFile.library

libdoc_d.dot / V1.0

Änderungshistorie

Version

Beschreibung

Datum

0.1

Erstellung

19.06.2007

0.2

Inhaltlich überarbeitet

27.06.2007

0.3

FileStatus, FileInfo

28.06.2007

0.4

Inhaltlich überarbeitet

12.07.2007

0.5

SysFileGetPath und FileStatus aktualisiert

03.08.2007

0.6

Kleine Korrekturen, Ergänzungen

15.10.2007

1.0

Review durch Entwickler, Update, Release

12.02.2008

1.1

Neu: SysFileGetName2, SysFileGetStatus2 (#33190)

23.06.2008

1.2

Review von 1.1

27.06.2008

2.0

Freigabe

27.06.2008