# Returning Measurements

How can you return reliable scalar measurements? The simple answer is to always check the status of a measurement before reading the measurement.

All measurements have a `:STATus?` child query that you can use for this task, as demonstrated in the script Example of :STATus? query included in this topic.

For example, to check the readiness of an Eye Height measurement (`:MEASure:EYE:EHEight`), first send the `:MEASure:EYE:EHEight:STATus?` query. The `:STATus?` query returns `CORR` (correct) if the measurement is ready to return, `INV` (invalid) if the measurement not ready to be returned, and `QUES` (questionable) if the measurement may not be valid.

Depending on the type of source waveform, Infiniium's settings, and what you want to achieve, it may be helpful to add an acquisition limit test to capture more data before returning a measurement result.

For example, measurements made on very long patterns may, under certain conditions, require several minutes to complete. An acquisition limit test followed by reading the measurement is demonstrated in Example of acquisition limit test in this topic.

## Example of :STATus? query

The following Python script is an example of using the `:STATus?` query to return a measurement as soon as the waveform has enough samples to be valid.

A valid eye diagram is assumed to be displayed on Infiniium.

The `return_scalar()` function returns an Eye Height measurement. If the measurement takes longer than this timeout value, the script throws an exception which is defined at the top of the function.

If your script is timing out, increase the IO timeout.

Scalar Measurement

    import time
    import pyvisa  # PyVISA package

    def return_scalar(Infiniium, query):
        class ScalarMeasQuestionableException(Exception):
            """ A scalar measurement result is questionable. """
            pass

        class ScalarMeasTimeOutException(Exception):
            """ A scalar measurement has timed out. """
            pass

        timeout = Infiniium.timeout / 1000  # convert ms to s
        query = query.strip('?')
        start_time = time.time()  # time in seconds
        while(True):
            time.sleep(0.2)
            status = Infiniium.query(f'{query}:STATus?')
            if 'CORR' in status:  # valid measurement result
                return Infiniium.query(f'{query}?')
            elif 'QUES' in status:
                reason = Infiniium.query(f'{query}:STATus:REASon?')
                s = f'{query}\nReason: {reason}'
                raise ScalarMeasQuestionableException(s)
            elif (int(time.time() - start_time)) > timeout:
                reason = Infiniium.query(f'{query}:STATus:REASon?')
                s = f'{query}\nReason: {reason}'
                raise ScalarMeasTimeOutException(s)

    rm = pyvisa.ResourceManager()
    Infiniium = rm.open_resource('TCPIP0::localhost::hislip0,4880::INSTR')
    Infiniium.timeout = 20000  # in milliseconds
    Infiniium.read_termination = '\n'
    Infiniium.write_termination = '\n'
    Infiniium.write(':MEASure:EYE:EHEight')  # show measurement on Infiniium
    print(f'Eye height: {return_scalar(Infiniium, ":MEASure:EYE:EHEight?")}')
    Infiniium.write(':SYSTem:GTLocal')
    Infiniium.close()

## Example of acquisition limit test

Use an acquisition limit test to ensure that a waveform has been built up from a specific number of waveforms, samples, or patterns before returning the measurement. This Python script is identical to the above script except for the addition of an `waveform_acquisition()` function. The function's `count` parameter is an integer that allows you to set the exact number of acquisitions.

After the acquisition limit test, the data acquisition is stopped and is not re-started. As a result, the measurement is not being updated and, if the measurement is not correct, the `return_scalar()` function will timeout.

You can, of course, place Infiniium in run mode after the acquisition test completes.

If your script is timing out, increase the IO timeout.

Scalar Measurement

    import time
    import pyvisa  # PyVISA package

    def waveform_acquisition(Infiniium, count):
        Infiniium.write(':ACQuire:STOP')  # single acquisition mode
        Infiniium.write(':ACQuire:CDISplay')  # Clear display
        Infiniium.write(f':LTESt:ACQuire:CTYPe:WAVeforms {str(count)}')
        Infiniium.write(':LTESt:ACQuire:STATe ON')
        Infiniium.query(':ACQuire:RUN;*OPC?')  # OPC required when limit testing
        Infiniium.write(':LTESt:ACQuire:STATe OFF')

    def return_scalar(Infiniium, query):
        class ScalarMeasQuestionableException(Exception):
            """ A scalar measurement result is questionable. """
            pass

        class ScalarMeasTimeOutException(Exception):
            """ A scalar measurement has timed out. """
            pass

        timeout = Infiniium.timeout / 1000  # convert ms to s
        query = query.strip('?')
        start_time = time.time()  # time in seconds
        while(True):
            time.sleep(0.2)
            status = Infiniium.query(f'{query}:STATus?')
            if 'CORR' in status:  # valid measurement result
                return Infiniium.query(f'{query}?')
            elif 'QUES' in status:
                reason = Infiniium.query(f'{query}:STATus:REASon?')
                s = f'{query}\nReason: {reason}'
                raise ScalarMeasQuestionableException(s)
            elif (int(time.time() - start_time)) > timeout:
                reason = Infiniium.query(f'{query}:STATus:REASon?')
                s = f'{query}\nReason: {reason}'
                raise ScalarMeasTimeOutException(s)

    rm = pyvisa.ResourceManager()
    Infiniium = rm.open_resource('TCPIP0::localhost::hislip0,4880::INSTR')
    Infiniium.timeout = 20000  # in milliseconds
    Infiniium.read_termination = '\n'
    Infiniium.write_termination = '\n'
    waveform_acquisition(Infiniium, 10)
    Infiniium.write(':MEASure:EYE:EHEight')  # show measurement on Infiniium
    print(f'Eye height: {return_scalar(Infiniium, ":MEASure:EYE:EHEight?")}')
    Infiniium.write(':SYSTem:GTLocal')
    Infiniium.close()