The PrimeBase REALbasic Plug-in

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
 
NameTypeDescription
ConnectionInfoStringProtocol 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.

ClientVersionIntegerThe versionnumber of the PrimeBase VM or RunTime library that has been loaded. (Version4.2.15 returns 4215).
ProtocolStringThe 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.

RowsAffectedIntegerThe numberof rows effected by the last operation. This only has meaning for "update"and "delete" SQL commands.
ServerStringThe PrimeBasedatabase server name. "PrimeServer" for example. This property is ignoredwhen making a "RunTime" connection.
ServerVersionIntegerThe versionnumber of the PrimeBase database server connected to. (Version 4.2.15 returns4215).
YieldBooleanWhen 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.
 
NameParametersDescription
ConnectDSNdsn 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.
PrepareStatementStatement asStringPrepares 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.
ProcedureCallCall as StringExecutes 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.
SQLExecuteReturningStatement asStringExecutes 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.
SQLSelectROSelectStringas StringSimilar tothe standard SqlSelect method but returns an object of type PBDatabaseCursorthat refers to an read only cursor.
SQLSelectRWSelectStringas StringSimilar 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.)
 
NameParametersDescription
ColumnNameColumn as IntegerReturns a columnname of a specific column. 
ColumnScaleColumn as IntegerReturns thescale of the data in the column if it is a decimal data type.
ColumnSizeColumn as IntegerReturns thelength of the data in the column. For example a column of type varchar(11)would have a size of 11.
ColumnTypeColumn as IntegerReturns 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
 
NameTypeDescription
BOFBooleanBeginning ofthe cursor.
EOFBooleanEnd of thecursor.
ErrorBooleanTrue if thelast method called resulted in an error.
ErrorCodeIntegerThe error code returned from thelast method called.
ErrorMessageStringThe text ofthe error message returned from the last method called.
FieldCountIntegerNumber of fieldsin the cursor.
NameStringThe name ofthe PBT cursor associated with this instance.
PositionIntegerThe positionof the cursor in the row set. The first row is at position 1.
RowsIntegerNumber 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.
YieldBooleanWhen 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.
 
NameParametersDescription
BindcolumnColumn 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.
ColumnNameColumn as IntegerReturns thecolumn name.
ColumnScaleColumn as IntegerReturns thescale of the data in the column if it is a decimal data type.
ColumnSizeColumn as IntegerReturns thelength of the data in the column. For example a column of type varchar(11)would have a size of 11.
ColumnTypeColumn as IntegerReturns 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.
ColumnTypeNameColumn as IntegerReturns 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.
GetBlobColumn as Integer

[ byRef Status as Boolean ]

See GetInteger.

Returns a PrimeBaseBlob object.

GetBooleanColumn as Integer

[ byRef Status as Boolean ]

See GetInteger

Returns a Boolean.

GetDoubleColumn as Integer

[ byRef Status as Boolean ]

See GetInteger

Returns a Double.

GetIntegerColumn 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.

GetMemColumn as Integer

[ byRef Status as Boolean ]

See GetInteger.

Returns a MemoryBlock.

GetSingleColumn as Integer

[ byRef Status as Boolean ]

See GetInteger

Returns a Single.

GetStringColumn as Integer

[ byRef Status as Boolean ]

See GetInteger.

Returns a String.

InsertTable as StringInsert 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.
MoveRow as IntegerPositions 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.
SetNullColumn as IntegerSame as SetValuebut sets the column's value to NULL.
SetRowRow as IntegerPositions 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
SetValueColumnas 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.

UnbindColumnColumn as IntegerUnbind 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
 
NameTypeDescription
ErrorBooleanTrue if thelast method called resulted in an error.
ErrorCodeIntegerThe error code returned from thelast method called.
ErrorMessageStringThe text ofthe error message returned from the last method called.
ParameterCountIntegerNumber of parametermarkers in the prepared statement.
RowsAffectedIntegerThe numberof rows affected by the last operation. This only has meaning for "update"and "delete" SQL commands.
TextStringThe preparedstatement text as passed into the PBDatabase class method PrepareStatement.
YieldBooleanWhen 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.
 
NameParametersDescription
BindParamParamIndexas 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.

BindParamFileParamIndexas 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.
StmtUnBindParamParamIndexas IntegerUnbinds 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
 
NameTypeDescription
ErrorBooleanTrue if thelast method called resulted in an error.
ErrorCodeIntegerThe error code returned from thelast method called.
ErrorMessageStringThe text ofthe error message returned from the last method called.
SizeIntegerThe size ofthe blob data in bytes.
YieldBooleanWhen 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.
 
NameParametersDescription
Cancel Cancel a commandcurrently being executed on this connection.
ReadBuffer 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.
WriteBuffer 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
 
NameTypeDescription
ErrorBooleanTrue if thelast method called resulted in an error.
ErrorCodeIntegerThe error codereturned from the last method called.
ErrorMessageStringThe text ofthe error message returned from the last method called.
CountIntegerThe numberof data sources in the  "connect.def" file.
PositionIntegerGets the positionof the current Data Source Name (DSN)
FileNameStringGets the full path name of the "connect.def" file.
NameString Gets and Sets the name/alias of the current DSN.
ServerStringGets and Sets the PrimeBase server's name in the currentDSN.
ProtocolStringGets 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.

ProtocoliIntegerGets 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
ConnectionInfoStringGets 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.

UserStringGets and Sets the user name to connect to the PrimeBaseserver as.
PasswordStringSets the user's password to use while connecting to thePrimeBase server.
ServerTypeStringGets 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.

ServerTypeiIntegerGets and Sets the type of PrimeBase server to connectto by id:
 
1: "PrimeBase"
2: "OpenServer"
DatabaseStringGets and Sets the database to connect to while openingthe connection. 

(Optional)

DBUserStringGets and Sets the user name to use while opening thedatabase if different than the name used to open the server connection.

(Optional)

DBPasswordStringSets the password to use while opening the database.

(Optional)

OpenServerOptionsStringGets and Sets OpenServer specific connection optionsrequired by the OpenServer brand targeted.

(Optional)

Methods:

Where a parameter is optional it willbe given in square brackets.
 
NameParametersDescription
Get position As integerGets the DSNat the indicated position. The first DSN is at position 1.
Moveold_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 integerDeletes 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.
ClearClear the current DSN and resets it's properties to theirdefault values.
TestTest the current DSN to see if it can be used to opena PrimeBase server connection.

Returns true if successful or false otherwise.

ConnectUser 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.
 
ParameterDescription
activateThe flag to turn on and off api logging.

 
Return ValueDescription
BooleanThe 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 ValueDescription
StringA 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.