# Process Data functions

## emonGetProcessData

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetProcessData([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwOffset, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataLen, [EC_T_DWORD](api.html.md#_CPPv410EC_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 [bytes] 
  * **dwTimeout** – [in] Timeout [ms] 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

## emonGetProcessDataBits

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonGetProcessDataBits([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_T_BOOL](api.html.md#_CPPv49EC_T_BOOL) bOutputData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwBitOffsetPd, [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*pbyData, [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwDataBitLen, [EC_T_DWORD](api.html.md#_CPPv410EC_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](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`emonGetProcessData()`](#_CPPv418emonGetProcessData10EC_T_DWORD9EC_T_BOOL10EC_T_DWORDP9EC_T_BYTE10EC_T_DWORD10EC_T_DWORD)

## emonGetProcessImageInputPtr

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*emonGetProcessImageInputPtr([EC_T_DWORD](api.html.md#_CPPv410EC_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 

## emonGetProcessImageOutputPtr

### [EC_T_BYTE](api.html.md#_CPPv49EC_T_BYTE) \*emonGetProcessImageOutputPtr([EC_T_DWORD](api.html.md#_CPPv410EC_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 

## emonFindInpVarByName

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindInpVarByName([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_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](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)

## emonFindInpVarByNameEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindInpVarByNameEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_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](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)

## emonFindOutpVarByName

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindOutpVarByName([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO](api_slave.html.md#_CPPv421EC_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](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO`](api_slave.html.md#_CPPv421EC_T_PROCESS_VAR_INFO)

## emonFindOutpVarByNameEx

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) emonFindOutpVarByNameEx([EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, const [EC_T_CHAR](api.html.md#_CPPv49EC_T_CHAR) \*szVariableName, [EC_T_PROCESS_VAR_INFO_EX](api_slave.html.md#_CPPv424EC_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](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

#### SEE ALSO
[`EC_T_PROCESS_VAR_INFO_EX`](api_slave.html.md#_CPPv424EC_T_PROCESS_VAR_INFO_EX)

## emonIoCtl - EC_IOCTL_GET_PDMEMORYSIZE

### EC_IOCTL_GET_PDMEMORYSIZE

Get the process data image size. This information may be used to provide process data image storage from outside the core. This IOCTL is to be called after network configuration. 

* **Parameters:**
  * **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](#da/df0/struct_e_c___t___m_e_m_r_e_q___d_e_s_c)) 
  * **dwOutBufSize** – [in] Size of the output buffer in bytes 
  * **pdwNumOutData** – [out] Pointer to EC_T_DWORD. Amount of bytes written to the output buffer. 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

### struct EC_T_MEMREQ_DESC

### Public Members

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPDOutSize

Size of the output process data image 

### [EC_T_DWORD](api.html.md#_CPPv410EC_T_DWORD) dwPDInSize

Size of the input process data image 

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## Process Data access functions

### 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`](#c.EC_GETBITS)

![Diagram illustrating the EC_COPYBITS macro copying 22 bits from a source byte array at bit offset 6 to a destination byte array at bit offset 3](../Media/EC_COPYBITS.PNG)
```cpp
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 */
```

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

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

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

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

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

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

### 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 only be 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`](#c.EC_GET_FRM_WORD)
- [`EC_GET_FRM_DWORD`](#c.EC_GET_FRM_DWORD)
- [`EC_GET_FRM_QWORD`](#c.EC_GET_FRM_QWORD)

## EC_TESTBIT

### EC_TESTBIT(pbyBuf, nBitOffs)

Test whether a bit in the buffer is set. 

* **Parameters:**
  * **pbyBuf** – Source buffer. 
  * **nBitOffs** – Bit offset to test. 
* **Returns:**
  EC_TRUE if bit is set, otherwise EC_FALSE. 

## emonIoCtl - EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

### EC_IOCTL_SET_IGNORE_INPUTS_ON_WKC_ERROR

Set ignore INPUTs on WKC error. 

* **Parameters:**
  * **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 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.EC_TRUE) as parameter will ignore input 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](notification_error.html.md#emonnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

### EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ERROR

Set INPUTs to zero on WKC error. 

* **Parameters:**
  * **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 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.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](notification_error.html.md#emonnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)

## emonIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

### EC_IOCTL_SET_ZERO_INPUTS_ON_WKC_ZERO

Set INPUTs to zero on WKC is zero. 

* **Parameters:**
  * **pbyInBuf** – [in] Pointer to value of EC_T_BOOL. EC_TRUE: Set INPUTs to zero if 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 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.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](notification_error.html.md#emonnotify-ec-notify-cyccmd-wkc-error) is generated and the application must consider this status for the current cycle.

## emonIoCtl - EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS

### EC_IOCTL_SET_ZERO_INPUTS_ON_FRAME_LOSS

Set inputs to zero on frame loss. 

* **Parameters:**
  * **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 
* **Returns:**
  [EC_E_NOERROR](error-codes_generic.html.md#d3/d2f/group___e_c___e_r_r_o_r___c_o_d_e_s___g_e_n_e_r_i_c_1ga8c8419c32e88e73d940a4501fe427116) or error code 

Calling this IOCTL with [`EC_TRUE`](api.html.md#c.EC_TRUE) as parameter will set inputs to zero on frame loss.
By default input data are ignored on frame loss and remain unchanged.

#### SEE ALSO
[`emonIoCtl()`](api_general.html.md#_CPPv49emonIoCtl10EC_T_DWORD10EC_T_DWORDPCK9EC_T_VOID10EC_T_DWORDPC9EC_T_VOID10EC_T_DWORDPC10EC_T_DWORD)