CAA Net Base Services Library Documentation ¶ Company CAA Technical Workgroup Title CAA Net Base Services Version 3.5.15.0 Categories Intern|CAA|Network Namespace NBS Author 3S - Smart Software Solutions GmbH Placeholder CAA NetBaseSrv Description 1 ¶ This Library implements a TCP Server, TCP Client and a UDP Peer as a collection of base services for ethernet Contents: ¶ CAA Net Base Services Enums Examples Function Blocks Functions GlobalConstants Param (ParamList) Structs GetSupplierVersion (Function) VersionConstants (GVL) Indices and tables ¶ 1 Based on CAA_NetBaseServices.library, last modified 24.07.2019, 08:29:50. LibDoc 4.4.0.0-b.27 The content file CAA_NetBaseServices.clean.json was generated with CODESYS V3.5 SP15 on 24.07.2019, 08:29:54.

Enums ¶ ERROR (Enum) TCP_WRITE_STATE (Enum)

CAA Net Base Services ¶ Enums ERROR (Enum) TCP_WRITE_STATE (Enum) Examples HoTo (GVL) Function Blocks TCP TCP_Client (FunctionBlock) TCP_Connection (FunctionBlock) IPAddress (Property) TCP_Read (FunctionBlock) TCP_ReadBuffer (FunctionBlock) TCP_Server (FunctionBlock) TCP_Write (FunctionBlock) TCP_WriteBuffer (FunctionBlock) UDP UDP_Peer (FunctionBlock) UDP_Receive (FunctionBlock) UDP_ReceiveBuffer (FunctionBlock) UDP_Send (FunctionBlock) UDP_SendBuffer (FunctionBlock) Functions Async DummyJob (Function) UDP IPSTRING_TO_UDINT (Function) IS_MULTICAST_GROUP (Function) UDINT_TO_IPSTRING (Function) UDP_GetDataSize (Function) GlobalConstants Constants (GVL) Param (ParamList) Structs IP_ADDR (Struct)

ERROR (ENUM) ¶ TYPE ERROR : This data structure describes errors, which might occur during handling functions of CAA_NetBaseServices.lib. Attributes: qualified_only InOut: Name Initial Comment NO_ERROR 0 No error occurred FIRST_ERROR 6000 Reserved TIME_OUT 6001 Reserved INVALID_ADDR 6002 IP address not valid INVALID_HANDLE 6003 Handle not valid INVALID_DATAPOINTER 6004 Data pointer not valid INVALID_DATASIZE 6005 Data size not valid UDP_RECEIVE_ERROR 6006 Not able to receive a UDP datagram UDP_SEND_ERROR 6007 Not able to send a UDP datagram UDP_SEND_NOT_COMPLETE 6008 Reserved UDP_OPEN_ERROR 6009 Not able to create the port UDP_CLOSE_ERROR 6010 Not able to release the port TCP_SEND_ERROR 6011 Not able to send a TCP message TCP_RECEIVE_ERROR 6012 Not able to receive a TCP message TCP_OPEN_ERROR 6013 Not able to create a TCP port TCP_CONNECT_ERROR 6014 Not able to establish a TCP connection TCP_CLOSE_ERROR 6015 Not able to release the TCP connecteion TCP_SERVER_ERROR 6016 Reserved WRONG_PARAMETER 6017 A parameter has an invalid value ERROR_UNKNOWN 6018 Reserved TCP_NO_CONNECTION 6019 There is no TCP connection IOCTL_ERROR 6020 Internal error (e.g. IOCTL not supported) FIRST_MF 6050 Reserved LAST_ERROR 6099 Reserved

TCP_WRITE_STATE (ENUM) ¶ TYPE TCP_WRITE_STATE : InOut: Name Initial IDLE 0 SENDING DONE

Examples ¶ Note The function blocks with an input or output variable with the name hBlock will internally use the library Segmented Block Manager . This library provides functionality for managing data structures in a way that the amount of copy actions is as minimal as possible. Currently the implementation of this library has a serious problem ( CDS-56664 ). It uses frequently function for allocating (SysMemAlloc) and releasing memory (SysMemFree) sections. This behaviour can lead to memory fragmentation. This is not a good practice in the industrial environment, because it is about the possibility of a continuous operation around the clock and 365 days a year. Inside this folder you will find a NetBaseServicesDemo project archive. Please download and open this archive to take a look inside and learn a little bit more about the usage of the TCP and UDP function blocks. TCP Server - Client A TCP_Server typically can handle more then one connection at the same time. To realize this in our examples we have encapsulated the logic for handling one connection inside a function block Handler . So one instance of a Server can be connected to one ore more instances of a Handler function block. Each of these instances may be located in a different task context. The function block Server need some information about the network ( ipAddr ) and the port ( uiPort ) it will listen for new connections. As long the xEnable input variable is TRUE the function block will accept new connections. The output variables xBusy = TRUE and hServer <> 0 will signal this situation. With resetting the xEnable variable to FALSE all active connections will be closed and the output variables xBusy and hServer will get inaktive values ( FALSE or INVALID_HANDLE ). After the server has accepted a new connection the output variable xActive of a specific Connection will be set to TRUE and the output variable hConncetion will change form INVALID_HANDLE to a valid handle value. The enabled TCP_ReadBuffer may provide a new message after each invocation. The output variable xActive will signal a new value at the hBuffer output variable. The best way to decouple this possibly very fast flowing data stream from the rest of your application is to use a so called Queue function block. It will store the incoming messages with a FIFO strategy (FirstIn - FirstOut) and is so providing the possibility to compensate load peaks. The TCP_WriteBuffer function block will send one message with each rising edge of its xExecute input variable. The time till the xDone output variable will be set to True depends on a variety of conditions and can lasts much more time than one or two plc cycles. This is the main reason to decouple the Reader and the Writer with the help of a Queue . In this example the ownership of the hBuffer handle is directly connected to the processing of the following function blocks or functions. If you do some other processing steps and you will take the ownership of a hBlock handle, it will be necessary to use the SBM.DeleteBuffer function to free the connected resources. UDP Producer - Consumer The UDP protocol is not stream orientated as the TCP protocol. Two peers (e.g. the producer and the consumer) on the same network segment will exchange messages (packages). The message length is restricted to the maximum transmission unit size. There is no guarantee against package loss. There is no mechanism for retransmission of lost messages. There is no rule for keeping the sequence of send packages in the same order as the received packages. The function block UDP_Send takes the description of a message via its input variables pData and szSize . After the detection of a rising edge on its xExecute input variable it will send the message over the next amount of invocations. The successful end of this operation will be signaled with xDone output variable. In our application we will repeat this sequence every 500 milliseconds. We have to solve the same problem related to the different operation time of a Receiver and a Sender as we did while we implemented the TCP Server - Client application. And we will use again a Queue at the consumer side of our application. The receiver can provide at any time (after each invocation) a new message. So it is very important to hand over the received messages directly to a Queue . The Queue is created after the Peer (Consumer) was activated and will be disposed after the Peer is deactivated. Activation and deactivation of the Peer is controlled by its xEnable input variable. After getting out an hBuffer handle out of the Queue the application will copy the content of the buffer in a different memory location. It will after this use the SBM.DeleteBuffer function to free the related resources and took the ownership of the handle back from the application to the library. HoTo (GVL)

HoTo (GVL) ¶ Attributes: qualified_only InOut: Name Type iDummy INT

Function Blocks ¶ TCP TCP_Client (FunctionBlock) TCP_Connection (FunctionBlock) IPAddress (Property) TCP_Read (FunctionBlock) TCP_ReadBuffer (FunctionBlock) TCP_Server (FunctionBlock) TCP_Write (FunctionBlock) TCP_WriteBuffer (FunctionBlock) UDP UDP_Peer (FunctionBlock) UDP_Receive (FunctionBlock) UDP_ReceiveBuffer (FunctionBlock) UDP_Send (FunctionBlock) UDP_SendBuffer (FunctionBlock)

TCP ¶ TCP_Client (FunctionBlock) TCP_Connection (FunctionBlock) IPAddress (Property) TCP_Read (FunctionBlock) TCP_ReadBuffer (FunctionBlock) TCP_Server (FunctionBlock) TCP_Write (FunctionBlock) TCP_WriteBuffer (FunctionBlock)

TCP_Client (FB) ¶ FUNCTION_BLOCK TCP_Client EXTENDS CBM.LTrig Implements a TCP Client. To connect to a TCP Server at the endpoint defined with ipAddr and uiPort the input xEnable should set to TRUE . While setup the connection xBusy is TRUE but xActive is FALSE . After the connection is established xActive and xBusy is TRUE and the hConnection output is valid. After closing the connection from the server side xActive becomes FALSE hConnection become CAA.gc_hINVALID and xDone becomes TRUE . InOut: Scope Name Type Initial Comment Inherited from Input xEnable BOOL TRUE : Action starts FALSE : Action stops, outputs xDone , xBusy , xError are resetted LTrig Output xDone BOOL TRUE : Action successfully completed LTrig xBusy BOOL TRUE : Function block active LTrig xError BOOL TRUE : Error occurred, function block aborts action FALSE : No error LTrig Input udiTimeOut UDINT 0 Defines the time (µs) after which the connection setup aborts with an error message. ipAddr IP_ADDR IP-Address of server to connect to uiPort UINT Port number of TCP socket to open Output eError ERROR xActive BOOL TRUE if a Connection is established hConnection CAA.HANDLE Valid, if xActive = TRUE