This chapter provides the following kinds of information about each of the SUPRA SQL classes:
♦ Class summary
♦ Class hierarchy
♦ Class usage information
♦ Class variables
♦ Instance variables
♦ Class methods
♦ Instance methods
The methods and variables described provide direct access to SUPRA SQL objects, via the SUPRA SQL classes. These methods and variables are frequently accessed from the abstract classes of the ObjectStudio database common object model. Although the ObjectStudio programmer is not restricted from direct access to the SUPRA SQL methods and variables, the common object model should be used unless specific application requirements demand otherwise.
Information on the method references is also available through the Class Browser.
Database User's Guide, P40-3203-03 99
Chapter: SUPRA SQL
SupraDatabase class
The SupraDatabase class implements the access layer for SUPRA SQL databases. Class summary
Module: supradb.cls SuperClass: ExternalDatabase
Description: Support for a SUPRA SQL database
Version: 1.2
Class hierarchy
Database (abstract)
ExternalDatabase (abstract)
SupraDatabase
Class usage information Consider the following:
♦ The SupraDatabase>>directory class method lists the database sources found in the supra.ini file. Just because a database is listed, however, does not necessarily mean that it is available. To be available, a server process must have been started for each database on the host machine.
♦ The database name for a SUPRA SQL database is case-sensitive.
♦ The SUPRA SQL Application Programming Interface (API) does not support creating and deleting SUPRA SQL databases.
♦ SUPRA SQL named result sets created with the FOR REUSE clause and either
execSql: or loadSql: must be explicitly closed via execSql:. SupraDatabase class variables
None
Database User's Guide, P40-3203-03 100
Chapter: SUPRA SQL
SupraDatabase instance variables
sessionNumber
Description: Contains the SUPRA SQL session number for the SupraDatabase instance. SupraDatabase class methods
checkAccessName: extDbName
Description: Checks whether the database specified by the extDbName parameter is active and accessible. It always returns the receiver.
Assumptions: None
Return Value: The receiver. Receiver Modified: No
dbTypeForClass: aClass
Description: Determines the SUPRA SQL database type for the requested class.
Assumptions: None
Return Value: An object of class Symbol. Receiver Modified: No
dbTypeForClass: aClass is: domain
Description: Determines the SUPRA SQL database type for the requested class and domain.
Assumptions: None
Return Value: An object of class Symbol. Receiver Modified: No
Database User's Guide, P40-3203-03 101
Chapter: SUPRA SQL
defaultDBType
Description: Retrieves the default type specified in DBCONV.INI for SUPRA SQL.
Assumptions: None
Return Value: An object of class Symbol. Receiver Modified: No
description
Description: Contains the class reference description. To view the description, select the class name in the Class Browser and then select the Class ⇒ Reference menu option.
Assumptions: None
Return Value: The receiver. Receiver Modified: No hasLogonView
Description: Returns true for objects of class SupraDatabase.
Assumptions: None Return Value: true
Receiver Modified: No initialize
Description: Defines the DLL module object and registers all primitive methods for the SUPRA SQL database.
Assumptions: None
Return Value: The receiver. Receiver Modified: No
Database User's Guide, P40-3203-03 102
Chapter: SUPRA SQL
loginUser: username password: password lock: lockmode timeout: timeout Description: Used by the login controller to log in the user. Can also be used by application
programs to change the user name and password.
Assumptions: username and password must be objects of class String. password can also be
nil, which specifies a password of null for the database.
lockmode can be nil. Otherwise, it must be an object of class Symbol and can have the values #NORMAL, #EXPLICIT, or #IMPLICIT. Specifying nil defaults to a lock mode of #NORMAL.
timeout can be nil. Otherwise, it must be an object of class SmallInteger and must be positive. Negative values and nil result in SUPRA SQL default-timeout behavior. Refer to the CONNECT statement in the SUPRA Server SQL Commands Reference Manual, P26-2420, for more information.
Return Value: The receiver or an error code (Integer). Receiver Modified: No
logonView
Description: Returns the SUPRA SQL logon window controller.
Assumptions: None
Return Value: An object of class SupraLogonController.
Receiver Modified: No
maxDatabaseNameLength
Description: Returns the maximum length, in characters, of a database identifier.
Assumptions: None
Return Value: An object of class SmallInteger. Receiver Modified: No
Database User's Guide, P40-3203-03 103
Chapter: SUPRA SQL
privateDBCreateHideOptions
Description: Returns a list of items that will be used to determine the options to be disabled or hidden from view for an interface. For a SUPRA SQL database, all options are hidden, because a new database cannot be created.
Assumptions: None
Return Value: An object of class Array. Receiver Modified: No
privateDirectory (primitive)
Description: Returns a list of available databases. A database is available if it can be opened and data can be retrieved with a SELECT statement.
Assumptions: None
Return Value: An object of class IdentityDictionary or class Message. Receiver Modified: No
supportedFeatures
Description: Returns an array of the supported database features for SupraDatabase.
Assumptions: None
Return Value: An object of class Array. Receiver Modified: No
supportsSize
Description: Returns true for objects of class SupraDatabase because SUPRA SQL supports sized database types.
Assumptions: None
Return Value: An object of class Boolean. Receiver Modified: No
Database User's Guide, P40-3203-03 104
Chapter: SUPRA SQL
tableClass
Description: Returns an object of class SupraTable. This is the table class belonging to SupraDatabase.
Assumptions: None
Return Value: An object of class SupraTable.
Receiver Modified: No
userName (primitive)
Description: Returns the user name that controls SUPRA SQL access.
Assumptions: None
Return Value: A string containing the user name for accessing SUPRA SQL. Receiver Modified: No
validPrecisionTypes
Description: Lists the SUPRA SQL database types that have a precision characteristic.
Assumptions: None
Return Value: An object of class Array. Receiver Modified: No
validSizedTypes
Description: Lists the SUPRA SQL database types that have a size characteristic.
Assumptions: None
Return Value: An object of class Array. Receiver Modified: No
Database User's Guide, P40-3203-03 105
Chapter: SUPRA SQL
validTypes
Description: Lists the valid SUPRA SQL database data types.
Assumptions: None
Return Value: An object of class Array. Receiver Modified: No
version (primitive)
Description: Returns the version number of the underlying DLL.
Assumptions: None
Return Value: A string containing the version number of the underlying DLL. Receiver Modified: No
Database User's Guide, P40-3203-03 106
Chapter: SUPRA SQL
SupraDatabase instance methods
byteArrayAsDBStringValue: value
Description: Returns a string containing the hexadecimal representation of the value parameter.
Assumptions: value must be an object of class ByteArray. Return Value: An object of class String.
Receiver Modified: No check (primitive)
Description: Executes the SQL statement CHECK DATABASE.
Assumptions: None
Return Value: An object of class Array or class Message. The array contains two entries:
♦ A small integer giving the percentage that the database is full.
♦ A small integer giving the percentage that the log is full.
Receiver Modified: No databaseType
Description: Responds with the SUPRA SQL database type.
Assumptions: None
Return Value: An object of class Symbol. Receiver Modified: No
Database User's Guide, P40-3203-03 107
Chapter: SUPRA SQL
dateAsDBStringValue: value
Description: Returns a string containing the date specified by the value parameter.
Assumptions: value must be an object of class Date. Return Value: An object of class String.
Receiver Modified: No driverName
Description: Returns the string SUPRA, which identifies the database in use.
Assumptions: None
Return Value: An object of class String. Receiver Modified: No
isSupra
Description: Returns true because the receiver is of class SupraDatabase.
Assumptions: None
Return Value: An object of class Boolean. Receiver Modified: No
load (primitive)
Description: Loads information about all tables in the database.
Assumptions: None
Return Value: The receiver. Receiver Modified: No
Database User's Guide, P40-3203-03 108
Chapter: SUPRA SQL
loadInfo
Description: Creates a set of tables that corresponds to the tables in the database. Only basic information is loaded.
Assumptions: None
Return Value: The receiver or an object of class Message. Receiver Modified: Yes
message (primitive)
Description: Returns the last error message.
Assumptions: None
Return Value: An object of class Message. Receiver Modified: No
nextStamp (primitive)
Description: Executes the SQL statement NEXT STAMP.
Assumptions: None
Return Value: An object of class ByteArray or class Message. The ByteArray will contain the
next SYSKEY value.
Receiver Modified: No privateExecSql: sql
Description: Works like privateExecSql:onError:. If an error occurs, it is written to the transcript. For more information, see the description of the
privateExecSql:onError: method that follows.
Assumptions: None
Return Value: The receiver. Receiver Modified: No
Database User's Guide, P40-3203-03 109
Chapter: SUPRA SQL
privateExecSql: sqlString onError: block (primitive)
Description: Executes the SQL statement specified by the sqlString parameter. The block parameter is executed when an error is encountered.
Assumptions: sqlString must be an object of class String.
block must be an executable block with one parameter. The parameter is the error code.
Return Value: If sqlString specifies a SELECT statement, an object of class Table is returned. Otherwise, 0 (SmallInteger) is returned. If a complete table could not be loaded because the data load limit was exceeded, the incomplete table is returned and block is executed. For more information, see “SupraDatabase class” on page 100.
Receiver Modified: No privateLoadSql: sql
Description: Works like privateExecSql:onError:. If an error occurs, it is written to the transcript. For more information, see the description of the
privateLoadSql:onError: method that follows.
Assumptions: None
Return Value: The receiver. Receiver Modified: No
Database User's Guide, P40-3203-03 110
Chapter: SUPRA SQL
privateLoadSql: sqlString onError: block (primitive)
Description: Executes an SQL SELECT statement and gives the result in the form of a vector table. The block parameter is executed when an error occurs.
Assumptions: sqlString must be an object of class String and must contain a SELECT
statement.
block must be an executable block with one parameter. The parameter is the error code.
Return Value: An object of class VectorTable.
Receiver Modified: No
privateOpenCursorSql: sqlString (primitive)
Description: Gets the next available cursor and assigns data to its instance variables based on the contents of sqlString.
Assumptions: sqlString must be an object of class String and must contain a SELECT
statement.
Return Value: An object of class SupraDatabaseCursor or class Message.
Receiver Modified: No
privateOpenScrollableCursorSql: sqlString (primitive)
Description: Gets the next available scrollable cursor and fills it with data based on the contents of sqlString.
Assumptions: sqlString must be an object of class String and must contain a SELECT
statement.
Return Value: An object of class SupraScrollableCursor or class Message.
Receiver Modified: No
Database User's Guide, P40-3203-03 111
Chapter: SUPRA SQL
privateSelectCountSql: sqlString (primitive) Description: Returns the number of records in a table.
Assumptions: sqlString must contain a SELECT statement that counts the number of records
in a table; for example, SELECT count (*) from employees.
Return Value: An object of class Integer. Receiver Modified: No
privateStart (primitive) Description: Starts the database.
Assumptions: None
Return Value: The receiver or an error message of class Message. Receiver Modified: No
privateStop (primitive)
Description: Stops the database and logs the user out.
Assumptions: None
Return Value: The receiver or an error message of class Message. Receiver Modified: No
removeDependencyFor: dependentObject
Description: Removes the dependency for the object specified in the dependentObject parameter.
Assumptions: None
Return Value: The receiver. Receiver Modified: Yes
Database User's Guide, P40-3203-03 112
Chapter: SUPRA SQL
sourceDirectory
Description: Returns the string SUPRA. It is used to specify the name of the source directory in the ObjectStudio tree.
Assumptions: None
Return Value: An object of class String. Receiver Modified: No
timeAsDBStringValue: value
Description: Returns a string containing the time specified by the value parameter.
Assumptions: value must be an object of class Time. Return Value: An object of class String.
Receiver Modified: No
Database User's Guide, P40-3203-03 113
Chapter: SUPRA SQL
SupraDatabaseCursor class
The SupraDatabaseCursor class provides the implementation details for SUPRA SQL nonscrollable cursors.
Class summary
Module: supracr.cls SuperClass: ExternalDatabaseCursor
Description: Support for SUPRA SQL nonscrollable cursors
Version: 1.2
Class hierarchy
Cursor (abstract class)
ExternalDatabaseCursor (abstract)
SupraDatabaseCursor
Class usage information Consider the following:
♦ All cursors remain open if a transaction is terminated by issuing a COMMIT WORK or ROLLBACK WORK.
♦ It is important to close cursors after using them. Failure to do so will cause unpredictable results when opening new cursors.
♦ The maximum number of cursors in a class is limited to 16. SupraDatabaseCursor class variables
cursors
Description: An array object that contains database cursors.
Database User's Guide, P40-3203-03 114
Chapter: SUPRA SQL
SupraDatabaseCursor instance variables
dataArea
Description: Contains the SUPRA SQL SQLDA used internally by the SupraDatabaseCursor instance. This area is large (15K) and should be inspected with caution, because it takes a long time to display (1–2 minutes).
parseId
Description: Contains the SUPRA SQL parse ID associated with a SupraDatabaseCursor instance.
sessionNumber
Description: Contains the SUPRA SQL session number for a SupraDatabaseCursor object.
Database User's Guide, P40-3203-03 115
Chapter: SUPRA SQL
SupraDatabaseCursor class methods
description
Description: Contains the class reference description. To view the description, select the class name in the Class Browser and then select the Class ⇒ Reference menu option.
Assumptions: None
Return Value: The receiver. Receiver Modified: No
initialize
Description: Assigns an empty array object to the class variable cursors. This variable is used to store database cursors.
Assumptions: None
Return Value: The receiver. Receiver Modified: Yes
maxCursors (primitive)
Description: Returns the maximum number of cursors that can be opened concurrently.
Assumptions: None
Return Value: An object of class SmallInteger. Receiver Modified: No
nextCursor
Description: Returns an uninitialized cursor at the next available index and sets its index position.
Assumptions: None
Return Value: An object of class SupraDatabaseCursor, or nil if no cursor is available. Receiver Modified: Yes
Database User's Guide, P40-3203-03 116
Chapter: SUPRA SQL
SupraDatabaseCursor instance methods
message (primitive)
Description: Returns the last error message.
Assumptions: None
Return Value: An object of class Message. Receiver Modified: No
name (primitive)
Description: Returns a string object containing the name of the cursor.
Assumptions: None
Return Value: An object of class String. Receiver Modified: No
privateClose (primitive)
Description: Frees allocated resources for the cursor and initializes the cursor position to 0.
Assumptions: None
Return Value: The receiver or an object of class Message. Receiver Modified: Yes
privateExecNoSelect: sqlString (primitive)
Description: Executes the SQL statement specified by the sqlString parameter.
Assumptions: sqlString is an object of class String and contains the SQL statement to be
executed. sqlString may not contain a SELECT statement.
Return Value: The receiver or an error code of class Integer. Receiver Modified: No
Database User's Guide, P40-3203-03 117
Chapter: SUPRA SQL
privateNext (primitive)
Description: Returns a dictionary with the next data record.
Assumptions: None
Return Value: An object of class Dictionary, or an error code of class Integer. Receiver Modified: No
updateWith: newValueDict
Description: Updates the value of all fields at the current cursor position that differs from the value in newValueDict. Valid only if the cursor was opened using “for update of.”
Assumptions: None
Return Value: The receiver or an object of class Message. Receiver Modified: No
Database User's Guide, P40-3203-03 118
Chapter: SUPRA SQL
SupraLogonController class
The SupraLogonController class provides the implementation details for the SUPRA SQL logon window.
Class summary
Module: logon.cls
SuperClass: LogonWindowController
Description: Support for the SUPRA SQL logon window
Version: 1.2
Class hierarchy Object (abstract class) InterfacePart Controller
ObjectStudioController LogonWindowController
SupraLogonController
Database User's Guide, P40-3203-03 119
Chapter: SUPRA SQL
Class usage information
SupraLogonController displays the SUPRA logon window. This window allows you to enter a SUPRA SQL user name, password, lock mode, and timeout value. These values are the same as those used in the SUPRA SQL CONNECT
statement. Refer to the SUPRA Server SQL Commands Reference Manual, P26-2420, for information on the CONNECT statement.
Also note:
♦ The SUPRA logon window displays when the SUPRA SQL database wrapper is first loaded. To display the logon window at other times, select the Other Tools icon from the ObjectStudio Workplace Desktop.
♦ You can input the logon information from within an ObjectStudio program by using the SupraDatabase loginUser:password:lock:timeout: class method. For more information, see “loginUser: username password:
password lock: lockmode timeout: timeout” on page 103.
♦ SupraLogonController provides a Logoff button, which stops access to all SUPRA SQL databases and disconnects any established sessions.
SupraLogonController class variables None
Database User's Guide, P40-3203-03 120
Chapter: SUPRA SQL
SupraLogonController instance variables
Cancel
Description: Cancel push-button controller item on the logon dialog box.
lockmode
Description: Lock mode value selected from the logon dialog box. A value of 1 indicates NORMAL, a value of 2 indicates EXPLICIT, and a value of 3 indicates IMPLICIT.
Logoff
Description: Logoff push-button controller item on the logon dialog box.
OK
Description: OK push-button controller item on the logon dialog box.
password
Description: Password entry-field text value.
timeout
Description: Timeout value entry-field numeric value.
userName
Description: User name entry-field text value.
Database User's Guide, P40-3203-03 121
Chapter: SUPRA SQL
SupraLogonController class methods
description
Description: Contains the class reference description. To view the description, select the class name in the Class Browser and then select the Class ⇒ Reference menu option.
Assumptions: None
Return Value: The receiver. Receiver Modified: No
initialize
Description: Executes when the SupraLogonController class is loaded into the system. Initializes the SUPRA SQL Logon dialog box.
Assumptions: None
Return Value: The receiver. Receiver Modified: Yes
Database User's Guide, P40-3203-03 122
Chapter: SUPRA SQL
SupraLogonController instance methods
createItems
Description: Defines the forms, controller items, and methods for the SUPRA SQL Logon dialog box.
Assumptions: None
Return Value: The receiver. Receiver Modified: Yes
database
Description: Sets the default database to SupraDatabase.
Assumptions: None
Return Value: SupraDatabase, which represents the global variable for the SUPRA SQL database.
Receiver Modified: No defaultMethod
Description: Sets the default action for the controller to the
loginUser:password:lock:timeout: method.
Assumptions: None
Return Value: A Symbol representing the loginUser:password:lock:timeout: method. Receiver Modified: No
Database User's Guide, P40-3203-03 123
Chapter: SUPRA SQL