viMoveAsync/viMoveAsyncEx
Purpose
Moves a block of data asynchronously.
C Syntax
ViStatus viMoveAsync(ViSession vi, ViUInt16 srcSpace, ViBusAddress srcOffset, ViUInt16 srcWidth, ViUInt16 destSpace, ViBusAddress destOffset, ViUInt16 destWidth, ViBusSize length, ViPJobId jobId)
ViStatus viMoveAsyncEx(ViSession vi, ViUInt16 srcSpace, ViBusAddress64 srcOffset, ViUInt16 srcWidth, ViUInt16 destSpace, ViBusAddress64 destOffset, ViUInt16 destWidth, ViBusSize length, ViPJobId jobId)
Visual Basic Syntax
N/A
Resource Classes
FireWire INSTR, GPIB-VXI INSTR, GPIB-VXI MEMACC, PXI INSTR, VXI INSTR, VXI MEMACC
Parameters
| Name | Direction | Description |
|---|---|---|
|
vi |
IN |
Unique logical identifier to a session. |
|
srcSpace |
IN |
Specifies the address space of the source. |
|
srcOffset |
IN |
Offset of the starting address or register from which to read. For viMove(), this is a 32-bit value for 32-bit applications and a 64-bit value for 64-bit applications. For viMoveEx(), this is always a 64-bit value. |
|
srcWidth |
IN |
Specifies the data width of the source. |
|
destSpace |
IN |
Specifies the address space of the destination. |
|
destOffset |
IN |
Offset of the starting address or register to which to write. For viMove(), this is a 32-bit value for 32-bit applications and a 64-bit value for 64-bit applications. For viMoveEx(), this is always a 64-bit value. |
|
destWidth |
IN |
Specifies the data width of the destination. |
|
length |
IN |
Number of elements to transfer, where the data width of the elements to transfer is identical to the source data width. |
|
jobId |
OUT |
Job identifier of this asynchronous move operation. |
Return Values
| Completion Codes | Description |
|---|---|
|
VI_SUCCESS |
Asynchronous operation successfully queued. |
|
VI_SUCCESS_SYNC |
Operation performed synchronously. |
| Error Codes | Description |
|---|---|
|
VI_ERROR_INV_OBJECT |
The given session reference is invalid. |
|
VI_ERROR_NSUP_OPER |
The given vi does not support this 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_QUEUE_ERROR |
Unable to queue move operation (usually due to the I/O completion event not being enabled or insufficient space in the session's queue). |
|
VI_ERROR_IN_PROGRESS |
Unable to queue the asynchronous operation because there is already an operation in progress. |
Description
The viMoveAsync() and viMoveAsyncEx() operations asynchronously move 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 carry out or complete. When the transfer terminates, a VI_EVENT_IO_COMPLETION event is generated, which indicates the status of the transfer.
This 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. VISA will never return VI_NULL for a valid jobId.
The source and the destination can either be local memory or the offset of the interface with which this INSTR or MEMACC Resource is associated. This operation uses the specified data width and address space. In some systems, such as VXI, users can specify additional settings for the transfer, such as byte order and access privilege, by manipulating the appropriate attributes.
The following table lists the valid entries for specifying address space.
| Value | Description |
|---|---|
|
VI_A16_SPACE (1) |
Address the A16 address space of the VXI/MXI bus. |
|
VI_A24_SPACE (2) |
Address the A24 address space of the VXI/MXI bus. |
|
VI_A32_SPACE (3) |
Address the A32 address space of the VXI/MXI bus. |
|
VI_LOCAL_SPACE (0) |
Address process-local memory (using a virtual address). |
|
VI_OPAQUE_SPACE (FFFFh) |
Addresses potentially volatile data (using a virtual address). |
The following table lists the valid entries for specifying widths.
| Value | Description |
|---|---|
|
VI_WIDTH_8 (1) |
Performs 8-bit (D08) transfers. |
|
VI_WIDTH_16 (2) |
Performs 16-bit (D16) transfers. |
|
VI_WIDTH_32 (4) |
Performs 32-bit (D32) transfers. |
|
VI_WIDTH_64 (8) |
Performs 64-bit (D64) transfers. |
All VXI and PXI accesses performed by the viMoveAsync() and viMoveAsyncEx() operations use either the same or successive offsets, depending on the increment value specified by VI_ATTR_SRC_INCREMENT and VI_ATTR_DEST_INCREMENT.
If srcSpace is VI_LOCAL_SPACE, viMove() will ignore VI_ATTR_SRC_INCREMENT. If destSpace is VI_LOCAL_SPACE, viMove() will ignore VI_ATTR_DEST_INCREMENT. Local accesses always increment the offset for each index in a multi-element transfer, rather than using the increment specified by the attributes. If srcSpace is any value other than VI_LOCAL_SPACE, including VI_OPAQUE_SPACE, viMove() will honor VI_ATTR_SRC_INCREMENT. If destSpace is any value other than VI_LOCAL_SPACE, including VI_OPAQUE_SPACE, viMove() will honor VI_ATTR_DEST_INCREMENT. While VI_OPAQUE_SPACE uses a process-local virtual address, it is not necessarily pointing to system memory, so it may be a FIFO. Therefore, VI_ATTR_SRC/DEST_INCREMENT do indeed apply.
INSTR Specific
If srcSpace is neither VI_LOCAL_SPACE nor VI_OPAQUE_SPACE, srcOffset is a relative address of the device associated with the given INSTR resource. Similarly, if destspace is neither VI_LOCAL_SPACE nor VI_OPAQUE_SPACE, destOffset is a relative address of the device associated with the given INSTR resource.
The primary intended use of this operation with an INSTR session is to asynchronously move data to or from the device. Therefore, either the srcSpace or destSpace parameter will usually be VI_LOCAL_SPACE.
To specify the full 48-bit offset for these methods on a FireWire INSTR session, a call to viSetAttribute using VI_ATTR_FIREWIRE_SRC_UPPER_OFFSET or VI_ATTR_FIREWIRE_DEST_UPPER_OFFSET is needed prior to calling these methods. Subsequent calls to viSetAttribute are needed only if the upper 16 bits of the FireWire offset change.
MEMACC Specific
The destOffset and srcOffset parameters specify absolute addresses. Notice also that the length specified in the viMoveAsync() and viMoveAsyncEx() operations is the number of elements (of the size corresponding to the srcWidth parameter) to transfer, beginning at the specified offsets. Therefore, srcOffset + length*srcWidth cannot exceed the total amount of memory exported by the given srcSpace. Similarly, destOffset + length*srcWidth cannot exceed the total amount of memory exported by the given destSpace.
Related Topics
VI_ATTR_FIREWIRE_DEST_UPPER_OFFSET