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

TCP_Connection (FB) ¶ FUNCTION_BLOCK TCP_Connection EXTENDS CBM.LTrig The next free connection is determined by handle exchange and set to active. As long as xActive is TRUE the handle of the connection is valid. If xActiveis FALSE the handle of the connection is invalid. hConnection can be used as input hConnection for function blocks TCP_Write , TCP_WriteBuffer , TCP_Read and TCP_ReadBuffer . InOut: Scope Name Type 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 hServer CAA.HANDLE Output eError ERROR xActive BOOL hConnection CAA.HANDLE Properties: IPAddress Structure: IPAddress (Property)

TCP_Read (FB) ¶ FUNCTION_BLOCK TCP_Read EXTENDS CBM.LTrig This function block serves to read data from the previously established connection given in hConnection . As long as xEnable is TRUE the handle of the connection is valid. The pointer pData specifies the memory area to write the read data to. szSize defines the max number of bytes to read. When the data was read successfully, xReady is set to TRUE and szCount indicates the actually read number of bytes. InOut: Scope Name Type 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 hConnection CAA.HANDLE szSize CAA.SIZE pData CAA.PVOID Output eError ERROR xReady BOOL szCount CAA.SIZE

TCP_ReadBuffer (FB) ¶ FUNCTION_BLOCK TCP_ReadBuffer EXTENDS CBM.LTrig Like TCP_Read this function block serves to read data from the previously established connection given in hConnection . As long as xEnable is TRUE the handle of the connection is valid. The function block returns the handle of the buffer containing the data. If xReady is TRUE , data has been read successfully and the handle of the buffer is valid. The buffer is passed on and not copied like at TCP_Read . InOut: Scope Name Type 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 hConnection CAA.HANDLE Output eError ERROR xReady BOOL hBuffer CAA.HANDLE

Decode (FUN) ¶ FUNCTION Decode : BOOL Function decodes “Source” (ARRAY OF BYTE) into “Destination” (ARRAY OF DWORD), meaning 4 BYTEs are decoded into 1 DWORD. Assumes “uiNumberOfBytes” is a multiple of 4, whereas if it is not “FALSE” will be returned. InOut: Scope Name Type Comment Return Decode BOOL function returns “TRUE” if decoding succeded Input pSource POINTER TO ARRAY [0..0] OF BYTE address of source memory pDestination POINTER TO ARRAY [0..0] OF DWORD address of destination memory uiNumberOfBytes UINT number of bytes to decode

Encode (FUN) ¶ FUNCTION Encode : BOOL Function encodes “Source” (ARRAY OF DWORD) into “Destination” (ARRAY OF BYTE), meaning 1 DWORD is split up into 4 BYTEs. Assumes “uiNumberOfBytes” is a multiple of 4, whereas if it is not “FALSE” is returned. InOut: Scope Name Type Comment Return Encode BOOL function returns “TRUE” if encoding succeeded Input pSource POINTER TO ARRAY [0..0] OF DWORD address of source memory pDestination POINTER TO ARRAY [0..0] OF BYTE address of destination memory uiNumberOfBytes UINT number of bytes to encode