1. PrimeBase Interface (PBI)Function overviewSession control functions
PrimeBase Interface API functions2. CL / PrimeBase Item Stream Interface (PBISI)
Function overviewSession-control functionsReturn valuesInteger values for return codesAPI functionsCLBreak()
CLConInfo()
CLExec()
CLGetErr()
CLGetItem()
CLGetSn()
CLInit()
CLSend()
CLSendItem()
CLState()
CLUnGetItem()3. PrimeBase Native (PBN) plug-in API
DefinesCallback functions supplied by the PrimeBase software
PBNFunc()Functions supplied by the plug-in
PBNGetInfo()
PBNGetParamVal()
PBNGetReturnBuf()
PBNReturnNull()
PBNExecString()
PBNRaiseError()
PBNReadBlob()
PBNWriteBlob()
PBNVersion()
PBNInit()
Optional functions.
PBNExit()
PBNOpenSession()
PBNCloseSession()4. PrimeBase Open Server (PBOS) plug-in API
General PrimeBase Open Server functionsConnection level API functions
PrimeBase Open Server callback functions
Logging functions5. Java Database Connectivity (JDBC)
6. Open Database Connectivity (ODBC)
ODBC compliance7. Enterprise Objects Framework (EOF)
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:
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.
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.
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.
Function Description PBIGetValue() Gets the value of a variable from a PBT program. PBIPutValue() Assigns a value to a variable of a PBT program.
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.
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.
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.
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.
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.
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.
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'.
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.";
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.
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().
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.
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.
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.
This function cancels all asynchronous tasks for the session.
Parameter Description session_id The session id returned by PBIConnect().
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); }
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);
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.
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.
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.
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);
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: 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.
- 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.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);
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.
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.
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.
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);
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);
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); }
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
- PBIExecute()
- PBIFetchRow()
- PBIGetBlobData()
- PBISetCursorPosition()
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.
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.
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.
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.
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.
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:
- Begin and end communication with a PrimeBase server.
- Send fragments of PBT programs to the runtime environment.
- Request execution of a program fragment.
- Determine the status of execution of a PBT program.
- Retrieve data passed back from a PBT program.
- Determine the type of data passed back from the PBT program.
- Force a break or abnormal termination of the PBT program.
- Collect details of any error that occurs during the execution of a PBT program.
The API functions described in this section may be divided into the following function groups:
- Session-control functions
- Program-execution functions
- Results-processing functions
Function Description CLInit() Begins a PBT session CLEnd() Ends a PBT session CLConInfo() Describes a PBT session CLGetSn() Returns the session number
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
Function Description CLGetItem() Describes and/or retrieves the next data item CLUnGetItem() Unretrieves the previous data item
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:
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.
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
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.
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:
All data is converted by this statement to VARCHAR strings; NULL values are represented by the string "$NULL".PRINTCTL 0;
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.
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.
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.
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.