6.4. Process Data Access Functions

6.4.1. esGetProcessImageInputPtr

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

The size of the process data image input area is returned by esIoControl - EC_IOCTL_GET_PDMEMORYSIZE and esRegisterClient() at EC_T_REGISTERRESULTS::dwPDInSize.

See also

esConfigureNetwork()
esIoControl - EC_IOCTL_GET_PDMEMORYSIZE
esIoControl - EC_IOCTL_REGISTER_CYCFRAME_RX_CB
esExecJob() ( eUsrJob_ProcessAllRxFrames) in case of polling mode

6.4.2. esGetProcessImageOutputPtr

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

The size of the process data image output area is returned by esIoControl - EC_IOCTL_GET_PDMEMORYSIZE and esRegisterClient() at EC_T_REGISTERRESULTS::dwPDOutSize.

See also

esConfigureNetwork()
esIoControl - EC_IOCTL_GET_PDMEMORYSIZE
esIoControl - EC_IOCTL_REGISTER_CYCFRAME_RX_CB
esExecJob() ( eUsrJob_ProcessAllRxFrames) in case of polling mode

6.4.3. 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_SETBITS
EC_GETBITS

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

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

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

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

6.4.7. EC_SET_FRM_WORD

EC_SET_FRM_WORD(ptr, w)

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

Parameters

ptr – [in] Destination buffer
w – [in] 16 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_WORD(byFrame + 1, 0x1234);
/* byFrame = FF 34 12 FF FF FF ... */

6.4.8. EC_SET_FRM_DWORD

EC_SET_FRM_DWORD(ptr, dw)

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

Parameters

ptr – [in] Destination buffer
dw – [in] 32 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_DWORD(byFrame + 1, 0x12345678);
/* byFrame = FF 78 56 34 12 FF ... */

6.4.9. EC_SET_FRM_QWORD

EC_SET_FRM_QWORD(ptr, qw)

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

Parameters

ptr – [in] Destination buffer
qw – [in] 64 bit value

EC_T_BYTE byFrame[32];

/* Initialize the frame buffer */
OsMemset(byFrame, 0xFF, 32);

EC_SET_FRM_QWORD(byFrame + 1, 0xFEDCBA9876543210);
/* byFrame = FF 10 32 54 76 98 BA DC FE FF FF ... */

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

EC_GET_FRM_WORD
EC_GET_FRM_DWORD
EC_GET_FRM_QWORD

6.4.11. EC_SETBITS

EC_SETBITS(pbyDstBuf, pbySrcData, nDstBitOffs, nBitSize)

Writes a given number of bits from source data starting at first bit to destination buffer at given bit offset.

Note

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

Parameters

pbyDstBuf – [out] Destination buffer where data is copied to
pbySrcData – [in] Source buffer to be copied, starting with first bit
nDstBitOffs – [in] Destination bit offset where data is copied to
nBitSize – [in] Bit count to be copied

See also

EC_SET_FRM_WORD
EC_SET_FRM_DWORD
EC_SET_FRM_QWORD

6.4.12. esGetProcessData

EC_T_DWORD esGetProcessData(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

6.4.13. esSetProcessData

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

Write Process data synchronized.

If process data shall be set 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 write request to the master stack and then check every millisecond whether new data is written. The master stack will copy the 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: write output data, EC_FALSE: write input data.
dwOffset – [in] Byte offset in Process data to write to.
pbyData – [in] Buffer containing transfered data
dwDataLen – [in] Buffer length [bytes]
dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

6.4.14. esSetProcessDataBits

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

Writes a specific number of bits from a given buffer to the process image 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: write output data, EC_FALSE: write input data.
dwBitOffsetPd – [in] Bit offset in Process data image.
pbyData – [in] Buffer containing 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

6.4.15. esGetProcessDataBits

EC_T_DWORD esGetProcessDataBits(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