viMoveAsync

Agilent VISA.NET

viMoveAsync

Syntax

viMoveAsync(ViSession vi, ViUInt16 srcSpace, ViBusAddress srcOffset, ViUInt16 srcWidth, ViUInt16 destSpace, ViBusAddress destOffset, ViUInt16 destWidth, ViBusSize length, ViPJobId jobId);

Description

This operation asynchronously moves data from the specified source to the specified destination. This operation queues up the transfer in the system, then it returns immediately without waiting for the transfer to complete. When the transfer terminates, a VI_EVENT_IO_COMPLETE event indicates the status of the transfer.

The operation returns jobId which you can use either with viTerminate to abort the operation or with VI_EVENT_IO_COMPLETION events to identify which asynchronous move operations completed. The source and destination can be either local memory or the offset of the device/interface with which this INSTR or MEMACC Resource is associated. This operation uses the specified data width and address space.

If the ViSession parameter (vi) refers to an INSTR session, the offset parameters specify relative offsets from the start of the instrument’s address space. If the ViSession parameter (vi) refers to a MEMACC session, the offset parameters are absolute offsets from the start of memory in the specified VXI address space.

Valid entries for specifying address space:

Value

Description

VI_A16_SPACE

Address A16 memory address space of the VXI/MXI bus.

VI_A24_SPACE

Address A24 memory address space of the VXI/MXI bus.

VI_A32_SPACE

Address A32 memory address space of the VXI/MXI bus.

VI_A64_SPACE

Address the A64 address space of VXI/MXI bus.

VI_LOCAL_SPACE

Address the process-local memory (using virtual address).

VI_OPAQUE_SPACE

Addresses potentially volatile data (using a virtual address).

VI_PXI_CFG_SPACE

Address the PCI configuration space.

VI_PXI_BAR0_SPACE –
VI_PXI_BAR5_SPACE

Address the specified PCI memory or I/O space.

VI_PXI_ALLOC_SPACE

Access physical locally allocated memory.

Valid entries for specifying widths:

Value

Description

VI_WIDTH_8

Performs an 8-bit (D08) transfer.

VI_WIDTH_16

Performs a 16-bit (D16) transfer.

VI_WIDTH_32

Performs a 32-bit (D32) transfer.

VI_WIDTH_64

Performs a 64-bit (D64) transfer.

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.

If you pass VI_NULL as the jobId parameter to the viMoveAsync operation, no jobId will be returned. This option may be useful if only one asynchronous operation will be pending at a given time. 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. The value VI_NULL is a reserved jobId and has a special meaning in viTerminate.

If srcSpace is not VI_LOCAL_SPACE, srcOffset is a relative address of the device associated with the given INSTR resource. Similarly, if destspace is not VI_LOCAL_SPACE, destOffset is a relative address of the device associated with the given INSTR resource.

Parameters

Name

Dir

Type

Description

vi

IN

ViSession

Unique logical identifier to a session.

srcSpace

IN

ViUInt16

Specifies the address space of the source.

srcOffset

IN

ViBusAddress

Offset of the starting address or register from which to read.

srcWidth

IN

ViUInt16

Specifies the data width of the source.

destSpace

IN

ViUInt16

Specifies the address space of the destination.

destOffset

IN

ViBusAddress

Offset of the starting address or register to write to.

destWidth

IN

ViUInt16

Specifies the data width of the destination.

length

IN

ViBusSize

Number of data elements to transfer, where the data width of the elements to transfer is identical to the source data width.

jobId

OUT

ViPJobId

Represents the location of an integer that will be set to the job identifier of this asynchronous move operation. Each time an asynchronous move operation is called, it is assigned a unique job identifier.

Special Value for jobId Parameter

Value

 

 

Action Description

VI_NULL

 

 

Operation does 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

Operation completed successfully.

VI_SUCCESS_SYNC

Operation performed synchronously.

Error Codes

Description

VI_ERROR_INV_SESSION
VI_ERROR_OBJECT

The given session or object reference is invalid (both are the same value).

VI_ERROR_NSUP_OPER

The given vi does not support this operation.

VI_ERROR_QUEUE

Unable to queue move 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.

See Also

viMove. Also, see INSTR and MEMACC Resource descriptions.