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

emGetProcessData()

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

EC_T_PROCESS_VAR_INFO

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

EC_T_PROCESS_VAR_INFO_EX

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

EC_T_PROCESS_VAR_INFO

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

EC_T_PROCESS_VAR_INFO_EX

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_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

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

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

See also

EC_GET_FRM_WORD
EC_GET_FRM_DWORD
EC_GET_FRM_QWORD

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

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

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