PrimeBase API Programmer's Guide


Table Of Contents

1. PrimeBase Interface (PBI)
Function overview
Session control functions

Program execution functions

Cursor functions

PBT variable access functions

Blob access functions

Data convertion functions

API logging functions


PrimeBase Interface API functions

Return codes and data types

Asynchronous execution mode

Callback functions

SDK Examples

Reporting problems

2. CL / PrimeBase Item Stream Interface (PBISI)

Function overview
Session-control functions

Program-execution functions

Results-processing functions

Return values
Integer values for return codes

Integer values for data type codes

Results processing

API functions and NULLs

API functions
CLBreak()
CLConInfo()
CLExec()
CLGetErr()
CLGetItem()
CLGetSn()
CLInit()
CLSend()
CLSendItem()
CLState()
CLUnGetItem()

3. PrimeBase Native (PBN) plug-in API

Defines

C data type codes

Type defs

Callback functions supplied by the PrimeBase software

PBNFunc()
PBNGetInfo()
PBNGetParamVal()
PBNGetReturnBuf()
PBNReturnNull()
PBNExecString()
PBNRaiseError()
PBNReadBlob()
PBNWriteBlob()
 
Functions supplied by the plug-in
PBNVersion()
PBNInit()
Optional functions.
PBNExit()
PBNOpenSession()
PBNCloseSession()

4. PrimeBase Open Server (PBOS) plug-in API

General PrimeBase Open Server functions

Statement level API functions

Connection level API functions

PrimeBase Open Server callback functions

Logging functions

Token translation functions

BLOB access functions

Standard memory functions

5. Java Database Connectivity (JDBC)
 
 

6. Open Database Connectivity (ODBC)

ODBC compliance

Data types

User Privileges

Connection String Attributes

7. Enterprise Objects Framework (EOF)


2. PrimeBase Interface (PBI)

 

 

The PrimeBase API is an advanced DBMS API which combines the best features found in other DBMS APIs with API calls unique to PrimeBase such as:

One of the advantages of the PrimeBase API over the Item Stream Interface is that the user doesn't have to know anything about PrimeBaseTalk (the native language of the PrimeBase Virtual Machine) to use it. Only knowledge of SQL is required. It also conforms more closely to the look and feel of the ODBC API and APIs used by other DBMSs.

PBI Function Overview

Session control functions

The session control functions are used to establish a connection with a PrimeBase server and return connection specific information.
 
Function Description
PBIInit() Initializes the PrimeBase API.
PBIDeinit() Deinitializes the PrimeBase API.
PBIConnect() Establishes a connection to a PrimeBase server.
PBIDSNConnect() Establishes a connection to a PrimeBase server.
PBIDisconnect() Disconnects a session opened by PBIConnect() or PBIDSNConnect().
PBIConnectionInfo() Returns connection information.
PBIGetError() Returns error information from the last PrimeBase API call.

 

Program execution functions

The program execution functions are used to send a PBT program to the PrimeBase Virtual Machine for execution and terminating it if required. In addition the PBIPoll() function can be used to poll for the completion of asynchronous PBI calls and PBIGetOutput() can be used to get the output created by PBT commands such as print and printall.
 
Function Description
PBIExecute() Sends a PBT program to the PrimeBase Virtual Machine for execution.
PBIPoll() Polls the API for completion of asynchronous API function calls.
PBICancel() Cancels all asynchronous tasks for the session.
PBIGetOutput() Assigns a buffer to use for collecting the output from PBT print commands. An optional callback routine can be supplied to notify the caller when something has been written into the output buffer.

 

Cursor functions

The cursor functions return information about a PBT cursor and retrieve data from the cursor into application specified buffers.
 
Function Description
PBIGetCursorID() Returns the cursor id for a cursor of a given name.
PBICursorInfo() Gets cursor information.
PBIColumnInfo() Gets information about the individual columns in a cursor.
PBIBindColumn() Binds storage location for a specified cursor.
PBISetCursorState() Sets the state of the cursor: unbind, reset, free.
PBIFetchRow() Fetches rows of data into locations bound by PBIBindColumn().
PBIGetColumnData() Gets data for a specific column from the current row in a cursor.
PBIGetCursorPosition() Gets the current position of the cursor.
PBISetCursorPosition() Sets the current position of the cursor.

 

PBT variable access functions

The PBT variable access functions allow applications to directly set and get values from a PBT program.
 
Function Description
PBIGetValue() Gets the value of a variable from a PBT program.
PBIPutValue() Assigns a value to a variable of a PBT program.

 

Blob access functions

The blob access functions allow applications to access blob data and create new blobs. PrimeBase blobs are reffered to by blob IDs. When a blob is selected out of a table the blob id is returned in the cursor and the application uses the blob access functions to read the data out of the blob. In the same way blobs can be inserted into a table by creating a new blob id then writing the data to the blob id. The blob id is then inserted into the table. The data must be written to the blob id before the insert or update occures.
 
Function Description
PBINewBlob() Creates a blob id into which data can later be written.
PBIFreeBlob() Frees a blob id which was allocated with PBINewBlob().
PBIGetBlobData() Reads data from a blob id.
PBIPutBlobData() Writes data to a blob id.

 

Data convertion functions

The PrimeBase API allows the application to supply it's own data conversion functions. The user defined data conversion functions will then be used automatically by the PrimeBase API when ever the specific data conversion is to take place. A typical use of user defined data conversion functions is to allow an application to specify a user defined data type in PBIBindColumn() or PBIGetColumnData() and then have the conversion function called automaticly when the data is fetched into the user's data buffer.
 
Function Description
PBIConvert() Converts data from one PBT data type to another.
PBISetConvert() Specifies a user defined data conversion function.
PBIGetConvert() Gets the user defined conversion function.

 

API logging functions

The API logging functions can be used by an application to trace what calls are being made and what is being sent to the PrimeBase API. This may be usefull when debugging an aplication.
 
Function Description
PBISetLogName() Sets the applications log file name and location.
PBILogStr() Write a messages to the log file.
PBITrace() Activate API tracing for a connection.

 

PrimeBase Interface API functions

 
 
Function Description
PBIInit() Initializes the PrimeBase API.
PBIDeinit() Deinitializes the PrimeBase API.
PBIConnect() Establishes a connection to a PrimeBase server.
PBIDSNConnect() Establishes a connection to a PrimeBase server.
PBIDisconnect() Disconnects a session opened by PBIConnect() or PBIDSNConnect().
PBIConnectionInfo() Returns connection information.
PBIGetError() Returns error information from the last PrimeBase API call.
PBIExecute() Sends a PBT program to the PrimeBase Virtual Machine for execution.
PBIPoll() Polls the API for completion of asynchronous API function calls.
PBICancel() Cancels all asynchronous tasks for the session.
PBIGetOutput() Assigns a buffer to use for collecting the output from PBT print commands. An optional callback routine can be supplied to notify the caller when something has been written into the output buffer.
PBIGetCursorID() Returns the cursor id for a cursor of a given name.
PBICursorInfo() Gets cursor information.
PBIColumnInfo() Gets information about the individual columns in a cursor.
PBIBindColumn() Binds storage location for a specified cursor.
PBISetCursorState() Sets the state of the cursor: unbind, reset, free.
PBIFetchRow() Fetches rows of data into locations bound by PBIBindColumn().
PBIGetColumnData() Gets data for a specific column from the current row in a cursor.
PBIGetCursorPosition() Gets the current position of the cursor.
PBISetCursorPosition() Sets the current position of the cursor.
PBIGetValue() Gets the value of a variable from a PBT program.
PBIPutValue() Assigns a value to a variable of a PBT program.
PBINewBlob() Creates a blob id into which data can later be written.
PBIFreeBlob() Frees a blob id which was allocated with PBINewBlob().
PBIGetBlobData() Reads data from a blob id.
PBIPutBlobData() Writes data to a blob id.
PBIConvert() Converts data from one PBT data type to another.
PBISetConvert() Specifies a user defined data conversion function.
PBIGetConvert() Gets the user defined conversion function.
PBISetLogName() Sets the applications log file name and location.
PBILogStr() Write a messages to the log file.
PBITrace() Activate API tracing for a connection.

 

short PBIInit(int global_api_tracing)

This function initializes the PrimeBase API. It should be called once before any other PrimeBase API call is made.
 
 
 
Parameter Description
global_api_tracing A boolean flag to activate API tracing on all connections. By activating tracing in PBInit() you will also be able to trace the calls to PBIConnect(). Unless PBISetLogName() is called to set the log file to be used, all logging will be written to a file called "pbvm.log" (PrimeBase Virtual Machine Log) in the applications current working directory.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

void PBIDeinit(void)

This function deinitializes the PrimeBase API. It should be called once after all other PrimeBase API call have been made. Once called the user should call PBIInit() before making any further calls to the PrimeBase API.
 
 

void PBIGetError(long session_id, long *perr, long *serr, char *msg, long size)

This function returns error information from the last PrimeBase API call for 'session_id'. Once called the error message is cleared. Error messages are not stacked, only the error, if any, from the last call using 'session_id' is available. As a result, you should always call PBIGetError() right after any PrimeBase API call that returns the value PB_ERROR.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect() or zero if the error occurred in a PrimeBase API call that was not associated with a session such as PBIInit().
perr A pointer to a long value in which will contain the primary error is returned. The parameter may be NULL if the caller is not interested in the primary error number.
serr A pointer to a long value in which will contain the secondary error number will be returned. The parameter may be NULL if the caller is not interested in the secondary error number.
msg A reference to a buffer into which the zero terminated error message is written. If the error mesage with zero terminator is greater then the buffer size then the message is truncated and zero terminated. This parameter may be NULL if the caller is not interested in the error message.
size The size in bytes of the buffer referenced by 'msg'.

 

short PBIConnect(long *session_id, char *pbserver, short server_type, short protocol, char *connection_options, char *user, char *passwd, char *database)

This function establishes a connection to a PrimeBase server and returns a unique session id by which to refer to it. If a database is specified it will be opened for the caller. The session id created by this function can be used in any PrimeBase API call requiring a sesion id.
 
 
 
Parameter Description
session_id A pointer to a long in which the session id is be returned. The session id is used
in all other PrimeBase API calls requiring a session id to refer to this session.
pbserver The name of the server to connect to. For example "PrimeServer". If 'pbserver' is NULL then a session will be opened but it will not be connected to a server.
server_type The type of server to connect to. There are currently two types of PrimeBase servers. 
  • PB_DATA_SERVER

  • This is the PrimeBase data server which is a relational database engine.
     
  • PB_OPEN_SERVER

  • This is the PrimeBase open server which is a server that can be used to connect to a database engine or be programmed to perform specific tasks such as acting as a file server etc.. Exactly what the Open server does and what subset of PrimeBaseTalk commands and SQL it implements depends on the open server plugin that it has loaded. Please see the documentation for the PrimeBase Open Server for more details. 
protocol The communication protocol to use to connect to the server. 
  • PB_TCP

  • Uses the TCP protocol. This is the recommended protocol. It can be used to communicate with both remote and local servers and is available on all platforms.
     
  • PB_SHARED_MEM

  • Use shared memory communications. This can be used for local communications only. On some platforms shared memory communications can be slightly faster than TCP.
     
  • PB_ADSP

  • Use the Apple data stream protocol (ADSP). This is only supported on Apple Macintosh machines.
     
  • PB_PROGRAM_LINKING

  • Use Apple Program Linking. This is only supported on Apple Macintosh machines.
     
  • PB_RUNTIME

  • The application has been linked to a PrimeBase runtime library and the values of 'pbserver' and 'server_type' can be ignored. 
connection_options Any protocol specific options required to connect to the PrimeBase server. 
  • PB_TCP

  • The IP address of the host machine on which the PrimeBase server is running. If 'connection_options' is blank or NULL then the PrimeBase server is assumed to be running on the same host as the client application.
     
  • PB_SHARED_MEM

  • Requires no connection options. 'connection_options' is ignored.
     
  • PB_ADSP

  • The apple zone in which the PrimeBase server is running. if 'connection_options' is blank or NULL then the PrimeBase server is assumed to be running in the same zone as the client application.
     
  • PB_PROGRAM_LINKING

  • The apple zone in which the PrimeBase server is running. if 'connection_options' is blank or NULL then the PrimeBase server is assumed to be running in the same zone as the client application.
     
  • PB_RUNTIME

  • The location of the database root for the databases to be used. You can think of the database root as the directory of folder in which the PrimeBase server would be running if you where to access the database via a normal server. For example, on unix, if you had installed a PrimeBase server in '/home/PrimeBase/server1' then this would be your database root and you would expect to find the directories 'db' and 'setup' in this location.

    If the application is running in the database root, i.e. the 'db' and 'setup' directories are in its current working directory, then a NULL pointer can be passed in as connection_options. 

user The user to log into the server as.
passwd The users password. If the user has no password then pass in a NULL pointer for 'passwd'.
database The name of the database to open. If a NULL pointer is passed in as 'database' then the connection will be made without opening a database. In this case the user name and password given will not be verified until the application tries to open a database.

 
 
Return Value Description
PB_OK The connection has been established successfully
PB_ERROR An error occurred. Call PBIGetError() for details.

 

Notes

The communication speed can be tested by using the different communication protocols and executing the following test:

int t, cnt;
cnt = 0;
t = $now() + 10;
while ( t > $now()) {
    cnt++;
    describe databases;
}

print cnt, " DESCRIBE DATABASES done in 10 seconds.";
 

short PBIDSNConnect(long *session_id, char *dsn, char *user, char *passwd)

This function establishes a connection to a PrimeBase server and returns a unique session id by which to refer to it. Unlike PBIConnect() this function maps the 'dsn' name passed in to a connection alias in the PrimeBase "connect. def" file and then uses that connection definition to make the database connection. The session id created by this function can be used in any PrimeBase API call requiring a sesion id.
 
 
 
Parameter Description
session_id A pointer to a long in which the session id is be returned. The session id is used
in all other PrimeBase API calls requiring a session id to refer to this session.
dsn The PrimeBase connection definition data source name (alias) to be used to establish the connection. If 'dsn' is NULL then a session will be opened but it will not be connected to a server.
user The user to log into the server as.
passwd The users password. If the user has no password then pass in a NULL pointer for 'passwd'.

 
 
Return Value Description
PB_OK The connection has been established successfully
PB_ERROR An error occurred. Call PBIGetError() for details.
 

void PBIDisconnect(long session_id)

This function disconnects a session opened by PBIConnect() and frees any resources associated with it.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().

 

short PBIConnectionInfo(long session_id, PBConnInfoPtr info)

This function returns the following information in the structure pointed to by 'info':

client_version: A 4 byte value representing the version of the PrimeBase virtual machine.

server_version: A 4 byte value representing the version of the PrimeBase server that the connection is connected to.

server_name: The name of the server that the connection is connected to.

server_brand: The brand name of the server that the connection is connected to. If the connection is to a PrimeBase Data Server then the brand name will always be "PrimeBase". If the connection is to a PrimeBase Open Server then the brand name will be the brand name supplied by the PrimeBase Open Server plugin that the Open Server has loaded.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
info A pointer to a connection info structure in which the connection information is returned which contains the following fields: 
  • client_version

  • A 4 byte value representing the version of the PrimeBase virtual machine.
     
  • server_version

  • A 4 byte value representing the version of the PrimeBase server that the connection is connected to.
     
  • server_name

  • The name of the server that the connection is connected to.
     
  • server_brand

  • The brand name of the server that the connection is connected to. If the connection is to a PrimeBase Data Server then the brand name will always be "PrimeBase". If the connection is to a PrimeBase Open Server then the brand name will be the brand name supplied by the PrimeBase Open Server plugin that the Open Server has loaded. 

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 


short PBIExecute(long session_id, char *text, long len, short execute, long *rows_effected, PBCallBackFuncType callback, void *user_data)

This function builds a PrimeBaseTalk program consisting of one or more statements and then executes it if the 'execute' parameter is set to PB_EXECUTE_NOW. Depending on if a callback is supplied, this will either be done synchronously or asynchronously. When done asynchronously the caller must call PBIPoll() until the callback is called to indicate completion.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
text A program segment.
len The length of text. If 'len' = PB_NTS then text is assumed to be a null terminated string.
execute A flag which can contain one of the following values: 
  • PB_EXECUTE_NOW

  • The program segment passed in is concatenated to any previous unexecuted segments and the resulting program is executed.
     
  • PB_EXECUTE_LATER

  • The program segment passed in is concatenated to any previous unexecuted segments and the function is to return with out executing the result. The values of the parameters 'rows_effected', 'callback', and 'user_data' is ignored in this case. 
rows_effected A reference to a long value in which the rows effected by the program just executed will be returned if applicable. This parameter can be set to NULL if the user is not interested in this information. 

If 'rows_effected' is not null and the caller has supplied a callback routine then the location referenced by 'rows_effected' will be set when the callback is called and so it is up to the caller to make sure that 'rows_effected' remains valid until after the callback is called.

callback For synchronous execution the 'callback' parameter should be NULL. If not NULL then execution will be done asynchronous and 'callback' is a pointer to a callback function which will be called on completion. Please refer to the descriptions of Asynchronous execution for more details.
user_data A pointer to user data to be passed into the callback routine apon completion. If no callback routine is supplied then this parameter is ignored.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_EXEC Execution has started and the caller will be notified of completion via the callback routine.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

short PBIPoll(long session_id, long timeout)

This function is used to poll for asynchronous task completion.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
timeout This is the maximum time to wait for asynchronous tasks to complete for the session. The time given is in hundredths of seconds. If 'time-out' is zero then asynchronous tasks are checked once and the function returns immediately. If 'time-out' is PB_FOREVER then the function will not return until all asynchronous tasks have completed.

For the best performance a time-out of more than 0.1 seconds is recommended when the application has no other work to be done. This will cause the application to sleep and be woken when the time expires or a reply is received from the server.


 
 
Return Value
This function returns the number of asynchronous tasks completed.

 

void PBICancel(long session_id)

This function cancels all asynchronous tasks for the session.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().

 

short PBIGetOutput(long session_id, char *buffer, long size, PBOutPutCallBackFuncType callback, void *user_data)

This function assigns a buffer to use for collecting the output from PBT print commands. An optional callback routine can be supplied to notify the caller when something has been written into the output buffer. Although supplying a callback function is optional it is recommended to prevent the output buffer from overflowing which could happen when displaying the results of a large result set with printall.

All data is converted to a C string and concatenated onto the current contents of the buffer. In the event of an overflow an overflow message will be placed at the end of the buffer and output data will be discarded until the buffer is cleared.

The buffer is cleared by the caller by resetting it's contents to a zero length string, (*buffer = 0;).

Data can be written into the output buffer and the callback called at any time while a PBT program is executing.

Data from the output stream will continue to be written into the output buffer and the callback, if supplied, will continue to be called until PBIGetOutput() is called again with the same session id and a null buffer pointer.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
buffer A pointer to a buffer into which the output data is to be written. If a null pointer is passed in then any previous call to PBIGetOutput() with the same session id will be cancelled and data in the output stream will be discarded.
size The size of buffer.
callback The callback function that will be called when ever data is read from the executing process's output stream.
user_data A pointer to user data to be passed into the callback routine when called. If no callback routine is supplied then this parameter is ignored.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

Example:

static void io_cb(void *user_data, char *buffer, long size)
{
	printf(buffer);
	*buffer = 0; // Reset the buffer.
}


static void PBIGetOutput_test(void) 
{
char output_buffer[1024];

	if (PBIGetOutput(session_id, output_buffer, 1024, io_cb, NULL) != PB_OK)
		goto error;
		
	if (PBIExecute(session_id,"describe databases;printall;", PB_NTS, PB_EXECUTE_NOW, NULL, NULL, NULL) != PB_OK)
		goto error;
		
	return;
error:
	display_error(session_id);
}

 

short PBIGetCursorID(long session_id,char *cursor_name, unsigned long *cursor_id)

This function returns the cursor id for a cursor. The cursor id can then be used in other PrimeBase API calls that require a cursor id. After the application is finished with the cursor id it is important to call PBISetCursorState() for the cursor id with the flag PB_CURSOR_FREE to release all resources associated with the cursor id.

It is not a good idea to call PBIGetCursorID() multiple times for the same cursor as this will create multiple unique cursor ids which are not necessarily interchangeable. For example you cannot bind using one and then fetch using the other.
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_name The name of the cursor for which the ID is to be returned. If cursor_name is NULL then the cursor id of the default cursor is returned.
cursor_id A pointer to an unsigned long into which the cursor id is returned.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

Example:

PBIExecute(session_id, "select * from mytab into my_cursor;", PB_NTS, PB_EXECUTE_NOW, NULL, NULL, NULL);
PBIGetCursorID(session_id, "my_cursor", &cursor_id);

PBIFetchRow(session_id, cursor_id, &rows, PB_FETCH_FIRST, NULL, NULL, NULL);
PBIGetColumnData(session_id, cursor_id, 1, NULL, buffer, NULL, NULL);

PBISetCursorState(session_id, cursor_id, PB_CURSOR_FREE);

short PBICursorInfo(long session_id, unsigned long cursor_id, PBCursorInfoPtr info)

The application can use this function to get cursor information structure which has the following fields:
 
 
 
Field Description
name The name of the cursor. (In case you forgot it?)
rows The number of rows in the cursor. This will only be valid if the select was
done for extract.
columns The number of columns in the cursor.
mode The mode of the cursor which will be one of the following: 
  • PB_CURSOR_UNKNOWN

  • A non-scrolling, non-updateable cursor.
     
  • PB_CURSOR_SCROLLABLE

  • The application can position the cursor using PBISetCursorPosition() but cannot update the cursor via an "UPDATE CURRENT OF" statement.
     
  • PB_CURSOR_UPDATEABLE

  • The application can not position the cursor but the cursor name can be used in an "UPDATE CURRENT OF" statement. 

 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
info A pointer to a CursorInfo structure to be filled out.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

short PBIColumnInfo(long session_id, unsigned long cursor_id, long col, PBDataFmtPtr type, PBColumnInfoPtr info)

After executing a SELECT statement and getting the cursor id via the PBIGetCursorID() function, the application can use the PBIColumnInfo() function to get information about the individual columns in the cursor. The data format structure pointed to by 'type' contains the following fields:
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
col The column number for which the information is requested. Column numbers start at 1 (i.e. 0 (zero) is not a valid column number).
type A pointer to a data format structure to be filled in. If NULL no data type information is returned.
info A pointer to a column information structure to be filled in. If NULL no column information is returned.

 
 
Return Value Description
PB_OK Function executed successfully.
PB_ERROR An error occured. Call PBIGetError() for details.

 
 
Data Structure: PBDataFmt Description
type The data type of the column, PB_CHAR for example.
len The length of the data. A varchar(11) column will have a len of 11.
scale The scale of the data type if it is PB_DECIMAL or PB_MONEY.
precision The size of the buffer required to ensure that the data is not truncated when fetched without conversion.
user_info This field is not affected.

 

The column information structure pointed to by 'info' contains the following fields:
 
 
 
PBColumnInfo Description
name The columns name.
width The maximum size of the data if fetched as a C string.

 

All other fields of this structure are left untouched.
 
 


short PBISetCursorState(long session_id, unsigned long cursor_id, long flag)

This function sets the state of the cursor associated with the cursor id.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
flag One of the following values: 
  • PB_CURSOR_FREE

  • Free the cursor and all resources associated with it. After this any further use of 'cursor_id' will result in an error.
     
  • PB_CURSOR_UNBIND

  • Unbind all bound columns for the cursor. See PBIBindColumn()[link].
     
  • PB_CURSOR_REBIND

  • Reset the 'storage' and 'info' bind locations to the start position. 


When the 'i_inc' or 'i_size' parameters of PBIBindColumn() are non zero then the location into which the data and/or info is written is incremented after each call to PBIFetchRow(). Calling PBISetCursorState() with flag PB_CURSOR_REBIND will reset the these locations to their original settings.

This is equivalent to recalling PBIBindColumn() for each bound column with the same parameters again.


 

short PBIBindColumn(long session_id, unsigned long cursor_id, long col, PBDataFmtPtr type, void *storage, long s_inc, void *info, long i_size, long i_inc)

 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
col The column number for which the information is requested. Column numbers start at 1 (i.e. 0 (zero) is not a valid column number).
type A pointer to a structure containing the information about the format that the data is to be returned as. The 'len' field in the DataFmt structure is the length of the storage supplied for each value. If the data type of the column is not convertible to the data type supplied PBIBindColumn will fail. If type is NULL then the data will be returned unconverted and the caller must ensure that the storage space supplied for each data item is at least as big as the maximum data length for the column.

Note that the bind buffer for a data type may require a buffer larger than the 'len' field in the DataFmt structure as returned by PBIColumnInfo(). For example PB_VCHAR and PB_VBIN require a buffer 'len' + 2 to ensure no data truncation.

storage If the value of 's_inc' is -1 then 'storage' is a pointer to an array of pointers that point to the location in which that the data is to be stored when it is fetched. 

If the value of 's_inc' is not -1 then 'storage' is a pointer to a location in memory large enough to hold one or more items.

If 'storage' is NULL then the column will be unbound and the values of 'type', 'size' and 'info' will be ignored.

s_inc This parameter tells the PrimeBase API how to increment the 'storage' pointer after fetching a row. If 's_inc' is -1 then the pointer is assumed to be a pointer to arrays of pointers to storage locations. If 's_inc' is greater than or equal to zero then the pointer 'storage' is incremented 's_inc' bytes after each fetch.
info If the value of 'i_inc' is -1 then 'info' is a pointer to an array of pointers that point to the location in which the info data is to be stored when after a fetch. 

If the value of 'i_inc' is not -1 then 'info' is a pointer to a location in memory large enough to hold one or more items of size 'i_size' bytes long.

If the type being returned is not of fixed size then the actual length of the data item to be fetched is returned in this location. If the actual length of the data was greater than 'type->len' then the data will be truncated and only 'type->len' bytes will be returned. The user can compare the length in 'info' with 'type->len' to determine if data was truncated.

If A null item is returned then storage location will be left untouched and info will be set to PB_NULL_DATA.

If 'info' is NULL then the user is not notified of null data items or the length of variable length data items.

i_size The size of the storage space available for column item info. Valid sizes are 0, 1, 2, and 4 bytes.
i_inc This parameter tells the PrimeBase API how to increment the 'info' pointer after fetching a row. If 'i_inc' is -1 then the pointer is assumed to be a pointer to arrays of pointers to storage locations. If 'i_inc' is greater than or equal to zero then the pointer 'info' is incremented 'i_inc' bytes after each fetch.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

This function binds storage location for a specified cursor into which data will be placed when PBIFetchRow() is called. Space can be bound for one or more rows with one call. The bindings remain in effect until PBIBindColumn() is called again with the same session id, cursor id, and column number. A column can be unbound by calling PBIBindColumn() with storage set to NULL. It is the responsibility of the user to ensure that when PBIFetchRow() is called that the bound columns contain storage space for all rows fetched. The arrays pointed to by 'storage' and 'info' must remain valid until the column is unbound or the user no longer wishes to fetch any more data. The user can change the contents of the array at any time with out having to call PBIBindColumn() again.

Example:

/*
* This example binds space for column 3. Up to 7 rows can be fetched.
*
* By setting the 'type' parameter to NULL we are telling the driver
* that we what the data to be returned unconverted and that we
* have supplied storage for the maximum possible value size returned.
* In our example we are assuming that no value fetched is larger than 32
* bytes. If we are wrong our program will crash while being demonstrated
* to our boss and we will be fired.
*/


char space[7][32], *storage[7];
Int4 flags[7], i, rows ;PBIBindColumn(session_id, my_cursor_id, 3, NULL, storage, -1, flags, 4, 4);


/*
* The above is equivalent to the following:
* DataFmt fmt;
*
* PBIColumnInfo(long session_id, my_cursor_id, 3, &fmt, NULL);
* PBIBindColumn(session_id, my_cursor_id, 3, &fmt, storage, -1, flags, 4, 4);
*/

for (i=0; i<3; i++)
{
    storage[i] = space[i];
}

rows = 3;
PBIFetchRow(session_id, cursor_id, &rows, FETCH_NEXT, NULL, NULL, NULL);

/*
* If we were to call
* PBISetCursorState(session_id, cursor_id, PB_CURSOR_REBIND);
* here, the next fetch would overwrite the data fetched by the previous fetch.
*/

/* Fetch the next 3 rows into the next storage locations. */
rows = 3;
PBIFetchRow(session_id, cursor_id, &rows, FETCH_NEXT, NULL, NULL, NULL);

short PBIFetchRow(long session_id, unsigned long cursor_id, long *rows, long position, short *data_truncated, PBCallBackFuncType callback, void *user_data)

 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
rows The address of a variable containing the number of rows to be fetched. Apon successful completion this variable will be set to the number of rows actually fetched.
position The position of the cursor in the result set from which the fetch is to be done. 'position' can be any value greater than zero or one of the following flags: 
  • PB_FETCH_FIRST

  • Positions the cursor at the first row in the result set before performing the fetch. This is the same as setting position to one.
     
  • PB_FETCH_LAST

  • Positions the cursor at the last row in the result set before performing the fetch.
     
  • PB_FETCH_PREVIOUS

  • Fetches the previous row set starting at the current cursor position. If no previous fetch has been done PBIFetchRow() return successfully and set the variable pointed to by 'rows' to zero. If the cursor is at the end of the result set this will fetch the last rows in the result set.  
     
  • PB_FETCH_NEXT

  • Fetches the next row set starting at the current cursor position. If no previous fetch has been done this will fetch the first rows in the result set. If the cursor is at the end of the result set PBIFetchRow() return successfully and set the variable pointed to by 'rows' to zero. 
If 'position' is greater than the number of rows in the row set PBIFetchRow() return A_OK and set the variable pointed to by 'rows' to zero.

For an updateable cursor, any value of 'position' other than PB_FETCH_NEXT will result in an error.

data_truncated The address of a variable which is set to 1 if fetched data has been truncated otherwise it is set to 0. If NULL is passed in for this parameter then the caller will not be notified when data is truncated.
callback For synchronous execution the 'callback' parameter should be NULL. If not NULL then execution will be done asynchronous and 'callback' is a pointer to a callback function which will be called on completion. Please refer to the descriptions of Asynchronous execution for more details.
user_data A pointer to user data to be passed into the callback routine apon completion. If no callback routine is supplied then this parameter is ignored.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_NODATA Execution completed successfully. The end of the result set was reached, no data returned.
PB_EXEC Execution has started and the caller will be notified of completion via the callback routine.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

This function fetches zero or more rows of data into locations specified by the PBIBindColumn() function. Only columns that have been bound will be fetched. It is the responsibility of the user to ensure that for any bound column there are sufficient storage locations supplied for the number of rows fetched.

If PBIFetchRow() is executed asynchronously then the user must ensure that the 'rows' pointer and the 'data_truncated' pointer, if not NULL, remain valid until the callback has been called.

Example:

/*
* This example fetches up to 7 rows of data starting with the third row of data    in
* the result set.
*/


Int4 rows;

rows = 7;

PBIFetchRow(session_id, cursor_id, &rows, 2, NULL, NULL, NULL);



short PBIGetColumnData(long session_id, unsigned long cursor_id, long col, PBDataFmtPtr type, void *storage, long *info, short *data_truncated)

This function is used to get data from the current row in the cursor indicated by the cursor_id parameter. This function has no effect on any binds that have been made to the columns in the cursor via calls to PBIBindColumn(). It is possible to bind a column with PBIBindColumn() and then call PBIGetColumnData() on the column to get the data into a different buffer than what was specified in PBIBindColumn(), possibly doing a type conversion on it at the same time.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
col The column number for which the information is requested. Column numbers start at 1 (i.e. 0 (zero) is not a valid column number).
type A pointer to a structure containing the information about the format that the data is to be returned as. The 'len' field in the DataFmt structure is the length of the storage supplied for each value. If the data type of the column is not convertible to the data type supplied PBIGetColumnData will fail. If type is NULL then the data will be returned unconverted and the caller must ensure that the storage space supplied for each data item is at least as big as the maximum data length for the column.

Note that the bind buffer for a data type may require a buffer larger than the 'len' field in the DataFmt structure as returned by PBIColumnInfo(). For example PB_VCHAR and PB_VBIN require a buffer 'len' + 2 to ensure no data truncation.

storage A pointer to a location in memory large enough to hold the item.
info If the type being returned is not of fixed size then the actual length of the data item to be fetched is returned in this location. If the actual length of the data was greater than 'type->len' then the data will be truncated and only 'type->len' bytes will be returned. The user can compare the length in 'info' with 'type->len' to determine if data was truncated. 

If A null item is returned then storage location will be left untouched and info will be set to PB_NULL_DATA.

If 'info' is NULL then the user is not notified of null data items or the length of variable length data items.

data_truncated The address of a variable which is set to 1 if fetched data has been truncated otherwise it is set to 0. If NULL is passed in for this parameter then the caller will not be notified when data is truncated.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

short PBIGetCursorPosition(long session_id, unsigned long cursor_id, long *pos)

This function gets the current position of the cursor. The first row is at position 1.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
pos A pointer to a variable into which the current cursor position is placed.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

short PBISetCursorPosition(long session_id, unsigned long cursor_id, long *pos, PBCallBackFuncType callback, void *user_data)

This function sets the current position of the cursor. The first row is at position 0. The cursor must be scrollable to use this function. Scrollable cursors are cursors created by doing a select "FOR SCROLLING" or a select "FOR EXTRACT".
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
cursor_id A cursor id returned by PBIGetCursorID().
pos The cursor position requested. Row 1 is at position 0.
callback For synchronous execution the 'callback' parameter should be NULL. If not NULL then execution will be done asynchronous and 'callback' is a pointer to a callback function which will be called on completion. Please refer to the descriptions of Asynchronous execution for more details.
user_data A pointer to user data to be passed into the callback routine apon completion. If no callback routine is supplied then this parameter is ignored.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

short PBIGetValue(long session_id, char *identifier, PBDataFmtPtr type, void *storage, unsigned long *info, short *data_truncated)

An application can use this function to get the value of a variables from a previously executed PrimeBase program.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
identifier A string representing a global variable name that has previously been declared and initialized. Only basic types are supported, Getting the value of arrays, cursors, and PrimeBase Talk[???] objects is not supported.
type A pointer to a structure containing the information about the format that the data is to be returned as. The 'len' field in the DataFmt structure is the length of the storage supplied for each value. If the data type of the variable is not convertible to the data type supplied PBIGetValue will fail. If 'type' is NULL then the data will be returned unconverted and the caller must ensure that the storage space supplied for the data item is at least as big as the maximum data length for the variable.
storage A pointer to a location in memory large enough to hold the item.
info If the type being returned is not of fixed size then the actual length of the data item to be fetched is returned in this location. If the actual length of the data was greater than 'type->len' then the data will be truncated and only 'type->len' bytes will be returned. The user can compare the length in 'info' with 'type->len' to determine if data was truncated. 

If A null item is returned then storage location will be left untouched and info will be set to PB_NULL_DATA.

If 'info' is NULL then the user is not notified of null data items or the length of variable length data items.

data_truncated The address of a variable which is set to 1 if fetched data has been truncated otherwise it is set to 0. If NULL is passed in for this parameter then the caller will not be notified when data is truncated.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

Example:

/*
* This program tests the client/server communications speed by seeing
* how many times it can execute the command "describe databases" in
* 10 seconds. ("describe databases" returns a cursor from the server
* with a list of available databases.)
*/

char buf[30];
int cnt;
PBDataFmt pb_type = {0};
char *the_PrimeBase_program = "\
int t, cnt;\
timestamp the_date;\
\
the_date = $now();\
cnt = 0;\
t = $now() + 10;\
while (t > $now()) {\
    describe databases;\
    cnt++;\
}\
";

PBIExecute(session_id,the_PrimeBase_program, PB_NTS, PB_EXECUTE_NOW, NULL, NULL, NULL);
PBIGetValue(session_id,"cnt", NULL, &cnt, NULL, NULL);

/* Get the timestamp as a C string. */
pb_type.len = 32;
pb_type.type = PB_CSTRING;
PBIGetValue(session_id,"the_date", &pb_type, buf, NULL, NULL);

printf("On: %s PrimeBase executed %d describe databases in 10 seconds.\n", buf, cnt);

short PBIPutValue(long session_id, char *identifier, PBDataFmtPtr type, void *data)

An application can use this function to set the value of a variables from a previously executed PrimeBase program.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
identifier A string representing a global variable name that has previously been declared. Only basic types are supported, Setting the value of arrays, cursors, and PrimeBase Talk objects is not supported.
type A pointer to a structure containing the information about the format of the data being assigned. If the data type of the data is not convertible to the data type of the variable PBIPutValue will fail. If 'type' is NULL then the data is assumed to be in the same format as the data type of the variable. For variable length data types you should always supply a non NULL 'type' parameter.
data A pointer to a buffer containing the data. If 'data' is a NULL pointer then the value of variable referenced by 'identifier' will be set to $NULL.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

Example:

/*
* This program tests the client/server communications speed by seeing
* how many times it can execute the command "describe databases" in
* the number of seconds supplied by the application. ("describe
* databases" returns a cursor from the server with a list of available
* databases.)
*/

char buf[30];
int cnt, execution_time;
PBDataFmt pb_type = {0};
char *the_PrimeBase_program = "\
int t, cnt;\
timestamp the_date;\
\
the_date = $now();\
cnt = 0;\
t = $now() + num_secs;\
while (t > $now()) {\
    describe databases;\
    cnt++;\
}\
";

PBIExecute(session_id,"int num_secs;", PB_NTS, PB_EXECUTE_NOW, NULL, NULL, NULL);
execution_time = 20;
PBIPutValue(session_id,"num_secs", NULL, &execution_time);

PBIExecute(session_id,the_PrimeBase_program, PB_NTS, PB_EXECUTE_NOW, NULL, NULL, NULL);
PBIGetValue(session_id,"cnt", NULL, &cnt, NULL, NULL);

/* Get the timestamp as a C string. */
pb_type.len = 32;
pb_type.type = PB_CSTRING;
PBIGetValue(session_id,"the_date", &pb_type, buf, NULL, NULL);

printf("On: %s PrimeBase executed %d describe databases in %d seconds.\n", buf, cnt, execution_time);

short PBIGetBlobData(long session_id, PBBlobRecPtr blobid, unsigned long offset, char *buffer, unsigned long *size, PBCallBackFuncType callback, void *user_data)

Blob data is not returned directly in cursors. Instead the cursor contains a blob id. This function can be used to get the actual blob data. Since, in general, there is no way that an application can bind a buffer for blob data and be sure that data will not be truncated, the application could do the following:
 
Parameter Description
session_id The session id returned by PBIConnect().
blobid A pointer to A blob ID data buffer as returned from PBIFetchRow() or PBIGetValue().
offset The offset in to the blob from which to read the data. Offsets are zero bases.
buffer A pointer to a buffer into which the data is written.
size On input '*size' contains the size in bytes of the buffer pointed to by 'buffer'. On output '*size' contains the size of the blob minus the value of 'offset'.
callback For synchronous execution the 'callback' parameter should be NULL. If not NULL then execution will be done asynchronous and 'callback' is a pointer to a callback function which will be called on completion. Please refer to the descriptions of Asynchronous execution for more details.
user_data A pointer to user data to be passed into the callback routine upon completion. If no callback routine is supplied then this parameter is ignored.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_EXEC Execution has started and the caller will be notified of completion via the callback routine.
PB_ERROR An error occurred. Call PBIGetError() for details.
Example:
/*
* This example will assume 1 column has been selected and it is of type PB_LCHAR.
*/


PBDataFmt pb_type = {0};
char *buf;
short was_truncated = 0;
unsigned long blob_size;


pb_type.type = PB_CHAR;
pb_type.len = 1024;
buf = malloc(pb_type.len);


/*Bind the column to a fixed length buffer as CHAR. */
PBIBindColumn(session_id, my_cursor_id, 1, &pb_type, buf, 0, &blob_size, 4, 0);

/* Do the fetch. */
PBIFetchRow(session_id, cursor_id, &rows, PB_FETCH_FIRST, &was_truncated, NULL, NULL);

if (was_truncated) { /* If the data was truncated. */
    PBBlobRec blob_id;
    unsigned long size;

    /* Grow the buffer. */
    buf = realloc(blob_size);

    /* Get the blob id. */
    PBIGetColumnData(session_id, cursor_id,1, NULL, &blob_id, NULL, NULL);

    /* Get the remaining data */
    size = blob_size - pb_type.len;
    PBIGetBlobData(session_id, &blob_id, pb_type.len, buf, &size, NULL, NULL);
}

 
 

short PBINewBlob(long session_id, PBBlobRecPtr blobid)

An application can use this function to create a blob id and then write the data to it by calling PBIPutBlobData().
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
blobid A pointer to a blob ID data buffer which will contain the id of the new blob.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

void PBIFreeBlob(long session_id, PBBlobRecPtr blobid)

This function frees a blob[???BLOB] id. It should only be used on blob ids allocated by PBINewBlob().
 
 
 
  Description
session_id The session id returned by PBIConnect().
blobid A pointer to a blob ID data buffer which contain the id of a blob allocated byPBINewBlob() to be freed.

 

short PBIPutBlobData(long session_id, PBBlobRecPtr blobid, unsigned long offset, char *buffer, unsigned long length)

An application can use this function to write the data to a blob before inserting it into a table or assigning it to a variable.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
blobid A pointer to a blob ID data buffer as returned from PBIGetValue() or PBINewBlob().
offset The offset in to the blob to which the data is to be written. If the offset is 0XFFFFFFFF then the data will be written to the end of the blob. If the offset if not 0XFFFFFFFF but beyond the end of the blob an error will be reported.
buffer A pointer to a buffer containing the data to be written.
length The length of the data to be written.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

short PBIConvert(long session_id, void *src, PBDataFmtPtr src_fmt, void *dst, PBDataFmtPtr dst_fmt, unsigned long *size)

If the conversion is not supported then a PB_ERROR is returned. If 'src' and 'dst' point to the same or overlapping memory locations then the result of the conversion is undefined. The built in conversion functions do not convert NULL data. If 'src' is NULL and the call to PBIConvert() would have invoked a built in conversion function then PBIConvert() will return PB_OK and the destination buffer will remain untouched.
 
 
 
Parameter Description
session_id The session id returned by PBIConnect().
src A pointer to the data to be converted. If 'src' is NULL then the conversion is done as if the data to be converted was NULL.
src_fmt A pointer to a structure containing the type information of the source data.
dst A pointer to the storage location into which the converted data is to be placed.
dst_fmt A pointer to a structure containing the type information of the destination data.
size A pointer to a 4 byte integer. If 'dst_fmt' points to a variable length data type then 'size' will contain the length of the data after conversion. If the converted data could not be placed in the 'dst' buffer with out truncation then the data will be truncated and 'size' will contain the untruncated length. The caller can test for truncation by comparing 'dst_fmt->len' and 'size'.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

short PBISetConvert(long session_id, short src_type, short dst_type, PBConvFuncType func)

This function can be used to set or clear a user conversion function. If 'func' is NULL and if a user defined conversion routine exists it is removed. After this call if there is a built in conversion function for the data types then it will be used. If there is no built in function then the conversion from 'src_type' to 'dst_type' will not be allowed. If 'func' is not NULL then after the successful completion of this call all conversions from 'src_type' to 'dst_type' will be done using the conversion function 'func'. This includes conversions done explicitly via a call to 'PBIConvert' and conversions done implicitly as a result of binding a column of type 'src_type' to a destination type of type 'dst_type'.

The user can replace built in conversion routines with this call or supply conversion routines for user defined data types. The values for the defined data types identifiers must start at PBI_USER_TYPE.

Note: User installed conversion functions must be prepared to be called with a NULL 'src' buffer when fetch loads a NULL data item into a bound buffer location.
 
 
 
Parameter Description
src_type The source type of the conversion routine.
dst_type The destination type of the conversion routine.
func A pointer to a conversion routine.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 


short PBIGetConvert(long session_id, short src_type, short dst_type, PBConvFuncType *func)

This function can be used to get the user defined conversion function set by a previous call to PBISetConvert(). If there is no user defined conversion function then 'func' will be set to NULL.
 
 
 
Parameter Description
src_type The source type of the conversion routine.
dst_type The destination type of the conversion routine.
func A pointer to a conversion routine.

 
 
Return Value Description
PB_OK Execution completed successfully.
PB_ERROR An error occurred. Call PBIGetError() for details.

 

void PBISetLogName(char *name)

This function can be used to set the applications log file name and location. If the log file name is given as NULL then no log file will be created. Depending on the values of the PrimeBase Virtual Machine environment variables the PrimeBase Virtual Machine may write messages to the log file. By setting the log file name to NULL the application override the environment variables settings and prevent anything from being logged.
 
 
 
Parameter Description
name The name of the log file to use for all future logging. By default the log file is called 'pbvm.log' (PrimeBase Virtual Machine Log) and it is created in the applications current working directory.

 

void PBILogStr(char *str)

This function can be used to add application specific messages to the log file. The application is responsible for formatting the string and adding any CR and/or LF characters to the end of the string.
 
 
 
Parameter Description
str A string to be sent to the log file.

 

void PBITrace(long session_id, int api_tracing)

This function can be used to activate API tracing for a specific connection. When API tracing is activated all calls made to the PrimeBase API will bee logged along with their parameters and return values. This is a very useful feature which can be used for debugging and reporting PrimeBase API problems to SNAP Innovation.
 
Parameter Description
session_id The session id returned by PBIConnect().
api_tracing A boolean flag to activate API tracing on the connection.

 

Return values

All the API functions return integer values to indicate either successful or unsuccessful completion of the call, or other types of status conditions. See the following tables:
 
 

Integer values for return codes

 
Symbol Value Description
PB_NODATA 2 The call completed successfully, no data was returned.
PB_EXEC 1 The call is still being executed.
PB_OK 0 The call completed successfully.
PB_ERROR -1 The call ended in an error condition. The error details can then be retrieved with PBIGetError().
PB_CANCELED -2 An asynchronous call was canceled.

 

Integer values for data type codes

 
Symbol Value PBT Data Type C Data Type Description
PB_BOOLEAN 1 BOOLEAN unsigned char 1-byte value, 0 = FALSE, 1 = TRUE.
PB_SMINT 2 SMINT signed char 2-byte signed integer value.
PB_INTEGER 3 INTEGER int 4-byte signed integer value.
PB_SMFLOAT 4 SMFLOAT float 4-byte floating point value.
PB_FLOAT 5 FLOAT double 8-byte floating point value.
PB_DATE 6 DATE struct{short year; unsigned char month; unsigned char day;} 4-byte PBDateRec value.
PB_TIME 7 TIME struct {unsigned char hour; unsigned char min; unsigned char sec; unsigned char hu;}  8-byte PBTimeRec value.
PB_TIMESTAMP 8 TIMESTAMP struct {PBDateRec date;PBTimeRec time;} 16-byte PBDateTimeRec value.
PB_CHAR 9 CHAR(n) char[n] Fixed length single byte char value.
PB_DECIMAL 10 DECIMAL(precision, scale) unsigned char[precision/2 +1] Binary coded decimal (BCD)
PB_MONEY 11 MONEY(precision, scale) unsigned char[precision/2 +1] Binary coded decimal (BCD)
PB_VCHAR 12 VARCHAR(n) struct {unsigned short len; char(n);} Variable length char value.
PB_VBIN 13 VARBIN(n) struct {unsigned short len; char(n);} Variable length binary value.
PB_LCHAR 14 LONGCHAR struct {long(16);} Large char value. The C type is a handle used by blob functions to get the data.
PB_LBIN 15 LONGBIN struct {long(16);} Large binary value. The C type is a handle used by blob functions to get the data.
PB_SINT1 19 - signed char One byte signed integer value.
PB_TINYINT 20 TINYINT unsigned char One byte unsigned integer value.
PB_UINT2 21 - unsigned short An unsigned 2-byte integer.
PB_UINT4 22 - unsigned int An unsigned 4-byte integer.
PB_CSTRING 26 char(n) char[n+1] Zero terminated character string.
PB_UNICODE 27 UNICODE(n) wchar(n) Double byte unicode string.

 

Asynchronous execution mode

When an asynchronous call is made any further asynchronous calls on the same connection will be queued.

If the application makes a non asynchronous call while an asynchronous call is in progress on the same connection, the non asynchronous call may block and wait for the completion of the outstanding asynchronous calls on the same connection. Any time the application makes an API call the application must be prepared for the event that an asynchronous calls callback may be executed during the call.
Unless the asynchronous call returns PB_ERROR, the caller's callback will be called even if the call completes with in the asynchronous call itself.
 
 


Callback functions

 

void User_CallBackFunc(void *user_data, short result, long primary_err, long secondary_err, char *msg)

This is the user supplied callback function used for asynchronous completion notification. The following API functions take an PBCallBackFunc pointer as a parameter: These are all functions that may have to send a request to the server and then wait for a reply. When executed in asynchronous mode rather than waiting on the server, they will complete with a return code of PB_EXEC and the application must call PBIPoll() to check for completion.

Execution of the callback may occur from within the API call if the function could be completed without having to wait on the server. In this case the function will still return PB_EXEC even though the callback has already been called.

No PrimeBase API call may be made from within a callback. Doing so will result in a deadlock.
 
 
 
Parameter Description
user_data A reference to the user data passed into the PrimeBase API function that was called asynchronously.
result This parameter can contain one of the following values: 
  • PB_NODATA

  • Call completed successfully, no data returned.
     
  • PB_OK

  • Call completed successfully.
     
  • PB_ERROR

  • Execution ended in error.
     
  • PB_CANCELED

  • The call was canceled. 
primary_err If 'result' is PB_ERROR 'primary_err' will contain the primary error number.
secondary_err If 'result' is PB_ERROR 'secondary_err' will contain the secondary error number.
msg If 'result' is PB_ERROR 'msg' will be a zero terminated error message.

 
 
 


void PBOutPutCallBackFunc(void *user_data, char *buffer, long size)

This is the user supplied callback function for PBIGetOutput() used for asynchronous output data notification.

The caller can expect this callback to be called at anytime while a program containing PBT ptint commands is executing.

No PrimeBase API call may be made from within a callback. Doing so will result in a deadlock.
 
 
 
Parameter Description
user_data A reference to the user data passed into PBIGetOutput().
buffer TThe pointer to the callers output buffer passed in when PBIGetOutput() was callled.
size The string length of the data in the output buffer.

 
 
 


short User_ConvFunc(long session_id, void *src, PBDataFmtPtr sfmt, void *dst, PBDataFmtPtr dfmt, unsigned long *size)

This is the user supplied conversion function that the application can register via the PBISetConvert() API call to be called when a specific data type conversion takes place. See the description of PBIConvert() for details.

No PrimeBase API call other than PBIConvert() may be made from within a user supplied conversion function. Doing so will result in a deadlock.
 
 



SDK Examples

Included in the PrimeBase SDK is a file called "pbshell.c" which contains examples of the API calls and how to use them. Anyone planning on writing an application using the PrimeBase API should have a look at this file. pbshell.c has been designed so that it can be easily extended by application builders to include their own tests.
 
 

Reporting problems

If a bug is suspected in the PrimeBase Virtual Machine or the PrimeBase API you can help speed up the problem resolution process by activating the PrimeBase API logging and sending a log showing the calls to the API during which the problem occurs. Ideally if you could create a test which could be added to the pbshell.c file to reproduce the problem it would be greatly appreciated and you can be guaranteed a prompt response.
 
 



2. CL / PrimeBase Item Stream Interface (PBISI)

This is an interface for applications that wish to write their programming logic in PBT and have it compiled and executed by the PrimeBase Virtual Machine (PBVM) runtime environment. This API is ideally suited to interactive applications where the application doesn't have control over what is being executed or what is being output. This API must be used if your application will be making use of the PBT satements which print items to the output stream such as the PRINT, PRINTROW, PRINTALL, PRINTF, and PRINTINFO statements.

The functions begin with the prefix CL and the prototypes are specified in the header file 'pbisi.h'.

The PBISI API functions are an interface between the client application and the PrimeBase Virtual Machine (PBVM) runtime environment. The client application calls the API functions to perform the following tasks:

The API functions described in this section may be divided into the following function groups:

Function overview

 

Session-control functions

 
Function Description
CLInit() Begins a PBT session
CLEnd() Ends a PBT session
CLConInfo() Describes a PBT session
CLGetSn() Returns the session number

 

Program-execution functions

 
Function Description
CLSend() Sends PBT program text to the runtime environment
CLSendItem() Sends binary data to the runtime environment
CLExec() Executes previously sent PBT programs
CLState() Checks PBT program execution status
CLGetErr() Retrieves error codes and messages
CLBreak() Interrupts and terminates PBT program execution

 

Results-processing functions

 
Function Description
CLGetItem() Describes and/or retrieves the next data item
CLUnGetItem() Unretrieves the previous data item

 
 

Return values

All the API functions return integer values to indicate either successful or unsuccessful completion of the call, or other types of status conditions. See the following tables:
 
 

Integer values for return codes

 
Symbol Value Description
A_NULL 1 The requested data item is a NULL, therefore no data was returned.
A_OK 0 Function successfully completed
A_VALUE 0 When returned by an information request call, the PBT program produces output data that is awaiting retrieval by the client application; when returned by a data retrieval call, the data item was successfully retrieved into the supplied buffer.
A_ERROR -1 Program execution ended in an error condition. The error details can then be retrieved with CLGetErr().
A_READY -2 The runtime environment is ready to accept program text. If a PBT program fragment was being executed, it has finished successfully and there is no more output to be processed by the client application.
A_BADTYPE -3 The item requested is not of the data type expected. No data has been returned.
A_BREAK -5 An API results-processing function was interrupted on request from the client application, or a timeout has occurred.
A_EXEC -6 A PBT program is currently being executed. There is no output data waiting to be processed by the client application.
A_NOTCONN -7 Specified session ID parameter is invalid.
A_SESSMAX -8 Specified session number parameter is out of range.
A_INUSE -9 Session is in use by another client application.
A_NOHOST -10 Session is open, but not connected to a host.

 

Integer values for data type codes

 
Symbol Data Type Value Len Places
A_BOOLEAN BOOLEAN 1 No No
A_SMINT SMINT 2 No No
A_INTEGER INTEGER 3 No No
A_SMFLOAT SMFLOAT 4 No No
A_FLOAT FLOAT 5 No No
A_DATE DATE 6 No No
A_TIME TIME 7 No No
A_TIMESTAMP TIMESTAMP 8 No No
A_CHAR CHAR 9 Yes No
A_DECIMAL DECIMAL 10 Yes Yes
A_MONEY MONEY 11 Yes Yes
A_VCHAR VARCHAR 12 Yes No
A_VBIN VARBIN 13 Yes No
A_LCHAR LONGCHAR 14 Yes No
A_LBIN LONGBIN 15 Yes No
A_UNICODE UNICODE 27 Yes No

 

Results processing

The API functions, CLGetItem(), and CLUnGetItem(), allow the client application to process output data generated by the execution of a PBT program. Output data is generated by the various "print" statements: PRINT, PRINTROW, PRINTALL, PRINTF, and PRINTINFO. The "print" statements generate an output data stream with an implicit row/column structure for each statement.

Output from the PBT program is treated as one continuous stream of data items by the PBISI API. The CLGetItem() function retrieves each data item in sequence, operating from the client application. The data items are returned to the client application each with a set of flags. The flags are used to indicate NULL values, end-of-row boundaries, and whether the output has been formatted by the PBT program.

The CLUnGetItem() function can be used to return a data item, that has just been retrieved, back to the stream, so that it can be retrieved again later. When no more data is there, i.e. when the end of the PBT program´s output data stream is reached, the API returns a A_READY result.

Another function of CLGetItem() is to obtain information about the data item from the API. For example, you may want to find out information on the data type and length of the next data item, and based on this information then allocate a buffer. You can then call the API a second time, and actually retrieve the data item, and place it in the buffer. In this way the client application can adapt to the returned data.
 
 

API functions and NULLs

A client application should be prepared to handle NULL values in the output data stream from the Server. The return value A_NULL from the CLGetItem() function indicates a NULL value.

If the client application cannot handle NULL values, you can use the PRINT statement:

PRINTCTL 0;
All data is converted by this statement to VARCHAR strings; NULL values are represented by the string "$NULL".
 
 

API functions

short CLBreak(long sessid, int abort)

This function interrupts the runtime environment, by resetting or aborting it.
 
 
 
Parameter Description
sessid The session ID that specifies which session is to be re-set or aborted. CLInit() returns the session ID.
abort This requests that the current runtime environment be aborted if non-zero. If zero, it requests that program execution be halted, and that the runtime environment be reset.

 
 
Return Value Description
A_OK The session has been successfully reset or aborted.
A_ERROR The reset or abort attempt was unsuccessful.

 

Notes

If the runtime environment is blocked, while waiting for a reply from the host, any attempt to reset the environment will be unsuccessful. The reason for this is that the runtime environment cannot process this function until the host returns control to it.

This function can also be used to break an infinite loop or stop runaway output from the program that is currently executing.
 
 

short CLConInfo(long sessid, int sessnum, long *outid, long *vrsid, char *host, char *user, char *network, char *connstr, long *start, long *statep)

This function returns information about a specified session.
 
 
 
Parameter Description
sessid The session ID specifying the session about which you want information. If sessnum is used instead to identify the session, then sessid must be zero.
sessnum The session number specifying the session about which you want information. If sessid is used instead to identify the session, then sessnum must be zero.
outid This is used to return the corresponding sessid from a call where only the sessnum was specified.
vrsid This is used to return the client API version number as a sequence of 4 bytes.
host This is used to return the host parameter that was specified in the CLInit() call that created the session. This is the name of the Server.
user This is used to return the user parameter that was specified in the CLInit() call that created the session.
network This is used to return the name of the type of network connection that is being used by the session.
connstr This is used to return the connection string parameter that was specified in the CLInit() call that created the session.
start This is used to return a unique TIMESTAMP value that is associated with the start of a session.
statep This returns the state of the session as it would be reported by the CLState() call. The possible return values are the same as the CLState() return values.

 
 
Return Value Description
A_VALUE Information for an active session has been retrieved successfully.
A_NULL The input session id or number refers to an inactive session.
A_SESSMAX The specified sessnum is out of range.

 

Notes

Normally, this function should be used with a non-zero sessid obtained from a previous CLInit() call (where sessnum is set to 0), in order to obtain information about a session that was initiated by the client application.

For testing purposes, sessnum can be used to find out information on all the available sessions - whether or not they were initiated by the client application.

The parameter statep can also return the value A_EXEC, which means that the requested session was already in use by another user at the time when the CLConInfo() call was made.
 
 

short CLExec(long sessid)

This function requests the execution of a program fragment that has previously been passed by one or more CLSend() or CLSendItem() calls. The run-time environment then begins execution of the fragment, and control is immediately returned to the client application.
 
 
 
Parameter Description
sessid The session ID specifying the session for which the program fragment should be executed. The session ID is that which is returned by the CLInit() call.

 
 
Return Value Description
A_OK Execution of program fragment has begun successfully.
A_ERROR An error occurred while trying to begin execution.

 

Notes

The client application is free to continue work, while the runtime environment begins execution.

This call is asynchronous, error messages may not be available at completion.

You can determine the current status of execution with the CLState() function call.
 
 

short CLGetErr(long sessid, long *perr, long *serr, char *itm1, char *itm2, char *msg)

This function retrieves error codes and messages after an error has occurred.
 
 
 
Parameter Description
sessid The session ID that is returned by CLInit().
perr The buffer in which the primary error code is placed.
serr The buffer in which the secondary error code is placed.
itm1 The buffer for the zero-terminated string that identifies the first object of the error message.
itm2 The buffer for the zero-terminated string that identifies the second object of the error message. The maximum number of bytes returned is 256 (including zero terminators).
msg The buffer for the returned error message. The maximum number of bytes returned is 256 (including zero terminators).

 
 
Return Value Description
A_OK The error information has been retrieved successfully.
A_ERROR An error occurred while retrieving the error information!

 

Notes

This call must be made following a function call that returns an error status without any intervening API calls. This must be so in order to retrieve the error information directly associated with the returned error status.

Any of the pointers may be NULL if the user is not interested in the data that may be returned

When used after an unsuccessful CLInit() call, this function may be used to determine why it was unsuccessful.

The message in msg always begins with the name of the program source, as well as the line in which the error occurred. This information is followed by a colon (:) and the error message itself. For program fragments sent by the CLSend() API function, the program source is identified as "network". It is often convenient to use the colon delimiter to parse the message so that only the latter half is revealed to the user of the client application.
 
 

short CLGetItem(long sessid, int timeout, short *typep, short *lenp, short *placesp, short *flagsp, char *buffer)

This function can either retrieve the next data item from the runtime environment´s output data stream, or it can obtain information about the type and size of the next data item.

This function call is an information request call when made with a NULL (0) buffer pointer, The next data item in the data stream is examined, and data type, length, number of decimal places and flags are returned to the client application, however, the item itself is not retrieved. With the help of the retrieved information, you can allocate a buffer to receive the next data item. Remember, however, that an information CLGetItem() call does not advance the API to the next data item in the data stream.

Data can be retrieved with a non-NULL buffer pointer. Again, the data type, length, number of decimal places, and flags for the next data item are returned in addition to the data item itself. In contrast to an information request call, the retrieval of a data item, with CLGetItem(), does advance the API to the next data item in the data stream.

By passing a data type code to the CLGetItem() function, the client application can tell the API what type of data item it expects to receive. If the type is different to the type of the next item in the output stream, an error code is returned. If the client application is prepared to receive any type of data, then the data-type code, A_ANYTYPE must be passed to the CLGetItem() function.
 
 
 
Parameter Description
sessid This specifies the session ID call, that is returned by CLInit().
timeout This specifies the length of time in hundredths of seconds that CLGetItem() should wait for an available data item before returning the code A_BREAK. If you do not wish to specify a time - and therefore allow an unlimited wait for the next data item, then you must pass the value AW_FOREVER.
typep The typep pointer points to a short value (a 2 byte signed value) that contains the expected data type of the retrieved data item. On return, the value is set to the actual type of the data.
lenp The lenp pointer points to a short value (a 2 byte signed value) that contains the length of the buffer pointed to by buffer. The range allowed by this short value is between 0 and 32767 bytes. Once the data item has been retrieved, the value is set to the actual length of the data item.
placesp The short value pointed to by placesp is set to the number of decimal places in the retrieved data item. If the item is not DECIMAL or MONEY type, then a zero is returned.
flagsp the short value pointed to by flagsp contains a series of bit flags that describe the retrieved data item. The flag AF_ISNULL indicates that the data item is a NULL value. The flag, AF_RECEND, specifies that the retrieved data item is in the last column of an output row. The client application can use this flag to test for an end-of-row condition.
buffer To retrieve information about the next item, this parameter must be set to NULL. For data retrieval, it must be a pointer to a buffer where the retrieved data can be placed. If the item is NULL, no data will be placed in the buffer.

 
 
Return Value Description
A_VALUE A non-NULL data value was retrieved.
A_NULL A NULL data value was retrieved.
A_ERROR The execution ended in an error. There is no more data.
A_READY Execution ended successfully; there is no more data.
A_BADTYPE The data item is not of the type expected.
A_BREAK The time limit specified by the timeout parameter ran out while waiting for data from the runtime environment.

 

Notes

The statements PRINT, PRINTF, PRINTALL and PRINTINFO generate the data items that are retrieved by this function call. The data values form continuous data stream, from which CLGetItem() retrieves each item in sequence.

For VARCHAR and CHAR types, the length returned is the number of data characters. The returned data also includes a NULL termination byte, which is not counted as a data byte. Therefore when such data types are expected, your buffer size should allow for the "returned length + 1".

In order to skip the following data item in the data stream, call CLGetItem() with a NULL buffer, and set typep to A_DISCARD.

A good use of the timeout feature in the CLGetItem() call is to supply a short timeout value and thus allow the client application to regain control and continue with other work, and not have to wait, should no data item be currently available. While the client application is continuing with other work, the function call CLState(), can be called to determine when a data item becomes available. An alternative to this procedure is to set the client application to loop, calling CLGetItem() repeatedly with a relatively short timeout value, then checking for other events between calls.
 
 

short CLGetSn(long sessid)

This function retrieves the internal PBT session number for a particular session ID.
 
 
 
Parameter Description
sessid The session ID, that can be obtained by CLInit(), for the session number that you are requesting.

 
 
Return Value
This function returns a session number, which is an integer value of 1 or more.

 

Notes

This function call is really only provided for testing and analytic purposes, and is rarely used by client applications. It is then most often used together with CLConInfo(), in order to retrieve information on all available sessions, whether or not they have been initiated by the client application.

The session number returned can be used as the sessnum of the CLConInfo() function call.
 
 

short CLInit (long *sessidp, char *host, char *user, char *passwd, char *connstr)

This function creates a PBT session. A session is a runtime environment in which a PBT program may execute. Each session has its own global variable and procedure space. PrimeBase creates the PBT session on the client workstation.

CLInit() must be called before any other API function.
 
 
 
Parameter Description
sessidp a buffer in which the session identifier returned by this function is stored.
host DAL compatible programs should pass ‘PrimeBaseHost’. PrimeBase specific application may pass the alias name of a connection defined in the ‘connect.def’ file.
user the name of a valid host user.
passwd the password of the user.
connstr a string containing information used to connect to the specified host.

 
 
Return Value Description
A_ERROR an error occurred while creating the session.
[nothing in case of success?) or null?]  

 

Notes

A long-integer session ID is always returned to the buffer at sessidp, even when CLInit() returns an error. This enables you to pass the session ID to CLGetErr(), in order to determine the cause of the error.

The CLEnd() should always be called with the session ID returned by CLInit(), so that all resources to do with that session can be freed. This must still be done, even if CLInit() returned A_ERROR.
 
 

short CLSend(long sessid, char *text, int len)

This function call sends program text to the runtime environment. Text is then added to any previously passed text, to assemble a program fragment. This program fragment is not executed until the client application has called the CLExec() function call.
 
 
 
Parameter Description
sessid The session ID for which the program fragment is being sent.
text A character string containing program text.
len The length of the text.

 
 
Return Value Description
A_OK The text was accepted successfully.
A_ERROR An error occurred while sending the text.

 

Notes

Program text can be passed in units as small as a single character. There is no requirement that complete statements be sent in a single function call. White space and semi-colons must be explicitly included in the passed text.

It is possible to embed new lines and carriage returns in the passed text, in order to divide it into lines. These characters are ignored syntactically. Remember, thought, that PBT error messages reference the line number where the error occurred. Line numbers begin at line 1 for the first text sent via CLSend() after a CLInit() or CLExec() call.
 
 

short CLSendItem(long sessid, int type, int len, int places, int flags, char *buffer)

This function call sends a binary data item to the runtime environment. This data item becomes part of the current program fragment that has been put together by a series of CLSend() and CLSendItem() calls.
 
 
 
Parameter Description
sessid The session ID (returned by CLInit()) for which the data is being sent.
type The data type code for the data item.
len The length of the data item. This is ignored if type specifies a data type that has a self-defining length.
places The number of decimal places in the data item. This is ignored for all data types other than DECIMAL and MONEY.
flags A word used to pass a flag value - in the same format as that returned by the CLGetItem() call. AF_ISNULL sends a NULL data item; to send non-NULL data items, pass a zero (0).

 
 
Return Value Description
A_OK The data item was accepted successfully.
A_ERROR An error occurred while sending the data item.

 

Notes

Data items retrieved in binary form by CLGetItem() can later be sent back to the runtime environment with CLSendItem().
 
 

short CLState(long sessid)

This function call returns the status of the runtime environment.
 
 
 
Parameter Description
sessid The session ID of the session for which the status is being requested.

 
 
Return Value Description
A_EXEC A program is currently being executed.
A_VALUE Output data is available for the client application.
A_NULL Output data (a NULL) is available.
A_READY Execution was successful; the runtime environment is ready for text.
A_ERROR Execution ended in an error.

 

Notes

CLState() does not suspend or block user activity.

The CLState() is not reset by CLSend(), but only by CLExec().
 
 

short CLUnGetItem(long sessid)

This function call basically undoes the effect of the last CLGetItem() data retrieval call. The data item that was retrieved by the immediately preceding CLGetItem() call is returned to the data stream, and can be re-retrieved the by the next CLGetItem() function call.
 
 
 
Parameter Description
sessid The session ID, as returned by CLInit().

 
 
Return Value Description
A_VALUE The undoing of the last CLGetItem() call was successful.
A_ERROR An error occurred during the "undoing".

 

Notes

Only a single data value can be undone; you cannot step back through previously retrieved data,

This function comes in handy when your allocated buffer is not large enough to handle the item and must then reallocate a larger buffer and retrieve the item again.



3. PrimeBase Native (PBN) plug-in API

PrimeBase native plug-ins allow users to call functions implemented in 'C' directly from a PrimeBaseTalk program as if they where a PrimeBaseTalk function. Native plug-in functions are declared in PrimeBaseTalk in much the same way as normal PrimeBaseTalk functions except that they use the keyword "Native" and they have no body.

Here is an example declaration of a native function called "Hello" that takes a string as an input parameter and returns a string as a return value:

native procedure Hello(name)
returns varchar;
ARGUMENT varchar name;
end procedure Hello;
This function could then be implemented in your plug-in like this (GetParamValue(), GetReturnBuf() and RaiseError() are described later in this document):
void DLLENTRY hello(PBNEnv pbn, PBNSession sid)
{
    char *value;
    char *buffer;
    PBNError err;

   value = my_calls.GetParamValue(pbn, 1, PBN_C_STRING, NULL,      &err);
    if (!value && err) {
        my_calls.RaiseError(pbn, err, NULL);
        return;
    }

    buffer = my_calls.GetReturnBuf(pbn, 1, PBN_C_STRING, strlen(value)      + 30, &err);
    if (err || !buffer) {
        my_calls.RaiseError(pbn, err, NULL);
        return;
    }

    sprintf(buffer, "Hello \"%s\"!", value);
}
The native procedure can now be called from within your PrimeBaseTalk program as if it were a PrimeBaseTalk program procedure. For example the PrimeBaseTalk program...
print Hello("PrimeBaseTalk");
...would produce the output...
Hello "PrimeBaseTalk"!
A more useful use of PrimeBase native plug-ins would be to make the API of third party software accessable from within a PrimeBaseTalk program.

Please refer to the examples supplied with the SDK for more details.

NOTE: A 4-byte integer data type size is assumed with this interface.
 
 

Defines

 
Name 'C' Type
PBN_INT_4 int
PBN_UINT_4 unsigned int
PBN_UINT_1 unsigned char
PBN_BLOB_ID unsigned int

C data type codes / constants

 
C data type code Value Description
PBN_C_INT 1 4-byte signed int
PBN_C_UINT 2 4-byte unsigned int
PBN_C_STRING 3 Null terminated C string
PBN_C_BIN 4 Binary data
PBN_C_FLOAT 5 8-byte floating point value
PBN_C_DATE 6 PBDateRec
PBN_C_TIME 7 PBTimeRec
PBN_C_TIMESTAMP 8 PBTimeStampRec
PBN_C_BLOB     9 PBN_BLOB_ID

NOTE: There is curently no 4-byte unsigned int in PrimeBaseTalk

Conversions between PrimeBaseTalk and C data types

Not all PrimeBaseTalk data types are convertable to all C data types and currently there are no conversion routines for cursors. As a rule of thumb if the conversion makes sense it is probably supported.

All data types are convertable to bin types. Converting to bin is really a no-op: the data is untouched, just the type changes.
 
 
 
PBTalk \ C  C_INT C_UINT C_STRING C_BIN C_FLOAT C_DATE C_TIME C_TIMESTAMP
BOOLEAN X X X X X - - -
SMINT X X X X X X X X
INTEGER X X X X X X X X
REAL X X X X X X X X
FLOAT X X X X X X X X
DATE X X X X X X - X
TIME X X X X X - X X
TIMESTAMP X X X X X X X X
CHAR X X X X X X X X
DECIMAL X X X X X - - -
MONEY X X X X X - - -
VARCHAR X X X X X X X X
VARBIN X X X X X X X X
LONGCHAR X X X X X X X X
LONGBIN X X X X X X X X
OBJNAME X X X X X X X X
GENERIC X X X X X X X X
TINYINT X X X X X X X X
CURSOR - - - - - - - -

Type defs

 
Name 'C' Type
PBNError int
PBNSession int
PBNEnv unsigned int
PBNBool unsigned char

 

Callback functions supplied by the PrimeBase software

 

void (*PBNFunc)(PBNEnv env, PBNSession sid)

This is the prototype for all plug-in function calls. The "env" parameter is used by the calling code and must be passed into all callbacks. Do not assume anything about the value "env".
 
 

PBNBool (*PBNGetInfoFunc)(PBNEnv env, PBN_INT_4 param_num, PBN_INT_4 *pbt_type, PBN_UINT_4 *len, PBN_UINT_4 *scale)

This is the prototype for GetParamInfo() and GetReturnInfo(). The plug-in can use these functions to verify that the PBTalk procedure declaration matches that of the plug-in procedure being called.

This function returns TRUE if the parameter exists and FALSE if it doesn't. If the caller is not interested in the information, pbt_type, len, or scale can be NULL.
 
 

void *(*PBNGetParamValFunc)(PBNEnv env, PBN_INT_4 param_num, PBN_INT_4 c_type, PBN_UINT_4 *len, PBNError *error)

Call the GetParamValue()[mismatch] function to get the data from the parameters. On error or if no data was passed in then the function returns NULL and sets the value of '*error' to indicate the error. If there was no data for the parameter but the parameter number was valid then the function returns NULL and '*error' is set to zero.

The data pointers returned by this function remain valid until the plug-in function has completed.
 
 

void *(*PBNGetReturnBufFunc)(PBNEnv env, PBN_INT_4 param_num, PBN_INT_4 c_type, PBN_UINT_4 len, PBNError *error)

Call the GetReturnBuf() function to get a buffer for a function's return values. The caller then places the data to be returned into the buffer. Return parameters that have not been allocated a buffer via this function will be set to $NULL. The 'len' parameter is ignored for all types other than PBN_C_BIN and PBN_C_STRING. In the case of PBN_C_STRING len is the string length plus one for the null terminator. i.e. the len for the string "cat" is 4.

The user can call GetReturnBuf() for the same param_num more than once in which case the previously allocated buffer will be freed and a new one allocated.

Once this function has been called for a parameter the parameter buffer allocated by this function will be assumed to contain valid data until SetReturnNull() has been called.

This function returns a pointer to the allocated buffer on successful completion or NULL if it fails and the value of '*error' to indicate the error.

Some possible reasons for failure may be:

void (*PBNReturnNullFunc)(PBNEnv env_id, PBN_INT_4 param_num)

Call the SetReturnNull()[mismatch] function to set a buffer for a function's return value to $NULL.
 
 

PBNError (*PBNExecStringFunc)(PBNEnv env, char *text)

Call the ExecString() function to initiate the execution of a string. Execution of the string begins after returning from the native library call.

NOTE: If ExecString() is called multiple times, then the strings are executed in reverse order ("last in, first to be executed")[correct?].

Call the ExecString() function to declare your native functions from inside PBNInit().

 

void (*PBNRaiseErrorFunc)(PBNEnv env, PBNError err_num, char *text)

Call the RaiseError() function to report an error. You can set the value of 'text' and 'err_num' to what ever you want including NULL[how? "null"?] and zero.

NOTE: Errors returned by ExecString(), GetParamValue() and set_return_val() are not  automatically reported. If you want them reported you must call RaiseError().
 

void *(*PBNReadBlobFunc)(PBNEnv env_id, PBN_BLOB_ID blob_id, PBN_UINT_4 offset, void *buffer, PBN_UINT_4 *size)

 Call the ReadBlob() function to access the data from blobs passed in as function paramaters.   To get that paramater's blob id call GetParamValue() for the blob paramater with c_type set to PBN_C_BLOB.
 
 
 
 
Parameter Description
env_id The environment id of the PBN function call.
blob_id A paramater's blob id as returned by GetParamValue() for a blob paramater with c_type set to PBN_C_BLOB.
offset The offset into the blob at which to start the read operation.
buffer A pointer to a buffer into which the data is to be read.
size On input the maximum number of bytes to be read, on cmpletion the actual amount of data available to be read will be returned in *size. 

Calling  ReadBlob() with offset and *size both set to 0 will result in the size of teh blob being returned in *size with out actually reading and data or touching the 'buffer' paramater.

 

void *(*PBNWriteBlobFunc)(PBNEnv env_id, PBN_BLOB_ID blob_id, PBN_UINT_4 offset, void *buffer, PBN_UINT_4 size)

 Call the WriteBlob() function to write the data to a blob being returned by a function. To get the return value's blob id call GetReturnBuf()  for the blob paramater with c_type set to PBN_C_BLOB. Only blob ids returned by  GetReturnBuf() are writeable.
 
 
 
 
Parameter Description
env_id The environment id of the PBN function call.
blob_id A paramater's blob id as returned by GetReturnBuf() for a blob paramater with c_type set to PBN_C_BLOB.
offset The offset into the blob at which to start the write operation. If the offset is -1 then the data will be written to the end of the blob. If the offset is not -1 and is beyond the end of the blob an error will be reported and no data will be witten.
buffer A pointer to a buffer to be written to the blob.
size The number of bytes to be written to the blob. 

 

The callback functions are passed to the plug-in via the following structure which is initialized by the host application when the plug-in's PBNInit() function is called.
 
 

        typedef struct PBNCallbacksRec {
                PBN_UINT_4 size; // The size of this structure 
                PBNGetInfoFunc GetParamInfo;
                PBNGetInfoFunc GetReturnInfo;
                PBNGetParamValFunc GetParamValue;
                PBNGetReturnBufFunc GetReturnBuf;
                PBNReturnNullFunc SetReturnNull;
                PBNExecStringFunc ExecString;
                PBNRaiseErrorFunc RaiseError;
                PBNReadBlobFunc ReadBlob;
                PBNWriteBlobFunc WriteBlob;
        } PBNCallbacksRec, *PBNCallbacksPtr;
 

Functions supplied by the plug-in

The following functions must be exported by any plug-in.
 
 

PBN_INT_4 PBNVersion(PBN_UINT_4 pb_version, PBN_INT_4 version)

PBNVersion() returns the PBN version conformance of the plug-in library. This function can be called before calling PBNInit(). Input is the version of the PrimeBase software, and the PrimeBase native API version.

Example implementation:

PBN_INT_4 DLLENTRY PBNVersion(PBN_UINT_4 pb_version, PBN_INT_4 version)
{
    return PBN_VERSION;
}

PBNError PBNInit(PBNCallbacksPtr pbn, PBNEnv env, PBNSession clone_id)

PBNInit() initializes the plug-in library and passes in pointers to the various callback functions. PBNInit() will be called before calling any other function in the plug-in with the exception of PBNVersion().

The session id passed to this function is the ID of the "clone" session. The clone session is created before all other sessions. Normal sessions are created by duplicating all variable and procedures in the clone session.

You can make use of this function to declare your native functions in PBTalk. To do this call ExecString() using the clone_id passed in and a string containing all your native function declarations. For example this is the implementation of PBNInit() used in the nativetest.c:

// This code declares the native function:
static char *my_native_funcs = "\
native procedure call_info(name)\n\
returns varchar;\n\
ARGUMENT varchar name;\n\
end procedure call_info;\n\
\n\
class NativeTest {\n\
native void print_hello(varchar name);\n\
};\n\
";

PBNCallbacksRec my_calls = { 0 };

PBNError DLLENTRY PBNInit(PBNCallbacksPtr calls, PBNEnv pbn, PBNSession sid)
{
    // Make a copy of the callback functions:
    memcpy(&my_calls, calls, sizeof(PBNCallbacksRec) <
        calls->size ? sizeof(PBNCallbacksRec) : calls->size);

    // Execute the code that declares the native function in this library:
    return my_calls.ExecString(pbn, my_native_funcs);
}
NOTE: The memory pointed to by "pbn" in not valid after the call to PBNInit(). The plug-in library must make a copy of it.
 
 
The implementation of the following functions is optional.

void PBNExit(PBNEnv env, PBNSession clone_id)

PBNExit() This function, if it exists, will be called just before the plug-in is closed. The session id passed to this function is the ID of the clone session.
 
 

PBNError PBNOpenSession(PBNEnv env, PBNSession sid)

PBNOpenSession() This function, if it exists, is called when a new session is opened. The plug-in code should call the ExecString() function at this time with any initialization code for the session including declarations for the plug-in functions. The session id number is passed in for use by the library to keep track of it's session specific data if any.
 
 

void PBNCloseSession(PBNEnv env, PBNSession sid)

PBNCloseSession() This function, if it exists, is called when a session is about to be closed.
 
 

4. PrimeBase Open Server (PBOS) plug-in API

The PrimeBase Open Server allows the PrimeBase Application Server or other applications using the PrimeBase Virtual Machine to connect to alternate data sources via PrimeBase Open Server plug-ins loaded by the PrimeBase Open Server. For example the Oracle plug-in enables you to access an Oracle database, or by loading the ODBC plug-in you will be able to access data servers via their ODBC drivers.

Developers can use the PBOS SDK to write their own PBOS plug-ins. The PBOS plug-in interface has been designed for accessing traditional DBMSes but the developer is not limited to this functionality. For example a PBOS plug-in could access files in a file system such as the 'file server' PBOS plug-in supplied as an example in the SDK.

Anyone planning to write a PBOS plug-in should study the 2 example PBOS plug-in supplied with the SDK. The way that the PBOS works is that it sends the SQL statements to the plug-in as a token list. The plug-in then converts the token list back into a string with the correct SQL syntax for the target DBMS. It is up to the plug-in how much of the syntax to support. If the plug-in will be used transparently as an alternat DBMS to the PrimeBase Data Server then the plug-in implementation should support as much of the syntax as possible. If the plug-in is a special purpose plug-in such as the 'file server' plug-in where the application is aware of the plug-in's limitations, then the plug-in only needs to impliment as much functionality as is required to support the calls that will be made to it.
 
 

General PrimeBase Open Server functions

 

PBOSStatus PBOSInit(void)

This function is called to initialize the PBOS plug-in. It is called before any other call is made to the PBOS plug-in. Once called successfully it will not be called again until after a call to PBOSDeinit() has been made.
 
 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

void PBOSDeinit(void)

This function is called to deinitialize the PBOS plug-in. It is called after a successful call to PBOSInit() has been made. Once called no other call will be made to the PBOS plug-inuntil a successful call to PBOSInit() has been made.
 
 

void PBOSInfo(char *dbms, Word4 size, Word4 *version)

This function returns the dbms brand and version number. This information will be made available to connected clients through the "describe open dbms" command. The dbms brand should be a C string no more than 32 characters long. For example the Oracle plug-in would return "Oracle" as its dbms brand.
 
 
 
Parameter Description
dbms A buffer into which dbms brand is to be written.
size The size of the buffer in bytes.
version The version of the dbms brand.

 

PBOSStatus PBOSError(PBOSCon con, PBOSStmt stmt, Int2 *errno, char *buffer, Word4 size)

This function will be called after a call has returned PBOS_ERROR. The error information must remain available to be retrieved by PBOSError() until after PBOSError() has been called for the connection or statement involved or another PBOS driver api call has been made on the same connection or statement. If 'stmt' != PBOS_BADSTMT then any error related to the statement is returned. If 'stmt' = PBOS_BADSTMT and 'con' != PBOS_BADCON then any error related to the connection is returned. If 'stmt' = PBOS_BADSTMT and 'con' = PBOS_BADCON then non connection specific error information is returned.

Error messages relating to statements must remain available until either PBOSError() has been called for statement or another PBOSI plug-in API all has been made using the statement.

Error messages relating to connections must remain available until either PBOSError() has been called for connections or an other PBOSI plug-in API call has been made using the connections.

Non connection and statements specific error messages must remain available until after PBOSError() or any other PBOSI plug-in API call has been made.
 
 
 
Parameter Description
con The connection handle of the connection that the error data is to be returned.
stmt The statement handle of the statement that the error data is to be returned.
errno A pointer to a location into which an error number can be written.
buffer A buffer into which any error message can be written. This can be a NULL pointer if the caller is not interested in the error message.
size The size of the buffer in bytes.

 
 
Return Value Description
PBOSI_OK Execution completed successfully.
PBOSI_NODATA Execution completed successfully but there is no error data to be returned.

 

PBOSStatus PBOSConnect(PBOSCon *con, char *user, char *passwd, char *options)

This function establishes a connection to the DBMS. The connection handle will then be used to refer to this connection in subsequent calls to the PBOS plug-in. How the last 3 parameters are used is PBOS plug-in specific. The content of the 'options' parameter could be connection settings or a complete connection definition.
 
 
 
Parameter Description
con A pointer to a connection handle. After a successful call to PBOSConnect() 'con' is set to a value which will be passed in to PBOS plug-in api calls requiring a connection handle. If PBOSConnect() fails then 'con' is set to PBOS_BADCON and PBOS_ERROR is returned.
user A Null terminated string containing the user name to connect as.
passwd A Null terminated string containing the users password.
options A Null terminated string containing PBOS plug-in specific options. The format and content of this string are driver specific.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

void PBOSDiconnect(PBOSCon con)

Disconnect the connection and free all related resources.
 
 
 
Parameter Description
con A connection handle returned from a successful call to PBOSConnect().

 

Statement level API functions

 

PBOSStatus PBOSAllocStmt(PBOSCon con, PBOSStmt *stmt)

Allocate a stmt handle to be used with PBOS plug-in functions. A new stmt handle will be allocated for each statement executed.
 
 
 
Parameter Description
con A connection handle returned from a successful call to PBOSConnect().
stmt A pointer to the location to receive the allocated stmt handle.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

void PBOSFreeStmt(PBOSStmt stmt)

Free all resources related to the stmt handle. Any process associated with the stmt handle is to be stopped.
 
 
 
Parameter Description
stmt A statementt handle to be freed.

 

PBOSStatus PBOSExec(PBOSStmt stmt, PBTokenPtr tokens, Word4 timeout)

This function executes a command passed in in the form of a token list. The dbms gateway guarentees that the dbms driver will only receive token lists for the following statements: Select, Update, Insert, Delete, Open Table, and Execute.

The execute command contains a string to be executed by the dbms. The format and content of the string are dbms specific. The execution of an execute statement returns no results only a PBOS_OK or PBOS_ERROR result.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
tokens The command to be executed given as a token list. The PBOS plug-in can use the utility functions supplied in the dbmsutils library to read the tokens and translate them into a DBMS specific format for execution.
timeout The time allowed for execution before returning PBOS_EXECUTING. The value of 'timeout' is given in hundredths of seconds. A value of zero indicates that the call should wait for completion.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_EXECUTING The function timedout before it could complete. The caller can call PBOSPoll() to wait for completion. Until PBOSPoll() returns a value other than PBOS_EXECUTING the token list will remain valid.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

void PBOSCancel(PBOSStmt stmt)

Cancel an executing statement.
 
 
 
Parameter Description
stmt A statement handle of the statement to be canceled.

 

PBOSStatus PBOSRowsEffected(PBOSStmt stmt, Word4 *rows)

This function returns the rows effected by the execution of any commands containing an "INSERT", "UPDATE", or "DELETE" command.
 
 
 
Parameter Description
stmt A statement handle of the statement to be canceled.
rows A pointer to a location into which the number of rows effected by the last command executed is to be placed. If the last command failed or rows effected does not apply to the command executed, then 'rows' should remain untouched and the function should return PBOS_NODATA.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().
PBOS_NODATA Rows effected[???] does not apply to the last command executed.

 

PBOSStatus PBOSNumCursors(PBOSStmt stmt, Word4 *cursors)

This function returns the number of cursors generated by the last command executed. Although in the future statements generating multiple cursors may be handle, as of this version statements are assumed to generate either 1 or 0 cursors.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
cursors A pointer to a location into which the number of cursors generated by the last command executed is to be placed. If the last command failed or no cursors were generated, then 'cursors' is set to zero and the function returns PBOS_OK.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSSetCursor(PBOSStmt stmt, Word4 cursor_num, char *name, Bool readonly)

This function sets the cursor to be assumed in API calls that use a cursor. The name of the cursor, if any, is returned in the "name" buffer.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
cursor_num The cursor being referred to. Cursors are numbered starting at 1 and going up to the value returned by PBOSNumCursors().
name A buffer in which the name of the cursor just set is returned. The size of the name buffer can be assumed to be atleast NAME_SIZE bytes in length.
readonly A flag indicating if the cursor is read only.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSNumColumns(PBOSStmt stmt, Word4 *columns)

This function returns the number of columns in the cursor reffered to by cursor_num.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
columns A pointer to a location into which the number of columns in the cursor is to be returned.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSNumRows(PBOSStmt stmt, Word4 *rows)

This function returns the number of rows in a cursor.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
rows A pointer to a location into which the number of rows in the result set is to be returned. If this can not be determined then PBOS_NODATA is returned.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().
PBOS_NODATA The number of rows in the cursor is unknown.

 

PBOSStatus PBOSColumnInfo(PBOSStmt stmt, Word4 col, PBOSColInfo *info)

This function gets the column information for a particular column in a particular cursor. The data type information for the PBT data types as described in the PrimeBase Talk Reference Manual.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
col The column in the cursor being referred to. Columns are numbered starting at 1 and going up to the value returned by PBOSNumColumns().
info A pointer to a column info structure in which the column name and column type information are to be returned. The data type information returned is the PBT type equivalent of the DBMS data type in the result set. The PBOS plug-in is responsible for the conversion between PBT and native DBMS data types.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSBindColumn(PBOSStmt stmt, Word4 col, void *storage, Word4 size, Word4 *info)

This function binds a storage location to a column in a cursor into which the data returned by a subsequent call to PBOSFetch() for the cursor is to be written. The bind remains in effect until a call to PBOSFreeResults() is called for the cursor or PBOSBindColumn() is called for the same cursor and column. The PBOS plug-in can assume that all columns in a cursor will be bound before PBOSFetch() is called.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
col The column in the cursor being referred to. Columns are numbered starting at 1 and going up to the value returned by PBOSNumColumns().
storage A pointer to a buffer into which the data fetched by the next call to PBOSFetch() for the result set referred to by 'cursor_num' and column 'cal' is to be placed 

OR

In the case of blob data, 'storage' will be a blob_id into which the blob data is to be written.

size The size in bytes of the buffer pointed to by storage. If the data type for result set 'cursor_num' and column number 'col' is of a fixed length then the PBOS plug-in can assume that the buffer pointed to by 'storage' is of the required size and the value of 'size' can be ignored. 

The PrimeBase Open Server will supply a buffer large enough for the maximum data length for the column as described by PBOSColumnInfo(). As a result the PrimeBase Open Server will always assume that the data fetched was not truncated. If the data fetched is greater then the value of size, the PBOS plug-in should report it as an error.

info A pointer to a buffer into which the PBOS plug-in, after the call to PBOSFetch(), places the actual size of the data fetched or the value PBOS_NULL_DATA if NULL data was fetched. For fixed length data the value of 'info' is ignored unless it is PBOS_NULL_DATA. For variable length data the value of 'info' can be used to indicate if the data was truncated or not by comparing it to the value of 'size' after the call to PBOSFetch().

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSFetch(PBOSStmt stmt, Word4 timeout)

This function fetches date from a cursor into the bound columns. Each call to this function must return the next row in the cursor until there are no more rows left, at which point it returns PBOS_NODATA.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
timeout The time allowed for execution before returning PBOS_EXECUTING. The value of 'timeout' is given in hundredths of seconds. A value of zero indicates that the call should wait for completion.

 
 
Return Value Description
PBOS_OK Execution completed successfully. All bound columns contain valid data.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().
PBOS_EXECUTING The function timedout before it could complete. The caller can call PBOSPoll() to wait for completion. Until PBOSPoll() returns a value other than PBOS_EXECUTING the values of bound columns is undefined.
PBOS_NODATA Execution completed successfully but the current row was out side of the result set.

 

PBOSStatus PBOSPoll(PBOSStmt stmt, Word4 timeout)

This function polls the PBOS plug-in for completion of a timed out call. The return values from PBOSPoll() are to be interpreted as if they were the return values from the function that originally timed out.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
timeout The time allowed for execution before returning PBOS_EXECUTING. The value of 'timeout' is given in hundredths of seconds. A value of zero indicates that the call should wait for completion.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().
PBOS_EXECUTING The function timedout before it could complete.
PBOS_NODATA Execution completed successfully but no data was returned. The meaning of this is dependent on what call was being polled for completion.

 

PBOSStatus PBOSDescribeDatabases(PBOSStmt stmt, Word4 timeout)

The support of this function by the dbms driver is optional. If supported this function must create a cursor containing the names of databases available on the dbms that can be opened with a call to PBOSOpenDatabase(). The cursor must be of the following format:
 
Column Name Type Length Scale Description
1 "name" A_VCHAR 31 n/a Database name

Columns beyond column 1 if they exist are dbms driver specific. (n/a = Not applicable)
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
timeout The time allowed for execution before returning PBOS_EXECUTING. The value of 'timeout' is given in hundredths of seconds. A value of zero indicates that the call should wait for completion.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_NOT_SUPPORTED This function is not supported by the dbms driver.
PBOS_EXECUTING The function timedout before it could complete. The caller can call PBOSPoll() to wait for completion. Until PBOSPoll() returns a value other than PBOS_EXECUTING the token list will remain valid.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSDescribeTables(PBOSStmt stmt, Word4 timeout)

The support of this function by the dbms driver is optional. If supported this function must create a cursor containing one row for each tables in the current default database as set by PBOSUseDatabase(). The cursor must be of the following format:

[???]
Column Name type length scale Description
-------------------------------------------------------------------------------------------
1 "name" A_VCHAR 31 na Table name.
2 "type" A_VCHAR 1 na Either 'T' for table or 'V' for view.
3 "ordered" A_BOOLEAN na na $true if the table is ordered.
4 "colcnt" A_SMINT na na Number of simple (non-composite) columns.
5 "rowcnt" A_INT na na Number of rows ($null if unknown) (1).
6 "parentcnt" A_SMINT na na Parent count (2).
7 "childcnt" A_SMINT na na Child count (2).
8 "title" A_VCHAR 31 na The title of the table.
9 "remarks" A_VCHAR 255 na Comment about the table .
10 "owner" A_VCHAR 255 na The table owner (in PrimeBase, the creator name).

Columns beyond column 10 if they exist are dbms driver specific.

The dbms driver must fill in columns 1,2 and 4. If the owner table qualifier is applicable to the
dbms then column 10 should also be filled in. The dbms driver can return $null in all other columns.

(na = Not applicable)
(1) PrimeBase always returns $null here in order to avoid accessing the database.
(2) Parent & child counts are part of a DAL feature are not supported by PrimeBase.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
timeout The time allowed for execution before returning PBOS_EXECUTING. The value of 'timeout' is given in hundredths of seconds. A value of zero indicates that the call should wait for completion.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_NOT_SUPPORTED This function is not supported by the PBOS plug-in.
PBOS_EXECUTING The function timedout before it could complete. The caller can call PBOSPoll() to wait for completion. Until PBOSPoll() returns a value other than PBOS_EXECUTING the token list will remain valid.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSDescribeColumns(PBOSStmt stmt, char *table, Word4 timeout)

The support of this function by the dbms driver is optional. If supported this function must create a cursor containing one row for each column in the table in the default database. The cursor must be of the following format:

[???]
Column Name type length scale Description
-------------------------------------------------------------------------------------------
1 "colnr" A_SMINT na na The column number (1).
2 "level" A_SMINT na na Columns level number (2).
3 "name" A_VCHAR 31 na The column name.
4 "type" A_SMINT na na The PBT type of the column.
5 "len" A_INT na na The maximum length of column values.
6 "places" A_SMINT na na Columns decimal places (scale), for DECIMAL types only.
7 "nullsok" A_BOOLEAN na na $true if null values are allowed on the column.
8 "groupcol" A_BOOLEAN na na Group column (2).
9 "parentnr" A_SMINT na na Parent column number (2).
10 "occurs" A_SMINT na na Parent column number (2).
11 "occdep" A_SMINT na na Occurs depending in column (2).
12 "updtok" A_BOOLEAN 255 na $true if column can be updated.
13 "title" A_VCHAR 31 na Column title.
14 "remarks" A_VCHAR 255 na Column remarks.
15 "primary" A_BOOLEAN na na $true if this column is part of the tables primary key. (3)

Columns beyond column 15 if they exist are dbms driver specific.

The dbms driver must fill in columns 1,3,4,5,6. If the owner table qualifier is applicable to the dbms then column 10 should also be filled in. The dbms driver can return $null in all other columns.

(na = Not applicable)

(1) Columns numbers begin always begin at 1. Columns are number in the order they are declared.

(2) Although PrimeBase supports composite columns, it does not support the hierarchical group columns specified by DAL. In PrimeBase, any particular simple column can be a member of any number of composite columns, as a result, the PrimeBase composite columns cannot be mapped to the DAL group column concept.

(3) This column is not part of the standard DAL "descripe columns" result set.
 
 
 
Parameter Description
stmt A statement handle returned from a successful call to PBOSAllocStmt().
table The name of the table whos columns are to be described.
timeout The time allowed for execution before returning PBOS_EXECUTING. The value of 'timeout' is given in hundredths of seconds. A value of zero indicates that the call should wait for completion.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_NOT_SUPPORTED This function is not supported by the PBOS plug-in.
PBOS_EXECUTING The function timedout before it could complete. The caller can call PBOSPoll() to wait for completion. Until PBOSPoll() returns a value other than PBOS_EXECUTING the token list will remain valid.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

Connection level API functions

 

PBOSStatus PBOSOpenDatabase(PBOSCon con, char *database, char *alias, char *user, char *passwd, Word4 *db_id)

This function is called to open a database. After a successful call to this function the Primebase Open Server will call PBOSUseDatabase() with the database id returned to set the default database to the database just opened.
 
 
 
Parameter Description
con A connection handle returned from a successful call to PBOSConnect().
database The name of the database to open.
alias The alias which the database may be refered to as. This paramater may be NULL.
user The user to access the database as. This paramater may be be NULL.
passwd The users password. This paramater may be be NULL.
db_id A pointer to a buffer in which the database id is to be returned. This id will be used in calls to PBOSUseDatabase() and PBOSCloseDatabase() to refer to the database just opened. Any value other than zero is a valid value for the database id. The database id of zero is used by PBOSCloseDatabase() to tell the PBOS plug-in to close all databases.

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PBOSStatus PBOSUseDatabase(PBOSCon con, Word4 db_id)

This function sets the default database to use if a statement refers to a table with out a database
qualifier.
 
 
 
Parameter Description
con A connection handle returned from a successful call to PBOSConnect().
db_id A database id returned from a successful call to PBOSOpenDatabase().

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

void PBOSCloseDatabase(PBOSCon con, Word4 db_id)

This function closes a database opened by a call to PBOSOpenDatabase(). If db_id is zero then the dbms driver is to close all databases. After closing the default database the dbms gateway will call PBOSUseDatabase() to set a new default database if any other databases are currently open.
 
 
 
Parameter Description
con A connection handle returned from a successful call to PBOSConnect().
db_id A database id returned from a successful call to PBOSOpenDatabase() or zero if the dbms driver is to close all open databases.

 

PBOSStatus PBOSTransaction(PBOSCon con, PBOSTransact action)

This function begins, commits, or rolls back a transaction. If a new transaction is begun while a transaction is currently running on the connection or a commit or roll back is received when there is no current transaction, then the behavour is dbms specific. If the dbms driver can handle nested transactions then it may do so, if not then it can either report an error or ignore the unexpected transaction command.

When there is no current transaction then all statements are to be treated as individual transactions in themselves.
 
 
 
Parameter Description
con A connection handle returned from a successful call to PBOSConnect().
action One of the following actions: 
  • PBOS_BEGIN

  • Begin a transaction.
     
  • PBOS_COMMIT

  • Commit the current transaction.
     
  • PBOS_ROLLBACK

  • Rollback the current transaction. 

 
 
Return Value Description
PBOS_OK Execution completed successfully.
PBOS_ERROR An error occurred. Details are available via a call to PBOSError().

 

PrimeBase Open Server callback functions

The following functions are all supplied to the plug-in as callback functions into the PrimeBase Open Server.
 

Logging functions

Protocol functions, depending on the logging levels set in the PrimeBase Open Server's environment file, will log to both the Open Server's console and the Open Server's log file.

Log functions, depending on the logging levels set in the Open Server's environment file, will log to the Open Server's log file only.

In both cases the format strings use the standard 'printf()' formats.
 
 

typedef enum {
        LOGPROT = 0, // Messages of this level are always logged.
        LOGERR,      // An error message.
        LOGWRN,      // A warrning.
        LOGTRACE,    // An informational message.
        DEBUGTRACE   // An informational message used for debugging.
} LogType;
 

char *PBGetNow(void)

GetNow() returns the current date and time as a string.

typedef char *(*PBGetNowFType)(void)

typedef void (*PBLogfFType)(LogType ltype, int display, char *fmt, void *args)
 
 

void PBLog(LogType ltype, char *fmt, ...)

 

void PBDisplay(LogType ltype, char *fmt, ...)

 

Token translation functions

 

PBTokenPtr PBNextToken(PBTokenPtr current_token)

Returns the next token from the token list.

typedef PBTokenPtr (*PBNextTokenFType)(PBTokenPtr current_token)
 
 

Word1 PBTokenNum(PBTokenPtr current_token)

Returns the token number of the current token.

typedef Word1 (*PBTokenNumFType)(PBTokenPtr current_token)
 
 

Word1 PBXTokenNum(PBTokenPtr current_token)

Returns the extended token number of the current token.
 
 

Bool PBTokenToString(PBTokenPtr current_token, char *buffer, Int4 *size)

This function returns true when the conversion has been done and sets size to the buffer spaced used. If the size required is more than the size passed in, size is set to the size required and the function returns false. This function will also fail if a conversion for the token has not been implemented in which case size is set to 0.

INPUT size includes the zero terminator.

OUTPUT size does NOT include the zero terminator.

typedef Bool (*PBTokenToStringFType)(PBTokenPtr current_token, char *buffer, Int4 *size)
 
 

void PBTokenNumToName(Word1 no, Word1 eno, char *name)

Convert a token number to a token name.
 
Parameter Description
no The token's number.
eno The token's extended number if no = T_EXTENDED.

 

typedef void (*PBTokenNumToNameFType)(Word1 no, Word1 eno, char *name)
 
 

void PBSetAsciiConversionFormats(char *decfmt, char *moneyfmt, char *datefmt, char *timefmt, char *timestampfmt)

Use this function to set the ASCII conversion formats to be used in TokenToString().

typedef void (*PBSetAsciiConversionFormatsFType)(char *decfmt, char *moneyfmt, char *datefmt, char *timefmt, char *timestampfmt)
 
 

void *PBGetValTokenData(PBTokenPtr current_token, Int1 *pbt_type, Word4 *len)

This function returns a pointer to the data associated with a value token. The PBT type is returned in 'pbt_type' and the length of the data is returned in 'len' measured in bytes.

typedef void *(*PBGetValTokenDataFType)(PBTokenPtr current_token, Int1 *pbt_type, Word4 *len)
 
 

Bool PBConvert(void *src_data, DataFmt *src_fmt, void *dst_data, DataFmt *dst_fmt, Word4 *dst_size)

The function PBConvert() converts PBT types.
 
Parameter Description
src_data Points to a buffer containing the source data to be converted.
src_fmt Points to a structure describing the source data type.
dst_data Points to a buffer into which the converted data is to be written.
dst_fmt Points to a structure describing the destination data type.
dst_size Points to a 4 byte value which contains the size of the buffer pointed to by dst_data. 

After the call returns this parameter will contain the actual length of the converted data. If the value returned in this paramater is greater then the value passed in then then data was truncated. C strings will always be null terminated even after truncation.


 

typedef Bool(*PBConvertFType)(void *src_data, DataFmt *src_fmt, void *dst_data, DataFmt *dst_fmt, Word4 *dst_size)

 

Word4 PBGetBlobInfo(void *data, Word4 *blob_id)

The function PBGetBlobInfo() gets the blob id and blob size from data pointer for a blob variable as returned from get_val_token_data(). PBGetBlobInfo() returns the size of the blob and sets *blob_id to the blobs id as used in the blob access functions. The actual blob must be read using the blob id and the blob access functions.

typedef Word4 (*PBGetBlobInfoFType)(void *data, Word4 *blob_id)
 
 

BLOB access functions

These functions are used to read and write the actual blob data associated with a blob id. The blobs when created have an expiry time but it is a good idea for the plug-in to free any blobs that are being sent to the DBMS after they have been read. Blobs coming from the DBMS will be freed by the Open Server when it has finished with them.
 
 

Word4 PBReadBlob(Word4 blob_id, Word4 offset, Word4 *len, void *buffer)

typedef Word4 (*PBReadBlobFType)(Word4 blob_id, Word4 offset, Word4 *len, void *buffer)
 
 

Word4 PBWriteBlob(Word4 blob_id, Word4 offset, Word4 len, void *buffer)

typedef Word4 (*PBWriteBlobFType)(Word4 blob_id, Word4 offset, Word4 len, void *buffer)
 
 

Word4 PBLinkBlob(Word4 blob_id, char *file_path)

typedef Word4 (*PBLinkBlobFType)(Word4 blob_id, char *file_path)
 
 

Word4 PBGetBlobSize(Word4 blob_id, Word4 *size)

typedef Word4 (*PBGetBlobSizeFType)(Word4 blob_id, Word4 *size)
 
 

Standard memory functions

The plug-in can use these memory functions to have it's memory allocated from the Open server's memory pool. The use of these functions is optional.
 
 

void *PBMalloc(Word4 size)

typedef void *(*PBMallocFType)(Word4 size)
 
 

void *PBRealloc(void *ptr, Word4 size)

typedef void *(*PBReallocFType)(void *ptr, Word4 size)
 
 

void PBFree(void *ptr)

typedef void (*PBFreeFType)(void *ptr)
 
 

void PBMemCheck(void)

This function is used to check for memory overwrites and bad pointers. This is only meant for debug purposes and requires a specially linked Open Server from SNAP to have any effect. Otherwise it does nothing.

typedef void (*PBMemCheckFType)(void)

void DLLENTRY InitPrimeBasePlugin(PBCallbacks *rec)

 

struct PBCallbacks_tag

typedef struct PBCallbacks_tag{
        PBGetNowFType PBGetNow;
        PBLogfFType PBLogf;

        PBNextTokenFType PBNextToken;
        PBTokenNumFType PBTokenNum;
        PBTokenNumFType PBXTokenNum;
        PBTokenToStringFType PBTokenToString;
        PBTokenNumToNameFType PBTokenNumToName;
        PBSetAsciiConversionFormatsFType PBSetAsciiConversionFormats;
        PBGetValTokenDataFType PBGetValTokenData;
        PBConvertFType PBConvert;
        PBGetBlobInfoFType PBGetBlobInfo;

        PBReadBlobFType PBReadBlob;
        PBWriteBlobFType PBWriteBlob;
        PBLinkBlobFType PBLinkBlob;
        PBGetBlobSizeFType PBGetBlobSize;

        PBMallocFType PBMalloc;
        PBReallocFType PBRealloc;
        PBFreeFType PBFree;
        PBMemCheckFType PBMemCheck;
} PBCallbacks;



5. Java Database Connectivity (JDBC)

You will find additional, user-relevant information in the documentation accompanying the PrimeBase JDBC driver.
 
 

Loading the PrimeBase JDBC Driver

Both versions of the PrimeBase JDBC driver are located in this package:
 com.primebase.jdbc
In order to make the driver currently located in the "com/primebase/jdbc" directory or the JAR file accessible, use something similar to the following in your application:
try
{
    Class.forName("com.primebase.jdbc.jDALDriver");
}
catch (Exception e)
{
    // Add some more thorough exception handling perhaps.
    e.printStackTrace();
}
The PrimeBase JDBC package directory or a JAR file containing this directory has to be accessible by Java according to the usual Java setup and configuration mechanisms.

That is...

SQLExceptions thrown by PrimeBase JDBC

Since the PrimeBase SQL Database Server returns more than a single error code, SQLExceptions may be chained to each other to return each error code separately.

Up to three SQLExceptions might be chained to each other in PrimeBase JDBC.

Use the SQLException.getNextException() method to retrieve further SQLExceptions in case you want to evaluate the PrimeBase SQL Database Server specific errors that might occur.

There are two different occasions where SQLExceptions can be thrown:

1.) When the PrimeBase client library or the PrimeBase SQL Database Server signal any errors

2.) When PrimeBase JDBC encounters any errors (I/O errors, network related errors, invalid parameters specified, etc.)

When SQLExceptions result from 1)... When SQLExceptions result from 2)...
 

Compiling the PrimeBase JDBC Driver

In order to compile the source of the PrimeBase JDBC driver yourself, use the version of the driver that corresponds with your JDK or JAVA tools.

The JDK 1.1.x version of the driver is available in the directory "JDBC 1.x".

The JDK 1.2+ version of the driver is available in the directory "JDBC 2.x".

To compile either of the sources, issue one of the following commands (or something comparable - depending on your platform and tools) on the commandline while being in the parent of the "com" directory.

Windows, JDK 1.1.x:

 javac -depend com\primebase\jdbc\jDALDriver.java
Windows, JDK 1.2.x
 javac com\primebase\jdbc\*.java
Unix, JDK 1.1.x:
 javac -depend com/primebase/jdbc/jDALDriver.java
Unix, JDK 1.2.x:
 javac com/primebase/jdbc/*.java

6. Open Database Connectivity (ODBC)

You will find additional, user-relevant information in the documentation accompanying the PrimeBase ODBC driver. To view this information choose to create or change an existing PrimeBase ODBC data source and press the "Help" button in the connection setup dialog.
.

ODBC compliance

The PrimeBase ODBC driver conforms to the ODBC 2.1 specifications with a level 1 API and Core level SQL grammar.

In addition to the level 1 functions the following level 2 API functions have been implemented :

 

Data types

The PrimeBase ODBC driver supports the Minimum and Core SQL data types as well as the following Extended SQL data types:

User Privileges

Normally users do not need any special privileges for system tables. But when accessing the database via ODBC the ODBC driver needs to perform selects from the system tables to supply the catalog information required by ODBC. As a result all database users that will be accessing the database via ODBC must be given select privileges on system tables. There is nothing in the system tables that a user should be prevented from seeing. Passwords stored in the system tables are encrypted. Here is a list of the system tables that the user needs to have access to when connecting.

Connection String Attributes

Connection string keyword/attribute pairs:
 
 
 
Keyword Description
UID Required. The name of the user to use for making the connection.
PWD The user's password.
DATABASE Required. The name of the primebase database to be opened.
SERVER Required for non-runtime connections. The name that the PrimeBase SQL Database Server is published under, for example "PrimeServer".
PROTOCOL Required. The communication protocol to use. Possible values are: "TCP", "IPC" (Unix and Windows only.), "ADSP" (Mac only.), "PPC" (Program linking, Mac only.), "MEM" (Runtime Connection).
PROT_OPTS Required for ADSP and TCP, for all other protocols this value is ignored. Protocol specific options, for TCP this is the IP address, For ADSP this is the Apple zone.
DATABASEROOT Required for MEM protocol, for all other protocols this value is ignored. The data server's root directory used for a runtime connection.
OPT_DISABLE_ASYNC Optional setting. Disables the use of asynchronous mode by the client. Possible settings: "YES", "NO". Default: "NO".
OPT_STRICT_CONFORMANCE Optional setting. When this option is set to "YES" the ODBC driver will generate an error whenever it encounters an unsupported ODBC feature. Possible settings: "YES", "NO". Default: "NO".
OPT_APILOG Optional setting. The name and path of the log into which the logging is to be written. If the file doesn't exist it will be created. API logging will be activated if a value is specified for this key.

 

Example settings:

PROTOCOL=TCP
PROT_OPTS=212.1.32.198
DATABASE=odbc_test
SERVER=PrimeServer
OPT_DISABLE_ASYNC=NO

7. Enterprise Objects Framework (EOF)

The PrimeBase Enterprise Objects Framework Adaptor complies with version 2.2 of the EOF framework.