Fixed-Size Array Length

Often you will need to write or read images, waveforms, or other large, structured data to and from instruments.  This data may be in framed binary blocks, ASCII, or other forms.  viScanf and viPrintf can handle the most common instrument formats, and the method overloads provided in the visa32.cs/vb header files provide some of the most common parameter lists.

viPrintf allows writing of array data as comma-separated lists, IEEE 488.2 binary blocks, or raw binary data.  There are two ways to tell viPrintf the size of the array data: you can hard-code the number into the format string; or you can use the ",*" format flag, meaning that the array size is passed as a 32-bit integer argument in front of the array argument.  A call with a hard-coded length might look like this:

Private Function WriteFixedWaveform(ByVal session As Integer, _
		            ByVal floatData() As Single) As Integer
    Debug.Assert(floatData.Length >= 100)
    WriteFixedWaveform = visa32.viPrintf(session, "%,100f" & vbLf, floatData)
End Function

The ",100" means it is an array of 100 elements to be written as a ASCII comma-separated list.  The "f" means it contains single-precision floating point numbers. (Note that if your array contains doubles, you must use the %lf format specifier.) It is easy to build the format string if you want to pass in an array of arbitrary size and are not concerned about the overhead of some simple string manipulation:

Private Function WriteVariableWaveform(ByVal session As Integer, _
		               ByVal floatData() As Single) As Integer
    WriteVariableWaveform = visa32.viPrintf(session, "%," & _
				floatData.Length & "f" _
				& vbLf, floatData)
End Function

See Advanced Use of viPrintf/viScanf for information about declaring more variables to do things like pass an array length argument.

viScanf allows reading of array data in the same formats that viPrintf allows for writing.  The .NET array is passed by value (meaning that a pointer to the first element is sent) to viScanf, which then fills in the array data in the space provided.  Because viScanf simply writes to the memory location given it, you must verify that the array argument contains enough space to receive all the data.  The maximum number of elements to be read can be indicated either through a hard-coded number in the format string or through an extra argument when the "#" format modifier is used.  The number of elements actually written is returned in the extra length argument.  

Two sets of viScanf/viSScanf function overloads for arrays are provided in the visa32.vb/cs files: one set with only one array argument, and another with an integer maximum length argument followed by the array argument.  Use the one-argument versions when the array size is hard-coded into the format string; use the two-argument version when the "#" format modifier is used.  Below are examples of reading arrays using fixed sizes and dynamic sizes respectively.

Fixed-Size Array Length

Private Function ReadKiloBLOB(ByVal session As Integer) As Byte()
    Dim result() As Byte = New Byte(999) {}
    Dim statusCode As Long
    statusCode = visa32.viScanf(session, "%1000y", result)
    If statusCode < visa32.VI_SUCCESS Then
        result = Nothing
    End If
    Return result
End Function

Parameterized-Size Array Length

Private Function ReadFloatList(ByVal session As Integer, _
			       ByVal maxSize As Integer) As Single()
    Dim result() As Single = New Single(maxSize) {}
    Dim statusCode As Long, elementCount As Long
    elementCount = maxSize
    statusCode = visa32.viScanf(session, "%,#f", elementCount, result)
    If statusCode < visa32.VI_SUCCESS Then
        result = Nothing
    ElseIf elementCount <> maxSize Then
        Dim newArr() As Single = New Single(elementCount) {}
        Array.Copy(result, newArr, elementCount)
        result = newArr
    End If
    Return result
End Function

Next: Putting it All Together