viReadAsync

Syntax

viReadAsync(ViSession vi, ViPBuf buf, ViUInt32 count, ViPJobId jobId);

Description

This function asynchronously transfers data from a device. The data that is read is stored in the buffer represented by buf. This function normally returns before the transfer terminates. An I/O Completion event is posted when the transfer is actually completed.

This function returns jobId, which you can use either with viTerminate to abort the operation or with an I/O Completion event to identify which asynchronous read operation completed.

If you pass VI_NULL as the jobId parameter to the viReadAsync operation, no jobId will be returned. This option may be useful if only one asynchronous operation will be pending at a given time. The value VI_NULL is a reserved jobId and has a special meaning in viTerminate.

If multiple jobs are queued at the same time on the same session, an application can use the jobId to distinguish the jobs, as they are unique within a session.

Parameters

Name	Dir	Type	Description
vi	IN	ViSession	Unique logical identifier to a session.
buf	OUT	ViPBuf	Represents the location of a buffer to receive data from the device.
count	IN	ViUInt32	Number of bytes to be read.
jobId	OUT	ViPJobId	Represents the location of a variable that will be set to the job identifier of this asynchronous read operation.
Special Value for jobId Parameter
Value			Description
VI_NULL			Do not return a job identifier.

Return Values 

Type ViStatus	This is the function return status. It returns either a completion code or an error code as follows.
Completion Codes	Description
VI_SUCCESS	Asynchronous read operation successfully queued.
VI_SUCCESS_SYNC	Read operation performed synchronously.
Error Codes	Description
VI_ERROR_INV_SESSION VI_ERROR_INV_OBJECT	The given session or object reference is invalid (both are the same value).
VI_ERROR_QUEUE_ERROR	Unable to queue read operation.
VI_ERROR_RSRC_LOCKED	Specified operation could not be performed because the resource identified by vi has been locked for this kind of access.
VI_ERROR_IN_PROGRESS	Unable to start a new asynchronous operation while another asynchronous operation is in progress.

Using viReadAsync

Programming Tip: Performing multiple asynchronous operations simultaneously: The VISA asynchronous functions viMoveAsync, viReadAsync and viWriteAsync initiate I/O operations to a device on a separate thread which allows the main thread to continue without blocking when doing I/O. VISA allows you to initiate multiple simultaneous asynchronous operations on a single VISA session, but the Agilent IO Libraries Suite allows only a single thread at a time from a given session to access the device. To perform multiple asynchronous operations simultaneously, you can work around this limitation by opening multiple sessions to the device and doing one VISA asynchronous call on each session.

The queuing method is commonly used when an immediate response from your application is not needed (refer to the Agilent VISA User Guide). To use the queuing method for receiving notification that an event has occurred, you must do the following:

• Enable one or several events with the viEnableEvent function.
• Use viReadAsync to obtain the specific jobId from the session you are monitoring.
• When ready to query, use the viWaitOnEvent function with VI_EVENT_IO_COMPLETION to check for queued events.

After the specified event has occurred, the event information is retrieved and the program returns immediately. If the specified event has not occurred, the program suspends execution until a specified event occurs or until the specified timeout period is reached.

The following example demonstrates this by reading *IDN? as the event.

See Also

viRead, viTerminate, viWrite, viWriteAsync