niSync_ReadMultipleTriggertimestamp

C Function Prototype

ViStatus _VI_FUNC niSync_ReadMultipleTriggertimestamp (ViSession vi, ViConstString terminal, ViUInt32 timestampsToRead, ViReal64 timeout, ViUInt32 * timeSecondsBuffer, ViUInt32 * timeNanosecondsBuffer, ViUInt16 * timeFractionalNanosecondsBuffer, ViInt32 * detectedEdgeBuffer, ViUInt32 * timestampsRead);

Purpose

Reads trigger timestamps from the internal software buffer for the specified terminal. The read operation is a destructive, blocking read. That is, the oldest unread timestamp associated with the specified terminal is returned. When a timestamp is read, it is removed from the buffer. The function does not return until the timestamps requested are available to be read, or the specified timeout elapses.

Troubleshooting a Full Buffer

If the internal software buffer associated with the specified terminal is full, timestamp operations for that terminal are suspended and an error specifying that the internal software buffer has overflowed is returned.

If the hardware timestamp buffer is full, all trigger timestamp operations are suspended and an error specifying that the hardware timestamp buffer has overflowed is returned. niSync_ReadMultipleTriggertimestamp continues to return previously generated timestamps, despite the overflow condition, until no timestamps are available.

To clear this error condition, you must invoke niSync_DisabletimestampTrigger or expand the size of the timestamp buffer using the NISYNC_ATTR_1588_TIMESTAMP_BUF_SIZE attribute.

Note Note  
  • If timestampsToRead is not equal to timestampsRead, the data held in the output arrays from index timestampsRead to the end of the arrays is uninitialized, and should be considered invalid.
  • NI-Sync supports only the time range between 1 January 1970 and 1 January 2100. Therefore, if the supported time range ends before a timestamp is captured, an error is returned.

Parameters

Name Type Description
vi ViSession The session handle that you obtain from niSync_init. The handle identifies a particular instrument session.
terminal viConstString Specifies the terminal that contains the the trigger signal you would like to read timestamps from.
timestampsToRead ViUInt32 Specifies the number of timestamps to read. If the number of timestamps is not available before the timeout elapses, the number read before the timeout occurred is returned.
timeout ViReal64 Specifies the time to wait, in seconds, for a timestamp to be generated. If the function can't find any timestamps to read on the specified terminal, it returns a timeout error and stops the program. The default value is 10 seconds.
timeSecondsBuffer ViUInt32 * An input pointer to an array of ViUInt32 values. The caller of this function must allocate an array of ViUInt32s of size timestampsToRead and pass the pointer to the array in this argument. The function sets the values of the ViUInt32s to the seconds field of when the timestamp occurred. After the function returns, index 0 holds the earliest occurring seconds value, and the value returned in timestampsRead, minus one, is the index in which the latest occurring seconds value is stored.
timeNanosecondsBuffer ViUInt32 * An input pointer to an array of ViUInt32 values. The caller of this function must allocate an array of ViUInt32s of size timestampsToRead and pass the pointer to the array in this argument. The function sets the values of the ViUInt32s to the nanoseconds field of when the time stamp occurred. After the function returns, index 0 holds the earliest occurring nanoseconds value, and the value returned in timestampsRead, minus one, is the index in which the latest occurring nanoseconds value is stored.
timeFractionalNanosecondsBuffer ViUInt16 * An input pointer to an array of ViUInt16 values. The caller of this function must allocate an array of ViUInt16s of size timestampsToRead and pass the pointer to the array in this argument. The function sets the values of the ViUInt16s to the fractional nanoseconds field of when the time stamp occurred. After the function returns, index 0 holds the earliest occurring fractional nanoseconds value, and the value returned in timestampsRead, minus one, is the index in which the latest occurring fractional nanoseconds value is stored.
detectedEdgeBuffer ViInt32 * An input pointer to an array of ViInt32s. The caller of this function must allocate an array of ViUInt32s of size timestampsToRead and pass the pointer to the array in this argument. After the function returns, index 0 holds the earliest occurring detectedEdge value, and the value returned in timestampsRead, minus one, is the index in which the latest occurring detectedEdge value is stored. Each detectedEdge is an integer enumeration that specifies the detected trigger condition.

Valid Values:
NISYNC_VAL_EDGE_RISING
NISYNC_VAL_EDGE_FALLING
timestampsRead ViUInt32 * An input pointer to a ViUInt32. The caller of this function must allocate a ViUInt32 and pass the pointer to the array in this argument. When the function returns, the value at this pointer is set to the number of actual time stamps read. This value may be different than timestampsToRead if a timeout or other error occurs while reading time stamps.

Return Values