Library Description:

CoDeSys V 3.x
SysCom.library

Document Version 1.0

libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Seite 1 von 11

SysCom_V3x_E.doc
 Library SysCom.library

CONTENT

1 OVERVIEW 3

2 LIBRARY MODULES 4
2.1 SysComOpen 4
2.2 SysComOpen2 4
2.3 SysComPurge 4
2.4 SysComRead 5
2.5 SysComSetSettings 5
2.6 SysComSetTimeout 6
2.7 SysComGetSettings 6
2.8 SysComClose 6
2.9 SysComWrite 7
2.10 Structure ComSettings 7
2.11 Structure ComSettingsEx 8
2.12 Enumeration COM_Baudrate 9
2.13 Enumeration COM_Parity 9
2.14 Enumeration COM_Ports 9
2.15 Enumeration COM_StopBits 10
2.16 Enumeration COM_Timeout 10

CHANGE HISTORY 11
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Seite 2 von 11

SysCom_V3x_E.doc
 Library SysCom.library

1 Overview

Note: It depends on the target system, which system libraries can be used in the application program.

This library supports the serial communication with a target system. If the target system
provides the functionality, then the following library functions can be used to open or close a
serial port and to read or write data via this port (The execution is synchronous.):

SysComOpen
SysComOpen2
SysComPurge
SysComRead
SysComSetSettings
SysComSetTimeout
SysComGetSettings
SysComClose
SysComWrite

The functions use the following structures and enumerations:

ComSettings
ComSettingsEx
COM_Baudrate
COM_Parity
COM_Ports
COM_StopBits
COM_Timeout
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Seite 3 von 11

SysCom_V3x_E.doc
 Library SysCom.library

2 Library Modules

2.1 SysComOpen
This function opens a serial port.

The return value of type RTS_IEC_HANDLE is a handle for the respective port, which can be
passed to other library functions. If the port cannot be opened, 0xFFFFFFFF will be returned.
Input Variable Data type Description

sPort COM_PORTS Specifies the port to be opened (COM1,..); Port-

Number, see enumeration COM_PORTS.
pResult POINTER TO Error code, see Document Runtime Error Codes.
RTS_IEC_RESULT

2.2 SysComOpen2
This function opens a serial port. Thereby additional settings concerning the opening of the
port can be passed via structures COMSettings and COMSettingsEX.

The return value of type RTS_IEC_HANDLE gives a handle for the port. This handle can be
passed to other library functions. If the port cannot be opened, 0xFFFFFFFF will be returned
as handle.
Input Variable Data type Description

pSettings POINTER TO Pointer on a COMSettings structure (see chap. 2.10).

COMSettings This pointer must not be NULL !
pSettingsEx POINTER TO Pointer on a COMSettingsEx structure (see 2.10).
COMSettingsEx This pointer may be NULL, if the COMSettingsEx
structure should not be used.

pResult POINTER TO Error code, see Document Runtime Error Codes.

RTS_IEC_RESULT

2.3 SysComPurge
This function empties the input and output buffer of the serial interface.

The return value of type RTS_IEC_RESULT is an error code which tells about the success of
the operation. See document Runtime Error Codes.
Input Variable Data type Description

hCom RTS_IEC_HANDLE Handle for the currently opened port, received from
SysComOpen
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 4 on 11

SysCom_V3x_E.doc
 Library SysCom.library

2.4 SysComRead
This function reads data from the COM-PORT. For this purpose you have to pass the handle
of the serial port, the address where the read data should be copied, the size of data to be
read and a function timeout.

The return value of type DINT gives the number of actually read bytes.
Input Variable Data type Description

hCom RTS_IEC_HANDLE Handle for the port to be read, acquired by

SysComOpen.
pbyBuffer POINTER TO BYTE Address, to which the read bytes should be copied
after having been read from the port. You can use the
ADR operator to get this address.
ulSize UDINT Number of bytes to be read.

ulTimeout COM_Timeout Time in milliseconds, after which the function returns

at the latest;
see chap. 2.16, Enumeration COM_Timeout.
pResult POINTER TO Error code, see Document Runtime Error Codes.
RTS_IEC_RESULT

2.5 SysComSetSettings
This function sets the default parameters for a serial port (baudrate, stopbits, parity, function
timeout, buffer size, scan time) resp. extended settings (character size, parameters for
hardware handshake, DTR/RTS control, CTS/DSR flow control and DSR sensitivity etc.). This
is done via the structures COMSettings (standard settings) resp. COMSettingsEx (extended
settings).

Depending on the target system the parameters of an interface may be modified during run
time. However ONCE after having opened the port it must be guaranteed that the parameters
get accepted. Thus, depending on the controller, it might be necessary to close and re-open
the port in order to be able to set the parameters.

The return value of type RTS_IEC_RESULT is an error code which tells about the success of
the operation. See document Runtime Error Codes.
Input Variable Data type Description

hCom RTS_IEC_HANDLE Handle for the port, for which the settings should be
made; acquired by SysComOpen.
pSettings POINTER TO Pointer on structure COMSettings, describing the port
COMSettings standard settings (see chap. 2.10); Operator ADR can
be used.
pSettingsEx POINTER TO Pointer on structure COMSettingsEx, describing
COMSettingsEX additional port settings (see chap. 2.11); Operator
ADR can be used.
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 5 on 11

SysCom_V3x_E.doc
 Library SysCom.library

2.6 SysComSetTimeout
This function sets a timeout at the currently opened port. After the given time any currently
called Read resp. Write function will return.

The return value of type RTS_IEC_RESULT is an error code which tells about the success of
the operation. See document Runtime Error Codes.
Input Variable Data type Description

hCom RTS_IEC_HANDLE Handle for the port, for which the timeout should be
set; acquired by SysComOpen.
ulTimeout COM_Timeout Time in milliseconds, after which the function returns
at latest;
see enumeration COM_Timeout (chap. 2.16).

2.7 SysComGetSettings
This function reads the parameters of a serial port (e.g. baudrate, stopbits, parity, function
timeout, buffer size and scan time. This is done via structure COMSettings (standard
parameters) resp. COMSettingsEx (extended settings).

The return value of type RTS_IEC_RESULT is an error code which tells about the success of
the operation. See document Runtime Error Codes.
Input Variable Data type Description

hCom RTS_IEC_HANDLE Handle for the port, for which the settings should be
read; acquired by SysComOpen.
pSettings POINTER TO Pointer on structure ComSettings describing the port
COMSettings standard parameters (see chap. 2.10);
Operator ADR can be used for this purpose.
pSettingsEx POINTER TO Pointer on structure ComSettingsEx describing
COMSettingsEX additional port parameters (see Chap. 2.11);
Operator ADR can be used for this purpose.

2.8 SysComClose
This function closes the COM-Port.

The return value of type RTS_IEC_RESULT is an error code which tells about the success of
the operation. See document Runtime Error Codes.
Input Variable Data type Description

hCom RTS_IEC_HANDLE Handle for the port, which should be closed;

acquired by SysComOpen.
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 6 on 11

SysCom_V3x_E.doc
 Library SysCom.library

2.9 SysComWrite
This function writes data to the given port. You have to pass the port handle, the address and
size of the data to be written and a timeout for the function.

The return value of type DINT gives the number of actually written bytes.
Input Variable Data type Description

hCom RTS_IEC_HANDLE Handle for the port, to which the data should be
written; acquired by SysComOpen.
pbyBuffer POINTER TO BYTE Memory address, from which the data to be written
should be read (can be acquired via ADR operator).
ulSize UDINT Number of bytes to be written.

ulTimeout COM_Timeout Time in milliseconds, after which the function will

return at the latest..
pResult POINTER TO Error code, see Document Runtime Error Codes.
RTS_IEC_RESULT

2.10 Structure ComSettings

This structure contains the standard parameters of a COM-Port. These can be set resp. get
via function SysComSetSettings resp. SysComGetSettings.
Structure- Data type Description
komponente

sPort COM_Ports Number of the port, see enumeration COM_Ports

(chap. 2.14).
byStopBits COM_StopBits Number of stopbits to be sent after each data byte
which is transferred on the port, see enumeration
COM_StopBits (chap. 2.15).
byParity BYTE Parity, see enumeration COM_Parity

ulBaudRate COM_Baudrate Baudrate, see enumeration COM_Baudrate

(chap. 2.12)
ulTimeout COM_Timeout Timeout of the interface in milliseconds. This is the
time between receiving or sending two characters,
after which the read or write operation will be
terminated.
Default = 0 (function returns immediately);
see enumeration COM_Timeout (chap. 2.16).
ulBufferSize UDINT Buffer size of the internal (FIFO) device buffer;
Default = 0
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 7 on 11

SysCom_V3x_E.doc
 Library SysCom.library

2.11 Structure ComSettingsEx

This structure contains additional parameters for a COM port (see also structure ComSettings
for the standard parameters).
Structure component Data type Description

byByteSize BYTE 4...8: Character size in number of data bits

bBinary BOOL TRUE : Binary mode activated

FALSE: Binary mode deactivated
bOutxCtsFlow BOOL Defines whether the CTS (clear-to-send) signal is
used for the output flow control. If the variable is
TRUE, the output on the serial port will be delayed
until CTS returns to High. Hardware-Handshake.
bOutxDsrFlow BOOL Specifies whether the DSR line is used as send lock.
If TRUE, data will be only sent if the DSR line is
switched on.
bDtrControl BYTE 0: Disables the DTR line when the port gets opened
and remains it disabled as long as the port is.
1: Enables the DTR line when the port gets opened
and remains it enabled as long as the port is.
2: Enables DTR handshaking.
bDsrSensitivity BOOL Specifies whether the communications driver is
sensitive to the state of the DSR signal. If this
member is TRUE, the driver ignores any bytes
received, unless the DSR modem input line is high.
bRtsControl BYTE 0: Disables the RTS line when the port gets opened
and leaves it disabled as long as the port is open.
1: Enables the RTS line when the port gets opened
and leaves it enabled as long as the port is open.
2: Enables RTS handshaking. The driver raises the
RTS line when the "type-ahead" (input) buffer is less
than one-half full and it lowers the RTS line when the
buffer is more than three-quarters full.
3: Specifies the RTS line will be high as long as bytes
are available for transmission. After all buffered bytes
have been sent, the RTS line will get low.
bTXContinueOnXoff BOOL Specifies whether the DSR (data-set-ready) signal is
monitored for output flow control. If the variable is
TRUE and DSR is turned off, output will be
suspended until DSR is sent again.
bOutX BOOL Specifies whether the XON/XOFF output flow control
should be activated during sending.
bInX BOOL Specifies whether the XON/XOFF input flow control
should be activated during sending.
byXonChar BYTE Character for XON
libdoc_e.dot / V1.0

byXoffChar BYTE Character for XOFF

wXonLim WORD Minimum number of bytes to be in the input buffer

before XON may be sent

3S - Smart Software Solutions GmbH Page 8 on 11

SysCom_V3x_E.doc
 Library SysCom.library

Structure component Data type Description

wXoffLim WORD Minimum number of bytes to be in the input buffer

before XOFF may be sent

2.12 Enumeration COM_Baudrate

This enumeration contains the possible settings of the baudrate parameter (see structure
ComSettings, chap. 2.10).
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

Component Description

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

This enumeration contains the possible settings of the parity parameter (see structure
ComSettings, chap. 2.10).
TYPE COM_Parity : (SYS_NOPARITY := 0, SYS_ODDPARITY, SYS_EVENPARITY) BYTE;
END_TYPE

Component Description

SYS_NOPARITY := 0 No parity control

SYS_ODDPARITY := 1 Odd parity

SYS_EVENPARITY := 2 Even parity

2.14 Enumeration COM_Ports

This enumeration contains the possible port numbers (port handles) used as input for
SysCom.library functions.
Enumeration COM_PORTS:
TYPE COM_Ports : (SYS_COMPORT_NONE := 0, SYS_COMPORT1 := 1, SYS_COMPORT2,
libdoc_e.dot / V1.0

SYS_COMPORT3, SYS_COMPORT4);
END_TYPE

3S - Smart Software Solutions GmbH Page 9 on 11

SysCom_V3x_E.doc
 Library SysCom.library

Component Description

SYS_COMPORT_NONE := 0 no Port

SYS_COMPORT1 := 1 Port 1

SYS_COMPORT2 Port 2

SYS_COMPORT3 Port 3

SYS_COMPORT4 Port 4

2.15 Enumeration COM_StopBits

This enumeration contains values for parameter StopBits (see structure ComSettings, chap.
2.10). This parameter specifies how many stop bits should be sent subsequent to each data
byte.
TYPE COM_StopBits : (SYS_ONESTOPBIT := 1, SYS_ONE5STOPBITS, SYS_TWOSTOPBITS)
BYTE;
END_TYPE

Component Description

SYS_ONESTOPBIT := 1 1 Stop Bit

SYS_ONE5STOPBITS := 2 1,5 Stop Bits

SYS_TWOSTOPBITS := 3 2 Stop Bits

2.16 Enumeration COM_Timeout

This enumeration contains values for parameter Timeout (see structure ComSettings, chap.
2.10).
TYPE COM_Timeout : (SYS_NOWAIT := 0, SYS_INFINITE := 16#FFFFFFFF) UDINT;
END_TYPE

Component Description

SYS_NOWAIT := 0 The function returns immediately.

SYS_INFINITE := The function waits until the reading resp. writing of the given
16#FFFFFFFF number of bytes has been finished.
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 10 on 11

SysCom_V3x_E.doc
 SysCom.library

Change History

Version Description Date

0.1 Issued 15.06.2007

0.2 Rework 27.06.2007
0.3 Translated corresponding to reviewed German version 0.4 15.07.2007
1.0 Release 19.07.2007
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH Page 11 on 11

SysCom_V3x_E.doc