Beagle Logo

Documentation

[Home] [Documentation] [Download] [Features] [History]

API Functions

BSQLConnect

Function: Connect to a Beagle Server.

Syntax: int BSQLConnect (char *host)

Remarks: When writing client applications for beagle, this is the first function that is needed to establish the connection to the server. This must be done before any other API calls are made.

Return Value: On error this function returns zero. On success this function returns the socket through which the client will communicate with the server.





BSQLDisconnect

Function: Disconnect from a Beagle Server

Syntax: void BSQLDisconnect (int socket)

Remarks: This function takes the socket descriptor for the connection as an argument. The function sends an exit message to the database backend process (the server) then returns.

Return Value: None





BSQLSetCurrentDB

Function: Sets the current database

Syntax: void BSQLSetCurrentDB (int socket, char *dbname)

Remarks: This function takes the socket descriptor for the connection and the database name as arguments. This function must be called before any queries are sent to the database server. BSQLConnect must be called before the use of this function.

Return Value: None

Also See: BSQLGetCurrentDB





BSQLGetCurrentDB

Function: Gets the name of the current database

Syntax: char *BSQLSetCurrentDB (int socket)

Remarks: This function takes the socket descriptor for the connection as an argument. BSQLConnect and BSQLSetCurrentDB must be called before the use of this function.

Return Value: The name of the current database set by the last call to BSQLSetCurrentDB

Also See: BSQLSetCurrentDB





BSQLQueryDB

Function: Sends a query to the database server

Syntax: struct bresult *BSQLQueryDB (int socket, char *query)

Remarks: This function takes the socket descriptor for the connection and a query string as arguments. BSQLConnect and BSQLSetCurrentDB must be called before the use of this function. Note that the client application is responsible for freeing the memory allocated by this function using BSQLFreeResult.

Return Value: Upon success, this function returns a pointer to a newly created result structure that contains information on the results of the query. On error, this function returns NULL.

Also See: BSQLFreeResult





BSQLntuples

Function: Get the number of tuples returned by a search

Syntax: long BSQLntuples (struct bresult *res)

Remarks: This function takes a result struct returned by a search as an argument. BSQLConnect, BSQLSetCurrentDB, and a search executed by BSQLQueryDB must be called before the use of this function.

Return Value: The number of tuples returned to the client following a search.

Also See: BSQLQueryDB, BSQLnfields





BSQLnfields

Function: Get the number of fields per tuple returned by a search

Syntax: long BSQLnfields (struct bresult *res)

Remarks: This function takes a result struct returned by a search as an argument. BSQLConnect, BSQLSetCurrentDB, and a search executed by BSQLQueryDB must be called before the use of this function.

Return Value: The number of fields per tuple returned to the client following a search.

Also See: BSQLQueryDB, BSQLntuples





BSQLresult

Function: Get the result string returned by a query.

Syntax: char *BSQLresult (struct bresult *res)

Remarks: This function takes a result struct returned by a query as an argument. BSQLConnect, BSQLSetCurrentDB, and BSQLQueryDB must be called before the use of this function.

Return Value: A string indication the result of the previous query. Usually 'OK' when a query is executed successfully and an error message when something goes wrong.

Also See: BSQLQueryDB





BSQLFieldName

Function: Get the field name for a column.

Syntax: char *BSQLFieldName (struct bresult *res, long col)

Remarks: This function takes a result struct returned by a query and a column number as arguments. BSQLConnect, BSQLSetCurrentDB, and BSQLQueryDB must be called before the use of this function.

Return Value: On success this function returns the name of the field for the specified column. On error, NULL is returned.

Also See: BSQLQueryDB





BSQLFieldType

Function: Get the field type for a column.

Syntax: int BSQLFieldType (struct bresult *res, long col)

Remarks: This function takes a result struct returned by a query and a column number as arguments. BSQLConnect, BSQLSetCurrentDB, and BSQLQueryDB must be called before the use of this function.

Return Value: On success this function returns a numeric identifier the field type for the specified column. On error, ERROR is returned.

Also See: BSQLQueryDB