Bibliotheksbeschreibung:

CoDeSys V 3.x
SysCom.library

libdoc_d.dot / V1.0

Dokument Version 1.0

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 1 von 11

SysCom.library

INHALT
1

BERBLICK

BIBLIOTHEKSBAUSTEINE

2.1

SysComOpen

2.2

SysComOpen2

2.3

SysComPurge

2.4

SysComRead

2.5

SysComSetSettings

2.6

SysComSetTimeout

2.7

SysComGetSettings

2.8

SysComClose

2.9

SysComWrite

2.10

Struktur ComSettings

2.11

Struktur ComSettingsEx

2.12

Enumeration COM_Baudrate

2.13

Enumeration COM_Parity

2.14

Enumeration COM_Ports

10

2.15

Enumeration COM_StopBits

10

2.16

Enumeration COM_Timeout

10

11

libdoc_d.dot / V1.0

NDERUNGSHISTORIE

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 2 von 11

Bibliothek SysCom.library

berblick
Hinweis: Es hngt vom verwendeten Zielsystem ab, welche Systembibliotheken im Steuerungsprogramm verwendet
werden knnen.

Diese Bibliothek untersttzt die synchrone, serielle Kommunikation mit einem Zielrechner.
Wenn das Zielsystem die Funktionalitt beinhaltet, knnen folgende Funktionen verwendet
werden, um einen seriellen Port zu ffnen und zu schlieen, Daten ber diesen Port zu
schreiben oder zu lesen und seine Einstellungen zu lesen bzw. zu verndern:
SysComOpen
SysComOpen2
SysComPurge
SysComRead
SysComSetSettings
SysComSetTimeout
SysComGetSettings
SysComClose
SysComWrite
Die Funktionen verwenden folgende Strukturen und Enumerationen:
ComSettings
ComSettingsEx
COM_Baudrate
COM_Parity
COM_Ports
COM_StopBits

libdoc_d.dot / V1.0

COM_Timeout

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 3 von 11

Bibliothek SysCom.library

2.1

Bibliotheksbausteine

SysComOpen
Diese Funktion ffnet einen seriellen Port.
Der Rckgabewert vom Typ RTS_IEC_HANDLE liefert ein Handle auf den Port, das beim
Aufruf der anderen Bibliotheksfunktionen bergeben wird. Wenn der Port nicht geffnet
werden kann, wird 0xFFFFFFFF als Handle zurckgegeben.
Zustzlich wird ein Fehler-Code ausgegeben, der ber den Erfolg der Operation Auskunft
gibt.

2.2

Input-Variable

Datentyp

Beschreibung

sPort

COM_PORTS

spezifiziert die zu ffnende Schnittstelle (COM1,..);

Port-Nummer, siehe Enumeration COM_PORTS.

pResult

POINTER TO
RTS_IEC_RESULT

Zeiger auf Fehler-Code, siehe Dokument Runtime

Error Codes.

SysComOpen2
Diese Funktion ffnet einen seriellen Port zu ffnen. Neben dem zu ffnenden Port knnen
zustzliche Einstellungen zum ffnen des Ports in den Strukturen COMSettings und
COMSettingsEX bergeben werden.
Der Rckgabewert vom Typ RTS_IEC_HANDLE liefert ein Handle auf den Port, das beim
Aufruf der anderen Bibliotheksfunktionen bergeben wird. Wenn der Port nicht geffnet
werden kann, wird 0xFFFFFFFF als Handle zurckgegeben.

2.3

Input-Variable

Datentyp

Beschreibung

pSettings

POINTER TO
COMSettings

Zeiger auf eine COMSettings Struktur (siehe 2.10).

Dieser Zeiger darf nicht NULL sein.

pSettingsEx

POINTER TO
COMSettingsEx

Zeiger auf eine COMSettingsEx Struktur (siehe 2.10).

Dieser Zeiger darf NULL sein, wenn die
COMSettingsEx Struktur nicht verwendet werden soll.

pResult

POINTER TO
RTS_IEC_RESULT

Zeiger auf Fehler-Code, siehe Dokument Runtime

Error Codes.

SysComPurge
Diese Funktion leert den Ein- und Ausgangspuffer der seriellen Schnittstelle.

libdoc_d.dot / V1.0

Der Rckgabewert: vom Typ RTS_IEC_RESULT liefert einen Fehler-Code, der ber den
Erfolg der Operation Auskunft gibt. Siehe hierzu auch das Dokument Runtime Error Codes.
Input-Variable

Datentyp

hCom

RTS_IEC_HANDLE aus SysComOpen erhaltenes Handle fr den aktuell

geffneten Port.

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Beschreibung

Seite 4 von 11

Bibliothek SysCom.library

2.4

SysComRead
Diese Funktion liest Daten vom COM-PORT. Dazu werden das Handel der seriellen
Schnittstelle, die Addresse, an die die gelesenen Daten kopiert werden sollen, die
gewnschte Gre der zu lesenden Daten und ein Timeout fr die Funktion angegeben.
Der Rckgabewert vom Typ DINT liefert die Anzahl der tatschlich gelesenen Bytes.

2.5

Input-Variable

Datentyp

Beschreibung

hCom

RTS_IEC_HANDLE aus SysComOpen erhaltenes Handle fr den aktuell

geffneten Port, von dem Daten gelesen werden
sollen.

pbyBuffer

POINTER TO BYTE Speicheradresse, in die die gelesenen Daten

geschrieben werden sollen. Die Speicheraddresse
kann mit ADR ermittelt werden.

ulSize

UDINT

Anzahl der zu lesenden Bytes.

ulTimeout

COM_Timeout

Zeit in Millisekunden, nach der die Funktion

sptestens zurckkehrt;
siehe Kap. 2.16, Enumeration COM_Timeout.

pResult

POINTER TO
RTS_IEC_RESULT

Zeiger auf Fehler-Code, siehe Dokument Runtime

Error Codes.

SysComSetSettings
Diese Funktion setzt fr einen seriellen Port die Standardparameter (Baudrate, Stopbits,
Parity, Funktions-Timeout, Buffer-Gre, Scan-Time) bzw. erweiterte Einstellungen
(Zeichengre, fr den Hardwarehandshake relevante Parameter, DTR/RTS-Control,
CTS/DSR Flukontrolle und DSR-Sensitvitt etc.). Dies geschieht ber die Struktur
COMSettings (Standardparameter) bzw. COMSettingsEx (erweiterte Einstellungen).
Je nach verwendeter Steuerung kann man die Parameter einer Schnittstelle zur Laufzeit
ndern, es muss aber einmal nach dem ffnen der Schnittstelle gewhrleistet sein, die
Parameter zu bernehmen. Je nach verwendeter Steuerung kann es also notwendig sein, die
Schnittstelle zu schlieen und neu zu ffnen, um Parameter setzen zu knnen.
Der Rckgabewert vom Typ RTS_IEC_RESULT gibt Auskunft ber den Erfolg der Operation.
Siehe hierzu auch das Dokument Runtime Error Codes.
Datentyp

hCom

RTS_IEC_HANDLE aus SysComOpen erhaltenes Handle fr den aktuell

geffneten Port, fr den die Parameter gesetzt
werden sollen.

pSettings

POINTER TO
COMSettings

Zeiger auf die Struktur COMSettings, die die PortStandardparameter beschreibt (siehe Kap. 2.10);
der Operator ADR kann dabei zu Hilfe genommen
werden.

pSettingsEx

POINTER TO
COMSettingsEX

Zeiger auf die Struktur COMSettingsEx, die weitere

Port-Parameter beschreibt (siehe Kap. 2.11);
der Operator ADR kann dabei zu Hilfe genommen
werden.

libdoc_d.dot / V1.0

Input-Variable

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Beschreibung

Seite 5 von 11

Bibliothek SysCom.library

2.6

SysComSetTimeout
Diese Funktion setzt einen Timeout am aktuell geffneten Port. Nach der angegeben Zeit
kehrt eine Read bzw. Write Funktion zurck.
Der Rckgabewert: vom Typ RTS_IEC_RESULT liefert einen Fehler-Code, der ber den
Erfolg der Operation Auskunft gibt. Siehe hierzu auch das Dokument Runtime Error Codes.

2.7

Input-Variable

Datentyp

Beschreibung

hCom

RTS_IEC_HANDLE aus SysComOpen erhaltenes Handle fr den aktuell

geffneten Port.

ulTimeout

COM_Timeout

Zeit in Millisekunden, nach der die Funktion

sptestens zurckkehrt; siehe Enumeration
COM_Timeout (Kap. 2.16).

SysComGetSettings
Diese Funktion liest fr einen seriellen Port die Parameter wie Baudrate, Stopbits, Parity,
Funktions-Timeout, Buffer-Gre und Scan-Time aus. Dies geschieht ber die Struktur
COMSettings (Standardparameter) bzw. COMSettingsEx (erweiterte Einstellungen).
Der Rckgabewert vom Typ RTS_IEC_RESULT gibt Auskunft ber den Erfolg der Operation.
Siehe hierzu auch das Dokument Runtime Error Codes.

2.8

Input-Variable

Datentyp

Beschreibung

hCom

RTS_IEC_HANDLE

aus SysComOpen erhaltenes Handle fr den aktuell

geffneten Port, dessen Parameter gelesen werden
sollen.

pSettings

POINTER TO
COMSettings

Zeiger auf die Struktur ComSettings, die die PortStandardparameter beschreibt (siehe Kap. 2.10); der
Operator ADR kann dabei zu Hilfe genommen
werden.

pSettingsEx

POINTER TO
COMSettingsEX

Zeiger auf die Struktur ComSettingsEx, die weitere

Port-Parameter beschreibt (siehe Kap. 2.11); der
Operator ADR kann dabei zu Hilfe genommen
werden.

SysComClose
Diese Funktion schliet den angegebenen COM-Port.
Der Rckgabewert vom Typ RTS_IEC_RESULT gibt Auskunft ber den Erfolg der Operation.
Siehe hierzu auch das Dokument Runtime Error Codes.
Datentyp

Beschreibung

hCom

RTS_IEC_HANDLE aus SysComOpen erhaltenes Handle fr den zu

schlieenden Port.

libdoc_d.dot / V1.0

Input-Variable

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 6 von 11

Bibliothek SysCom.library

2.9

SysComWrite
Diese Funktion schreibt Daten an den angegebenen Port. Dazu werden die Port-Nummer, die
Adresse, von der die Daten kopiert werden sollen, die gewnschte Gre der zu
schreibenden Daten und ein Timeout fr die Funktion angegeben.
Der Rckgabewert vom Typ DINT liefert die Anzahl der tatschlich geschriebenen Bytes.
Input-Variable

Datentyp

Beschreibung

hCom

RTS_IEC_HANDLE aus SysComOpen erhaltenes Handle fr den aktuell

geffneten Port, von dem Daten gelesen werden
sollen.

pbyBuffer

POINTER TO BYTE Speicheradresse, aus der die zu schreibenden Daten

geholt werden sollen (Ermittlung mit ADR).

ulSize

UDINT

Anzahl der zu schreibenden Bytes.

ulTimeout

COM_Timeout

Zeit in Millisekunden, nach der die Funktion

sptestens zurckkehrt.

pResult

POINTER TO
RTS_IEC_RESULT

Zeiger auf Fehler-Code, siehe Dokument Runtime

Error Codes.

2.10 Struktur ComSettings

Diese Struktur enthlt die Standardparameter eines COM-Ports. Diese knnen ber die
Funktionen SysComSetSettings bzw. SysComGetSettings gesetzt bzw. gelesen werden.
Datentyp

Bedeutung

sPort

COM_Ports

Nummer des Ports fr den die Parameter gelten,

siehe Enumeration COM_Ports (siehe Kap. 2.14).

byStopBits

COM_StopBits

Anzahl Stopbits, die nach jedem ber den Port

bertragenen Daten-Byte gesendet werden, siehe
Enumeration COM_StopBits (Kap. 2.15).

byParity

BYTE

Paritt (Parity), siehe Enumeration COM_Parity

ulBaudRate

COM_Baudrate

Baudrate, siehe Enumeration COM_Baudrate (Kap.

2.12)

ulTimeout

COM_Timeout

Timeout der Schnittstelle in ms. Zeit zwischen zwei

eingegangen oder gesendeten Zeichen, nach der die
Lese- oder Schreiboperation beendet wird.
Default = 0 (Funktion kehrt sofort zurck);
siehe Enumeration COM_Timeout (Kap. 2.16).

ulBufferSize

UDINT

Puffergre des internen (FIFO) Gertepuffers,

Default = 0

libdoc_d.dot / V1.0

Strukturkomponente

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 7 von 11

Bibliothek SysCom.library

2.11 Struktur ComSettingsEx

Diese Struktur enthlt zustzliche Parameter eines COM-Ports (siehe Struktur ComSettings
fr die Standardparameter).
Strukturkomponente

Datentyp

Bedeutung

byByteSize

BYTE

4...8: Zeichengre in Anzahl Datenbits

bBinary

BOOL

TRUE : Binary Mode ist aktiviert

FALSE: Binary Mode ist deaktiviert

bOutxCtsFlow

BOOL

Gibt an, ob das CTS-Signal fr Ausgabekontrolle

benutzt wird. Wenn die Variable TRUE ist, wird die
Ausgabe auf der seriellen Schnittstelle solange
verzgert bis CTS wieder auf High geht. HardwareHandshake.

bOutxDsrFlow

BOOL

Gibt an, ob die DSR-Leitung als Sendesperre benutzt

wird. Wenn diese Variable TRUE ist, wird nur bei
eingeschalteter DSR-Leitung gesendet.

bDtrControl

BYTE

0:Schaltet die DTR Leitung ab und lsst sie

abgeschaltet, solange die Schnittstelle geffnet ist.
1: Schaltet die DTR Leitung ein und lsst sie
eingeschaltet, solange die Schnittstelle geffnet ist.
2:Aktiviert das DTR Handshake.

bDsrSensitivity

BOOL

Gibt an ob der Kommunikationstreiber bei

eingeschaltetem DSR ankommende Zeichen
ignoriert. Ist diese Variable TRUE, wird der Status der
DSR-Leitung ignoriert.

bRtsControl

BYTE

0:Schaltet die RTS Leitung ab solange die

Schnittstelle geffnet ist.
1:Schaltet die RTS Leitung ein, solange die
Schnittstelle geffnet ist.
2:Aktiviert das RTS Handshake. Der Treiber aktiviert
die RTS-Leitung, wenn der Eingangspuffer weniger
als halb voll ist und deaktiviert die Leitung wenn der
der Puffer mehr als dreiviertel voll ist.
3:RTS wird vom Treiber immer eingeschaltet, wenn
noch Zeichen fr die bertragung anstehen. Wenn
alle Zeichen gesendet wurden, wird die RTS Leitung
abgeschaltet.

libdoc_d.dot / V1.0

bTXContinueOnXoff BOOL

Gibt an, ob die bertragung nach dem Senden des

XoffChar gestoppt wird.
TRUE: bertragung wird fortgesetzt.
FALSE: bertragung wird gestoppt, bis der Treiber
das XOnChar gesendet hat.

bOutX

BOOL

Gibt an, ob XON/XOFF flow control beim Senden

aktiviert werden soll.

bInX

BOOL

Gibt an, ob XON/XOFF flow control beim Senden

aktiviert werden soll.

byXonChar

BYTE

Zeichen fr XON

byXoffChar

BYTE

Zeichen fr XOFF

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 8 von 11

Bibliothek SysCom.library

Strukturkomponente

Datentyp

Bedeutung

wXonLim

WORD

Mindestanzahl an Bytes im Eingangspuffer bevor

XON gesendet werden darf

wXoffLim

WORD

Maximalanzahl an Bytes im Eingangspuffer bevor

XOFF gesendet werden darf.

2.12 Enumeration COM_Baudrate

Diese Enumeration verwaltet die Werte fr den in Struktur ComSettings (Kap. 2.10)
verwendeten Parameter Baudrate.
TYPE COM_Baudrate : (SYS_BR_4800 := 4800, SYS_BR_9600 := 9600, SYS_BR_19200
:= 19200, SYS_BR_38400 := 38400, SYS_BR_57600 := 57600, SYS_BR_115200 :=
115200) DWORD;
END_TYPE
Komponente

Bedeutung

SYS_BR_4800 := 4800

Baudrate 4800

SYS_BR_9600 := 9600

Baudrate 9600

SYS_BR_19200 := 19200

Baudrate 19200

SYS_BR_38400 := 38400

Baudrate 38400

SYS_BR_57600 := 57600

Baudrate 57600

SYS_BR_115200 := 115200

Baudrate 115200

2.13 Enumeration COM_Parity

Diese Enumeration verwaltet die Werte fr den in Struktur ComSettings (Kap. 2.10)
verwendeten Paritts-Parameter Parity.
TYPE COM_Parity : (SYS_NOPARITY := 0, SYS_ODDPARITY, SYS_EVENPARITY) BYTE;
END_TYPE
Bedeutung

SYS_NOPARITY := 0

keine Parittskontrolle

SYS_ODDPARITY := 1

"Odd parity" Parittssumme ungerade

SYS_EVENPARITY := 2

"Even parity" Parittssumme gerade

libdoc_d.dot / V1.0

Komponente

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 9 von 11

Bibliothek SysCom.library

2.14 Enumeration COM_Ports

Diese Enumeration verwaltet die Port-Nummern, die als Eingabe fr die Funktionen der
SysCom.library bentigt werden.
Enumeration COM_PORTS:
TYPE COM_Ports : (SYS_COMPORT_NONE := 0, SYS_COMPORT1 := 1, SYS_COMPORT2,
SYS_COMPORT3, SYS_COMPORT4);
END_TYPE
Komponente

Bedeutung

SYS_COMPORT_NONE := 0

kein Port

SYS_COMPORT1 := 1

Port 1

SYS_COMPORT2

Port 2

SYS_COMPORT3

Port 3

SYS_COMPORT4

Port 4

2.15 Enumeration COM_StopBits

Diese Enumeration COM_StopBits enthlt Werte fr den in Struktur ComSettings (Kap. 2.10)
verwendeten Parameter StopBits zur Definition, wie viele Stopbits im Anschluss an jedes
bertragene Daten-Byte gesendet werden.
TYPE COM_StopBits : (SYS_ONESTOPBIT := 1, SYS_ONE5STOPBITS, SYS_TWOSTOPBITS)
BYTE;
END_TYPE
Komponente

Bedeutung

SYS_ONESTOPBIT := 1

1 Stop Bit

SYS_ONE5STOPBITS := 2

1,5 Stop Bits

SYS_TWOSTOPBITS := 3

2 Stop Bits

2.16 Enumeration COM_Timeout

Diese Enumeration COM_Timeout enthlt Werte fr den in Struktur ComSettings (Kap. 2.10)
verwendeten Parameter Timeout.

libdoc_d.dot / V1.0

TYPE COM_Timeout : (SYS_NOWAIT := 0, SYS_INFINITE := 16#FFFFFFFF) UDINT;

END_TYPE
Komponente

Bedeutung

SYS_NOWAIT := 0

Die Funktion kehrt sofort zurck.

SYS_INFINITE := 16#FFFFFFFF Die Funktion wartet bis das Lesen bzw. Schreiben der
angegebenen Anzahl an Bytes abgeschlossen ist.

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 10 von 11

SysCom.library

nderungshistorie
Beschreibung

Datum

0.1

Erstellung

15.06.2007

0.2

Review und Dokument entspr. inhaltlich berarbeitet

27.06.2007

0.3

Dokument formell berarbeitet

27.06.2007

0.4

Anpassung an V3.1.2.0 der Lib (pResult als VAR_INPUT)

12.07.2007

1.0

Freigabe

19.07.2007

libdoc_d.dot / V1.0

Version

3S - Smart Software Solutions GmbH

SysCom_V3x_D.doc

Seite 11 von 11