6.4. Process Data Access

6.4.1. emGetProcessData

static EC_T_DWORD ecatGetProcessData(EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwLength, EC_T_DWORD dwTimeout)
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)

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.

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

The function is blocking and should be used carefully in time-sensitive contexts and may not be called from within the JobTask context.

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 or error code

emGetProcessData() Example
/* get Process data (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0 };
dwRes = emGetProcessData(dwInstanceId, EC_FALSE, 0 /* byte offset */,
    abyData, 1 /* byte length */, 5000);
EcLogMsg(EC_LOG_LEVEL_INFO, (pEcLogContext, EC_LOG_LEVEL_INFO, 
    "Process Data: 0x%02X\n", abyData[0]));

6.4.2. emGetProcessDataBits

static EC_T_DWORD ecatGetProcessDataBits(EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyDataDst, EC_T_DWORD dwBitLengthDst, EC_T_DWORD dwTimeout)
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 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 or error code

See also

emGetProcessData()

emGetProcessDataBits() Example
/* get bits from Process Data Image (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0 };
dwRes = emGetProcessDataBits(dwInstanceId, EC_FALSE, 0 /* bit offset */, 
    abyData, 8 /* bit length */, 5000);

6.4.3. emSetProcessData

static EC_T_DWORD ecatSetProcessData(EC_T_BOOL bOutputData, EC_T_DWORD dwOffset, EC_T_BYTE *pbyData, EC_T_DWORD dwLength, EC_T_DWORD dwTimeout)
EC_T_DWORD emSetProcessData(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 transferred data

  • dwDataLen – [in] Buffer length [bytes]

  • dwTimeout – [in] Timeout [ms]

Returns

EC_E_NOERROR or error code

emSetProcessData() Example
/* write value 0x12 to Process Data Image (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0x12 };
dwRes = emSetProcessData(dwInstanceId, EC_FALSE, 0 /* byte offset */,
    abyData, 1 /* byte length */, 5000);

6.4.4. emSetProcessDataBits

static EC_T_DWORD ecatSetProcessDataBits(EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_BYTE *pbyDataSrc, EC_T_DWORD dwBitLengthSrc, EC_T_DWORD dwTimeout)
EC_T_DWORD emSetProcessDataBits(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 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 or error code

See also

emSetProcessData()

emSetProcessDataBits() Example
/* write bits to Process Data Image (synchronized with JobTask) */
EC_T_BYTE abyData[1] = { 0x12 };
dwRes = emSetProcessDataBits(dwInstanceId, EC_TRUE, 0 /* bit offset */,
    abyData, 8 /* bit length */, 5000);

6.4.5. emForceProcessDataBits

static EC_T_DWORD ecatForceProcessDataBits(EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wBitLength, EC_T_BYTE *pbyData, EC_T_DWORD dwTimeout)
EC_T_DWORD emForceProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wDataBitLen, EC_T_BYTE *pbyData, EC_T_DWORD dwTimeout)

Force a specific number of bits from a given buffer to the process image with a bit offset.

All output data set by this API are overwriting the values set by the application. All input data set by this API are overwriting the values read from the slaves. Forcing will be terminated by calling the corresponding functions. This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

  • bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data

  • dwBitOffsetPd – [in] Bit offset in Process data image

  • wDataBitLen – [in] Buffer length [bit]

  • pbyData – [in] Buffer containing transfered data

  • dwTimeout – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

emForceProcessDataBits() Example
/* force specific number of bits from given buffer to process image with a bit offset */
EC_T_BYTE abyData[1] = { 1 };
dwRes = emForceProcessDataBits(dwInstanceId, dwClientId,
    EC_FALSE, 0 /* bit offset */, 1 /* bit length */, abyData, 5000 /* timeout */);

See also

6.4.6. emReleaseProcessDataBits

static EC_T_DWORD ecatReleaseProcessDataBits(EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wBitLength, EC_T_DWORD dwTimeout)
EC_T_DWORD emReleaseProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_BOOL bOutputData, EC_T_DWORD dwBitOffsetPd, EC_T_WORD wBitLength, EC_T_DWORD dwTimeout)

Release previously forced process data.

  • Forced output: Value set by application become valid again. Because forced process data bits are written directly into the process output image, the application has to update the process image with the required value, otherwise the forced value is still valid.

  • Forced input: Value read from the slaves become valid again.

This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

  • bOutputData – [in] EC_TRUE: write output data, EC_FALSE: write input data

  • dwBitOffsetPd – [in] Bit offset in Process data image

  • wBitLength – [in] Number of bits that shall be written to the process image.

  • dwTimeout – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

emReleaseProcessDataBits() Example
/* release previously forced process data */
dwRes = emReleaseProcessDataBits(dwInstanceId, dwClientId,
    EC_FALSE, 0 /* bit offset */, 1 /* bit length */, 5000 /* timeout */);

See also

6.4.7. emReleaseAllProcessDataBits

static EC_T_DWORD ecatReleaseAllProcessDataBits(EC_T_DWORD dwClientId, EC_T_DWORD dwTimeout)
EC_T_DWORD emReleaseAllProcessDataBits(EC_T_DWORD dwInstanceID, EC_T_DWORD dwClientId, EC_T_DWORD dwTimeout)

Release all previously forced process data for a dedicated client.

  • Forced output: Value set by application become valid again. Because forced process data bits are written directly into the process output image, the application has to update the process image with the required value, otherwise the forced value is still valid.

  • Forced input: Value read from the slaves become valid again.

This function may not be called from within the JobTask’s context.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • dwClientId – [in] Client ID returned by RegisterClient (0 if all registered clients shall be notified)

  • dwTimeout – [in] Timeout [ms]. The timeout value must not be set to EC_NOWAIT.

Returns

EC_E_NOERROR or error code

emReleaseAllProcessDataBits() Example
/* release all previously forced process data of client */
dwRes = emReleaseAllProcessDataBits(dwInstanceId, dwClientId, 5000 /* timeout */);

See also

6.4.8. emGetProcessImageInputPtr

static EC_T_BYTE *ecatGetProcessImageInputPtr(EC_T_VOID)
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

emGetProcessImageInputPtr() Example
EC_T_BYTE* pbyProcessImageInput = emGetProcessImageInputPtr(dwInstanceId);

See also

6.4.9. emGetProcessImageOutputPtr

static EC_T_BYTE *ecatGetProcessImageOutputPtr(EC_T_VOID)
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

emGetProcessImageOutputPtr() Example
EC_T_BYTE* pbyProcessImageOutput = emGetProcessImageOutputPtr(dwInstanceId);

See also

6.4.10. emGetDiagnosisImagePtr

static EC_T_BYTE *ecatGetDiagnosisImagePtr(EC_T_VOID)
EC_T_BYTE *emGetDiagnosisImagePtr(EC_T_DWORD dwInstanceID)

Gets the diagnosis image pointer.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

Diagnosis image pointer

emGetDiagnosisImagePtr() Example
EC_T_BYTE* pbyProcessImageOutput = emGetDiagnosisImagePtr(dwInstanceId);

6.4.11. emGetDiagnosisImageSize

static EC_T_DWORD ecatGetDiagnosisImageSize(EC_T_VOID)
EC_T_DWORD emGetDiagnosisImageSize(EC_T_DWORD dwInstanceID)

Gets the diagnosis image size.

Parameters

dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

Returns

Diagnosis image size

6.4.12. emGetProcessVarInfoNumOf, emGetProcessVarInfoEx

static EC_T_DWORD ecatGetProcessVarInfoNumOf(EC_T_VAR_DIRECTION eVarDirection, EC_T_VAR_SOURCE eVarSource, EC_T_BOOL bFixedAddress, EC_T_WORD wSlaveAddress, EC_T_DWORD *pdwProcessVarInfoNumOf)
EC_T_DWORD emGetProcessVarInfoNumOf(EC_T_DWORD dwInstanceID, EC_T_VAR_DIRECTION eVarDirection, EC_T_VAR_SOURCE eVarSource, EC_T_BOOL bFixedAddress, EC_T_WORD wSlaveAddress, EC_T_DWORD *pdwProcessVarInfoNumOf)

Get process variables information.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • eVarDirection – [in] INPUTs, OUTPUTs, … . See EC_T_VAR_DIRECTION .

  • eVarSource – [in] Slave, Master, … . See EC_T_VAR_SOURCE .

  • bFixedAddress – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.

  • wSlaveAddress – [in] Slave address according to bFixedAddress

  • pdwProcessVarInfoNumOf – [out] Process variables count

Returns

EC_E_NOERROR or error code

static EC_T_DWORD ecatGetProcessVarInfoEx(EC_T_VAR_DIRECTION eVarDirection, EC_T_VAR_SOURCE eVarSource, EC_T_BOOL bFixedAddress, EC_T_WORD wSlaveAddress, EC_T_PROCESS_VAR_INFO_EX *aoVarInfo, EC_T_DWORD dwMaxProcessVarInfoNumOf, EC_T_DWORD *pdwProcessVarInfoNumOf)
EC_T_DWORD emGetProcessVarInfoEx(EC_T_DWORD dwInstanceID, EC_T_VAR_DIRECTION eVarDirection, EC_T_VAR_SOURCE eVarSource, EC_T_BOOL bFixedAddress, EC_T_WORD wSlaveAddress, EC_T_PROCESS_VAR_INFO_EX *aoVarInfoEx, EC_T_DWORD dwMaxVarInfoCnt, EC_T_DWORD *pdwVarInfoCnt)

Get process variables information.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • eVarDirection – [in] INPUTs, OUTPUTs, … . See EC_T_VAR_DIRECTION .

  • eVarSource – [in] Slave, Master, … . See EC_T_VAR_SOURCE .

  • bFixedAddress – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.

  • wSlaveAddress – [in] Slave address according to bFixedAddress

  • aoVarInfoEx – [out] The read process variable extended information entries

  • dwMaxVarInfoCnt – [in] Maximum number of variables that can be stored at aoVarInfoEx

  • pdwVarInfoCnt – [out] Number process variable entries that have been stored in aoVarInfoEx

Returns

EC_E_NOERROR or error code

The following example demonstrates how to get all process data variables:

emGetProcessVarInfoEx() Example
EC_T_DWORD dwProcessVarInfoNumOf = 0;
dwRes = emGetProcessVarInfoNumOf(dwInstanceId, eVarDirection_All, eVarSource_All, EC_FALSE, 0, &dwProcessVarInfoNumOf);
/* ... */
EC_T_PROCESS_VAR_INFO_EX* aoVarInfoEx = (EC_T_PROCESS_VAR_INFO_EX*)OsMalloc(dwProcessVarInfoNumOf * sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emGetProcessVarInfoEx(dwInstanceId, eVarDirection_All, eVarSource_All, EC_FALSE, 0, aoVarInfoEx, dwProcessVarInfoNumOf, EC_NULL);
/* ... */
OsSafeFree(aoVarInfoEx);

EC_T_VAR_DIRECTION

enum EC_T_VAR_DIRECTION

Values:

enumerator eVarDirection_Undefined

Undefined Direction

enumerator eVarDirection_INPUT

INPUTs

enumerator eVarDirection_OUTPUT

OUTPUTs

enumerator eVarDirection_All

INPUTs and OUTPUTs

enumerator eVarDirection_BCppDummy

EC_T_VAR_SOURCE

enum EC_T_VAR_SOURCE

Values:

enumerator eVarSource_Undefined

Undefined Source

enumerator eVarSource_All

Slaves and Master/Monitor/Simulator

enumerator eVarSource_AllSlaves

All Slaves

enumerator eVarSource_Slave

Slave

enumerator eVarSource_Master

Master

enumerator eVarSource_Monitor

Monitor

enumerator eVarSource_Simulator

Simulator

enumerator eVarSource_BCppDummy

6.4.13. emGetSlaveInpVarInfoNumOf

static EC_T_DWORD ecatGetSlaveInpVarInfoNumOf(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveInpVarInfoNumOf)
EC_T_DWORD emGetSlaveInpVarInfoNumOf(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveInpVarInfoNumOf)

Gets the number of input variables of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • pwSlaveInpVarInfoNumOf – [out] Number of found process variable entries

Returns

See also

emGetSlaveInpVarInfoNumOf() Example
/* get number of input variables of specific slave */
EC_T_WORD numOfVars = 0;
dwRes = emGetSlaveInpVarInfoNumOf(dwInstanceId, EC_TRUE, 1004, &numOfVars);

6.4.14. emGetSlaveInpVarInfo

static EC_T_DWORD ecatGetSlaveInpVarInfo(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)
EC_T_DWORD emGetSlaveInpVarInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

Gets the process variable information entries of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • wNumOfVarsToRead – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries

  • pSlaveProcVarInfoEntries – [out] The read process variable information entries

  • pwReadEntries – [out] The number of read process variable information entries

Returns

EC_E_NOERROR or error code

struct EC_T_PROCESS_VAR_INFO

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN]

[out] Name of the found process variable

EC_T_WORD wDataType

[out] Data type of the found process variable (according to ETG.1000, section 5). See also EcType.h, DEFTYPE_BOOLEAN.

EC_T_WORD wFixedAddr

[out] Station address of the slave that is owner of this variable

EC_T_INT nBitSize

[out] Size in bits of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

[out] Determines whether the found process variable is an input variable or an output variable

MAX_PROCESS_VAR_NAME_LEN

Maximum length of a process variable name: 71 characters

emGetSlaveInpVarInfo() Example
/* get process variable information entries of specific slave */
EC_T_PROCESS_VAR_INFO aSlaveInpVarInfoNumOf[4];
EC_T_WORD wReadEntries = 0;
EC_T_WORD numOfVars = 0;
emGetSlaveInpVarInfoNumOf(dwInstanceId, EC_TRUE, 1004, &numOfVars);
dwRes = emGetSlaveInpVarInfo(dwInstanceId, EC_TRUE, 
    1001, numOfVars, aSlaveInpVarInfoNumOf, &wReadEntries);

6.4.15. emGetSlaveInpVarInfoEx

static EC_T_DWORD ecatGetSlaveInpVarInfoEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)
EC_T_DWORD emGetSlaveInpVarInfoEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntriesEx, EC_T_WORD *pwReadEntries)

Gets the input process variable extended information entries of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • wNumOfVarsToRead – [in] Number process variable entries that have been stored in pSlaveProcVarInfoEntries

  • pSlaveProcVarInfoEntriesEx – [out] The read process variable extended information entries

  • pwReadEntries – [out] The number of read process variable information entries

Returns

struct EC_T_PROCESS_VAR_INFO_EX

Public Members

EC_T_CHAR szName[MAX_PROCESS_VAR_NAME_LEN_EX]

[out] Name of the found process variable

EC_T_WORD wDataType

[out] Data type of the found process variable (according to ETG.1000, section 5). See also EcType.h, DEFTYPE_BOOLEAN.

EC_T_WORD wFixedAddr

[out] Station address of the slave that is owner of this variable

EC_T_INT nBitSize

[out] Size in bits of the found process variable

EC_T_INT nBitOffs

[out] Bit offset in the process data image

EC_T_BOOL bIsInputData

[out] Determines whether the found process variable is an input variable or an output variable

EC_T_WORD wIndex

[out] Object index

EC_T_WORD wSubIndex

[out] Object sub index

EC_T_WORD wPdoIndex

[out] Index of PDO (process data object)

EC_T_WORD wWkcStateDiagOffs

[out] Bit offset in the diagnostic image (API GetDiagnosisImagePtr)

EC_T_WORD wMasterSyncUnit

[out] Master Sync Unit ID (ENI: Slave/ProcessData/RxPdo[1..4]@Su, Slave/ProcessData/TxPdo[1..4]@Su, comment at Cyclic/Frame/Cmd)

EC_T_DWORD dwTaskId

[out] ID of task where process variable is located

EC_T_CYC_COPY_INFO CopyInfo

[out] Copy Info if applied to the variable

MAX_PROCESS_VAR_NAME_LEN_EX

Maximum length of an extended process variable name: 127 characters

emGetSlaveInpVarInfoEx() Example
EC_T_PROCESS_VAR_INFO_EX aSlaveInpVarInfoNumOf[4];
EC_T_WORD wReadEntries = 0;
EC_T_WORD  wNumOfVarsToRead = 4;
emGetSlaveInpVarInfoNumOf(dwInstanceId, EC_TRUE, 1004, &wNumOfVarsToRead);
/* get extended process variable information entries of specific slave */
dwRes = emGetSlaveInpVarInfoEx(dwInstanceId, EC_TRUE, 1001, 
    wNumOfVarsToRead, aSlaveInpVarInfoNumOf, &wReadEntries);

6.4.16. emGetSlaveOutpVarInfoNumOf

static EC_T_DWORD ecatGetSlaveOutpVarInfoNumOf(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveOutpVarInfoNumOf)
EC_T_DWORD emGetSlaveOutpVarInfoNumOf(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD *pwSlaveOutpVarInfoNumOf)

Gets the number of output variables of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • pwSlaveOutpVarInfoNumOf – [out] Number of found process variables

Returns

EC_E_NOERROR or error code

emGetSlaveOutpVarInfoNumOf() Example
/* get number of output variables of specific slave */
EC_T_WORD numOfVars = 0;
dwRes = emGetSlaveOutpVarInfoNumOf(dwInstanceId, EC_TRUE, 1002, &numOfVars);

See also

6.4.17. emGetSlaveOutpVarInfo

static EC_T_DWORD ecatGetSlaveOutpVarInfo(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)
EC_T_DWORD emGetSlaveOutpVarInfo(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)

Gets the output process variable information entries of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • wNumOfVarsToRead – [in] Number of found process variable entries

  • pSlaveProcVarInfoEntries – [out] The read process variable information entries

  • pwReadEntries – [out] The number of read process variable information entries

Returns

EC_E_NOERROR or error code

emGetSlaveOutpVarInfo() Example
/* get general output process variable information entries of specific slave */
EC_T_PROCESS_VAR_INFO aoSlaveOutpVarInfo[4]; /* see emGetSlaveOutpVarInfoNumOf() */
EC_T_WORD wSlaveOutpVarInfoCnt = 0;
dwRes = emGetSlaveOutpVarInfo(dwInstanceId, EC_TRUE, 1002, 
    4 /* see emGetSlaveOutpVarInfoNumOf() */, aoSlaveOutpVarInfo, &wSlaveOutpVarInfoCnt);

See also

EC_T_PROCESS_VAR_INFO

6.4.18. emGetSlaveOutpVarInfoEx

static EC_T_DWORD ecatGetSlaveOutpVarInfoEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntries, EC_T_WORD *pwReadEntries)
EC_T_DWORD emGetSlaveOutpVarInfoEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wNumOfVarsToRead, EC_T_PROCESS_VAR_INFO_EX *pSlaveProcVarInfoEntriesEx, EC_T_WORD *pwReadEntries)

Gets the output process variable extended information entries of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • wNumOfVarsToRead – [in] Number of process variable information entries

  • pSlaveProcVarInfoEntriesEx – [out] The read process extended variable entries

  • pwReadEntries – [out] The number of read process variable information entries

Returns

EC_E_NOERROR or error code

emGetSlaveOutpVarInfoEx() Example
/* get extended output process variable information entries of specific slave */
EC_T_PROCESS_VAR_INFO_EX aoSlaveOutpVarInfo[4]; /* see emGetSlaveOutpVarInfoNumOf() */
EC_T_WORD wSlaveOutpVarInfoCnt = 0;
dwRes = emGetSlaveOutpVarInfoEx(dwInstanceId, EC_TRUE, 1002, 
    4 /* see emGetSlaveOutpVarInfoNumOf() */, aoSlaveOutpVarInfo, &wSlaveOutpVarInfoCnt);

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.19. emGetSlaveInpVarByObjectEx

static EC_T_DWORD ecatGetSlaveInpVarByObjectEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)
EC_T_DWORD emGetSlaveInpVarByObjectEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

Gets the input process variable extended information entry by object index, subindex of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • wIndex – [in] Object index

  • wSubIndex – [in] Object sub index

  • pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

emGetSlaveInpVarByObjectEx() Example
/* get input process variable extended information entry by object index, 
   subindex of specific slave */
EC_T_PROCESS_VAR_INFO_EX processVarInfoEntry;
OsMemset(&processVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emGetSlaveInpVarByObjectEx(dwInstanceId, EC_TRUE, 
    1004, 0x6000 /* Index */, 1 /* SubIndex */, &processVarInfoEntry);

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.20. emGetSlaveOutpVarByObjectEx

static EC_T_DWORD ecatGetSlaveOutpVarByObjectEx(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)
EC_T_DWORD emGetSlaveOutpVarByObjectEx(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)

Gets the input process variable extended information entry by object index, subindex of a specific slave.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • bFixedAddressing – [in] EC_TRUE: use station address, EC_FALSE: use AutoInc address

  • wSlaveAddress – [in] Slave address according bFixedAddressing

  • wIndex – [in] Object index

  • wSubIndex – [in] Object sub index

  • pProcessVarInfoEntry – [out] Process variable extended information entry

Returns

EC_E_NOERROR or error code

emGetSlaveOutpVarByObjectEx() Example
/* get output process variable extended information entry 
   by object index, subindex of specific slave. */
EC_T_PROCESS_VAR_INFO_EX oSlaveOutpVarInfo;
OsMemset(&oSlaveOutpVarInfo, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emGetSlaveOutpVarByObjectEx(dwInstanceId, EC_TRUE, 
    1002, 0x3001 /* Index */, 1 /* SubIndex */, &oSlaveOutpVarInfo);

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.21. emFindInpVarByName

static EC_T_DWORD ecatFindInpVarByName(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)
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

emFindInpVarByName() Example
/* get general information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO));
dwRes = emFindInpVarByName(dwInstanceId, "Slave_1004 [EL1014].Channel 1.Input", &oProcessVarInfoEntry);

See also

EC_T_PROCESS_VAR_INFO

6.4.22. emFindInpVarByNameEx

static EC_T_DWORD ecatFindInpVarByNameEx(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)
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

emFindInpVarByNameEx() Example
/* get extended information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO_EX oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emFindInpVarByNameEx(dwInstanceId, "Slave_1004 [EL1014].Channel 1.Input", &oProcessVarInfoEntry);

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.23. emFindOutpVarByName

static EC_T_DWORD ecatFindOutpVarByName(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO *pProcessVarInfoEntry)
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

emFindOutpVarByName() Example
/* get general information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO));
dwRes = emFindOutpVarByName(dwInstanceId, "Slave_1002 [EL2004].Channel 1.Output", &oProcessVarInfoEntry);

See also

EC_T_PROCESS_VAR_INFO

6.4.24. emFindOutpVarByNameEx

static EC_T_DWORD ecatFindOutpVarByNameEx(const EC_T_CHAR *szVariableName, EC_T_PROCESS_VAR_INFO_EX *pProcessVarInfoEntry)
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

emFindOutpVarByName() Example
/* get extended information about Process Data variable by name */
EC_T_PROCESS_VAR_INFO_EX oProcessVarInfoEntry;
OsMemset(&oProcessVarInfoEntry, 0, sizeof(EC_T_PROCESS_VAR_INFO_EX));
dwRes = emFindOutpVarByNameEx(dwInstanceId, "Slave_1002 [EL2004].Channel 1.Output", &oProcessVarInfoEntry);

See also

EC_T_PROCESS_VAR_INFO_EX

6.4.25. emLinkInputVarByName

static EC_T_DWORD ecatLinkInputVarByName(const EC_T_CHAR *szVarName, EC_T_LINK_VAR_INFO *pLinkVarInfo)
EC_T_DWORD emLinkInputVarByName(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVarName, EC_T_LINK_VAR_INFO *pLinkVarInfo)

Link application variable to input process image. Input process variable is given by its name.

Parameters

  • dwInstanceID – [in] Master instance ID

  • szVarName – [in] Name of variable

  • pLinkVarInfo – [in] Information about linked variable

Returns

EC_E_NOERROR or an error code

typedef EC_T_VOID (*EC_PF_LINK_VAR_CONVERTER)(const EC_T_LINK_VAR_INFO *pApplVarInfo, EC_T_BYTE *pbyProcessImage)
Param pApplVarInfo

[in] Information about application variable

Param pbyProcessImage

[in] Pointer to input resp. output process image

struct EC_T_LINK_VAR_INFO

Public Members

EC_T_VOID *pvContext

[in] Arbitrarily application-defined parameter

EC_T_BYTE *pbyApplVar

[in] Pointer to application variable where process variable should be linked to

EC_T_WORD wApplVarType

[in] Type of application variable

EC_T_WORD wApplVarBitSize

[in] Size of variable (in bits)

EC_T_DWORD dwApplVarBitOffs

[in] Bit offset of variable

EC_PF_LINK_VAR_CONVERTER pfnConverter

[in] Callback function to manipulate the input when reading from process image resp. the output when writing to process image (could be EC_NULL)

EC_T_PROCESS_VAR_INFO_EX *pProcVarInfoEx

[out] Extended information about process variable

6.4.26. emLinkInputVarByObject

static EC_T_DWORD ecatLinkInputVarByObject(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_LINK_VAR_INFO *pLinkVarInfo)
EC_T_DWORD emLinkInputVarByObject(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_LINK_VAR_INFO *pLinkVarInfo)

Link application variable to input process image. Input process variable is given by its object index and subindex of a specific slave.

Parameters

  • dwInstanceID – [in] Master instance ID

  • bFixedAddressing – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.

  • wSlaveAddress – [in] Slave address according to bFixedAddressing

  • wIndex – [in] Object index

  • wSubIndex – [in] Object subindex

  • pLinkVarInfo – [in] Information about linked variable

Returns

EC_E_NOERROR or an error code

See also

EC_T_LINK_VAR_INFO

6.4.27. emLinkOutputVarByName

static EC_T_DWORD ecatLinkOutputVarByName(const EC_T_CHAR *szVarName, EC_T_LINK_VAR_INFO *pLinkVarInfo)
EC_T_DWORD emLinkOutputVarByName(EC_T_DWORD dwInstanceID, const EC_T_CHAR *szVarName, EC_T_LINK_VAR_INFO *pLinkVarInfo)

Link application variable to output process image. Output process variable is given by its name.

Parameters

  • dwInstanceID – [in] Master instance ID

  • szVarName – [in] Name of variable

  • pLinkVarInfo – [in] Information about linked variable

Returns

EC_E_NOERROR or an error code

See also

EC_T_LINK_VAR_INFO

6.4.28. emLinkOutputVarByObject

static EC_T_DWORD ecatLinkOutputVarByObject(EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_LINK_VAR_INFO *pLinkVarInfo)
EC_T_DWORD emLinkOutputVarByObject(EC_T_DWORD dwInstanceID, EC_T_BOOL bFixedAddressing, EC_T_WORD wSlaveAddress, EC_T_WORD wIndex, EC_T_WORD wSubIndex, EC_T_LINK_VAR_INFO *pLinkVarInfo)

Link application variable to output process image. Output process variable is given by its object index and subindex of a specific slave.

Parameters

  • dwInstanceID – [in] Master instance ID

  • bFixedAddressing – [in] Use station address if EC_TRUE. Otherwise use AutoInc address.

  • wSlaveAddress – [in] Slave address according to bFixedAddressing

  • wIndex – [in] Object index

  • wSubIndex – [in] Object subindex

  • pLinkVarInfo – [in] Information about linked variable

Returns

EC_E_NOERROR or an error code

See also

EC_T_LINK_VAR_INFO

6.4.29. emTraceDataConfig

static EC_T_DWORD ecatTraceDataConfig(EC_T_WORD wTraceDataSize)
EC_T_DWORD emTraceDataConfig(EC_T_DWORD dwInstanceID, EC_T_WORD wTraceDataSize)

Configures a trace data buffer and enables it for transmission.

Must be called after initialization and before configuration.

Note

If wTraceDataSize is too large, configuration will fail with return code EC_E_XML_CYCCMDS_SIZEMISMATCH.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • wTraceDataSize – [in] Size of Trace Data in bytes

Returns

6.4.30. emTraceDataGetInfo

static EC_T_DWORD ecatTraceDataGetInfo(EC_T_TRACE_DATA_INFO *pTraceDataInfo)
EC_T_DWORD emTraceDataGetInfo(EC_T_DWORD dwInstanceID, EC_T_TRACE_DATA_INFO *pTraceDataInfo)

Get information about the offset and size of trace data.

The trace data buffer is located in EC_T_TRACE_DATA_INFO.pbyData at the byte offset EC_T_TRACE_DATA_INFO.dwOffset.

Parameters

  • dwInstanceID – [in] Instance ID (Multiple EtherCAT Network Support)

  • pTraceDataInfo – [out] Information about trace data

Returns

EC_E_NOERROR or error code

struct EC_T_TRACE_DATA_INFO

Public Members

EC_T_BYTE *pbyData

[out] Process data output buffer, containing trace data

EC_T_DWORD dwOffset

[out] Trace data offset in bytes

EC_T_WORD wSize

[out] Trace data size in bytes

emTraceDataGetInfo() Example
/* get trace data offset and size */
EC_T_TRACE_DATA_INFO traceDataInfo;
OsMemset(&traceDataInfo, 0, sizeof(EC_T_TRACE_DATA_INFO));
dwRes = emTraceDataGetInfo(dwInstanceId, &traceDataInfo);

6.4.31. 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.32. 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.33. 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.34. 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.35. 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.36. 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.37. 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

Diagram illustrating how EC_COPYBITS copies a contiguous bit range from a source byte array at a given bit offset into a destination byte array at a separate bit offset 
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 0x3D 0xAD 0x00 */

6.4.38. EC_COMPAREBITS

EC_COMPAREBITS(pbyBuf1, nBitOffs1, pbyBuf2, nBitOffs2, nBitSize)

Compares a block of bits of two buffers.

Note

The buffers are compared bitwise with the same semantic as memcmp(). The buffers are not checked for overrun.

Parameters

  • pbyBuf1 – [in] Buffer 1

  • nBitOffs1 – [in] Bit offset within buffer 1

  • pbyBuf2 – [in] Buffer 2

  • nBitOffs2 – [in] Bit offset within buffer 2

  • nBitSize – [in] Bit size to compare

Returns

Integral value indicating the relationship between the content of the memory blocks:

  • 0: The blocks of bits within the two buffers are equal

  • <0: Binary value from block of bits in buffer 1 has a lower value than binary value from block of bits in buffer 2

  • >0: Binary value from block of bits in buffer 1 has a greater value than binary value from block of bits in buffer 2

See also

EC_T_BYTE pbyBuf1[] = {0xB8, 0x3D, 0xAD, 0x00};
EC_T_BYTE pbyBuf2[] = {0xF4, 0xED, 0x69, 0xA5};
assert(0 == EC_COMPAREBITS(pbyBuf1, 3, pbyBuf2, 6, 22));

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

6.4.40. 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 only be 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

6.4.41. EC_COPYBIT

EC_COPYBIT(pbyBuf, nBitOffs, bVal)

Copy a boolean bit value into the buffer.

Parameters

  • pbyBuf – Destination buffer.

  • nBitOffs – Bit offset to write.

  • bVal – Boolean bit value.

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

6.4.43. EC_SETBIT

EC_SETBIT(pbyBuf, nBitOffs)

Set a single bit in the buffer.

Parameters

  • pbyBuf – Destination buffer.

  • nBitOffs – Bit offset to set.

6.4.44. EC_CLRBIT

EC_CLRBIT(pbyBuf, nBitOffs)

Clear a single bit in the buffer.

Parameters

  • pbyBuf – Destination buffer.

  • nBitOffs – Bit offset to clear.