hil_open :: Quanser C Functions

navigation bar

hil_open

Opens an HIL board.

Description

The hil_open function opens a particular HIL board. The handle to the board returned by this function is used by the other functions in the HIL API to refer to the board. This handle must be closed using the hil_close function when the board is no longer in use.

Prototype

t_error
hil_open(const char * card_type, const char * card_identifier, t_card * card);

Parameters

const char * card_type

A string indicating the type of HIL board being configured. For example, for the Q8 board the board type is q8. Some other valid board types are q4 and qpid_e.

const char * card_identifier

A string identifying the particular board among all the boards of the same type. This parameter is only used when there is more than one board of the given type in the computer. Typically, this parameter is "0", indicating the first board of the given type. Subsequent boards are typically numbered sequentially. Hence, the second board in the system is board "1".

t_card * card

A handle to the board is returned in the t_card variable passed in this parameter. This argument cannot be NULL. Pass the address of a variable of type t_card.

Return value

The return value is 0 if the board is opened successfully. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h. A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_UNRECOGNIZED_BOARD_TYPE

The specified board type is not recognized. There is no HIL driver for this board type.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

QERR_DRIVER_MISSING_OPEN_OR_CLOSE

An HIL driver for the board type was found, but the driver is invalid. It is missing an hil_open or hil_close function.

QERR_CARD_ARGUMENT_IS_NULL

The card argument is NULL. A pointer to a t_card variable must be supplied because this variable must be passed to the other HIL functions to refer to the card.

QERR_BOARD_TYPE_ARGUMENT_IS_NULL

The card type argument is NULL. A card type must be specified.

QERR_BOARD_NOT_FOUND

An operating system specific kernel-level driver for the specified card could not be found. The card may not be installed. The kernel-level driver is the driver that gets installed when the operating system detects the hardware.

QERR_BOARD_IN_USE

The board is in use by another process and the board-specific driver does not support multi-process access to the card.

QERR_UNABLE_TO_OPEN_DRIVER

An operating system specific kernel-level driver for the card was found but could not be loaded. There may be a device conflict, hardware problem, or the driver may not be correctly installed.

QERR_UNABLE_TO_LOCK_CARDS

It was not possible to gain access to the database of open boards. A thread may continue to hold the lock or the system may be low on memory.

Requirements

Include Files	Libraries
hil.h	hil.lib;quanser_runtime.lib;quanser_common.lib

Examples

t_card board;
t_error result = hil_open("q8", "0", &board);
if (result == 0) {
    ...
    hil_close(board);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open board. %s (error %d)\n"), message, -result);
}