ClientRequest (FB)

FUNCTION_BLOCK ABSTRACT ClientRequest EXTENDS CBML.ETrigTo IMPLEMENTS IClientRequest

MODBUS client (master) request base class.

There are specific client request function blocks related to all supported MODBUS “function codes”.

A ClientRequest relies on a Client to provide the communication infrastructure, this means a ClientRequest needs to be connected to one Client (ClientSerial or ClientTCP) to work with.

Once a client request is triggered (rising edge on xExecute) it is processed by the Client it is connected to. The Client does process the triggered requests strictly in the order they got triggered (first come, first served). A successful client request is indicated by xDone=TRUE, a client request in progress is indicated by xBusy=TRUE. A failed client request is indicated by xError=TRUE, and a specific eErrorID. ClientRequest does have a timeout (it extends CBML.ETrigTo - udiTimeout in µs) to avoid endless, effectless client operations. So in general the application should: - trigger the request with rising edge on xExecute (set xExecute:=TRUE) - check if request is done (xDone=TRUE) or error occured (xError=TRUE) - falling edge on xExecute (set xExecute:=FALSE) - eventually repeat

Client request errors and timeout

A client request can fail (xError=TRUE) for different reason:

• “exception reply” - the server is answering in time, but signals an invalid request. In this case eErrorID is set to Error.RequestException and eException contains the specific exception code. This is kind of a normal reply a server can do, because of client request parameters not valid for the server “data model”.

• “reply timeout” - the server is not answering in time (udiReplyTimeout - for consistency to CBML.ETrigTo.udiTimeout in µs as well). This includes incomplete (frames) or invalid replies which are dropped, but does not include “exception replies”. In this case eErrorID is set to Error.ReplyTimeout. In general the application can’t do a lot about this type of error except choosing adequate udiReplyTimeout.

• “request starvation” - too many client requests triggered in parallel, causing a timeout (see udiTimeout) before server reply or “reply timeout” happens. In this case eErrorID is set to Error.RequestNotProcessed. In general the application is responsible to avoid “request starvation”. The client does process the client requests as fast as possible, but in sequential order. Processing one client request involves waiting for the server reply to be processed (including eventual “reply timeout”). In case a number of client requests are triggered in parallel, processing time and waiting sums up for the subsequent client requests triggered already, but not processed yet.

Because “request starvation” can not be avoided in general, it is recommended to trigger client requests in “daisy chains” (first client request xDone=TRUE or xError=TRUE triggering second client request) to avoid client “request starvation” at all.

Client request errors and connection shutdown

In case of a client request there is no other action on client involved - the client connection stays alive. In case there is a need to disconnect the client (shutdown the client connection either TCP or serial) on such a single client request error, this has to be done in the application by setting client.xConnect:=FALSE.

Timeout default

It is not possible to overload member defaults of base classes in IEC61131. CBML.ETrigTo defaults udiTimeout to 0 which is not optimal for ClientRequest’s because it’s state machine would get stuck without timeout on “reply timeout” or “request starvation”. So ClientRequest.fb_init writes udiTimeout to 2s (in µs) initially. In case you want to chose another udiTimeout you need to assign it explicitly after initializaton (in a PLC application cycle).

“data item” offset / “data item” numbers

Please note: unlike standard MODBUS, in CODESYS MODBUS the “data item” numbers are equal to the “data addresses”. The MODBUS standard states: “In the MODBUS data Model each element within a data block is numbered from 1 to n.” In CODESYS MODBUS the “data items” are numbered from 0 to n-1.

InOut:

Scope	Name	Type	Initial	Comment	Inherited from
Input	xExecute	BOOL		Rising edge: Starts defined operation FALSE: Resets the defined operation after ready condition was reached	ETrigTo
	udiTimeOut	UDINT		Max. operating time for executing [µs], 0: No operating time limit	ETrigTo
Output	xDone	BOOL		Ready condition reached	ETrigTo
	xBusy	BOOL		Operation is running	ETrigTo
	xError	BOOL		Error condition reached	ETrigTo
Inout	rClient	Client		Reference to Client.
Input	uiUnitId	UINT	0	Unit-Id to send the request to.
	udiReplyTimeout	UDINT	(50 * 1000)	Reply timeout in µs - accepted maxmimum time between request message send and reply message receveived - default 50ms.
	uiMaxRetries	UINT	0	Maximum number of request retries in case of “reply timeout”.
Output	eErrorID	Error		Error status
	eException	ExceptionCodes		Request exception code.
	uiRetryCnt	UINT	0	Number of request retries in case of “reply timeout”.