8.3. Process Data functions
8.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
8.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
See also
8.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
8.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
8.3.5. emFindInpVarByName
-
EC_T_DWORD emFindInpVarByName(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
8.3.6. emFindInpVarByNameEx
-
EC_T_DWORD emFindInpVarByNameEx(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
8.3.7. emFindOutpVarByName
-
EC_T_DWORD emFindOutpVarByName(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
8.3.8. emFindOutpVarByNameEx
-
EC_T_DWORD emFindOutpVarByNameEx(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
8.3.9. 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_NULLdwInBufSize
: [in] Should be set to 0pbyOutBuf
: [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
8.3.10. Process Data access functions
8.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_SETBITS

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 */
8.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 */
8.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 */
8.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 */
8.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
8.3.11. 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_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [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.
8.3.12. 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_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [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.
8.3.13. 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_NULLdwOutBufSize
: [in] Should be set to 0pdwNumOutData
: [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.