9.3. Process Data functions

9.3.1. emonGetProcessData

EC_T_DWORD emonGetProcessData(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwDataLen, EC_T_DWORD dwTimeout)

Blocking function to retrieve consistent process data from outside the JobTask context.

This function requests a copy of the process data (stored in RAM). The actual memcpy operation is executed by the JobTask to ensure data consistency. While waiting for the copy to complete, the calling context blocks and repeatedly calls sleep with an interval of at least the cycle time or one millisecond, whichever is greater. The function returns either with the requested process data once the copy is finished, or when the specified timeout has expired.

Note

The function is blocking and should be used carefully in time-sensitive contexts and may not be called from within the JobTask context. If process data are required outside the cyclic monitor job task (which is calling emonExecJob), direct access to the process data is not recommended as data consistency cannot be guaranteed. A call to this function will send a data read request to the monitor stack and then check every millisecond whether new data is provided. The monitor stack will provide new data after calling emonExecJob(eUsrJob_MonitorTimer) within the job task. This function is usually only called remotely (using the Remote API).

Note

This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bOutputData – [in] EC_TRUE: read output data, EC_FALSE: read input data.

  • dwOffset – [in] Byte offset in Process data to read from.

  • pbyData – [out] Buffer receiving transferred data

  • dwDataLen – [in] Buffer length in bytes

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

9.3.2. emonGetProcessDataBits

EC_T_DWORD emonGetProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyData, EC_T_DWORD dwDataBitLen, EC_T_DWORD dwTimeout)

Reads a specific number of bits from the process image to the given buffer with a bit offset (synchronized).

This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bOutputData – [in] EC_TRUE: read output data, EC_FALSE: write input data.

  • dwBitOffsetPd – [in] Bit offset in Process data image.

  • pbyData – [out] Buffer receiving transferred data

  • dwDataBitLen – [in] Buffer length [bit]

  • dwTimeout – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

See also

emonGetProcessData()

9.3.3. emonGetProcessImageInputPtr

EC_T_BYTE *emonGetProcessImageInputPtr(EC_T_DWORD dwInstanceID)

Gets the process data input image pointer.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

Process data input image pointer

9.3.4. emonGetProcessImageOutputPtr

EC_T_BYTE *emonGetProcessImageOutputPtr(EC_T_DWORD dwInstanceID)

Gets the process data output image pointer.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

Process data output image pointer

9.3.5. emonFindInpVarByName

EC_T_DWORD emonFindInpVarByName(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)

Finds an input process variable information entry by the variable name.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • szVariableName – [in] Variable name

  • pProcessVarInfoEntry – [out] Process variable information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

9.3.6. emonFindInpVarByNameEx

EC_T_DWORD emonFindInpVarByNameEx(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

Finds an input process variable extended information entry by the variable name.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • szVariableName – [in] Variable name

  • pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

9.3.7. emonFindOutpVarByName

EC_T_DWORD emonFindOutpVarByName(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)

Finds an output process variable information entry by the variable name.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • szVariableName – [in] Variable name

  • pProcessVarInfoEntry – [out] Process variable information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO

9.3.8. emonFindOutpVarByNameEx

EC_T_DWORD emonFindOutpVarByNameEx(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

Finds an output process variable extended information entry by the variable name.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • szVariableName – [in] Variable name

  • pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

See also

EC_T_PROCESS_VAR_INFO_EX

9.3.9. emonIoControl - EC_IOCTL_GET_PDMEMORYSIZE

Get the process data image size. This information may be used to provide process data image storage from outside the EC-Monitor core. This IOCTL is to be called after emonConfigureNetwork().

emonIoControl - EC_IOCTL_GET_PDMEMORYSIZE
Parameter

  • pbyInBuf: [in] Should be set to EC_NULL

  • dwInBufSize: [in] Should be set to 0

  • pbyOutBuf: [out] Pointer to memory where the memory size information will be stored (type: EC_T_MEMREQ_DESC).

  • dwOutBufSize: [in] Size of the output buffer in bytes.

  • pdwNumOutData: [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer.

struct EC_T_MEMREQ_DESC

Public Members

EC_T_DWORD dwPDOutSize

Size of the output process data image

EC_T_DWORD dwPDInSize

Size of the input process data image

9.3.10. Process Data access functions

9.3.10.1. EC_COPYBITS

EC_COPYBITS(pbyDst, nDstBitOffs, pbySrc, nSrcBitOffs, nBitSize)

Copies a block of bits from a source buffer to a destination buffer.

Note

The memory buffers must be allocated before. The buffers must be big enough to hold the block starting at the given offsets! The buffers are not checked for overrun.

Parameters

  • pbyDst – [out] Destination buffer

  • nDstBitOffs – [in] Bit offset within destination buffer

  • pbySrc – [in] Source buffer

  • nSrcBitOffs – [in] Bit offset within source buffer

  • nBitSize – [in] Block size in bits

See also

EC_T_BYTE pbySrc[] = {0xF4, 0xED, 0x69, 0xA5};
EC_T_BYTE pbyDst[] = {0x00, 0x00, 0x00, 0x00};
EC_COPYBITS(pbyDst, 3, pbySrc, 6, 22);

/* pbyDst now contains 0xB8 0x3C 0xAC 0x00 */

9.3.10.2. EC_GET_FRM_WORD

EC_GET_FRM_WORD(ptr)

Reads a value of type EC_T_WORD (16 bit) at given pointer. The value is swapped on big endian systems.

Parameters

  • ptr – [in] Source buffer

Returns

EC_T_WORD value (16 bit) from buffer. 

EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_WORD wResult = 0;

wResult = EC_GET_FRM_WORD(byFrame);
/* wResult is 0xF401 on little endian systems */

wResult = EC_GET_FRM_WORD(byFrame + 5);
/* wResult is 0x6000 on little endian systems */

wResult = EC_GET_FRM_WORD(byFrame + 2);
/* wResult is 0x85DD on little endian systems */

9.3.10.3. EC_GET_FRM_DWORD

EC_GET_FRM_DWORD(ptr)

Reads a value of type EC_T_DWORD (32 bit) at given pointer. The value is swapped on big endian systems.

Parameters

  • ptr – [in] Source buffer

Returns

EC_T_DWORD value (32 bit) from buffer. 

EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_DWORD dwResult = 0;

dwResult = EC_GET_FRM_DWORD(byFrame);
/* dwResult is 0x85DDF401 on little endian systems */

dwResult = EC_GET_FRM_DWORD(byFrame + 5);
/* dwResult is 0x00C16000 on little endian systems */

dwResult = EC_GET_FRM_DWORD(byFrame + 2);
/* dwResult is 0x000385DD on little endian systems */

9.3.10.4. EC_GET_FRM_QWORD

EC_GET_FRM_QWORD(ptr)

Reads a value of type EC_T_QWORD (64 bit) at given pointer. The value is swapped on big endian systems.

Parameters

  • ptr – [in] Source buffer

Returns

EC_T_QWORD value (64 bit) from buffer. 

EC_T_BYTE byFrame[] = {0x01, 0xF4, 0xDD, 0x85, 0x03, 0x00, 0x60, 0xC1, 0x00};
EC_T_UINT64 ui64Result = 0;

ui64Result = EC_GET_FRM_QWORD(byFrame + 1);
/* wResult is 0x00C160000385DDF4 on little endian systems */

9.3.10.5. EC_GETBITS

EC_GETBITS(pbySrcBuf, pbyDstData, nSrcBitOffs, nBitSize)

Reads a given number of bits from source buffer starting at given bit offset to destination buffer.

Note

This function should be only used to get bit-aligned data. For byte-aligned data the corresponding functions should be used.

Parameters

  • pbySrcBuf – [in] Source buffer to be copied

  • pbyDstData – [out] Destination buffer where data is copied to

  • nSrcBitOffs – [in] Source bit offset where data is copied from

  • nBitSize – [in] Bit count to be copied

See also

9.3.11. emonIoControl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

Ignore inputs on WKC error

emonIoControl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR
Parameter

  • pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: Ignore inputs on WKC error.

  • dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

Calling this IOCTL with EC_TRUE as parameter will ignore inputs data of cyclic commands on WKC error. By default input data are updated if WKC is non zero. If WKC is not matching the expected value a notification emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is generated and the application must consider this status for the current cycle.

9.3.12. emonIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

Set inputs to zero on WKC error

emonIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR
Parameter

  • pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set inputs to zero on WKC error.

  • dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

Calling this IOCTL with EC_TRUE as parameter will set inputs to zero on WKC error. By default input data are updated if WKC is non zero. If WKC is not matching the expected value a notification emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is generated and the application must consider this status for the current cycle.

9.3.13. emonIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

Set inputs to zero on WKC is zero

emonIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO
Parameter

  • pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set inputs to zero on WKC is zero.

  • dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

Calling this IOCTL with EC_TRUE as parameter will set inputs to zero on WKC is zero. By default input data are ignored on WKC is zero and remain unchanged. If WKC is not matching the expected value a notification emonNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is generated and the application must consider this status for the current cycle.

9.3.14. emonIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS

Set inputs to zero on frame loss

emonIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS
Parameter

  • pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set inputs to zero on frame loss.

  • dwInBufSize: [in] Size of the input buffer provided at pbyInBuf in bytes.

  • pbyOutBuf: [out] Should be set to EC_NULL

  • dwOutBufSize: [in] Should be set to 0

  • pdwNumOutData: [out] Should be set to EC_NULL

Calling this IOCTL with EC_TRUE as parameter will set inputs to zero on frame loss. By default input data are ignored on frame loss and remain unchanged.