viRead
Syntax
viRead(ViSession vi, ViPBuf buf, ViUInt32 count, ViPUInt32 retCount);
Description
This function synchronously transfers data from a device. The data that is read is stored in the buffer represented by buf. This function returns only when the transfer terminates. Only one synchronous read function can occur at any one time. A viRead operation can complete successfully if one or more of the following conditions were met. It is possible to have one, two, or all three of these conditions satisfied at the same time.
- END indicator received
- Termination character read
- Number of bytes read is equal to count
Note: You must set specific attributes to make the read terminate under specific conditions. See VISA Resource Classes for details.
Note: If you are using viRead in Visual Basic 6, see Notes on Using viRead/viWrite in Visual Basic 6 for information on modifying its declaration to allow efficient reading and writing of numeric arrays.
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 device. |
|
count |
IN |
ViUInt32 |
Number of bytes to be read. |
|
retCount |
OUT |
ViPUInt32 |
Represents the location of an integer that will be set to the number of bytes actually transferred. |
|
Special Value for retcount Parameter |
|||
|
Value |
Description |
VI_NULL |
Do not return the number of bytes transferred. |
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 |
The function completed successfully and the END indicator was received (for interfaces that have END indicators). |
|
VI_SUCCESS_TERM_CHAR |
The specified termination character was read. |
|
VI_SUCCESS_MAX_CNT |
The number of bytes read is equal to count. |
|
Error Codes |
Description |
|
VI_ERROR_ASRL_FRAMING |
A framing error occurred during transfer. |
|
VI_ERROR_ASRL_OVERRUN |
An overrun error occurred during transfer. A character was not read from the hardware before the next character arrived. |
|
VI_ERROR_ASRL_PARITY |
A parity error occurred during transfer. |
|
VI_ERROR_BERR |
Bus error occurred during transfer. |
|
VI_ERROR_CONN_LOST |
The I/O connection for the given session has been lost. |
|
VI_ERROR_INV_SESSION |
The given session or object reference is invalid (both are the same value). |
|
VI_ERROR_INV_SETUP |
Unable to start read function because setup is invalid (due to attributes being set to an inconsistent state). |
|
VI_ERROR_IO |
An unknown I/O error occurred during transfer. |
|
VI_ERROR_NCIC |
The interface associated with the given vi is not currently the controller in charge. |
|
VI_ERROR_NLISTENERS |
No Listeners condition is detected (both NRFD and NDAC are deasserted). |
|
VI_ERROR_NSUP_OPER |
The given vi does not support this function. |
|
VI_ERROR_OUTP_PROT_VIOL |
Device reported an output protocol error occurred during transfer. |
|
VI_ERROR_RAW_RD_PROT_VIOL |
Violation of raw read protocol occurred during transfer. |
|
VI_ERROR_RAW_WR_PROT_VIOL |
Violation of raw write protocol occurred during transfer. |
|
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_TMO |
Timeout expired before function completed. |
See Also
viWrite
Notes on Using viRead/viWrite in Visual Basic 6