ser_sr24_open


ser_sr24  ser_sr24_open(
     char *serial,   //name of serial port or device file to use
     int baud,   //constant denoting baud rate to connect at
     int *result   //pointer to integer which receives result code
     );

Summary

The ser_sr24_open function is used to open and initialize the serial I/O board.   It returns a handle that identifies the board to the other API functions. This function checks for errors and conflicts when it opens the board.

Note that this function actually communicates with the serial board, checking if it exists. If the board cannot be found, the function will timeout in 1 second.

Note: This function resets the I/O board configuration, meaning that all buffers will be enabled, all ports will be configured as digital input ports, and all events will be disabled.

Parameters

serial:
    Identifies which serial port to use. On Windows machines, this will be 'COM1', 'COM3', etc. On Unix machines, it will be the name of the serial port device file, such as '/dev/ttyS1'.
baud:
    Pass a constant which denotes the baud rate at which you want to connect. Note that you do not pass the actual baud rate (eg the number 9600); you must pass a pre-defined constant which represents the baud rate you desire. See the API reference page for a complete list of baud rate constants. Also note that you must pass the baud rate that matches the currently set baud rate on the actual serial board (set with jumpers) in order for the computer and serial board to successfully communicate. In other words, the serial board will not automatically adjust its baud rate to the value you specify here.
result:
    This is a pointer to the integer variable where the result code for this function will be stored. Since the return value of the function is a handle to the serial board, this variable is used to give you access to the actual error code if an error occurs. If the function succeeds, a value of zero will be written to result. Also note that if you are not interested in the actual error code, you may pass a NULL pointer here.

Return Values

If the board has been opened successfully, the function will return a new handle for the board. Because this handle is a pointer to the data structure for the board, it will never be NULL if the function succeeds. On failure, a NULL pointer is returned, indicating that an error has occured. The value of 'result' after the function returns provides more in-depth error codes. Some possible error codes include:

Sample

Here is a small sample of code that could be used to open a serial I/O board:
/* declare the variables */
ser_sr24 handle;
int result;

/* attempt to open the board */
handle = ser_sr24_open("COM1", SER_9600, &result);

/* see if the board was successfully opened */
if(handle == 0) /* if we got a NULL pointer */
{
	switch(result)
	{
		case SER_SERIAL_ERROR:
			printf("Oops! COM1 is busy or doesn't exist\n");
			break;
		case SER_DEVICE_NOTFOUND:
			printf("Is the serial board turned on?\n");
			break;
		default:
			printf("The following error occurred: %s\n", ser_sr24_error_string(result));
			break;
	}
}
else
{
	printf("Successfully opened the board.");
}

Visual Basic Notes

The Visual Basic equivalent of this function is the OpenBoard method. The board handle is maintained internally, so the method returns the result. Return values are listed above.

Prototype:
object.BoardOpen(
     ByVal serial As String,   'name of serial port or device file to use
     ByVal baud As BaudRate,   'constant denoting baud rate to connect at
     ) As Long

Example

Here is a typical example of how you would open a connection to the board. Note that you must first declare an object variable for the serial board. This is done in 'General Declarations' and is a form-level variable so that it will last the life of the application. The object variable declaration must include the 'WithEvents' keyword in order to properly support serial board hardware events. Then you must initialize the object variable and open a connection. This is usually done in the Form_Load( ) routine.
'General Declarations
    'Declare the serial board object variable
    Public WithEvents board As ser_sr24

Private Sub Form_Load()
    'Initialize serial board object variable
    Set board = New ser_sr24
    
    'Open connection to the board
    result = board.OpenBoard("COM1", SER_9600)
    If result <> 0 Then
        'Error opening board
        MsgBox board.ErrorString(result)
        End
    End If
End Sub


Back to Contents Winford Engineering (2000)