Table Of Contents

PrimeBase Plug-in Classes

 PBDatabase
 PBDatabaseCursor
 PrimeBaseRowSet
 PrimeBaseStmt
 PrimeBaseBlob
 PrimeBaseDSN

PrimeBase Plug-in Functions

 PrimeBaseDebugMode
 PrimeBaseInfo

Default Settings

---

The PrimeBase Plug-in Classes

PBDatabaseClass
 
 

Used to open a PrimeBase database connection.This is an extension of the REALbasic database class with custom PrimeBaseproperties, methods, and events added.

Super Class

Database

Properties
 

Name	Type	Description
ConnectionInfo	String	Protocol specificconnection information."TCP": The network address of thecomputer on which the PrimeBase database server is running, 192.168.1.220for example.  "MEM": ConnectionInfo property is ignored. "ADSP": The apple zone in which thePrimeBase database server is running. If not supplied the current zoneis assumed. "RT": The full path to the PrimeBase"databases" folder not including the "databases" folder itself. If notsupplied the "databases" folder will be assumed to be in the applicationscurrent working directory. See the documentation on setting up a runtimeconnection for more details.
ClientVersion	Integer	The versionnumber of the PrimeBase VM or RunTime library that has been loaded. (Version4.2.15 returns 4215).
Protocol	String	The communicationprotocol to use. One of the following:"TCP" : Use tcp to communicate withthe PrimeBase server. This protocol can be used for connecting to any PrimeBaseserver running remotely or locally. "MEM": Use shared memory to communicatewith the PrimeBase server. Use this to communicate with a server runningon the same computer as the application. "ADSP": Apple Data Stream Protocol.Use this to communicate with a PrimeBase server running on a computer supportingADSP. The client computer must also support ADSP. "RT": Make a "RunTime" connection.This protocol accesses the PrimeBase databases directly with out connectingto a separately running database server. To use this protocol the PrimeBase"Databases" folder must be located locally on the same computer as theapplication and not be in use by another application or database server.
RowsAffected	Integer	The numberof rows effected by the last operation. This only has meaning for "update"and "delete" SQL commands.
Server	String	The PrimeBasedatabase server name. "PrimeServer" for example. This property is ignoredwhen making a "RunTime" connection.
ServerVersion	Integer	The versionnumber of the PrimeBase database server connected to. (Version 4.2.15 returns4215).
Yield	Boolean	When set to"true" calls made to the PrimeBase database server or "RunTime" serverwill be made in non-blocking mode and time will be yielded back to theapplication. This involves polling the connection for completion and mayresult in poorer performance. Normally the need for this option can beavoided by using REALbasic threads, but applications running on Mac OSClassic my still want to use this setting in some cases.

Methods:

The following methods are providedin addition to those provided by the REALbasic Database class.
 

Name	Parameters	Description
ConnectDSN	dsn As PrimeBaseDSN user As String,  passwd As String	Open a connection to a PrimeBase data source using theinformation stored in the PrimeBaseDSN object. Returns a boolean value to indicate success or failure.
BeginTansaction		Signals thestart of a transaction. The transaction is ended by the "Commit" or "Rolllback"methods. If an error occurs on the connection the transaction is automaticallyrolled back.
Cancel		Cancel a commandcurrently being executed on this connection.
Disconnect		Disconnectsthe connection to the PrimeBase server with out freeing any other resources.
NewBlob		Returns a PrimeBaseBlobobject associated with this database connection.
NewCursor		Returns a PrimeBaseRowSetobject associated with this database connection.
PrepareStatement	Statement asString	Prepares astatement for execution and returns a PrimeBaseStmt object associated withthis database connection. The statement can contain parameter markers indicatedby '?'s in the statement. The statement can be a single SQL statement oran entire PBT program.
ProcedureCall	Call as String	Executes acall to a user declared PrimeBase PBT procedure that returns a cursor andreturns an object of type PBDatabaseCursor which refers to an read onlycursor returned by the procedure.
SQLExecuteReturning	Statement asString	Executes astatement which may or may not create a cursor, if it doesn't then nilis returned otherwise it returns an object of type PBDatabaseCursor whichrefers to a read only cursor.
SQLSelectRO	SelectStringas String	Similar tothe standard SqlSelect method but returns an object of type PBDatabaseCursorthat refers to an read only cursor.
SQLSelectRW	SelectStringas String	Similar tothe standard SqlSelect method but returns an object of type PBDatabaseCursorthat refers to an update able cursor. For the cursor to be update ablethe select must be from a single table.

 

Events:

The PBDatabase class provides the event:PrimeBaseOutput(output As String).

This event returns items output bythe PrimeBase Talk (PBT) print commands. For example the following command:

Print "Hello", "REALbasic";

Would result in 2 events, one returning"Hello" and one returning " REALbasic", since "REALbasic" was the lastitem in the row being printed it would also contain a CRLF character.

The following:

Select * from foo into bar;

Printall bar;

Will result in the PrimeBaseOutputevent being called ounce per column, times the number of rows in the resultset. The item printed for the last column in each row will have a CRLFadded to it.
 
 

To access the PrimeBaseOutput eventin REALbasic you must first create a new class with PBDatabase as its superand then drag that class into your REALbasic project.
 
 

PBDatabaseCursorClass
 
 

This is an extension of the REALbasicRecordSet class with custom PrimeBase methods added. This class shouldbe used if you want to use the custom methods that it supplies but stillwant to access the data using the standard REALbasic RecordSet class methods.Use the PrimeBaseRowSet class if you want the PrimeBase plug-in to controlthe data access.

Unless you need to use the REALbasicRecordSet methods it is recommended that you use the PrimeBaseRowSet Class.The PBDatabaseCursor class is maintained mostly for backward compatibilitywith Version 1 of the PrimeBase plug-in.

Super Class

RecordSet

Methods:

The following methods are providedin addition to those provided by the REALbasic RecordSet class. In allmethods that require a column as a parameter, the column is specified byits position; the first column is in position 1. (NOTE: This is a changefrom version 1 of the PrimeBase plug-in and has been done to conform tothe conventions used by standard REALbasic methods.)
 

Name	Parameters	Description
ColumnName	Column as Integer	Returns a columnname of a specific column.
ColumnScale	Column as Integer	Returns thescale of the data in the column if it is a decimal data type.
ColumnSize	Column as Integer	Returns thelength of the data in the column. For example a column of type varchar(11)would have a size of 11.
ColumnType	Column as Integer	Returns thecolumn type of the specific column. Refer to the "PrimeBase SQL ReferenceManual" for a description of the PrimeBase data types and their numericvalues.
NumRows		Returns thenumber of rows in the cursor. The value returned by this method may notbe accurate for cursors that were not selected with SQLSelectRO()or via a call to PrimeBaseProcedure() returning a cursor that hasbeen selected for extract.

 

PrimeBaseRowSetClass
 
 

Used to access data in a PBT cursor.Calling the NewCursor method in an instance of a PBDatabase, PrimeBaseStmt,or PrimeBaseRowSet class creates an instance of a PrimeBaseRowSet. Beforean instance of a PrimeBaseRowSet can be used it must be associated withan already existing PBT cursor. This is done by using the SetCursorNamemethodand passing in an optional cursor name. If no cursor name is supplied thenthe instance will be associated with the default PBT cursor.

An effort has been made to make thePrimeBaseRowSet class as compatible as possible with the REALbasic RecordSetclass.

Super Class

Object

Properties
 

Name	Type	Description
BOF	Boolean	Beginning ofthe cursor.
EOF	Boolean	End of thecursor.
Error	Boolean	True if thelast method called resulted in an error.
ErrorCode	Integer	The error code returned from thelast method called.
ErrorMessage	String	The text ofthe error message returned from the last method called.
FieldCount	Integer	Number of fieldsin the cursor.
Name	String	The name ofthe PBT cursor associated with this instance.
Position	Integer	The positionof the cursor in the row set. The first row is at position 1.
Rows	Integer	Number of rowsin the cursor. This value may not be accurate for cursors that were notselected for extract. By default all cursors are selected for extract.
Yield	Boolean	When set to"true" calls made to the PrimeBase database server or "RunTime" serverwill be made in non blocking mode and time will be yielded back to theapplication. This involves polling the connection for completion and mayresult in poorer performance. Normally the need for this option can beavoided by using REALbasic threads, but applications running on Mac OSClassic my still want to use this setting in some cases.

Methods:

Some methods such as Bindcolumnaccept parameters of different types. When this is the case the allowedtypes will be given as a comma delimited list inside of round brackets.Where a parameter is optional it will be given in square brackets.

In all methods that require a columnor row as a parameter, the column or row is specified by its position;the first column or row is in position 1.
 

Name	Parameters	Description
Bindcolumn	Column as Integer byRef Buffer as (Integer, Single, Double,Boolean, String , MemoryBlock , PrimeBaseBlob)	Binds a columnin the cursor to a REALbasic variable. Bound variables will receive thosevalues of the column to which they are bound after any call to Move,MoveFirst, MoveLast, MovePrevious, and MoveNext. Bound columns work in both directions. If the update or insertmethods are called then the current values of the bound variables willbe used for the update or insert. The only exception is thatif the SetValue method has been called then the value set will takeprecedence over the value in the bound column.  The bind remains in effect until UnbindColumnis called.
Cancel		Cancel a commandcurrently being executed on this connection.
ColumnName	Column as Integer	Returns thecolumn name.
ColumnScale	Column as Integer	Returns thescale of the data in the column if it is a decimal data type.
ColumnSize	Column as Integer	Returns thelength of the data in the column. For example a column of type varchar(11)would have a size of 11.
ColumnType	Column as Integer	Returns thecolumn type of the specific column. Refer to the "PrimeBase SQL ReferenceManual" for a description of the PrimeBase data types and their numericvalues or use the ColumnTypeName method.
ColumnTypeName	Column as Integer	Returns thecolumn type name. "Varchar(21)" or "Longbin" for example.
CursorFree		Frees resourcesheld by the cursor. PrimeBaseRowSet instance is then returned to its statebefore SetCursorName was called.
DeleteRecord		Deletes thecurrent row from the table.  This method is only valid on cursorsbased on a select from a single table.
Edit		Does nothing.Included for compatibility with the REALbasic RecordSet class.
GetBlob	Column as Integer [ byRef Status as Boolean ]	See GetInteger. Returns a PrimeBaseBlob object.
GetBoolean	Column as Integer [ byRef Status as Boolean ]	See GetInteger.  Returns a Boolean.
GetDouble	Column as Integer [ byRef Status as Boolean ]	See GetInteger.  Returns a Double.
GetInteger	Column as Integer [ byRef Status as Boolean ]	Returns thevalue from the specified column as an Integer.  If the 'status' parameter is suppliedit will be set to true if a value was returned. If status is false andthe Error property is false then the column contained a NULL.
GetMem	Column as Integer [ byRef Status as Boolean ]	See GetInteger. Returns a MemoryBlock.
GetSingle	Column as Integer [ byRef Status as Boolean ]	See GetInteger.  Returns a Single.
GetString	Column as Integer [ byRef Status as Boolean ]	See GetInteger. Returns a String.
Insert	Table as String	Insert thecurrent row into the table using the values passed in by the SetValuemethod.Ifa column was bound but not set then the current value of the bound variablewill be used for updating.
Move	Row as Integer	Positions thecursor to the position passed in in the 'row' parameter and fetches therow.
MoveFirst		Positions thecursor to the first row of data and fetches the row.
MoveLast		Positions thecursor to the Last row of data and fetches the row.
MoveNext		Positions thecursor to the next row of data and fetches the row.
MovePrevious		Positions thecursor to the previous row of data and fetches the row.
NewCursor		Returns a newinstance of a PrimeBaseRowSet object associated with the same databaseconnection as this one.
SetCursorName	[ Name as String]	Associate thecursor with a PBT cursor.
SetNull	Column as Integer	Same as SetValuebut sets the column's value to NULL.
SetRow	Row as Integer	Positions thecurrent row in side of the cursor. This method just changes the positionof the current row, no data is fetched and values set by the SetValueandSetNull methods remain in effect
SetValue	Columnas Integer Buffer as (Integer, Single, Double,Boolean, String , MemoryBlock , PrimeBaseBlob)	Setsthe value of the specified column in the current row to the value passedin. This value will then be used when the Insert or Updatemethods are called. The values set by the SetValue andSetNull methods remain in effect until a new row is fetched by callingMove,MoveFirst, MoveLast, MovePrevious, or MoveNext.
Update		Update thecurrent row in the table with the values passed in by the SetValue method.Ifa column was bound but not set then the current value of the bound variablewill be used for updating. This method is only valid on cursorsbased on a select from a single table.
UnbindColumn	Column as Integer	Unbind a columnbound with Bindcolumn.

 
 
 

PrimeBaseStmtClass
 
 

Used to create and execute preparedstatements that may contain parameter markers. An instance of a PrimeBaseStmtis created by calling the PrepareStatement method in an instanceof a PBDatabase class.

Super Class

Object

Properties
 

Name	Type	Description
Error	Boolean	True if thelast method called resulted in an error.
ErrorCode	Integer	The error code returned from thelast method called.
ErrorMessage	String	The text ofthe error message returned from the last method called.
ParameterCount	Integer	Number of parametermarkers in the prepared statement.
RowsAffected	Integer	The numberof rows affected by the last operation. This only has meaning for "update"and "delete" SQL commands.
Text	String	The preparedstatement text as passed into the PBDatabase class method PrepareStatement.
Yield	Boolean	When set to"true" calls made to the PrimeBase database server or "RunTime" serverwill be made in non blocking mode and time will be yielded back to theapplication. This involves polling the connection for completion and mayresult in poorer performance. Normally the need for this option can beavoided by using REALbasic threads, but applications running on Mac OSClassic my still want to use this setting in some cases.

Methods:

Some methods such as BindParam acceptparameters of different types. When this is the case the allowed typeswill be given as a comma delimited list inside of round brackets. Wherea parameter is optional it will be given in square brackets.

In all methods that require a parameterindex as a parameter, the parameter is specified by its position; the firstparameter is in position 1.
 

Name	Parameters	Description
BindParam	ParamIndexas integer ForInput as Boolean byRef Buffer as (Integer, Single, Double,Boolean, String , MemoryBlock , PrimeBaseBlob)	Bind the parameterto the buffer. The 'forInput' parameter indicates if the parameter is tobe bound for input or output.  If the parameter is bound for inputthen when the execute method is called the current contents of thebound variable will be used in place of the parameter marker when executingthe statement.  If the parameter is bound for outputthen the statement will be executed and the value of the parameter afterexecution will be placed into the bound buffer.  The binds remain in effect until theparameter is unbound by calling the method UnBindParam or is reboundby a new call to BindParam. Unbound input parameters will assumethe value NULL when the statement is executed.
BindParamFile	ParamIndexas integer ForInput as Boolean File as String	Bind the parameterto the file name passed in.  For parameters bound for input thedata for the parameter is taken from the file at execution time. For parameters bound for output thedata is written to the file after execution time. The binds remain in effect until theparameter is unbound by calling the method UnBindParam or is reboundby a new call to BindParam.
Cancel		Cancel a commandcurrently being executed on this connection.
Execute		Executes theprepared statement.
NewBlob		Returns a PrimeBaseBlobobject associated with associated with the same database connection asthe prepared statement.
NewCursor		Returns a PrimeBaseRowSetobject associated with associated with the same database connection asthe prepared statement.
StmtUnBindParam	ParamIndexas Integer	Unbinds theparameter. Unbound input parameters are assumed to have the value NULLat execution time.

 

PrimeBaseBlobClass
 
 

Used to read and write PrimeBase longbinand longchar data directly. An instance of a PrimeBaseBlob is created bycalling the NewBlob method in an instance of a PBDatabase or PrimeBaseStmtclass.

Super Class

Object

Properties
 

Name	Type	Description
Error	Boolean	True if thelast method called resulted in an error.
ErrorCode	Integer	The error code returned from thelast method called.
ErrorMessage	String	The text ofthe error message returned from the last method called.
Size	Integer	The size ofthe blob data in bytes.
Yield	Boolean	When set to"true" calls made to the PrimeBase database server or "RunTime" serverwill be made in non blocking mode and time will be yielded back to theapplication. This involves polling the connection for completion and mayresult in poorer performance. Normally the need for this option can beavoided by using REALbasic threads, but applications running on Mac OSClassic my still want to use this setting in some cases.

Methods:

Where a parameter is optional it willbe given in square brackets.
 

Name	Parameters	Description
Cancel		Cancel a commandcurrently being executed on this connection.
Read	Buffer as MemoryBlock [ Offset as integer ]	Reads the blobdata into the MemoryBlock buffer. The size of the memory block determineshow much data will be read. This method returns the number of bytesavailable to be read before the method was called. If the 'offset' parameteris supplied, then the data will be read starting at that offset. If nooffset is supplied then the data will be read starting form where the lastread ended.
Reset		Resets theblob to size zero.
Write	Buffer as MemoryBlock	Writes thedata from the MemoryBlock buffer to the blob. If this method is calledmore than once the data is added to the data already in the blob.

 

PrimeBaseDSNClass
 
 

Used to set-up and use connection definitionsin the  the PrimeBase "connect.def" file.

Super Class

Object

Properties
 

Name	Type	Description
Error	Boolean	True if thelast method called resulted in an error.
ErrorCode	Integer	The error codereturned from the last method called.
ErrorMessage	String	The text ofthe error message returned from the last method called.
Count	Integer	The numberof data sources in the  "connect.def" file.
Position	Integer	Gets the positionof the current Data Source Name (DSN)
FileName	String	Gets the full path name of the "connect.def" file.
Name	String	Gets and Sets the name/alias of the current DSN.
Server	String	Gets and Sets the PrimeBase server's name in the currentDSN.
Protocol	String	Gets and Sets the communication protocol to use to connectto the PrimeBase server. Valid protocols are: "TCP" : Use tcp to communicatewith the PrimeBase server. This protocol can be used for connecting toany PrimeBase server running remotely or locally. "MEM": Use shared memory to communicatewith the PrimeBase server. Use this to communicate with a server runningon the same computer as the application. "ADSP": Apple Data Stream Protocol.Use this to communicate with a PrimeBase server running on a computer supportingADSP. The client computer must also support ADSP. "RT": Make a "RunTime" connection.This protocol accesses the PrimeBase databases directly with out connectingto a separately running database server. To use this protocol the PrimeBase"Databases" folder must be located locally on the same computer as theapplication and not be in use by another application or database server.
Protocoli	Integer	Gets and Sets the communication protocol to use to connectto the PrimeBase server by protocol id: 1: TCP 2: MEM 3: ADSP 4: not used 5: RT
ConnectionInfo	String	Gets and Sets the protocol specificconnection information."TCP": The network address of thecomputer on which the PrimeBase database server is running, 192.168.1.220for example.  "MEM": ConnectionInfo property is ignored. "ADSP": The apple zone in which thePrimeBase database server is running. If not supplied the current zoneis assumed. "RT": The full path to the PrimeBase"databases" folder not including the "databases" folder itself. If notsupplied the "databases" folder will be assumed to be in the applicationscurrent working directory. See the documentation on setting up a runtimeconnection for more details.
User	String	Gets and Sets the user name to connect to the PrimeBaseserver as.
Password	String	Sets the user's password to use while connecting to thePrimeBase server.
ServerType	String	Gets and Sets the type of PrimeBase server to connectto. Valid types are:   "PrimeBase": Connect to a PrimeBase databaseserver. "OpenServer": Connect to a PrimeBase Open server.
ServerTypei	Integer	Gets and Sets the type of PrimeBase server to connectto by id:   1: "PrimeBase" 2: "OpenServer"
Database	String	Gets and Sets the database to connect to while openingthe connection.  (Optional)
DBUser	String	Gets and Sets the user name to use while opening thedatabase if different than the name used to open the server connection. (Optional)
DBPassword	String	Sets the password to use while opening the database. (Optional)
OpenServerOptions	String	Gets and Sets OpenServer specific connection optionsrequired by the OpenServer brand targeted. (Optional)

Methods:

Where a parameter is optional it willbe given in square brackets.
 

Name	Parameters	Description
Get	position As integer	Gets the DSNat the indicated position. The first DSN is at position 1.
Move	old_positionAs integer new_position As integer	Moves the DSNfrom the  old_position to the new_position in the file.If the new position is beyond the last entry in the file the DSN is positionedat the end of the file.
Delete	position As integer	Deletes theDSN at the indicated position.
Update		Updates thefile with settings in the current DSN.
Add	[position As integer]	Add the current DSN into the file at the specified position.If no position is specified or if it is beyond the lastentry in the file the DSN is added at the end of the file.
Clear		Clear the current DSN and resets it's properties to theirdefault values.
Test		Test the current DSN to see if it can be used to opena PrimeBase server connection. Returns true if successful or false otherwise.
Connect	User As String,  Passwd As String	Opens a connection to the current DSN and returns a PBDatabasewhen successful.

 
 

PrimeBase Functions

---

PrimeBaseDebugMode()

To aid in the debugging of applications the function PrimeBaseDebugMode()is provided that allows the REALbasic developer to create a PrimeBase APIlog which contains a trace of all calls made to the PrimeBase API. Whenreporting a suspected problem with the plug-in please include an API tracelog.

PrimeBaseDebugMode(activate  As Boolean) as Boolean

This method only has an effect if it is calledbefore any connections are opened.
 

Parameter	Description
activate	The flag to turn on and off api logging.

 

Return Value	Description
Boolean	The logging mode in effect before the method was called.

---

PrimeBaseInfo()

To aid in the debugging of applications the function PrimeBaseInfo()is provided that allows the REALbasic developer to find out the versioninformation of the PrimeBase plug-in and any PrimeBase libraries it uses.

PrimeBaseInfo( ) as String

 

Return Value	Description
String	A human readable string containing version information.

Default Settings

When a connection is opened the following defaults formatsare set.

$decfmt="9999.9";
$moneyfmt=$decfmt
$datefmt="YYYY-MM-DD";
$timefmt="HH:MM:SS";
$tsfmt="YYYY-MM-DD HH:MM:SS";

You can change these by by executing a string settingthe desired format and executing it via a REALbasic db.SQLExecute() call.Please refer to the "PrimeBaseTalk Programmer's Guide" for more informationon valid settings for these variables.

---