7.3. Process Data functions

7.3.1. emGetProcessData

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

Retrieve Process data synchronized.

If process data are required outside the cyclic master job task (which is calling ecatExecJob), 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 master stack and then check every millisecond whether new data are provided. The master stack will provide new data after calling ecatExecJob(eUsrJob_ MasterTimer) 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 transfered data

  • dwDataLen – [in] Buffer length [bytes]

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

7.3.2. emGetProcessDataBits

EC_T_DWORD emGetProcessDataBits(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 transfered 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

7.3.3. emGetProcessImageInputPtr

EC_T_BYTE *emGetProcessImageInputPtr(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

7.3.4. emGetProcessImageOutputPtr

EC_T_BYTE *emGetProcessImageOutputPtr(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

7.3.5. emIoControl - 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 emConfigureNetwork().

emIoControl - 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.

Return

EC_E_NOERROR or error code

struct EC_T_MEMREQ_DESC

7.3.6. Process Data access functions

7.3.6.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 */

7.3.6.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 */

7.3.6.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 */

7.3.6.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 */

7.3.6.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

7.3.7. emIoControl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

Set ignore inputs on WKC error

emIoControl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR
Parameter
  • pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: inputs are ignored 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

Return

EC_E_NOERROR or error code

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

7.3.8. emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

Set zero inputs on WKC error

emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR
Parameter
  • pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: inputs are set 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

Return

EC_E_NOERROR or error code

Calling this IOCTL with EC_TRUE as parameter will set the inputs data of cyclic commands to zero on WKC error. The default behavior will copy the input data if WKC is non zero and below the expected value. If WKC is not matching the expected value a notification emNotify - EC_NOTIFY_CYCCMD_WKC_ERROR is generated and the application must consider this status for the current cycle.

7.3.9. emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

Set zero inputs on WKC is zero

emIoControl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO
Parameter
  • pbyInBuf: [in] Pointer to value of EC_T_BOOL. EC_TRUE: inputs are set 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

Return

EC_E_NOERROR or error code

Calling this IOCTL with EC_TRUE as parameter will ignore the inputs data of cyclic commands on WKC error. At default behavior it will ignore the input data if WKC is zero, and keep the previous state.