DESCRIPTION

The global symbol HDW_ERR was introduced in spec release 4.05.01 (1999). Prior to its introduction, certain hardware access errors (see the list below) would always cause spec to reset to command level. With its introduction, setting HDW_ERR to -1 before the call to the user-level hardware access functions prevents the reset. The user code can instead take appropriate action on the error and continue executing commands.

On return from the user-level function, HDW_ERR contains a code that characterizes the error. Codes for non-fatal errors that do not cause a reset to command level are also assigned to HDW_ERR.

Initially, HDW_ERR was associated with user-level functions for hardware access, such as ca_get(), ca_put(), gpib_get(), gpib_put(), gpib_poll(), gpib_cntl(), port_get(), port_getw(), port_put(), port_putw(), ser_get() and ser_put(). Later releases of spec implemented the setting of HDW_ERR for these additional user-level hardware access functions: sock_get(), sock_put(), sock_par(), fbus_get(), fbus_put(), vxi11_get(), vxi11_put().

When there is an error in these functions, they usually return -1, or sometimes zero. However, such values can also be valid return values. If one is doing error checking, one should check HDW_ERR after the function call.

As of spec release 6.03.03 (2015), use of HDW_ERR has expanded. For one, the symbol is now built into the code. Previously, the symbol was only used if the user had made it a global symbol. In addition, more hardware related functions will set HDW_ERR. Those functions are ca_fna(), counter_par(), motor_par(), mca_par(), gpib_par() and ser_par().

With spec release 6.06.01 (2017), the functions mca_get(), mca_put(), mca_sget(), mca_sput(), image_par(), image_get() and image_put() also set HDW_ERR when appropriate.

The following table lists the possible values for HDW_ERR and what each value indicates:

1 - Generic error

2 - GPIB no listener

3 - Timeout

4 - A non-fatal error

5 - Function called with bad argument

6 - Trying to access unconfigured hardware

7 - Function called with bad address

8 - Lost connection

9 - User abort (^C)

10 - Unresponsive hardware

11 - Disabled hardware

12 - Bad parameter

13 - Read only parameter

14 - Write only parameter

Additional error codes are included with spec release 6.08.08 (2019). In addition, bits 8 to 15 may now include a sub-error code. Currently, that is only implemented for Modbus errors.

15 - Error reading hardware

16 - Error writing to hardware

17 - Checksum error

18 - A Modbus error

See the fbus help file for details on the Modbus sub-error codes.

If the value of HDW_ERR is -1 before the call to the user-level hardware access function, no reset to command level will take place for any errors. Otherwise, traditionally fatal errors will still be fatal.

"FATAL" HARDWARE ERRORS

Certain errors in calls to some hardware-related functions can produce fatal errors in spec, where a "fatal" error means spec resets to the top level command prompt, similar to when a user types ^C. If HDW_ERR is assigned a value of -1 before a call to these functions, spec will not reset. Instead, the function will return with HDW_ERR set to a value from the above list.

These are the functions and circumstances that can generate "fatal" errors:

ca_io()

Called with an out-of-range CAMAC slot number.

ca_fna()

Called with the wrong number of arguments or out-of-range arguments.

fbus_get() and fbus_put()

Called with an out-of-range unit number or references an unconfigured or unusable unit.

gpib_cntl()

Called with an unrecognized command.

gpib_get(), gpib_put(), gpib_poll(), gpib_cntl()

For GPIB controllers "Nat Inst with cib.o", "Nat Inst with CIB.o", "Nat Inst GPIB-ENET (built-in)" and "TANGO GPIB server", if spec fails to reset an unresponsive card or if a transaction returns any error other than "not controller in charge" or "timeout".

gpib_get(), gpib_put(), gpib_poll(), gpib_cntl()

For the GPIB controller "HP/Agilent E2050/E5810 GPIB", if spec fails to reset an unresponsive device.

port_get(), port_put(), port_getw() and port_putw()

Called with an unconfigured address or trying to write to a read-only port or to read from a write-only port.