NI TClk High Level Functions

High-Level Functions

• niTClk_ConfigureForHomogeneousTriggers
• niTClk_Synchronize
• niTClk_Initiate
• niTClk_WaitUntilDone
• niTClk_GetExtendedErrorInfo

niTClk_ConfigureForHomogeneousTriggers

ViStatus niTClk_ConfigureForHomogeneousTriggers (ViUInt32 sessionCount, ViSession sessions []);

Purpose

Configures the attributes commonly required for the TClk synchronization of device sessions with homogeneous triggers in a single PXI chassis or a single PC.

Use the niTClk_ConfigureForHomogeneousTriggers function to configure attributes for the Reference Clocks, Start Triggers, Reference Triggers, Script Triggers, and Pause Triggers.

If the niTClk_ConfigureForHomogeneousTriggers function cannot perform all the steps required for the given sessions, it returns an error. If the niTClk_ConfigureForHomogeneousTriggers function returns an error, use the instrument driver functions and attributes, along with the following NI-TClk attributes, for signal routing.

• NITCLK_ATTR_START_TRIGGER_MASTER_SESSION
• NITCLK_ATTR_REF_TRIGGER_MASTER_SESSION
• NITCLK_ATTR_SCRIPT_TRIGGER_MASTER_SESSION
• NITCLK_ATTR_PAUSE_TRIGGER_MASTER_SESSION

The niTClk_ConfigureForHomogeneousTriggers function affects the following clocks and triggers:

Reference Clocks

The niTClk_ConfigureForHomogeneousTriggers function configures the reference clocks if they are needed. Specifically, if you use the internal sample clocks or internal Sample Clock timebases, and the Reference Clock Source is either not configured—or set to None (no trigger configured), the niTClk_ConfigureForHomogeneousTriggers function configures the following:

Start Triggers

If the Start Trigger is set to None (no trigger configured) for all sessions, the sessions are configured to share the Start Trigger. The Start Trigger is shared by:

If the Start Triggers are None for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures the sessions to share the Start Trigger from the one excepted session. The Start Trigger is shared by:

If the Start Triggers are configured for all sessions, the niTClk_ConfigureForHomogeneousTriggers function does not affect the Start Triggers. Start Triggers are considered to be configured for all sessions if one of the following conditions is true:

Reference Triggers

For sessions that support Reference Triggers, if the Reference Triggers are set to None (no trigger configured) for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures sessions to share the Reference Triggers. The Reference Triggers are shared by:

If the Reference Triggers are configured for all sessions that support Reference Triggers, the niTClk_ConfigureForHomogeneousTriggers function does not affect the Reference Triggers. Reference Triggers are configured for all sessions if one of the following conditions is true:

Reference Trigger Holdoffs

Acquisition sessions may be configured with the Reference Trigger. For acquisition sessions, when the Reference Trigger is shared, niTClk_ConfigureForHomogeneousTriggers configures the holdoff attributes (which are instrument driver specific) on the Reference Trigger master session so that the session does not recognize the Reference Trigger before the other sessions are ready. This condition is only relevant when the Sample Clock rates, Sample Clock timebase rates, sample counts, holdoffs, and/or any delays for the acquisitions are different.

When the Sample Clock rates, Sample Clock timebase rates, and/or the sample counts are different in acquisition sessions sharing the Reference Trigger, you must also set the holdoff attributes for the Reference Trigger master, using the instrument driver.

Script Triggers

For sessions that support Script Triggers, if the Script Triggers are set to None (no trigger configured) for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures sessions to share the Script Triggers. The Script Triggers are shared by:

If the Script Triggers are configured for all sessions that support Script Triggers, niTClk_ConfigureForHomogeneousTriggers does not affect Script Triggers. Script Triggers are configured for all sessions if one of the following conditions is true:

Pause Triggers

For sessions that support Pause Triggers, if the Pause Triggers are set to None (no trigger configured) for all except one session, the niTClk_ConfigureForHomogeneousTriggers function configures sessions to share the Pause Triggers. The Pause Triggers are shared by:

If the Pause Triggers are configured for all generation sessions that support Pause Triggers, niTClk_ConfigureForHomogeneousTriggers does not affect Pause Triggers. Pause Triggers are configured for all sessions if one of the following conditions is true:

Parameters

Input

Name	Type	Description
sessionCount	ViUInt32	Specifies the number of elements in the sessions array.
sessions	ViSession []	Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference.

Return Value

The status code returned by the function.

• A value of 0 indicates success.
• A negative value indicates an error.
• A value greater than 0 indicates a warning.

Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.

niTClk_Synchronize

ViStatus niTClk_Synchronize (ViUInt32 sessionCount, ViSession sessions [], ViReal64 minTime);

Purpose

Synchronizes the TClk signals on the given sessions. After the niTClk_Synchronize function executes, the TClk signals from all the sessions are synchronized.

Note  Before using the niTClk_Synchronize function, verify that your system is configured, as described in the PXI Trigger Lines and RTSI Lines topic.

Parameters

Input

Name	Type	Description
sessionCount	ViUInt32	Specifies the number of elements in the sessions array.
sessions	ViSession []	Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference.
minTime	ViReal64	Specifies the minimum TClk period, in seconds. Valid values are 0.0 s to 0.050 s (50 ms), inclusive. The minimum period for a single chassis/PC is 200 ns. If the specified value is less than 200 ns, NI-TClk automatically coerces the minimum TClk period to 200 ns. For multichassis synchronization, adjust this value to account for the propagation delays through the various devices and cables.

Return Value

The status code returned by the function.

• A value of 0 indicates success.
• A negative value indicates an error.
• A value greater than 0 indicates a warning.

Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.

niTClk_Initiate

Specific Function

ViStatus niTClk_Initiate (ViUInt32 sessionCount, ViSession sessions []);

Purpose

Initiates the acquisition and/or generation sessions that you specify. This function also processes any special requirements that are needed for the synchronization.

For example, the session that exports the TClk-synchronized Start Trigger is not initiated until after the niTClk_Initiate function initiates all the sessions that import the TClk-synchronized Start Trigger.

Parameters

Input

Name	Type	Description
sessionCount	ViUInt32	Specifies the number of elements in the sessions array.
sessions	ViSession []	Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference.

Return Value

The status code returned by the function.

• A value of 0 indicates success.
• A negative value indicates an error.
• A value greater than 0 indicates a warning.

Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.

niTClk_WaitUntilDone

ViStatus niTClk_WaitUntilDone (ViUInt32 sessionCount, ViSession sessions [], ViReal64 timeout);

Purpose

Waits until the acquisitions and/or generations corresponding to the sessions are done, or until the function returns a timeout error.

niTClk_WaitUntilDone is a blocking function that periodically checks the operation status. This function returns control to the calling program, if the operation completes successfully, or if an error occurs (including a timeout error).

This function is most useful for finite data operations that you want to complete within a certain time.

Parameters

Input

Name	Type	Description
sessionCount	ViUInt32	Specifies the number of elements in the sessions array.
sessions	ViSession []	Specifies the array of session references that are being synchronized. Obtain session references from the instrument driver by using the Get Session Reference function, where is the name of the instrument driver. Example: niScope_GetSessionReference.
timeout	ViReal64	Specifies the amount of time, in seconds, that the niTClk_WaitUntilDone function waits, for the sessions to complete. If the timeout parameter is exceeded, the niTClk_WaitUntilDone function returns an error.

Return Value

The status code returned by the function.

• A value of 0 indicates success.
• A negative value indicates an error.
• A value greater than 0 indicates a warning.

Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.

niTClk_GetExtendedErrorInfo

Specific Function

ViStatus niTClk_GetExtendedErrorInfo (ViChar errorString [], ViUInt32 errorStringSize);

Purpose

Reports extended error information for the most recent NI-TClk function that returned an error.

To determine the function that returned an error, use the return values of the individual functions. After the niTClk_GetExtendedErrorInfo function reports an errorString, this function does not report an empty string again.

Parameters

Input

Name	Type	Description
errorString	ViChar []	Extended error description. If errorString is NULL, then the string is not large enough to hold the entire error description. In this case, niTClk_GetExtendedErrorInfo returns the size of the full error string, which can be used with niTClk_GetExtendedErrorInfo to retrieve the full error string.
errorStringSize	ViUInt32	Size of errorString. If errorStringSize is 0, then it is not large enough to hold the entire error description. In this case, niTClk_GetExtendedErrorInfo returns the size of the full error string, which can be used with niTClk_GetExtendedErrorInfo to retrieve the full error string.

Return Value

The status code returned by the function.

• A value of 0 indicates success.
• A negative value indicates an error.
• A value greater than 0 indicates a warning.

Use niTClk_GetExtendedErrorInfo to get detailed information about individual errors and warnings.