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

	You must set specific attributes to make the read terminate under specific conditions. See VISA Resource Classes for details.
	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

Completion Code	Description
Type ViStatus	This is the function return status. It returns either a completion code or an error code as follows.
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 Code	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 VI_ERROR_INV_OBJECT	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.

C# Example

public int ReadBytes(int session, int maxCount, out byte[] data)
{
	data = new Byte[maxCount];
	int viError, readCount;
	viError = visa32.viRead(session, data, maxCount, out readCount);
	if (viError < visa32.VI_SUCCESS)
	{
		System.Text.StringBuilder error = 
				new System.Text.StringBuilder(256);
		visa32.viStatusDesc(session, viError, error);
		throw new ApplicationException(error.ToString());
	}
	return readCount;
}

VB .NET Example

Public Function ReadBytes(ByVal session As Integer, ByVal maxCount As Integer, _
			  ByRef data() As Byte) As Integer
    data = New Byte(maxCount) {}
    Dim viError As Integer, readCount As Integer
    viError = visa32.viRead(session, data, maxCount, readCount)
    If viError < visa32.VI_SUCCESS Then
        Dim err As System.Text.StringBuilder = New System.Text.StringBuilder(256)
        visa32.viStatusDesc(session, viError, err)
        Throw New ApplicationException(err.ToString())
    End If
    Return readCount
End Function