Download Database User`s Guide

OBJECTSTUDIO
Database User's Guide
P40-3203-03
Release information for this manual
ObjectStudio Database User's Guide, P40-3203-03, is dated November 1, 2003.
This document supports Release 6.9 of ObjectStudio.
Cincom Technical Support for ObjectStudio
All customers
Web:
http://supportweb.cincom.com
USA customers
Phone:
1-800-727-3525
Fax:
(513) 612-2000
Attn: ObjectStudio Support
Mail:
Cincom Systems, Inc.
Attn: ObjectStudio Support
55 Merchant Street
Cincinnati, OH 45246-3732
USA
All:
Visit the support links at
http://www.cincom.com to find contact
information for your nearest Customer
Service Center.
Outside of USA
Using this document
This guide is for database application developers. It discusses Smalltalk classes
and methods used in ObjectStudio® to support database access. It also
describes the tools in the ObjectStudio development environment that are
relevant to creating database access.
As a prerequisite, you should be familiar with relational database theory, the
object-oriented approach to software development, and the ObjectStudio
Smalltalk development environment.
Document organization
The information in this guide is organized as follows:
Chapter 1—Overview of database support
Contains an overview of how ObjectStudio supports access to many types of
database management systems (DBMSs).
Chapter 2—How ObjectStudio implements database support
Describes the databases and the classes that ObjectStudio supports.
Chapter 3—Working with databases
Provides information about techniques to use when you work with
databases.
Chapter 4—ODBC
Discusses topics specific to ODBC.
Chapter 5—DB2
Discusses topics specific to DB2®.
Chapter 6—Informix
Discusses topics specific to Informix®.
Chapter 7—SUPRA SQL
Discusses topics specific to SUPRA® SQL.
Chapter 8—UniSQL Server
Discusses topics specific to UniSQL Server.
Chapter 9—Other databases
Discusses topics specific to Oracle®, Oracle OCI, ADABAS®, SQL Server, and
SYBASE® OpenClient.
Chapter 10—Database Notebook
Describes the Database Notebook, which provides access to all internal and
external databases.
Chapter 11—SQL tools
Describes tools in ObjectStudio that allow you to create SQL statements.
Chapter 12—Report Editor
Describes the Report Editor and how to use it.
Appendix A—Cross-platform development
Discusses Windows® character set conversion.
Index
Contents
Overview of database support........................................................ 12
How ObjectStudio supports databases............................................................... 12
Database classifications ................................................................................ 12
Database object framework ........................................................................... 13
Database objects ................................................................................... 13
Table objects ....................................................................................... 14
Query objects ....................................................................................... 14
Cursor objects ...................................................................................... 14
Database tools ........................................................................................... 15
How ObjectStudio implements database support ................................ 16
Introduction .............................................................................................. 16
Supported databases.................................................................................... 17
ODBC database...................................................................................... 17
Oracle database .................................................................................... 18
ADABAS database ................................................................................... 19
IBM DB2 database................................................................................... 19
Microsoft SQL Server database ................................................................... 20
SYBASE OpenClient database ..................................................................... 20
Informix database .................................................................................. 20
SUPRA SQL database ............................................................................... 21
UniSQL Server database ........................................................................... 21
Internal Database .................................................................................. 21
Database classes......................................................................................... 22
Database class hierarchy .......................................................................... 22
Database class ...................................................................................... 23
ExternalDatabase class ............................................................................ 24
ODBCDatabase class................................................................................ 24
OracleDatabase class .............................................................................. 25
AdabasDatabase class.............................................................................. 25
ESDatabase class ................................................................................... 25
SQLServerDatabase class .......................................................................... 26
SybaseDatabase class .............................................................................. 26
INFDatabase class .................................................................................. 26
SupraDatabase class ............................................................................... 26
Database User's Guide, P40-3203-03
Contents
5
ORDBDatabase class................................................................................ 27
LocalDatabase class ................................................................................ 27
InternalDatabase class............................................................................. 27
Table classes ............................................................................................. 28
Table class hierarchy .............................................................................. 29
Table class........................................................................................... 29
ExternalTable class ................................................................................ 30
VectorTable class................................................................................... 30
Cursor classes ............................................................................................ 31
Cursor class hierarchy ............................................................................. 32
Cursor class.......................................................................................... 33
Nonscrollable cursors .............................................................................. 33
Scrollable cursors................................................................................... 34
LocalCursor class ................................................................................... 35
Query classes............................................................................................. 36
Query class .......................................................................................... 37
SqlDirect class ...................................................................................... 37
SqlParse class ....................................................................................... 37
SQL Query classes .................................................................................. 38
SqlSelect class ...................................................................................... 39
SqlSubSelect class .................................................................................. 39
SqlUpdate class ..................................................................................... 39
Working with databases................................................................ 40
Introduction .............................................................................................. 40
Loading external database support................................................................... 40
Connecting to a DBMS .................................................................................. 42
Connecting options................................................................................. 42
Database-specific connection information ..................................................... 43
Accessing a database ................................................................................... 45
accessName: ........................................................................................ 45
directory ............................................................................................. 45
visibleTablesAt:put:................................................................................ 46
Performing transactions................................................................................ 48
Using SQL to query databases ......................................................................... 49
Methods for executing SQL statements ......................................................... 49
Creating strings containing SQL code ........................................................... 51
Using SQL versus using cursors ................................................................... 52
Executing SQL with a local database ............................................................ 52
Database User's Guide, P40-3203-03
Contents
6
Working with cursors ................................................................................... 53
Data format returned .............................................................................. 53
Cursor messages .................................................................................... 53
Methods for cursor support ....................................................................... 54
Types of cursors .................................................................................... 55
Using cursors with ODBC .......................................................................... 55
Using cursors with SQL Server .................................................................... 55
Using cursors with Informix ....................................................................... 55
Selecting multiple tables to create a cursor, in all databases except UniSQL ........... 56
Selecting multiple tables to create a cursor, in UniSQL ..................................... 57
Working with tables..................................................................................... 58
Linking to cursors and tables .......................................................................... 59
Types of links ....................................................................................... 59
Creating a normal link ............................................................................. 60
Creating an update link ........................................................................... 61
Enhancing performance ................................................................................ 62
Handling errors .......................................................................................... 62
Packaging applications ................................................................................. 63
Including login controllers in the image ........................................................ 63
Delaying initialization of the DLL ................................................................ 64
Delaying a database login ......................................................................... 65
ODBC ....................................................................................... 66
Introduction .............................................................................................. 66
ODBC elements .......................................................................................... 66
ODBC conformance levels.............................................................................. 67
API conformance levels............................................................................ 67
ODBC SQL grammar conformance levels........................................................ 68
ObjectStudio supports all ODBC conformance levels ......................................... 68
ObjectStudio ODBCDatabase and driver conformance-level dependencies ............... 68
Low-level ODBC support................................................................................ 69
Additional ODBC classes................................................................................ 70
Typical session ........................................................................................... 71
Data type mapping ...................................................................................... 73
System catalog access .................................................................................. 74
Example of using stored procedures ............................................................ 75
Parametric SQL statements....................................................................... 76
Cursors and scrollable cursors.................................................................... 80
Working with Binary Large Objects (BLOBs) ........................................................ 82
Enabling ODBC Support ............................................................................ 82
Using chunks ........................................................................................ 82
Handling errors .......................................................................................... 85
Database User's Guide, P40-3203-03
Contents
7
DB2 ......................................................................................... 86
Introduction .............................................................................................. 86
Extended services ....................................................................................... 86
Cursors .................................................................................................... 86
ORDER BY clause and Extended Services database cursors .................................. 86
Support for DB2 and Cursors with Hold ......................................................... 86
Manually binding the DB2 files ........................................................................ 87
Descriptions of the bind file pairs to use in manual binding ................................ 87
Performing the manual binding .................................................................. 89
Granting database access to users other than yourself ...................................... 90
Cataloging databases ................................................................................... 91
Uncataloging databases ................................................................................ 92
Executing stored procedures .......................................................................... 92
Methods to execute DB2 procedures ............................................................ 93
Considerations for parameters used by stored procedures .................................. 94
Examples of DB2 stored procedures ............................................................. 94
Informix ................................................................................... 95
Introduction .............................................................................................. 95
Looking for Informix databases ....................................................................... 95
Connecting to Informix databases .................................................................... 95
Transaction processing: commit and rollback ...................................................... 95
Executing stored procedures .......................................................................... 96
SUPRA SQL ................................................................................ 97
Introduction .............................................................................................. 97
Working with SUPRA SQL string columns ............................................................ 98
ASCII/EBCDIC/BYTE designations and SUPRA SQL character columns........................... 98
FLOAT precision in SUPRA SQL ........................................................................ 98
Avoiding COMMIT WORK RELEASE and ROLLBACK WORK RELEASE ............................... 98
Using multiple SUPRA SQL sessions ................................................................... 98
SUPRA SQL class reference ............................................................................ 99
Introduction ......................................................................................... 99
SupraDatabase class .............................................................................. 100
SupraDatabaseCursor class....................................................................... 114
SupraLogonController class ...................................................................... 119
SupraScrollableCursor class...................................................................... 126
SupraStringColumn class ......................................................................... 131
SupraTable class................................................................................... 136
Database User's Guide, P40-3203-03
Contents
8
UniSQL Server........................................................................... 145
Introduction ............................................................................................. 145
Using the lock_timeout_in_secs_parameter ....................................................... 146
Report editor considerations ......................................................................... 146
UniSQL Server class reference ....................................................................... 147
Introduction ........................................................................................ 147
ORDBDatabase class............................................................................... 148
ORDBDatabaseCursor class ....................................................................... 162
ORDBLogonController class ...................................................................... 168
ORDBScrollableCursor class ...................................................................... 174
ORDBTable class ................................................................................... 179
Other databases ........................................................................ 186
Introduction ............................................................................................. 186
Oracle and Oracle OCI support ....................................................................... 187
Oracle support ..................................................................................... 187
Oracle OCI support ................................................................................ 192
ADABAS support......................................................................................... 196
SQL Server support ..................................................................................... 196
Logging on using Windows Authentication .................................................... 196
Looking for SQL Server databases .............................................................. 196
Message and error blocks ........................................................................ 197
MicroDecisionware access........................................................................ 199
Microsoft SQL Server wrapper sets local host name ......................................... 199
SYBASE OpenClient support........................................................................... 200
Message and error blocks ........................................................................ 200
Database Notebook .................................................................... 202
Introduction ............................................................................................. 202
Using the Database Notebook ........................................................................ 203
Database Notebook pop-up menu............................................................... 203
Creating a new database......................................................................... 204
Creating and modifying a table ................................................................. 206
Saving changes to the Internal Database ...................................................... 210
Entering data ........................................................................................... 211
Accessing the default data entry form......................................................... 211
Customizing the Data Entry dialog box ........................................................ 213
Managing data .......................................................................................... 214
Opening the default Data Manager ............................................................. 214
Customizing the Data Manager Form ........................................................... 216
Creating a SQL query .................................................................................. 217
Using the SQL tools................................................................................ 217
Using the SQL Browser............................................................................ 218
Database User's Guide, P40-3203-03
Contents
9
SQL tools ................................................................................. 220
Introduction ............................................................................................. 220
SQL Editor ............................................................................................... 220
Creating an SQL statement ...................................................................... 221
Using the Selection dialog box .................................................................. 224
Executing a statement............................................................................ 233
Defining a WHERE clause......................................................................... 234
Defining a JOIN clause............................................................................ 236
Defining a GROUP BY clause ..................................................................... 238
Defining a HAVING clause ........................................................................ 238
Defining an ORDER BY clause .................................................................... 239
Creating parametric SQL statements........................................................... 240
Committing changes .............................................................................. 242
Rolling back changes.............................................................................. 242
Importing and exporting statements ........................................................... 243
Creating a report for the statement ........................................................... 243
SQL Window ............................................................................................. 244
File menu ........................................................................................... 244
Actions menu....................................................................................... 244
Creating an SQL statement ...................................................................... 245
Loading an ASCII text file into the SQL Window .............................................. 245
Report Editor............................................................................ 246
Using the Report Editor ............................................................................... 246
Creating a report .................................................................................. 247
Saving reports...................................................................................... 249
Working with report sections......................................................................... 250
Level breaks........................................................................................ 250
Adding or removing sections..................................................................... 251
Formatting sections ............................................................................... 251
Using level breaks ................................................................................. 252
Working with report items ............................................................................ 256
Adding report items............................................................................... 257
Resizing report items ............................................................................. 258
Deleting report items ............................................................................. 258
Copying or moving report items................................................................. 259
Formatting report items .............................................................................. 260
Formatting multi-line string items.............................................................. 262
Formatting graphic items ............................................................................. 263
Formatting lines and topic boxes ............................................................... 264
Creating and formatting bitmapped images .................................................. 265
Registering a graphics file ....................................................................... 267
Database User's Guide, P40-3203-03
Contents
10
Defining and formatting graphs and graph legends ............................................... 268
Placing a graphics field........................................................................... 268
Defining a graphics field ......................................................................... 269
Formatting graphics fields ....................................................................... 269
Formatting graphics legends..................................................................... 271
Formatting, previewing, and printing a report .................................................... 272
Formatting report pages ......................................................................... 272
Previewing a report ............................................................................... 274
Printing from the Report Preview .............................................................. 274
Setting the report timer.......................................................................... 275
Setting output options............................................................................ 277
Printing or previewing a report ................................................................. 278
Cross-platform development......................................................... 279
Windows character set conversion .................................................................. 279
Index ...................................................................................... 280
Database User's Guide, P40-3203-03
Contents
11
1
Overview of database support
How ObjectStudio supports databases
Support for each database is a loadable application (or package, if using the
Repository) containing class and method definitions that allow you to work with
that specific database.
Features of ObjectStudio database support include:
♦
Easy porting of an application from one database to another.
♦
The ability to access more than one database simultaneously, whether of
the same type or of different types.
Database classifications
ObjectStudio classifies databases as either:
♦
Local. There is one local database (the Internal Database) for prototyping.
The Internal Database allows you to design and test an application without
consuming valuable server resources. The Internal Database is limited in
size by the amount of memory in your system.
♦
External. There are a number of external databases supported by
ObjectStudio.
Database User's Guide, P40-3203-03
Chapter: Overview of database support
Section: How ObjectStudio supports databases
12
Database object framework
ObjectStudio implements the following classes to support database
connections:
♦
Database
♦
Table
♦
Query
♦
Cursor
This structure matches typical relational database objects and provides a
common frame of reference for working with databases.
For each supported database, ObjectStudio provides subclasses of each of
these classes. Use these classes to define the access layer of an application.
For more information, see “Database classes” on page 22.
Database objects
Each database that ObjectStudio supports is represented as a subclass of class
Database. When you open a connection to a specific database, ObjectStudio
creates an instance of the appropriate Database subclass.
You can send messages to Database objects to open cursors, execute SQL
statements, and begin and end transactions. Database objects also maintain
information regarding the differences between database types.
Database User's Guide, P40-3203-03
Chapter: Overview of database support
Section: Database object framework
13
Table objects
Databases contain Table objects that represent the structure of each table
within a database. A Table object describes a database table’s columns and the
data type of each column, but it does not contain the actual data.
You can query a Table object for its attributes, including column information
and records. You can add, remove, and modify records directly through the
Table object, or you can perform these functions using a combination of SQL
statements and cursors.
For external databases, using SQL statements can be more efficient than
working with Table objects.
Query objects
Query objects allow you to save SQL queries as objects. You can create a link
to a query, either visually using the Designer, or with a method-based Model
View Controller (MVC) interface. You can pass a Query object to a database for
execution, or you can use a Query object to open a cursor. Queries can include
parameters. Associated with each parameter is a block of Smalltalk code that is
executed dynamically to get the parameter value when the query is performed.
Cursor objects
Cursor objects are used to process a result set, which is the set of records
obtained by executing a query. When you work with cursors, the DBMS keeps
the result set. This allows ObjectStudio to work with one record at a time.
Cursors are useful when you are working with a large result set, enabling you to
read, update, and delete individual records.
Database User's Guide, P40-3203-03
Chapter: Overview of database support
Section: Database object framework
14
Database tools
ObjectStudio provides database tools for data definition and data
manipulation. Use these tools to work with application data after you define
the data access layer of an ObjectStudio application.
The database tools include:
♦
Database Notebook. Data management facility that builds a default form
for any Table or Query. Use the default form to perform data manipulation
and data entry. You can customize the form for inclusion into an end-user
application.
♦
SQL Editor. Graphical query builder that allows you to construct Query
objects. You can include the Query objects within an application
framework.
♦
Report Editor. Facility for creating database reports.
Database User's Guide, P40-3203-03
Chapter: Overview of database support
Section: Database tools
15
2
How ObjectStudio implements
database support
Introduction
This chapter describes the databases and the classes that ObjectStudio
supports. If you are using a database that is no longer supported by the
database vendor (for example, DB2 Database Version 2.1 or Sybase OpenClient
Version 10), refer to the ObjectStudio Release Notes, P40-3208.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Introduction
16
Supported databases
This section provides a brief overview of each database that ObjectStudio
supports. Specifications are supplied for each database, including:
♦
Loadable application (Package, if using the Repository)
♦
Subclass of Database
♦
Subclass of Table
♦
Subclass of Cursor
ObjectStudio uses a common object model to support DBMS and database
connections. The model implements abstract classes to support Databases,
Tables, Cursors, and Queries. Use these classes to create the database access
layer of an application.
Support for each database is implemented as a loadable application (or
package, if using the Repository). For more information on loading databases,
see “Loading external database support” on page 40.
ODBC database
Loadable
application/Package:
ODBC
Subclass of Database:
ODBCDatabase
Subclass of Table:
ODBCTable
Subclass of Cursor:
ODBCCursor
ODBCScrollableCursor
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Supported databases
17
Oracle database
Loadable
application/Package:
Oracle Database Client 8.1.5
Oracle Database Client 8.1.5 (ORACLE Mode)
Oracle Database Client 9.2
Oracle Database Client 9.2 (ORACLE Mode)
Oracle Database Client (OCI)
Subclass of Database:
OracleDatabase
Subclass of Table:
OracleTable
Subclass of Cursor:
OracleDatabaseCursor
OracleScrollableCursor
ANSI and Oracle Mode database wrappers. See “ANSI and Oracle Mode
loadable applications” on page 187 for information on:
♦
Oracle Database Client 8.1.5 loadable application vs. Oracle Database
Client 8.1.5 (ORACLE Mode) loadable application
♦
Oracle Database Client 9.2 loadable application vs. Oracle Database Client
9.2 (ORACLE Mode) loadable application
Oracle Database Client (OCI). For more information, see “Oracle OCI support”
on page 192. Version Note: Oracle 8.1.5 is the first Oracle release with which
the Oracle OCI database wrapper will work. However, the Oracle OCI database
wrapper should work with subsequent releases of Oracle.
Unsupported Oracle database wrappers that are still available as goodies.
Cincom has removed the following loadable applications from ObjectStudio’s
loadable application list:
♦
Oracle Database Client 7.3
♦
Oracle Database Client 7.3 (ORACLE Mode)
♦
Oracle Database Client 8.0
♦
Oracle Database Client 8.0 (ORACLE Mode)
Cincom no longer supports the databases wrappers loaded by these
applications. However, these loadable applications are still available in the
Goodies folder.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Supported databases
18
ADABAS database
Loadable
application/Package:
Adabas Database
Subclass of Database:
AdabasDatabase
Subclass of Table:
AdabasTable
Subclass of Cursor:
AdabasDatabaseCursor
AdabasScrollableCursor
IBM DB2 database
Loadable
application/Package:
DB2 Database Version 6.1
DB2 Database Version 6.1 (Cursor with Hold)
DB2 Database Version 7.2
DB2 Database Version 7.2 (Cursor with Hold)
Subclass of Database:
ESDatabase
Subclass of Table:
ESTable
Subclass of Cursor:
ESDatabaseCursor
ESScrollableCursor
“Cursor with Hold” loadable applications. According to the ANSI standard, a
database must close and destroy a Cursor when you perform a commit on the
database. However, when you use a “Cursor with Hold” loadable application
for DB2 6.1 or 7.2, DB2 can both keep open and update a database Cursor when
you perform a commit. When DB2 does this, you may see a performance
improvement over the ANSI standard behavior.
Unsupported DB2 database wrapper that is still available as a goody.
Cincom has removed the DB2 Database Version 5.0 loadable application from
ObjectStudio’s loadable application list. Although Cincom no longer supports
the database wrapper loaded by this application, this loadable application is
still available in the Goodies folder.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Supported databases
19
Microsoft SQL Server database
Loadable
application/Package:
MS SQL Server Database
Subclass of Database:
SQLServerDatabase
Subclass of Table:
SQLServerTable
Subclass of Cursor:
SQLServerDatabaseCursor
SQLServerScrollableCursor
You can use the “MS SQL Server Database” wrapper with SQL Server 6.5, 7.0,
or 2000. However, this wrapper supports SQL Server 7.0 and 2000 only at the
SQL Server 6.5 level. Cincom has not enhanced the Microsoft library, used by
ObjectStudio, for SQL Server 7.0 and 2000.
SYBASE OpenClient database
Loadable
application/Package:
SYBASE OpenClient Version 11.5
SYBASE OpenClient Version 12.5
Subclass of Database:
SybaseDatabase
Subclass of Table:
SybaseTable
Subclass of Cursor:
SybaseDatabaseCursor
SybaseScrollableCursor
Informix database
Loadable
application/Package:
Informix Client Version 7.12
Informix Client Version 7.3
Subclass of Database:
INFDatabase
Subclass of Table:
INFTable
Subclass of Cursor:
INFDatabaseCursor
INFScrollableCursor
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Supported databases
20
SUPRA SQL database
Loadable
application/Package:
SUPRA SQL 2720
SUPRA SQL 2800
SUPRA SQL 2900
Subclass of Database:
SupraDatabase
Subclass of Table:
SupraTable
Subclass of Cursor:
SupraDatabaseCursor
SupraScrollableCursor
UniSQL Server database
Loadable
application/Package:
UniSQL 3.5.3
Subclass of Database:
ORDBDatabase
Subclass of Table:
ORDBTable
Subclass of Cursor:
ORDBDatabaseCursor
ORDBScrollableCursor
Internal Database
Loadable
application/Package:
None (already loaded)
Subclass of Database:
InternalDatabase
Subclass of Table:
Not applicable
Subclass of Cursor:
Not applicable
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Supported databases
21
Database classes
The database classes have the following features:
♦
They implement methods that open cursors, execute SQL statements, and
begin and end transactions.
♦
They contain Table objects that represent each table within a database.
You can retrieve and manipulate these tables within ObjectStudio.
Database class hierarchy
The Database class hierarchy is:
Database (Abstract)
ExternalDatabase (Abstract)
ODBCDatabase
OracleDatabase
AdabasDatabase
ESDatabase
SQLServerDatabase
SybaseDatabase
INFDatabase
SupraDatabase
ORDBDatabase
LocalDatabase (Abstract)
InternalDatabase
The remainder of this section describes the classes in the Database class
hierarchy.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Database classes
22
Database class
The Database class is an abstract class, which defines the basic functions for its
subclasses. All subclasses of Database inherit the following features from
Database:
♦
Ability to track all accessible databases
♦
Logon and Logoff functions (if they are needed)
♦
Ability to track the database types that are loaded in ObjectStudio
An instance of the Database class:
♦
Contains instances of subclasses of class Table that represent each table in
the physical database.
♦
Executes an SQL string.
♦
Creates a cursor as part of executing an SQL SELECT statement (optionally).
The cursor, which is a direct connection to the result set, allows the user
to update the database.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Database classes
23
ExternalDatabase class
The ExternalDatabase class is an abstract class that implements features
specific to external databases. All external database classes are subclasses of
this class.
The main difference between the ExternalDatabase and LocalDatabase classes
is that ExternalDatabase passes SQL statements directly to the physical
database. The LocalDatabase class includes a query evaluator.
The ExternalDatabase class adds itself to the StartStopAnnouncementList global
variable when the class is loaded. If you then save this image with active
databases, ObjectStudio will try to reconnect to those databases on startup.
For details about how this is implemented, refer to the start and stop class
methods in the ExternalDatabase class. For more information about how
StartStopAnnouncementList can be used in ObjectStudio, refer to the
ObjectStudio User’s Guide, P40-3201.
Class ExternalDatabase uses the variable DataLoadLimit to restrict the number
of rows returned by an SQL query. The default maximum number of rows is
500. To change the value, send the setDataLoadLimitTo: class message.
ExternalDatabase allows you to use the Visible Tables feature to tell
ObjectStudio with which tables you want to work. You can use this feature
when the database has a large number of tables to prevent ObjectStudio from
querying the physical database to determine the name of each table. For more
information on this feature, see “Enhancing performance” on page 62.
ODBCDatabase class
The ODBCDatabase class implements the access layer for the complete
Microsoft ODBC Version 2.5 Application Programming Interface (API). It
provides you with easy access to the X/Open-compliant Call Level Interface
(CLI) to SQL databases and to Microsoft extensions to this standard, as specified
in the ODBC Version 2.5 specification document.
From ObjectStudio, you can use either high-level support or low-level support
for ODBC. High-level support works with the ODBCDatabase class. You may
want to use high-level support if you have already implemented database code
in ObjectStudio.
With low-level support, you program directly to the SQL Access Group (SAG)
CLI. For more information on low-level support, see “Low-level ODBC support”
on page 69.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Database classes
24
OracleDatabase class
The OracleDatabase class implements the access layer for Oracle databases. In
addition to the features it inherits, this class supports:
♦
Execution of PL/SQL blocks, stored procedures, and functions
♦
Ability to set the number of records retrieved using arrayFetch with
execSql: and loadSql:
♦
Ability to set the maximum number of characters returned for a LONG
column
♦
Logon methods and the name of an ObjectStudio Controller to use for
logging in to the database
♦
Ability to gain access to an instance of OracleDatabase on login
AdabasDatabase class
The AdabasDatabase class implements the access layer for ADABAS databases
using the Oracle API. See the preceding “OracleDatabase class” section for
access layer information.
ESDatabase class
The ESDatabase class implements the access layer for the IBM DB2 database. In
addition to the features it inherits, this class supports:
♦
Ability to execute stored procedures.
♦
Inserting the user ID and password in the class so that you can log in to the
database without using a login window. For NT servers, you must include
the user ID and password.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Database classes
25
SQLServerDatabase class
The SQLServerDatabase class implements the access layer for the Microsoft SQL
Server database. In addition to the features it inherits, this class supports:
♦
Ability to execute stored procedures and retrieve multiple result sets.
♦
Logon methods and the name of an ObjectStudio Controller to use for
logging in to the database.
With Microsoft SQL Server, you log in to a server rather than to a particular
database. All databases on that server become available through
ObjectStudio as instances of this class.
♦
A getServers method to return all known SQL Servers on the network. Each
of these servers is queried for their available databases. This method is
used primarily by the logon Controller.
SybaseDatabase class
The SybaseDatabase class implements the access layer for the SYBASE
OpenClient database. In addition to the features it inherits, this class supports:
♦
Ability to execute stored procedures and retrieve multiple result sets.
♦
Logon methods and the name of an ObjectStudio controller to use for
logging in to the database.
With SYBASE OpenClient databases, you log in to a server rather than to a
particular database. All databases on that server become available through
ObjectStudio as instances of this class.
INFDatabase class
The INFDatabase class implements the access layer for the Informix database.
In addition to the features it inherits, this class supports the ability to execute
stored procedures.
SupraDatabase class
The SupraDatabase class implements the access layer for the SUPRA SQL
database.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Database classes
26
ORDBDatabase class
The ORDBDatabase class implements the access layer for the UniSQL Server
database.
LocalDatabase class
The LocalDatabase class is an abstract class that implements features specific
to databases that require their own SQL query evaluator. LocalDatabase
implements the query evaluator as instance methods, which are inherited by
all its subclasses.
InternalDatabase class
The InternalDatabase class provides a mechanism for treating objects as if they
were tables. The Internal Database is extremely useful for prototyping when
you are developing an application. You can also use the Internal Database to
work with data that resides in more than one database.
The Internal Database, however, does not have the features of a real DBMS,
such as locking, facilities for multiple users, and transaction control. It also
does not save its data to files on disk. To interact with the Internal Database,
use the Database Notebook, as described in “Using the Database Notebook” on
page 203.
The InternalDatabase class supports a collection of instances of class Table. In
every ObjectStudio environment, there is a single instance of the
InternalDatabase class, called EnfinInternalDb. If an instance of class Table is a
member of this database, it can be included in SQL queries against the Internal
Database.
The InternalDatabase class implements the tableLocations variable. When an
instance of the InternalDatabase class is asked for a particular table, it first
looks to see if the table exists. If the table does not exist, it looks in
tableLocations to see if the table is referenced there. If it exists, it uses the
tableLocations variable to load a class that recreates the table. This variable
allows internal tables to be loaded on demand. ObjectStudio supplies several
example tables that work with the Internal Database and are handled this way.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Database classes
27
Table classes
There is a Table subclass for each type of supported database. For all
databases, each Table class maintains information about the external column
types supported by the database and can map the column types into
ObjectStudio objects. The Table instances for the Internal Database also
contain each table’s data.
The Table classes implement:
♦
The dbTablesAt: method, which retrieves a Table instance from its
associated database
♦
Methods that query for attributes, including column information and
records
♦
Methods that add, remove, and modify records directly
♦
Methods that handle SQL statements and cursors
Table classes allow you to link to tables using the Designer or using a
programmatic Model View Controller (MVC) interface.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Table classes
28
Table class hierarchy
The Table class hierarchy is:
Table (ObjectStudio Internal Table)
ExternalTable (Abstract Class)
ADABASTable
ESTable
INFTable
ODBCTable
OracleTable
ORDBTable
SQLServerTable
SupraTable
SybaseTable
VectorTable
The remainder of this section describes the classes in the Table class hierarchy.
Table class
The Table class is an internal ObjectStudio abstract class that supports a table
structure. It provides methods for table creation and modification, record
insertion, record deletion, and record modification. Tables can also be saved to
and loaded from disk. Subclasses of Table inherit its methods.
To create a Table, send the execSQL: method to an instance of class
InternalDatabase or ExternalDatabase. The method returns an instance of
Table.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Table classes
29
ExternalTable class
The ExternalTable class is an abstract class that provides the framework for
tables associated with objects of class ExternalDatabase. It also allows you to
manage cursors for use in all record access methods. To use the cursor
methods, you first must send the startAccessForUpdate: message.
The following table lists the subclasses of ExternalTable and the databases to
which they correlate:
Database
Subclass of ExternalTable
ADABAS
ADABASTable
DB2
ESTable
Informix
INFTable
ODBC
ODBCTable
Oracle
OracleTable
SQL Server
SQLServerTable
SUPRA
SupraTable
SYBASE
SybaseTable
UniSQL
ORDBTable
VectorTable class
The VectorTable class is a special type of internal table class that stores table
data by column rather than by row. VectorTable stores numeric columns as
vectors and stores nonnumeric columns as arrays. This strategy saves space
because numeric columns can be stored as single objects.
The interfaces to VectorTable and Table are nearly identical. Therefore, you
can use the two classes interchangeably. At times, using VectorTable is more
efficient because accessing data by row can be slower than accessing a Table
object. This is because the rows must be constructed as needed.
One way to create an instance of VectorTable is to use the return value (a
VectorTable) of loadSql: (a message that you send to an instance of Database).
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Table classes
30
Cursor classes
A cursor is a common DBMS mechanism that returns rows of a result set one
row at a time. The result set of a cursor exists on the DBMS. The ObjectStudio
Cursor classes allow the control of the cursor object (the result set) that
resides on the DBMS.
Usually, the cursor mechanism is vendor-specific. ObjectStudio Cursor classes
for different DBMSs operate in basically the same manner.
You open a cursor by sending a variation of the openCursor message to a
database and by providing an SQL SELECT statement. Once a cursor is open,
you can use it to position the current row in the result set, to update column
values for the current row, and to delete the current row.
For more information on using cursors, see “Working with cursors” on page 53.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Cursor classes
31
Cursor class hierarchy
The Cursor class hierarchy is:
Cursor (Abstract Class)
ExternalDatabaseCursor (Abstract Class)
AdabasDatabaseCursor
ESDatabaseCursor
ExtDbScrollableCursor (Abstract Class)
ADABASScrollableCursor
ESScrollableCursor
INFScrollableCursor
ODBCScrollableCursor
OracleScrollableCursor
ORDBScrollableCursor
SQLServerScrollableCursor
SupraScrollableCursor
SybaseScrollableCursor
INFDatabaseCursor
ODBCCursor
OracleDatabaseCursor
ORDBDatabaseCursor
SQLServerDatabaseCursor
SupraDatabaseCursor
SybaseDatabaseCursor
LocalCursor (Abstract Class)
The remainder of this section describes the classes in the Cursor class
hierarchy.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Cursor classes
32
Cursor class
The Cursor class is an abstract class that provides basic features for all
database cursors. The class keeps track of the query that created the cursor,
including its field names, types, and formats. It maintains a current position in
the result set, and it contains the necessary machinery for ObjectStudio
Designer MVC links.
Nonscrollable cursors
This section describes classes that implement nonscrollable cursors.
ExternalDatabaseCursor class
The ExternalDatabaseCursor class is an abstract class that implements features
for external database nonscrollable cursors. In addition to the features it
inherits, it implements features that:
♦
Add records
♦
Perform positioned updates and deletes
♦
Move the record pointer forward to the next record
Other nonscrollable cursor subclasses
The following table lists the subclasses of ExternalDatabaseCursor and the
databases to which they correlate. Each of these subclasses represents a
nonscrollable cursor.
Database
Subclass of ExternalDatabaseCursor
ADABAS
AdabasDatabaseCursor
DB2
ESDatabaseCursor
Informix
INFDatabaseCursor
ODBC
ODBCCursor
Oracle
OracleDatabaseCursor
SQL Server
SQLServerDatabaseCursor
SUPRA
SupraDatabaseCursor
SYBASE
SybaseDatabaseCursor
UniSQL
ORDBDatabaseCursor
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Cursor classes
33
Scrollable cursors
This section describes classes that implement scrollable cursors.
ExtDbScrollableCursor class
The ExtDbScrollableCursor class is an abstract class that implements features
for external database scrollable cursors. In addition to the features it inherits,
it implements features that:
♦
Add records
♦
Perform positioned updates and deletes
♦
Ask for the size of the result set
♦
Move the record pointer to any position in the result set
ODBCScrollableCursor class
The ODBCScrollableCursor class uses native scrollable cursors (that is, cursors
that are supplied by the database driver) if the data source offers the following
features:
♦
ODBC API call SQLExtendedFetch
♦
Two fetch options:
♦
-
SQL_FD_FETCH_NEXT
-
SQL_FD_FETCH_PREV
At least one of the following scroll options:
-
SQL_SO_KEYSET_DRIVEN
-
SQL_SO_DYNAMIC
-
SQL_SO_MIXED
Otherwise, ObjectStudio provides a simulated scrollable cursor, which is based
on native fetch-forward-only cursors. To determine whether the database
driver complies with the features described in the previous list, send the
message nativeScrollableCursors to class ODBCDatabase.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Cursor classes
34
Other scrollable cursor subclasses
The following table lists the subclasses of ExtDbScrollableCursor and the
databases to which they correlate. Each of these subclasses represents a
scrollable cursor.
Database
Subclass of ExtDbScrollableCursor
ADABAS
ADABASScrollableCursor
DB2
ESScrollableCursor
Informix
INFScrollableCursor
ODBC
ODBCScrollableCursor
Oracle
OracleScrollableCursor
SQL Server
SQLServerScrollableCursor
SUPRA
SupraScrollableCursor
SYBASE
SybaseScrollableCursor
UniSQL
ORDBScrollableCursor
LocalCursor class
The LocalCursor class is an abstract class that implements cursors for local
database cursors. The class implements methods that:
♦
Add records
♦
Perform positioned updates and deletes
♦
Move the record pointer to any position in the result set
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Cursor classes
35
Query classes
The Query classes provide a mechanism for saving SQL queries and linking to
them. You can implement the links either visually, by using the Designer, or
programmatically, by working with the MVC interface. You can pass a query
object to a database for execution or to open a cursor.
The Query class hierarchy is:
Query (Abstract Class)
SqlDirect
SqlParse (Abstract Class)
SqlDelete
SqlInsert
SqlSelect
SqlSubSelect
SqlUpdate
The remainder of this section describes the classes in the Query class
hierarchy.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Query classes
36
Query class
The Query class is an abstract class that implements the basic features of
queries. Primarily, it keeps track of all instances of its subclasses.
SqlDirect class
The SqlDirect class provides the ability to create an SQL object for a string that
cannot be parsed by ObjectStudio. This includes all non-ANSI-standard SQL
statements such as stored procedure access for SQL Server and PL/SQL for
Oracle. SqlDirect implements a creation routine, the new: class method, which
takes the SQL string as a parameter.
SqlParse class
The SqlParse class is an abstract class that provides features for all query types
that can be parsed by ObjectStudio. The class includes the query parser and
some default behavior.
To create an instance of SqlParse (or one of its subclasses), send the
parseString: class method. This method takes an SQL string and, depending on
the type of SQL statement, either generates an error or an instance of one of
the SqlParse subclasses.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Query classes
37
SQL Query classes
The following table lists the SQL Query classes and the SQL queries that they
represent:
Query class
Query type
SqlDelete
SQL DELETE
SqlInsert
SQL INSERT
SqlSelect
SQL SELECT
SqlSubSelect
SQL SUBSELECT
SqlUpdate
SQL UPDATE
Note the following about SQL Query classes:
♦
The easiest way to create an instance of each of these classes is to use the
SQL Editor, which is described in “SQL Editor” on page 220.
♦
You can create an SQL object by sending the parseString: message to the
Query class or to one of its subclasses. The parameter is an SQL string.
♦
To execute an SQL query, send execute to an instance of the Query class or
one of its subclasses.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Query classes
38
SqlSelect class
In addition to using the execute message, you can use one of the
“openCursor…” or “openScrollableCursor…” messages to pass an SQL SELECT
statement to a DBMS. You can also use the Designer to link to an SqlSelect
object.
You can associate a cursor with an SqlSelect instance. The first time the
startAccessForUpdate:scrollable: message is sent to an SqlSelect object, a
cursor is opened and returned. You can specify that a cursor is updateable or
scrollable in the original startAccess method, or you can change the cursor in
subsequent sends. The cursor is shared with all callers of the
startAccessForUpdate:scrollable: message.
Add dependencies to the cursor rather than to the SqlSelect object. This
ensures that all objects using the query are using a common cursor and that
updates to the cursor are reflected in all objects using it. A refresh message is
also supported by SqlSelect objects; it rebuilds the associated cursor and
updates all its dependencies.
SqlSubSelect class
Instances of the SqlSubSelect class provide for subselects within SQL
statements. Generally, they are used internally only within other SQL objects.
SqlUpdate class
Instances of the SqlUpdate class provide for the SQL INSERT statement. Use the
execSql: message to pass an SqlUpdate query to a database.
Database User's Guide, P40-3203-03
Chapter: How ObjectStudio implements database support
Section: Query classes
39
3
Working with databases
Introduction
This chapter provides information on techniques to use when you work with
databases. These techniques apply to all database platforms. Where
appropriate, there is additional information necessary for working with a
specific database.
Loading external database support
Before you can work with an external database, you must load an application
that supports access to a specific DBMS into the ObjectStudio environment.
The Internal Database is already loaded into the ObjectStudio environment. For
more information on the Internal Database, see “Internal Database” on page 21
and “InternalDatabase class” on page 27.
After loading the application that supports your underlying database, you have
complete access to the databases and tables associated with your database
management system (to the limits defined by your database administrator).
For a complete list of supported databases and gateways, see “Supported
databases” on page 17.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Introduction
40
To load a database application:
1. Ensure the external database is available, either locally or through a
network connection. (See your network administrator if you need help.)
2. Load the database application:
A. Display the Repository Explorer window by selecting
Repository ⇒ Explore from the Desktop menu.
B. From the Package pull-down list box, select the name of the package
that corresponds to the DBMS with which you want to work.
C. Select a version in the Versions area of the Repository Explorer
window.
D. Press mouse button 2 and select Load ⇒ Selected Version.
A. Display the Application dialog box by selecting File ⇒ Load application
from the Desktop menu.
B. From the Applications dialog box, select the name of the loadable
application that corresponds to the DBMS with which you want to work.
C. Click Load.
As the application loads, ObjectStudio:
♦
Creates the subclasses of Database, Table, Cursor, and Query for the
DBMS with which you are working
♦
Links to the dynamic link libraries (DLLs) that provide client support for
the DBMS
♦
Initiates the login procedure, if applicable, to the database
3. If a database logon interface appears, enter the requested information.
If your underlying database requires you to log on, ObjectStudio creates a
logon interface on the work area of the Desktop. The logon interface opens
automatically if you attempt to access the database without logging on.
To access your external database every time you start ObjectStudio, save
an image file after loading the application. For more information on saving
the ObjectStudio image, refer to the ObjectStudio User’s Guide, P40-3201.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Loading external database support
41
Connecting to a DBMS
This section describes how to log in to a DBMS from ObjectStudio. Logging in
involves identifying the server on which the database is installed and
initializing communications to that server.
Each database has its own login procedure. ObjectStudio provides methods that
you can use with most of the databases that ObjectStudio supports.
After you log in to a database, select the specific database that you want to
access. For a description of this process, see “Accessing a database” on
page 45.
You do not need to log in to the Internal Database. For more information on
the Internal Database, see “Internal Database” on page 21 and
“InternalDatabase class” on page 27.
Connecting options
There are two ways in which you can connect to a database:
♦
Programmatically
♦
With a controller
Connecting programmatically
You can log in to a database programmatically, without using the ObjectStudiosupplied login controller. To do so, use the Class Browser to search for the
login messages for the database you are using.
Connecting with a controller
For most DBMSs, you can display a login controller (a user interface) that
prompts for a user name, a password, and a server name.
ObjectStudio provides the following Database class methods that allow you to
work with a login controller for the DBMS with which you are working:
♦
hasLogonView. Returns a Boolean value indicating whether the database
has a controller for logging in associated with it.
♦
logonView. Returns the controller that allows a user to log in to a
database. Include this controller in the image that you create for the
application.
♦
initialize. Opens the login controller for the database. When the user
clicks OK on the controller, ObjectStudio logs the user in to the database.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Connecting to a DBMS
42
Database-specific connection information
Each database has a specific login procedure:
♦
Oracle. When you log in to an Oracle database, type an SQL*Net connect
string in the server entry field. If you do not provide an SQL*Net string, a
local connection is assumed.
♦
ADABAS. When you log in to an ADABAS database, type an SQL*Net
connect string in the server entry field. If you do not provide an SQL*Net
string, a local connection is assumed.
♦
IBM DB2. When you send the directory message to the ESDatabase class, it
returns an instance of the class ESDatabase for each database that has
been cataloged on the workstation. Only one of these databases can be
active at a time.
♦
SQL Server. The SQLServerDatabase class provides a getServers method
that returns a list of all SQL Servers available on the network. The login
controller uses this method to display a list of available servers. The login
controller provides a list of SQL Servers found only on Windows. For more
information, see “Looking for SQL Server databases” on page 196.
♦
SYBASE OpenClient. When you log in to a SYBASE OpenClient database,
enter the name of the SYBASE Server in the server entry field. You also
need to enter a user name and a password. The database name will be
case-sensitive.
♦
Informix. Informix-Online Workgroup Server must be installed either on
your computer or on another computer to which your computer is
connected over a network. Informix automatically verifies your user ID and
password. It uses the information you selected in the Informix client
software program SetNet32. After the Informix application is loaded, use
the ExternalDatabase>>accessName: method to establish a connection.
Here is an example that will connect to the ‘stores7’ database on server
‘demo’:
INFDatabase accessName: #'stores7@demo'.
If a connection fails, verify that the user ID and the password are defined
to the Informix Online Workgroup server with the required privileges.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Connecting to a DBMS
43
♦
SUPRA SQL. With SUPRA SQL database wrapper support, you can log on up
to eight databases concurrently. Each logon records the user name,
password, lock mode, and timeout values, which are used when
SupraDatabase objects are created (a connection to SUPRA SQL is
established when a SupraDatabase object is created). You can access
multiple databases by creating multiple SupraDatabase objects and
specifying a different database name for each SupraDatabase object.
Logging on to SUPRA SQL does not establish a connection to a SUPRA SQL
database. The logon only saves the user name, password, lock mode, and
timeout values for later use when a SupraDatabase object is created. If
multiple databases are used, a logon may be required before each
SupraDatabase object is created in order to specify these values for each
SUPRA SQL database.
The SUPRA SQL logon window allows the user name, password, lock mode,
and timeout values to be entered. Refer to the CONNECT statement section
in the SUPRA Server SQL Commands Reference Manual, P26-2420, for more
information on each of these variables.
♦
♦
UniSQL Server. Consider the following:
-
With UniSQL Server database wrapper support, you log in to one
database server at a time. This login records the user name and
password, which are used later when you access the database. If you
do not enter a user name and password, the UniSQL Server default user
name and a password are used.
-
From the UniSQL Server Logon window, you can reset the user name
and password back to the UniSQL Server default by pressing the OK
button without specifying a user name and password.
-
Sending the “directory” message to the ORDBDatabase class provides a
list of available databases you can access.
-
The database name will be case-sensitive.
Internal Database. You do not need to log in to the Internal Database.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Connecting to a DBMS
44
Accessing a database
This section describes how to select the specific database with which to work.
This process is also called making a database active. In programmatic terms,
when you access a database, ObjectStudio creates an instance of the
appropriate subclass of Database.
ObjectStudio allows you to access one database of a given type at a time.
However, you can access more than one database type at a time. For example,
you can access only one ODBC database at a time, but you can access an ODBC
database and an Oracle database simultaneously.
The subclasses of Database support the following class methods that help you
access a database.
accessName:
The parameter is an instance of class Symbol that represents the name of the
database you want to access. On success, the method returns an instance of
the appropriate subclass of Database. If the method is unsuccessful, it returns
an instance of Message, which contains an error message.
The accessName: method can place locks on data. After performing an
accessName:, you may want to perform the commit method to release those
locks. For more information on the commit method, see “Performing
transactions” on page 48.
directory
Returns an array of symbols representing names of available databases.
Usually, you develop an application that uses a specific database, so you do not
need to use this method. The Database Notebook is an example of an
application that uses this method.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Accessing a database
45
visibleTablesAt:put:
This method is implemented in ExternalDatabase and its subclasses.
Use this method when the application is working with a large database but only
needs to use some of the data. Perform this method before performing the
accessName: method to restrict the tables of a database with which
ObjectStudio interacts. You can also perform the method at any time to change
the visible tables for the database.
For example:
ExternalDatabase visibleTablesAt: databaseName
put: array
where:
databaseName is an instance of class Symbol that represents the database
with which you are working.
array is an array of instances of class Symbol that represent qualified or
unqualified table names. If the table names are not qualified, the current
user is assumed to own the table. If they are qualified, they should be in
the form:
#'owner.tablename'
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Accessing a database
46
The following table lists variations on the array parameter:
Variation
Array of
symbols
Use
Prevents catalog access to the database. It limits tables to
those listed in the array. Use this option before accessing the
database to set initial table access, or at any time to change
table access.
If the array includes an invalid table name, ObjectStudio
creates an empty table with the invalid name. If the Database
Notebook displays a table with no column names, or if you
attempt to access a table and receive a “Table not found”
message, check that all table names are specified or are
qualified correctly.
nil
Performs catalog access of the database. Instructs the system
to ignore the visible tables list.
{}
(empty
array)
Prevents catalog access and sets visibleTables to none. Use
this option when no Table objects are needed.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Accessing a database
If you are using execSql:, loadSql:, and cursors, exclusively,
you do not need access to Table objects. Table objects are
necessary only when you are linking to them, referring to
them in code, or using the ObjectStudio Table tools (for
example, the Database Notebook).
47
Performing transactions
ObjectStudio supports database transactions, which are units of work that the
database can either save or undo. Traditionally, a transaction is performed this
way:
1. Begin the transaction.
2. Perform the unit of work.
3. End the transaction (either save it or undo it). Ending a transaction can
release data locks.
Transactions in ObjectStudio have the following features and restrictions:
♦
You do not have to declare the beginning of a transaction. The exception to
this is SQL Server and SYBASE OpenClient support.
♦
You can perform several steps before you end the transaction.
♦
You cannot nest transactions.
Most database servers (except SQL Server and SYBASE OpenClient) do not
require that transactions be started explicitly.
ObjectStudio provides the following instance methods in class Database to
support transactions.
♦
beginTran. Begins a transaction. This method is required for SQL Server
and SYBASE OpenClient databases. It is implemented for other database
platforms but does nothing.
♦
commit. Ends a transaction by saving the work you did since the last
commit or rollback.
The accessName: and dbTablesAt: methods can place locks on data. After
performing these methods, you may want to perform the commit method
to release those locks.
♦
rollback. Ends a transaction by undoing the work you did since the last
commit or rollback.
Local databases and transactions. Local databases do not perform
transactions. For local databases, the transaction methods beginTran, commit,
and rollback are implemented but do nothing; they are provided for
compatibility with external databases.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Performing transactions
48
Using SQL to query databases
This section describes how to interact directly with a database through its SQL
interface.
Methods for executing SQL statements
ObjectStudio provides the following instance methods in subclasses of Database
that allow you to execute SQL statements on the DBMS:
♦
execSql: aString. Executes an SQL statement. The aString parameter is an
SQL string. The string can contain any statements that the target accepts.
For more information on creating an SQL string, see “Creating strings
containing SQL code” on page 51.
If the SQL statement is an INSERT statement, the method returns a small
integer representing the return code.
If the SQL statement is a SELECT statement, the result of the method is an
instance of Table. On some database platforms, an SQL statement can
contain multiple clauses. The return value of a multiple-clause statement
is an array of tables.
You can treat the resulting table like any other Table object in the
ObjectStudio environment. You can perform the following tasks with it:
-
Use the Table method interface.
-
Add the table to the Internal Database and perform subsequent SQL
statements on it. When you use this technique, subsequent SQL
statements are performed in memory and do not require additional
fetches from the original database.
-
Link to the table using ObjectStudio TableLinks.
The instance of Table has an instance variable, dbRecords, which is an
array. Each element of the array is also an array and represents a record in
the table:
{ {Row 1 elements} {Row 2 elements} ... }
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Using SQL to query databases
49
♦
execSql: aString onError: aBlock. Executes an SQL statement in the same
manner as execSql: but also allows you to specify a 1-parameter block. If
an error occurs during the execution of the SQL statement, ObjectStudio
passes the error code to the block and performs the code in the block.
♦
execSql: aString vars: vars. Executes an SQL statement (which cannot, in
this case, be a select statement) in the same manner as execSql: but also
allows you to specify parameters. These parameters must be bound for
execution. The vars array contains the string values to be bound to the SQL
statement.
Subclasses of ExternalDatabase that support execSql:vars:. Only two
subclasses of ExternalDatabase, ESDatabase and OracleDatabase, really
support execSql:vars:. Calling this method from other subclasses of
ExternalDatabase will result in an error.
♦
loadSql: aString. Executes an SQL SELECT statement in the same manner
as execSql: and returns an instance of the class VectorTable. VectorTable is
a special type of internal table that stores table data by column rather
than by row. The dbRecords instance variable has the following format:
{ {Column 1 elements} {Column 2 elements} ... }
VectorTable provides an interface that is almost identical to that of
internal tables, so that you can use the two interchangeably. The
advantage of using a VectorTable is that it stores numeric columns as
vectors, rather than as arrays. VectorTable is efficient for dealing with
numeric data, because a numeric column is one object.
However, VectorTable is slower than regular Tables for working with
individual rows. To work with a row in a VectorTable, ObjectStudio must
select one element from each column array or vector.
♦
loadSql: aString onError: aBlock. Executes an SQL SELECT statement in
the same manner as loadSql: and returns an instance of the class
VectorTable. It also allows you to specify a 1-parameter block. If an error
occurs during the execution of the SQL statement, ObjectStudio passes the
error code to the block and performs the code in the block.
♦
setDataLoadLimitTo:. Sets the maximum number of rows to return from
an SQL SELECT statement by assigning a value to the variable
dataLoadLimit. The default value is 500.
This method is for subclasses of ExternalDatabase only.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Using SQL to query databases
50
Creating strings containing SQL code
The first parameter to the execSql: or loadSql: methods is a string containing
SQL code. This section provides information about creating an SQL string.
Using standard SQL
Recall that some database platforms allow variations in SQL code. If you are
writing SQL code that you may want to use on more than one database
platform, remember to write SQL code that is standard across platforms.
Creating the string
An SQL string is a standard Smalltalk string that you create by using standard
string-construction methods, for example:
str := 'EXEC SQL' + ' SELECT *'
Specifying parameters
Database platforms can have different requirements for specifying certain
types of data. For example, the format for specifying a date within an SQL
statement is different for each database platform.
Use the method asDBStringFor: to format data into SQL strings for each
supported database. When you use this method, you ensure platform
independence in the application you are creating. You also ensure that the
format of data is acceptable to the database.
Use the asDBStringFor: method to format each parameter of an SQL statement.
For example, the following code creates and executes an SQL SELECT
statement with a date that is formatted correctly for a specific database:
result := db execSql:
'select * from Employees where bDate =' +
(myDateObj asDBStringFor: db).
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Using SQL to query databases
51
Using SQL versus using cursors
When you use the execSql: or loadSql: methods, the entire result set resides in
memory on the system where the application is running. Result sets containing
a large number of records can cause poor performance.
If an SQL SELECT statement might return a large result set, consider using
cursors instead of the direct SQL methods. When you work with cursors, the
result set resides on the system with the database, and the system running the
application loads only one record at a time. For more information on cursors,
see “Working with cursors” on page 53.
Executing SQL with a local database
Local databases use the ObjectStudio SQL evaluator, implemented in the
LocalDatabase class. The evaluator supports standard SQL for SELECT, UPDATE,
INSERT, and DELETE statements.
The following are not supported:
♦
Table aliasing
♦
SUBSELECT statements
♦
Expressions in SELECT clauses
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Using SQL to query databases
52
Working with cursors
Cursors are more efficient than SQL statements because they do not load the
entire result set at one time. They are also useful for maintaining a connection
to a database for a positioned UPDATE. The result set stays on the DBMS and
allows ObjectStudio to work with one record at a time.
When you update a field for the current row of a cursor, the data in the
database is also updated. In this way, ObjectStudio maintains consistency
between the data on the application system and the data in the database.
Data format returned
Cursors usually return data in dictionaries where each key is a column name
and each value is the column data for that column.
Cursor messages
Cursors have the same field type and format information as Tables, and cursors
and tables respond to many of the same messages.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Working with cursors
53
Methods for cursor support
ObjectStudio provides the following methods to support cursors:
♦
asInternalTable. Converts a cursor into an internal table. This message
creates an instance of class Table and fetches all of the data from the
cursor into the rows of the new table.
♦
close. Closes a cursor and releases the system resources the cursor was
using.
♦
copy. Creates a copy of a record in a result set so you can save that
record. For example:
myRecord := cursor next copy.
♦
next. Returns the next record in the result set.
♦
openCursorSql: aString forUpdateOf: anArray. Creates a nonscrollable
cursor that returns an instance of class Cursor. The aString parameter is an
SQL string, and anArray is an array of field names if the SQL statement is
an UPDATE statement. Otherwise, it is nil. For more information on SQL
strings, see “Creating strings containing SQL code” on page 51.
If the method fails, it returns an instance of Message, which contains an
error message.
♦
openScrollableCursorSql: aString forUpdateOf: anArray. Identical to
method openCursorSQL:forUpdateof: except that it creates a scrollable
cursor. You must create a scrollable cursor if you are working with tabular
list boxes or reports with header totals.
♦
position. Returns an integer representing the current position in the result
set.
♦
previous. Returns the previous record in the result set. This method is for
scrollable cursors only.
♦
setPositionTo: anInteger. Sets the position of the cursor to a specific
record location in the result set specified by anInteger and resets the value
of the record instance variable.
♦
size. Returns an integer representing the number of records in the result
set. This method is for scrollable cursors only.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Working with cursors
54
Types of cursors
ObjectStudio supports two types of cursors:
♦
Nonscrollable cursors. Can move only forward in a result set. They can
never move backward over a result set. Nonscrollable cursors also are
called “normal” or “forward-fetching” cursors.
♦
Scrollable cursors. Can move forward or backward in a result set. They
allow you to position the cursor at any record in the result set. Note that
scrollable cursors require more system resources than nonscrollable
cursors.
In most cases, scrollable cursors are supported by means of their native
database implementation. When the support is not native, using scrollable
cursors can be far less efficient than using nonscrollable cursors.
When you create a cursor, ObjectStudio creates an instance of class Cursor and
allocates an instance variable record. The record variable is an instance of
class Dictionary, which holds the current record in the result set.
Using cursors with ODBC
To allow the user to update ODBC cursors, the database driver must conform
with ODBC SQL core grammar and API Level 1 (positioned UPDATE and DELETE).
The database driver must also support at least two concurrently opened
statements per connection. (For example, the Microsoft SQL Server driver
supports only one open statement per connection and does not support
positioned UPDATE and DELETE.)
For more information on using cursors with ODBC, see “Cursors and scrollable
cursors” on page 80.
Using cursors with SQL Server
SQL Server supports updateable cursors only for single table queries against
tables that have a timestamp column and a unique index.
Using cursors with Informix
Informix supports updateable cursors only for single table queries.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Working with cursors
55
Selecting multiple tables to create a cursor, in all databases
except UniSQL
This section applies to all databases except UniSQL.
If you select multiple tables to create a cursor: in the result set, any column
name that is shared by two or more tables will be prefixed by the name of its
respective table.
For example, consider tables Customer and User. Table Customer contains
columns Name and ID, and table User contains columns Name and Address. You
select both tables Customer and User, and in the result set:
♦
Column Name from table Customer will be referred to as Customer.Name.
♦
Column ID from table Customer will be referred to as ID.
♦
Column Name from table User will be referred to as User.Name.
♦
Column Address from table User will be referred to as Address.
If you attempt to access a shared column (such as Name) without using its
qualified name (such as User.Name), you will receive the following error:
“Column name ambiguously defined.” However, non-shared column names
(such as ID) will not have appended table names. If you attempt to access a
non-shared column name (such as ID) using a qualified column name (such as
User.ID), you will receive nil.
For more detailed information, refer to the online method reference.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Working with cursors
56
Selecting multiple tables to create a cursor, in UniSQL
This section applies only to UniSQL.
If you select multiple tables: in the result set, every column name will be
prefixed by the name of its respective table, regardless of whether it is shared
by two or more tables.
For example, consider tables Customer and User. Table Customer contains
columns Name and ID, and table User contains columns Name and Address. You
select both tables Customer and User, and in the result set:
♦
Column Name from table Customer will be referred to as Customer.Name.
♦
Column ID from table Customer will be referred to as Customer.ID.
♦
Column Name from table User will be referred to as User.Name.
♦
Column Address from table User will be referred to as User.Address.
If you attempt to access any column (such as Name) without using its qualified
name (such as User.Name), you will receive the following error: “Column name
ambiguously defined.”
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Working with cursors
57
Working with tables
Use Table objects when you need to fetch information about field names or
field types before you can perform a query. This can happen if the table has
variable data, or if you have an application like the Database Notebook that
looks up table structures before displaying them.
Subclasses of the Database class support the following methods for working
with tables:
♦
add: anArray. Inserts a record into a table. The parameter anArray is an
array that contains one element for each field. The order and type of
parameters in the array must match those in the table exactly.
♦
dbTables. Returns an instance of class Dictionary of all of the tables in a
database. The keys represent the names of tables. The values are the
database tables. Performing this method can be time-consuming.
♦
dbTablesAt: aTable. Returns a table. The parameter aTable is an instance
of class Symbol that is the name of the database table.
Releasing data locks with the commit method. The dbTables and dbTablesAt:
methods can place locks on data. After performing one of these methods, you
may want to perform the commit method to release those locks. For more
information on the commit method, see “Performing transactions” on page 48.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Working with tables
58
Linking to cursors and tables
You can create a link to a table or a cursor, either graphically, using the
Designer, or programmatically, using the MVC link interface.
To learn more about using the Designer to create links and about MVC, refer to
ObjectStudio User Interface Guide, P40-3205.
Types of links
ObjectStudio supports the following link types. To understand them, consider
the example of linking a form item to a table.
♦
Normal. If you create a normal link, the contents of the form item change
in response to a change in the table.
♦
Update. If you create an update link, the contents of the table change in
response to a change in the form item.
Two objects can have a normal link and an update link between them, so that
updates in either object affect the other object.
This section describes how to use the MVC link interface to set up links
programmatically.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Linking to cursors and tables
59
Creating a normal link
If you want an object (for example, a form item) to be notified whenever a
table or cursor changes, add the object as a dependent of the table or cursor.
When an object changes, ObjectStudio sends the changed message to all of the
object’s dependents.
To set up an object to receive changed messages from a table or cursor object:
1. Add the object as a dependent of the table or cursor object by sending one
of the following messages:
objLinkedTo addDependent: self.
objLinkedTo addDependent: self
field: #fieldName.
In the second message, the object is notified only when the specified field
changes.
2. Implement the following method, which is called every time the linked-to
object changes:
update: objLinkedTo with: field with: position
with: type
The following table describes the parameters in the previous example:
Parameter
objLinkedTo
field
position
type
Description
The object that is changed.
The field that is changed or the symbol #All.
The current row position of objLinkedTo.
The type of change that occurred, as indicated by one
of the following symbols:
#Add
A row was added at this position.
#All
Assume that the whole table may have
changed.
#Position
The position has changed.
#Remove
The old row at this position has been
removed.
#Value
The value for this field or row has
changed.
3. Start access to the object linked to by sending the following message:
objLinkedTo startAccessUpdateDependent: self
field: fieldName.
This initializes the object for access, if needed, and sends your object the
first update:with:with:with: message, as described in step 2, with the field
you pass in and a type of #All.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Linking to cursors and tables
60
Removing a dependency
To remove an object from the dependency list of another object, send the
following message:
objLinkedTo removeDependent: self.
Stopping access
To stop access, send the following message:
objLinkedTo stopAccess.
Creating an update link
This section shows how to add an update link so that when an object changes,
a dependent table or cursor changes accordingly.
To add a table or cursor as a dependent of another object:
1. Add the table or cursor as a dependent of the object by sending one of the
following messages:
myObject addDependent: tabOrCursObj.
myObject addDependent: tabOrCursObj
field: #fieldName.
In the second message, the table or cursor is notified only when the
specified field changes.
2. When myObject changes, it should send the changed message to itself. The
changed method is implemented in class Object, so all objects inherit it.
Its interface is:
changed: position type: type
The following table describes the parameters in the previous example:
Parameter
position
type
Description
The new position if type is #Position.
If type is #Value, the position at which the value is
changed (the current position).
It is either #Position or #Value. If it is #Value, the
following message is sent to the object:
valueAtField: fieldName
You must implement the changed method to provide the new value to the
dependent object.
Removing a dependency
To remove an object from the dependency list of another object, send the
following message:
myObject removeDependent: tabOrCursObj.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Linking to cursors and tables
61
Enhancing performance
It is important to use techniques that enhance performance when you work
with databases and ObjectStudio. You should:
♦
Restrict the tables that are loaded into memory when you access a
database by performing the visibleTablesAt:put: method.
♦
Use cursors to work with one record at a time instead of executing an SQL
statement. When you execute an SQL statement, you work with an entire
result set. For more information, see “Using SQL versus using cursors” on
page 52.
Handling errors
When an error occurs, nearly all ObjectStudio database methods return
instances of class Message, which contain the error message. The exceptions
are the execSql:onError: and loadSql:onError: methods. For more information
on these methods, see “Using SQL to query databases” on page 49.
Each database uses a set of numeric return codes specific to that database. All
but two of these codes are passed directly through ObjectStudio without
translation. For all database types, ObjectStudio intercepts and translates the
two numeric codes described in the following table:
Code
Description
100
End-of-fetch condition for cursors.
16000
The data load limit has been exceeded while processing either
an execSql: or a loadSql: message.
You can retrieve the last error message processed by a database or cursor
instance at any time by performing the message method. This method returns a
Message object containing the text of the last error that occurred.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Enhancing performance
62
Packaging applications
This section describes techniques to use when you are packaging an application
with database support for delivery to users.
Including login controllers in the image
When you create an image for an application containing database support,
include login controllers for any databases that the application can use. The
logonView method returns the login controller for a specific database.
To suppress login controllers in a program-generated application, create a
secondary class file (or class extension, if using the Repository) for the
appropriate database class, and add the following class method:
hasLogonView
^ false.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Packaging applications
63
Delaying initialization of the DLL
This section describes a technique that delays initializing the database DLL
until the user actually starts to use the database.
This technique is useful when you want to allow a user to use any of several
databases, but you are not sure which databases are loaded on the user’s
system.
Loading DLL support
Recall from “Loading external database support” on page 40 that when you
load a database application, ObjectStudio loads support for the database DLL.
ObjectStudio performs the initModule method, which loads the DLL and makes
ObjectStudio aware of the procedures defined in the DLL.
Default DLL support in images. One step in packaging an application is to
create an image. By default, if you create an image for an application that
works with a database, ObjectStudio performs the initModule method when the
user starts the application.
Delaying initialization
To delay initialization of database DLLs, do the following after loading the
database application and before creating the application image:
1. Find the name of the loaded database DLL (the module) in
ModuleDictionary, which is a global variable.
2. Send the freeModule message to the module.
3. Remove the module from ModuleDictionary.
4. Add code to the application that sends the initModule class message to the
database’s subclass of Database when the user starts to use the database.
You can now save the image.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Packaging applications
64
Delaying a database login
This section describes a technique that delays logging in to a database.
Default login
By default, when you create an image for an application that works with a
database, ObjectStudio adds the database to the global variable,
StopStartAnnouncementList. When the user starts the image, ObjectStudio tries
to log the user in to the database. If the database is still open when the user
closes ObjectStudio, StartStopAnnouncementList closes the database.
Overriding default login behavior
You may want to control when the user logs in to a database. One reason to use
nondefault login behavior is to save system resources—maintaining an idle
connection to a database can use system resources.
To stop the default login behavior, remove the subclass of Database from the
StartStopAnnouncementList global variable and use one of the login techniques
described in “Connecting to a DBMS” on page 42. For more information about
how StopStartAnnouncementList is used in ObjectStudio, refer to the
ObjectStudio User’s Guide, P40-3201.
Database User's Guide, P40-3203-03
Chapter: Working with databases
Section: Packaging applications
65
4
ODBC
Introduction
This chapter describes how the support for ODBC differs from the standard
ObjectStudio database support.
ODBC elements
To understand how to work with ODBC from ObjectStudio, you must know
about three important ODBC elements:
♦
Environment. The environment establishes the link between the
application (ObjectStudio) and the ODBC run-time system. An application
usually has one environment link to the ODBC system.
♦
Connection. An application uses one or more connections. Each
connection is a communication channel to a DBMS and references a
particular driver and data source combination. The connection makes it
transparent to the application whether data access is local or remote. The
database driver in use determines whether multiple connections to the
same data source are allowed at one time.
♦
Statement. A statement holds all of the information required to execute
an SQL command and to process its results. A statement exists in the
context of a connection. A connection can have multiple active statements
at one time.
For SQL SELECT commands, a statement behaves like an embedded SQL
cursor. It provides you with a movable pointer into a derived table, by
which the application can retrieve, update, and delete rows. For more
information on ODBC cursors, see “Cursors and scrollable cursors” on
page 80.
Determining maximum active statements per connection. The database
driver determines the maximum number of active statements per
connection.
Minimum active statements for UPDATE and DELETE. A minimum of two
active statements is required to perform positioned UPDATE and DELETE
SQL statements.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Introduction
66
ODBC conformance levels
ODBC drivers can be classified according to their ODBC conformance levels. A
“conformance level” refers to a general set of capabilities an ODBC database
driver supports. Microsoft defines two areas that have levels of ODBC
conformance:
♦
Application Programming Interface (API)
♦
SQL grammar and corresponding ODBC SQL data types
The conformance level of the API can differ from the conformance level of the
SQL grammar for a particular driver.
API conformance levels
A database driver conforms to an API level if it supports all of the functions
defined for that level. ODBC defines three API conformance levels:
♦
Core level. The ODBC core-conformance level is identical to the SAG CLI
(SQL Access Group Command Language Interpreter) specification.
Therefore, a core-level-compliant driver is automatically a SAG CLIcompliant driver. The classes SAGSqlConnection and SAGSqlStatement
implement the core-level API functionality.
♦
Level 1. ODBC Conformance Level 1 implements extensions specific to
Microsoft, providing the developer with information about the driver, data
source, and DBMS in use for a particular connection. It supports functions
providing basic data-catalog access for database objects such as tables,
views, columns, and synonyms. It also adds more convenient ways to
connect to a data source.
Level 1 extensions are proprietary extensions of Microsoft and are not
standardized.
♦
Level 2. ODBC Conformance Level 2 adds functions providing extended
data catalog access for key data (primary, foreign, and index keys), data
describing stored procedures and their parameters, and user access rights.
Also, block data fetching and scrollable cursors are supported.
Level 2 extensions are proprietary extensions of Microsoft and are not
standardized.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: ODBC conformance levels
67
ODBC SQL grammar conformance levels
ODBC defines the following SQL grammar conformance levels:
♦
Minimum SQL grammar. Minimum functionality includes the CHAR data
type only, and the basic Data Definition Language (DDL) and Data
Manipulation Language (DML) SQL statements.
♦
Core and extended SQL grammar. The core and extended SQL grammar
conformance levels add more of the following:
-
DDL statements
-
Data types
-
DML statements (such as outer JOIN)
Most important are the positioned UPDATE and DELETE statements for
cursors.
A useful database driver should support at least the core SQL grammar.
Most drivers do.
ObjectStudio supports all ODBC conformance levels
ObjectStudio ODBC support implements the entire Microsoft ODBC Version 2.5
API. Therefore, it conforms to all ODBC API and SQL grammar conformance
levels.
ObjectStudio ODBCDatabase and driver conformance-level
dependencies
The ODBCDatabase class is a layer implemented on top of the ODBC class
library and generally works with every ODBC driver. Depending on the driver,
the ODBCDatabase class can make use of concepts such as true scrollable
cursors, Binary Large Objects (BLOBs), stored procedures, and parameterized
SQL statements.
If you are processing large volumes of data, choose an ODBC database driver
that is at least API Level 1 and core SQL grammar compliant. Otherwise,
portions of the ObjectStudio external database support will not be available.
For example, the data manager will show up in read-only mode and cursors
cannot be updated.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: ODBC conformance levels
68
Low-level ODBC support
Low-level ODBC support allows you to program directly to the industry standard
CLI for SQL data access, as defined by the SQL Access Group (SAG) and X/Open.
(The Microsoft ODBC core set of API calls is a full implementation of the SAG
CLI.)
Low-level support has the following features:
♦
Binds you to the Microsoft Windows operating system. (The SAG CLI is
widely accepted and is the emerging API standard.)
♦
Handles two-phase commit-related issues (not supported in Microsoft’s
ODBC implementation) in distributed environments.
♦
Allows you to specialize code (for example, you can prepare a statement),
and offers additional features not available with high-level support (for
example, asynchronous execution of statements).
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Low-level ODBC support
69
Additional ODBC classes
ObjectStudio support for ODBC provides the following classes in addition to
those described under “How ObjectStudio supports databases” on page 12:
♦
Class SAGSqlConnection and its subclass ODBCConnection. These classes
implement SAG CLI or ODBC compliant connections.
Class SAGSqlConnection uses the class variable henv to implement the link
to the ODBC system. ObjectStudio establishes the link at load time of the
class library and releases it at normal program-termination time.
♦
Class SAGSqlStatement and its subclass ODBCStatement. These classes
implement SAG CLI or ODBC compliant statements.
Because ODBC is an extension to the SAG CLI, the basis of the implementation
is made up of the four classes shown in the following figure. Most of the
methods found in the classes map almost one-to-one to the SAG CLI API
function calls.
Has Active Statements
SAGSqlConnection
SAGSqlStatement
ResultSetColumns
Has lastError
Input
Parameters
Has lastError
SAGSqlError
SAGSqlColumnDescription
The ODBCConnection and ODBCStatement classes implement the Microsoftspecific extensions of the SAG CLI. Therefore, they are subclasses of
SAGSqlConnection and SAGSqlStatement as shown here:
Has Active Statements
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Additional ODBC classes
SAGSqlConnection
SAGSqlStatement
ODBCConnection
ODBCStatement
70
Typical session
The following steps illustrate a typical ODBC support session with ObjectStudio:
1. Allocate the environment by initializing the ODBC interface and allocate
the environment handle.
2. Allocate a connection handle.
3. Connect to a database.
4. Allocate statements.
5. Process statements.
6. Receive results.
7. Free statements.
8. Disconnect from the database.
The environment handle is freed only when you exit ObjectStudio.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Typical session
71
Example. The following example shows how the basic elements are
implemented using ObjectStudio’s ODBC support:
" establish a connection to a data source "
c := ODBCConnection connect: #sample uid: #admin pwd: #school.
" open a statement within the scope of the connection c "
s := c addStatement.
" prepare the statement "
s prepare: 'select * from Student'.
" assign a cursor name to the statement (optional) "
s setCursorName: #StudentCursor.
" send the statement to the data source for execution "
s execute.
" fetch one record of the result set at a time and show them in
the System Transcript window "
[s fetch == 0] whileTrue: [
s recordAsArray out.
].
" close the statement (optional, because the following command
implicitly does it) "
s close.
" delete the statement from the collection of known statements
for the connection "
c removeStatement: s.
" disconnect from data source "
c disconnect.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Typical session
72
Data type mapping
ODBC support maps ODBC data types to ObjectStudio classes and vice versa.
The following table shows these mappings:
ODBC type
Type #
Smalltalk class
SQL_CHAR
1
Symbol
SQL_NUMERIC
2
Decimal
SQL_DECIMAL
3
Decimal
SQL_INTEGER
4
LongInteger
SQL_SMALLINT
5
SmallInteger
SQL_FLOAT
6
Float
SQL_REAL
7
Float
SQL_DOUBLE
8
Float
SQL_DATE
9
Date
SQL_TIME
10
Time
SQL_TIMESTAMP
11
Timestamp
SQL_VARCHAR
12
Symbol
SQL_BIT
−7
Boolean
SQL_BIGINT
−5
LongInteger
SQL_TINYINT
−6
SmallInteger
SQL_LONGVARCHAR
−1
ODBCBlob
SQL_BINARY
−2
ByteArray
SQL_VARBINARY
−3
ByteArray
SQL_LONGVARBINARY
−4
ODBCBlob
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Data type mapping
73
System catalog access
Methods in class ODBCTable can retrieve primary key, unique key, foreign key,
and index key information from the system catalog. These methods return
values only for drivers conforming to ODBC API Level 2. If the drivers do not
conform to Level 2, empty IdentitySets are returned.
The following table lists the retrieval instance methods in class ODBCTable:
Method
Returns
primaryKey
The primary key (a specially marked unique key)
uniqueKeys
All unique keys
foreignKeys
All foreign keys
indexKeys
All index keys
Each method in the previous table returns an IdentitySet of the key objects
defined for the Table object. The following key object class hierarchy exists:
Class
Description
ExternalTableKey
Abstract class describing keys
ExternalTableIndexKey
Index key
ExternalTableUniqueKey
Unique keys
ExternalTableForeignKey
Foreign key
Because the primary key of a table is a specially marked unique key, no
separate class exists that describes primary keys. Instead, class
ExternalTableUniqueKey has an instance variable indicating whether or not the
unique key is also the primary key of the table.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
74
Example of using stored procedures
This section provides an example of how to use a stored procedure with ODBC
and SQL Server.
1. Create a stored procedure for SQL Server (authors and titles are existing
database tables in the database). For example:
create procedure showall
as select * from authors
select * from titles
2. Retrieve all records returned by a call to the stored procedure showall. For
example:
" establish a connection to a data source "
conn := ODBCConnection connect: #'pubs' uid: #sa
#xy.
pwd:
" open a statement within the scope of the connection "
s := conn addStatement: '{call showall}'.
" set initial value to true for the flag identifying whether
there are more result sets"
moreResultSets := true.
" get result sets one at a time; loop through the records in
the result set and display each record in the System
Transcript window "
[moreResultSets] whileTrue: [
" fetch the first record in a result set "
rc := s fetch.
[rc == 0] whileTrue: [
" display a record in the System
Transcript window "
s recordAsArray out.
" fetch the next record "
rc := s fetch.
].
" check if there is another result set
available "
moreResultSets := s prvMoreResults == 0.
].
" close a statement "
s close.
" disconnect from data source "
conn disconnect.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
75
Parametric SQL statements
ODBC support includes the ability to use parametric SQL statements.
Parametric statements improve performance, depending on whether the driver
compiles the access plan at preparation time.
Parameter descriptors
Formal parameters are represented by the question mark (?) and are
substituted at run time using the actual parameter values. Define a parameter
descriptor for each parameter. The descriptor sets the ODBC data type, scale
and precision, and holds the actual value of the parameter at run time. To
describe a parameter:
p := SAGSqlColumnDescriptor type: aType precision: aPrec scale:
aScale nullable: aBool.
…where aType must be one of the ODBC data-type integer values described in
“Data type mapping” on page 73.
Some drivers determine the type of parameters and provide those values using
the API (for example, Watcom SQL 3.1). In this case, the following method asks
the driver to return the parameter descriptor:
p := stmt describeParam: 1.
Checking to see if the driver supports this function. The program should
always determine whether the driver supports this function (see the examples
later in this section) before sending this method.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
76
Automatic data-type conversion of parameter values
Although the data type specified in the class method
type:precision:scale:nullable must match the data type of the table column
exactly, ObjectStudio converts actual parameter values at execution time.
The following table describes the data types and the conversion that
ObjectStudio performs:
Data type
Action
SQL_TIMESTAMP
Accepts Timestamp, Date, or Time
objects. If a Date object is passed, the
time component is set to 12:00. If a
Time object is passed, the Date
component is set to 1900-1-1.
SQL_DATE
Accepts Date and Timestamp objects.
If a Timestamp object is passed, the
time component is ignored.
SQL_TIME
Accepts Time and Timestamp objects.
If a Timestamp object is passed, the
date component is ignored.
SQL_CHAR SQL_VARCHAR
Accepts Strings, Symbols, and any type
of object responding to the asString
method.
SQL_DOUBLE SQL_REAL SQL_FLOAT
Accepts any object responding to the
asFloat method.
SQL_BIT
Sets the parameter to false unless it is
the true object.
SQL_INTEGER SQL_BIGINT
Accepts any object responding to the
asInteger method.
SQL_SMALLINT
Accepts any object responding to the
asInteger method that results in a
SmallInteger object after conversion.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
77
Examples of parameterized INSERT statements
Consider the following:
♦
The following example shows how to use a parameterized INSERT
statement:
" establish a connection to a data source "
conn := ODBCConnection connect: #ODBCTest uid: #OSTUDIO pwd:
#OSTUDIO.
" open a statement within the scope of the connection"
(stmt := conn addStatement) notNil ifTrue: [
" prepare the statement "
stmt prepare: 'insert into ss2 (f1) values (?)'.
" check whether describe parameter function is supported by a
driver "
(conn functionSupported:
#SQL_API_SQLDESCRIBEPARAM) ifTrue: [
" call describe parameter function "
p1 := stmt describeParam: 1.
] ifFalse: [
" describe parameter explicitly "
p1 := SAGSqlColumnDescriptor type: 1
precision: 30 scale: 0 nullable: true.
].
" set parameter description "
stmt setParamDescr: 1 to: p1.
1 to: 20 do: [ :idx |
" set parameter value "
p1 value: 'Record' ++ idx.
" send the statement to the data source
for execution "
stmt execute.
].
" remove statement from the collection of
known statements for a connection "
conn removeStatement: stmt.
" commit a connection "
conn commit.
].
" disconnect from data source "
conn disconnect.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
78
♦
The following example shows how to use a parameterized SELECT
statement:
" assign parameter value with wildcard "
p1val := 'S%'.
" establish connection to a data source "
conn := ODBCConnection connect: ''.
" open a statement within the scope of the connection "
stmt := conn addStatement.
" prepare the statement "
stmt prepare: 'select * from Student where Surname like ?'.
" describe parameter to a statement explicitly "
p1 := SAGSqlColumnDescriptor type: 1 precision: 30 scale: 0
nullable: true.
" set parameter description "
stmt setParamDescr: 1 to: p1.
" bring up a pop-up menu to enter/edit the parameter
value; loop while value is being changed "
[(rc := p1val editIn: nil) ~~ p1val] whileTrue: [
" get the user entered value "
p1val := rc.
" set parameter value "
p1 value: p1val.
" send the statement to the data source
for execution "
stmt execute.
" fetch a statement in a loop "
[stmt fetch == 0] whileTrue: [
" display record in System Transcript"
stmt recordAsArray out.
].
" close a statement "
stmt close.
].
" remove a statement from the collection of known
statements for a connection "
conn removeStatement: stmt.
" disconnect from data source "
conn disconnect.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
79
Cursors and scrollable cursors
For SQL SELECT commands, the statement replaces the concept of an
embedded SQL cursor. Each statement used for an SQL SELECT command has a
name that the application can use to reference it. Each name within a given
connection is unique. Before executing the SELECT statement, an application
can specify a name to keep the system from generating a name. An application
can retrieve any name the system has generated. (This is required for
positioned UPDATE and DELETE statements.)
Examples. Following are examples using cursors and scrollable cursors:
♦
The following example shows how to use a cursor:
" establish a connection to a data source "
c := ODBCConnection connect: #sample uid: #admin pwd:
#school.
" open a statement within the scope of the connection
c "
s := c addStatement.
" prepare the statement "
s prepare: 'select * from Student'.
" assign a cursor name to the statement (optional) "
s setCursorName: #StudentCursor.
" send the statement to the data source for execution "
s execute.
" fetch one record of the result set at a time and show them
in the System Transcript"
[s fetch == 0] whileTrue: [
s recordAsArray out.
].
" close the statement (optional, because the
command implicitly does it) "
s close.
following
" delete the statement from the collection of known
statements for the connection "
c removeStatement: s.
" disconnect from data source "
c disconnect.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
80
♦
The following example shows how to use a scrollable cursor:
" establish a connection to a data source "
c := ODBCConnection connect: #sample uid: #admin pwd:
#school.
" open a statement within the scope of the connection "
s := c addStatement.
" set options that control behavior of a cursor associated
with the statement; set concurrency to be read only; keep
the key for every row retrieved "
((ret := s setScrollOptionsConcurrency: 1 keyset:
-1) == SQL_SUCCESS)
if True: [
" prepare a statement "
s prepare: 'select * from Student order by
Studum'.
" send the statement to the data source
for execution "
s execute.
" position at first record "
s extendedFetchNext.
" display the first record of the result set
in the System Transcript window "
s recordAsArray out.
" absolute positioning at record 5 "
s extendedFetchAbsolute: 5.
" display the record in the result set in
the System Transcript window "
s recordAsArray out.
" position a cursor at a previous record
(position 4)"
s extendedFetchPrevious.
" display the record in the System
Transcript window "
s recordAsArray out.
] if False: [s lastError out].
" close a statement "
s close.
" remove a statement from the collection of known statements
for a connection "
c removeStatement: s.
" disconnect from data source "
c disconnect.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: System catalog access
81
Working with Binary Large Objects (BLOBs)
Enabling ODBC Support
BLOBs are supported only in ODBC Extension Level 1 or 2.
To enable ODBCBlob object support for all ODBCStatements executed for an
ODBCConnection, send the message blobSupport: true to the ODBCConnection
object.
To enable ODBCBlob object support for a specific ODBCStatement only, send
the message blobSupport: true to the ODBCStatement object prior to preparing
and executing the statement.
ODBC supports BLOBs through the LONG_VARCHAR and LONG_VARBINARY data
types. ODBC support handles only BLOBs containing Text (LONG_VARCHAR).
Using chunks
Theoretically, the maximum size of BLOBs is 2 gigabytes. To handle this
amount of data, you must use chunks. Columns containing BLOB data can be
read in chunks of up to 32K using the ODBCBlob object. A TextBlob object
pointing to the real data is returned for columns of type LONG_VARCHAR in a
result set. The implementation is currently read-only (that is, data cannot be
written in chunks).
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Working with Binary Large Objects (BLOBs)
82
Example. The following example shows how to retrieve a BLOB object from a
record:
" column f2 is assumed to be a LONG_VARCHAR "
" establish a connection to a data source "
conn := ODBCConnection connect:
'DSN=ODBCTest;UID=OSTUDIO;PWD=OSTUDIO'.
" open a statement within the scope of the connection "
stmt := c addStatement.
" set blob support option "
stmt blobSupport: true.
" prepare a statement "
stmt prepare: 'select f1, f2 from t3'.
" send the statement to the data source for execution "
stmt execute.
" fetch the first record of the result set "
stmt fetch.
" get a blob object from a record "
blobObj := (stmt recordAsArray) at: 2.
" get chunk of a blob "
chunk := blobObj getChunk.
chunk notNil whileTrue: [
" display chunk in System Transcript"
chunk out.
" get next chunk "
chunk := blobObj getChunk.
].
" remove statement from the collection of known statements for a
connection "
conn removeStatement: stmt.
" disconnect from data source "
conn disconnect.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Working with Binary Large Objects (BLOBs)
83
If you want to use the read-chunkwise approach to handle BLOBs, make sure
that you have only one column of type LONG_VARCHAR in your SELECT
statement. (However, you can have more than one such column in your
database table, if the DBMS supports this.) Also, make sure that the
LONG_VARCHAR column is the last in the set of result columns. Otherwise, you
will not receive any data, but you will get the error message “S1002: Invalid
column number” (because of an ODBC limitation in dynamic data binding used
by ObjectStudio ODBC support).
If you receive the “error allocating memory” error instead of an ODBCBlob
object: Manually set the maximum length option to 0 (stmt maxLength: 0.)
prior to preparing the statement.
If you do not want a text BLOB object to be returned for LONG_VARCHAR
columns, send the message maxLength: aLongInteger to the statement object.
(Send this message before preparation or direct execution of the statement.) In
this case, no ODBC BLOB object is returned. Instead, only the first chunk of
BLOB data up to the maximum size specified in aLongInteger is returned as an
object of class String. (Because of the current ObjectStudio string length
limitation of a maximum of 32,767 bytes, do not assign a value greater than
32,767 to aLongInteger.)
If you send the method maxLength: aLongInteger to a connection object, all
subsequent statements for that connection return the first chunk of data as a
string. The message blobSupport: false sets the length of columns containing
BLOB data to a maximum of 32,767 bytes.
Default behavior for columns with data type SQL_LONGVARCHAR: Return the
first 32K of data as a String object.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Working with Binary Large Objects (BLOBs)
84
Handling errors
The following return codes are used with low-level ODBC support:
♦
SQL_SUCCESS
♦
SQL_SUCCESS_WITH_INFO
♦
SQL_ERROR
♦
SQL_STILL_EXECUTING
♦
SQL_INVALID_HANDLE
♦
SQL_NEED_DATA
♦
SQL_NO_DATA_FOUND
If the returned error code is SQL_ERROR, send the lastError message to a
connection or statement to get the error information.
For additional information on ODBC error handling, refer to the documentation
in the Microsoft Open Database Connectivity Software Development kit.
Database User's Guide, P40-3203-03
Chapter: ODBC
Section: Handling errors
85
5
DB2
Introduction
This chapter describes how the support for DB2 differs from the standard
ObjectStudio database support.
Extended services
ObjectStudio transparently handles the specific operations necessary to support
IBM databases via the DDCS/2™ gateway.
Cursors
ORDER BY clause and Extended Services database cursors
Extended Services database cursors are not updateable if an ORDER BY clause is
used within the SELECT statement.
Support for DB2 and Cursors with Hold
According to the ANSI standard, a database must close and destroy a Cursor
when you perform a commit on the database. However, when you use the “DB2
Database Version 6.1 (Cursor with Hold)” loadable application, DB2 can both
keep open and update a database Cursor when you perform a commit. When
DB2 does this, you may see a performance improvement over the ANSI standard
behavior.
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Introduction
86
Manually binding the DB2 files
ObjectStudio attempts to automatically bind the DB2 files. However, if the
automatic bind fails, you must perform manual binding, using the appropriate
pair of bind files. Each bind file in the pair creates an access plan within the
database.
Location of bind files. All of the bind file pairs are located in your
ObjectStudio folder.
Descriptions of the bind file pairs to use in manual binding
Bind file pair for the (now officially unsupported) DB2 5.0
database wrapper
The DB2 5.0 database wrapper has two bind files, enabling the access plan
created by each bind file to use a different isolation level. The bind files are:
Availability of DB2 5.0 bind file pair. Although Cincom no longer officially
supports the DB2 5.0 database wrapper, the DB2 5.0 bind file pair is still
available in the ObjectStudio folder.
Setting a different isolation level for a bind file. If you wish to set the
isolation level for either bind file differently than described below,
appropriately modify the commands listed in “Performing the manual binding”
on page 89.
♦
OSDB250s.bnd. The access plan created by this bind file provides support
for all database access other than scrollable-cursor-related functions. By
default, this access plan operates in the Cursor Stability isolation level.
Cursor Stability isolation level. The Cursor Stability isolation level
provides less locking than the Repeatable Read isolation level but provides
more concurrency.
♦
OSDB250c.bnd. The access plan created by this bind file provides support
for scrollable-cursor-related functions. By default, this access plan
operates in the Repeatable Read isolation level.
Repeatable Read isolation level. The Repeatable Read isolation level
provides more locking than the Cursor Stability isolation level but provides
less concurrency.
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Manually binding the DB2 files
87
Bind file pair for the DB2 6.1 database wrappers
The DB2 6.1 database wrapper has two bind files. The bind functionality for
DB2 6.1 is split across two files not for technical reasons, but rather for
consistency with the DB2 5.0 database bind files. The bind files are:
A different isolation level for a bind file. If you wish to set the isolation level
for either bind file differently than described below, appropriately modify the
commands in “Performing the manual binding” on page 89.
♦
OSDB261s.bnd. The access plan created by this bind file provides support
for all database access other than scrollable-cursor-related functions. By
default, this access plan operates in the Cursor Stability isolation level.
Cursor Stability isolation level. The Cursor Stability isolation level
provides less locking than the Repeatable Read isolation level but provides
more concurrency.
♦
OSDB261c.bnd. The access plan created by this bind file provides support
for scrollable-cursor-related functions. By default, this access plan
operates in the Cursor Stability isolation level.
Bind file pair for the DB2 7.2 database wrappers
The DB2 7.2 database wrapper has two bind files. The bind functionality for
DB2 7.2 is split across two files not for technical reasons, but rather for
consistency with the DB2 5.0 database bind files. The bind files are:
A different isolation level for a bind file. If you wish to set the isolation level
for either bind file differently than described below, appropriately modify the
commands in “Performing the manual binding” on page 89.
♦
OSDB272s.bnd. The access plan created by this bind file provides support
for all database access other than scrollable-cursor-related functions. By
default, this access plan operates in the Cursor Stability isolation level.
Cursor Stability isolation level. The Cursor Stability isolation level
provides less locking than the Repeatable Read isolation level but provides
more concurrency.
♦
OSDB272c.bnd. The access plan created by this bind file provides support
for scrollable-cursor-related functions. By default, this access plan
operates in the Cursor Stability isolation level.
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Manually binding the DB2 files
88
Performing the manual binding
If the automatic bind fails, a user with the BINDADD privilege must perform
manual binding. To perform manual binding, enter one of the following sets of
statements into the DB2 Command Line Processor:
♦
For DB2 5.0. Execute the following commands:
DB2 CONNECT TO <database-name>
DB2 BIND OSDB250s.bnd ISOLATION CS BLOCKING ALL GRANT PUBLIC
DB2 BIND OSDB250c.bnd ISOLATION RR BLOCKING ALL GRANT PUBLIC
♦
For DB2 6.1. Execute the following commands:
DB2 CONNECT TO <database-name>
DB2 BIND OSDB261s.bnd ISOLATION CS BLOCKING ALL GRANT PUBLIC
DB2 BIND OSDB261c.bnd ISOLATION CS BLOCKING ALL GRANT PUBLIC
♦
For DB2 7.2. Execute the following commands:
DB2 CONNECT TO <database-name>
DB2 BIND OSDB272s.bnd ISOLATION CS BLOCKING ALL GRANT PUBLIC
DB2 BIND OSDB272c.bnd ISOLATION CS BLOCKING ALL GRANT PUBLIC
GRANT PUBLIC parameter and public database access. Including the GRANT
PUBLIC parameter in the preceding commands allows all users to access this
database through ObjectStudio. If you do not include the GRANT PUBLIC
parameter, you will have exclusive access to the database through
ObjectStudio, since you are the owner of the execution plans. (You would also
have exclusive access to the database through ObjectStudio if ObjectStudio
automatically bound in the execution plans.)
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Manually binding the DB2 files
89
Granting database access to users other than yourself
If you specify yourself as the only user who can access the database through
ObjectStudio (that is, who has the right to EXECUTE on the access plans), you
can later grant database access to other users.
Granting database access to all users
To grant database access to all users, enter one of the following pairs of
statements into the DB2 command-line processor:
♦
For DB2 5.0. Execute the following:
GRANT EXECUTE ON PACKAGE OSDB250s TO PUBLIC
GRANT EXECUTE ON PACKAGE OSDB250c TO PUBLIC
♦
For DB2 6.1. Execute the following:
GRANT EXECUTE ON PACKAGE OSDB261s TO PUBLIC
GRANT EXECUTE ON PACKAGE OSDB261c TO PUBLIC
♦
For DB2 7.2. Execute the following:
GRANT EXECUTE ON PACKAGE OSDB272s TO PUBLIC
GRANT EXECUTE ON PACKAGE OSDB272c TO PUBLIC
Granting database access to a specific user
To grant database access to a specific user, enter the appropriate pair of
statements found in “Granting database access to all users” above, but replace
all occurrences of PUBLIC with the specific user’s user name.
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Manually binding the DB2 files
90
Cataloging databases
ObjectStudio provides a method interface for the catalog functions in DB2. Use
the ESDatabase class method to catalog a database.
Following is the ESDatabase class method:
ESDatabase catalogDatabaseName: dbName
alias: dbAlias nodeName: nodeName
comment: comment drive: drive type: type
cmtCodePage: cmtCodePage.
The following table describes the parameters for the preceding method:
Parameter
Description
dbName
The actual name of the database as a Symbol.
dbAlias
The alias you wish to use as a Symbol.
nodeName
The name of the node containing the database as a
Symbol.
comment
A comment associated with this catalog entry as a
String, or nil for none.
drive
The drive designation on which the database resides or
nil for default.
$0 = Primary adapter (default)
$1 = Alternate adapter
type
The type of database, or nil for default.
$0 = Indirect—Database resides on this machine
$1 = Remote (default)—Database resides on
machine
cmtCodePage
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Cataloging databases
another
The code page used for the comment as a SmallInteger,
or nil for default code page on the application machine
91
Uncataloging databases
Use the following statement to uncatalog a database:
ESDatabase unCatalogDatabaseName: dbName.
The dbName parameter is the actual name of the database as a Symbol.
Executing stored procedures
ObjectStudio provides methods that execute DB2 procedures. There are two
varieties of each of these methods, one that includes a block of code that
executes when an error occurs, and one that does not include the block.
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Uncataloging databases
92
Methods to execute DB2 procedures
Use one of the following methods to execute DB2 procedures:
♦
execProc: procStr. Executes stored procedure and returns an instance of
class Array containing the output values from the procedure or, if an error
occurs, an instance of class Message or an instance of class Integer
(representing the return code from the stored procedure).
procStr contains a string object identifying the procedure name of the DB2
stored procedure to execute.
♦
execProc: procStr onError: errorBlock. Executes stored procedures in
the same manner as execProc:. errorBlock specifies an instance of
BlockContext.
♦
execProc: procStr params: params paramTypes: paramTypes. Executes
stored procedures in the same manner as execProc:. params is an array of
objects to be passed to/from the DB2 stored procedure. Each object of the
array must match the corresponding type defined by paramTypes. params
and paramTypes must be arrays of the same size.
paramTypes is an array of instances of class Symbol. Each Symbol
represents the DB2 data type for the corresponding parameter of params.
Valid paramTypes are:
#SMALL
#SMALL_OUT
#INTEGER
#INTEGER_OUT
#FLOAT
#FLOAT_OUT
#DECIMAL
#DECIMAL_OUT
#LONG
#LONG_OUT
#VARCHAR
#VARCHAR_OUT
#DATE
#DATE_OUT
#TIME
#TIME_OUT
#STAMP
#STAMP_OUT
#CHAR
#CHAR_OUT
The symbols with the suffix _OUT indicate that data is not transmitted to
the stored procedure but is expected as output from the stored procedure.
♦
execProc: procStr params: params paramTypes: paramTypes onError:
errorBlock. Executes stored procedures in the same manner as
execProc:params:paramTypes: with the addition of the errorBlock
parameter.
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Executing stored procedures
93
Considerations for parameters used by stored procedures
In order to pass data to or receive data from a DB2 stored procedure, you must
consider the parameter’s characteristics and define that parameter’s
characteristics with the usual ObjectStudio allocation techniques.
For example, if you plan to pass a string of 18 bytes as input to a stored
procedure and receive up to 100 bytes as output from the same parameter of a
stored procedure, the String object passed as a parameter should be defined as
a 100-byte string. Here is the code:
aString := 'My eighteen bytes.' append: (String new: 82).
Another example: if you want to receive (output only parameter) a decimal
value back from a stored procedure that has a precision of 9 and scale of 2,
ensure the stored procedure is called with a Decimal object that has the
precision and scale properly defined. Here is the code to accommodate a
decimal value with precision 9 and scale 2:
aDecimal := 9999999.99.
In general, predefine parameter objects used by stored procedures by defining
their maximum precision before calling the stored procedure or at least ensure
that the parameters passed have the same precision as those expected by the
stored procedure.
Examples of DB2 stored procedures
♦
The following is an example of the execProc:params:paramTypes: method:
a := db2Db execProc: 'inpsrv' params: {'presidents',
'Lincoln', 'Washington', 'Kennedy'} paramTypes: {#VARCHAR
#CHAR #CHAR #CHAR}.
♦
The following is an example of the execProc:onError: method:
b := db2Db execProc: 'testsrv' onError: [ :error |
^ self processDbError: error. ].
♦
The following is an example of the execProc:params:paramTypes:onError:
method:
c := db2Db execProc: 'outsrv' params: { 99999.99d }
paramTypes: {#DECIMAL} onError: [ :error |
^ self processDbError: error. ].
Here are the corresponding results for the previous examples:
a == {String, Symbol, Symbol, Symbol}.
b == Integer.
c == {Decimal}.
Database User's Guide, P40-3203-03
Chapter: DB2
Section: Executing stored procedures
94
6
Informix
Introduction
This chapter describes how the support for Informix differs from the standard
ObjectStudio database support.
Looking for Informix databases
You can set the InformixSERVER and InformixHOST environment variables to the
server and host required for your application by using Informix’s SetNet32
program. Once these variables are set, a list of databases can be obtained by
using the INFDatabase>>privateDirectory method from ObjectStudio.
Connecting to Informix databases
Informix automatically verifies your user ID and password. It uses the
information you selected in the Informix client software program SetNet32.
After the Informix application is loaded, use the
ExternalDatabase>>accessName: method to establish a connection. Here is an
example that will connect to the ‘stores7’ database on server ‘demo’:
INFDatabase accessName: #'stores7@demo'.
Transaction processing: commit and rollback
In order to commit or rollback updates to the database, a transaction must be
established. The following is an example of starting a transaction, then
committing the updates:
instanceDatabase := INFDatabase accessName: #'stores7@demo'.
instanceDatabase beginTran. " Executes the BEGIN WORK command"
instanceDatabase execSql: 'LOCK TABLE client IN EXCLUSIVE MODE'.
result := instanceDatabase privateExecSql: 'INSERT into client
Values ( "kim", 8, "abc street")'
(result isKindOf: Message) ifTrue: [ ^instanceDatabase rollback.
"Executes the ROLLBACK WORK command" ]
instanceDatabase commit. "Executes the COMMIT WORK command and
end the transaction"
Database User's Guide, P40-3203-03
Chapter: Informix
Section: Introduction
95
Executing stored procedures
Informix has an SPL (Stored Procedure Language) facility. You can list the
available stored procedures by using the INFDatabase>>storedProcedureNames
method.
If you want to know the contents of a stored procedure, then use the
INFDatabase>>storedProcedure: method. The input is the name of the stored
procedure. For example:
InstanceDatabase storedProcedure: #syslist
If you want to create a stored procedure, use the following example:
instanceDatabase execSql: 'CREATE PROCEDURE square_w_default
(i INT DEFAULT 0) RETURNING INT; DEFINE j INT; LET j = i * i;
RETURN j; END PROCEDURE;'
To run a stored procedure, use the following as an example:
instanceDatabase privateExecSql: 'CREATE TABLE client (name
CHAR(08) DEFAULT USER, num INTEGER, new_num INTEGER)'.
instanceDatabase execSql: 'select num, square_w_default (num)
new_num from client'
The preceding example creates a table called client. At some point, the table
may contain the following data:
Variable
Sample data
Num
3
new_num
1
After executing the stored procedure, the resulting row information changes
to:
Variable
Sample data
Num
1
new_num
9 (equal to 3 squared)
Database User's Guide, P40-3203-03
Chapter: Informix
Section: Executing stored procedures
96
7
SUPRA SQL
Introduction
This chapter contains the following database information that is specific to
SUPRA SQL support in ObjectStudio:
♦
Working with SUPRA SQL string columns. See “Working with SUPRA SQL
string columns” on page 98.
♦
ASCII/EBCDIC/BYTE designations and SUPRA SQL character columns. See
“ASCII/EBCDIC/BYTE designations and SUPRA SQL character columns” on
page 98.
♦
FLOAT precision in SUPRA SQL. See “FLOAT precision in SUPRA SQL” on
page 98.
♦
Avoiding COMMIT WORK RELEASE and ROLLBACK WORK RELEASE. See
“Avoiding COMMIT WORK RELEASE and ROLLBACK WORK RELEASE” on
page 98.
♦
Using multiple SUPRA SQL sessions. See “Using multiple SUPRA SQL
sessions” on page 98.
♦
SUPRA SQL class reference. See “SUPRA SQL class reference” on page 99.
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: Introduction
97
Working with SUPRA SQL string columns
SUPRA SQL string columns are supported using class SupraStringColumn.
However, these objects are not always supported by the ObjectStudio tools.
(Tables containing SUPRA SQL string columns can be accessed by the Database
Notebook, but data in string columns cannot be displayed using the Database
Notebook.) You can use the Mapping Tool tools with SUPRA SQL tables that
contain string columns, but you must add additional code to the code
generated by the Mapping Tool to access the data in SUPRA SQL string columns.
ASCII/EBCDIC/BYTE designations and SUPRA SQL character
columns
The ASCII/EBCDIC/BYTE designations are dropped for SUPRA SQL character
columns when the columns are used by the ObjectStudio database tools. This
was necessary to make the tools operate properly. These designations can be
retrieved using SHOW TABLE as a parameter to execSQL:, if needed.
FLOAT precision in SUPRA SQL
FLOAT type columns support a precision of 15 decimal digits. (Some SUPRA SQL
utilities support 18-digit precision, but the SUPRA SQL API used by the SUPRA
SQL database wrapper supports only 15-digit precision.)
Avoiding COMMIT WORK RELEASE and ROLLBACK WORK RELEASE
You should not use the COMMIT WORK RELEASE or ROLLBACK WORK RELEASE
statements. Connection to SUPRA SQL is managed by ObjectStudio whenever a
SupraDatabase object is created. You should use the SupraDatabase stop
method to terminate the connection, rather than COMMIT WORK RELEASE or
ROLLBACK WORK RELEASE. Use of these statements can cause unpredictable
results.
Using multiple SUPRA SQL sessions
Multiple database sessions are supported. You can establish up to eight
concurrent sessions to SUPRA SQL databases. No session number is required
when executing SQL statements, because this is handled internally by
ObjectStudio.
One SupraDatabase object is equivalent to one SUPRA SQL session. To use
multiple SUPRA SQL sessions, create multiple SupraDatabase objects and use
the appropriate instance to execute each SQL statement.
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: Working with SUPRA SQL string columns
98
SUPRA SQL class reference
Introduction
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
99
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
100
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
101
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
102
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
103
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
104
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
105
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
106
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
107
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
108
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
109
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
110
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
111
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
112
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
113
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
114
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
115
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
116
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
117
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
118
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
119
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
120
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
121
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
122
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
123
desktopWpObjIconSource
Description:
Returns a string containing the pathname for the SupraLogonWindowView
object icon’s source.
Assumptions:
None
Return Value: An object of class String.
Receiver Modified:
No
desktopWpObjName
Description:
Returns the string Supra Logon for the SupraLogonWindowView object name.
Assumptions:
None
Return Value: An object of class String.
Receiver Modified:
No
dropOnDesktop
Description:
Returns true indicating that this controller is to be shown on the ObjectStudio
desktop.
Assumptions:
None
Return Value: An object of class Boolean.
Receiver Modified:
No
initializeBindings
Description:
Creates the bindings between the controller items and the methods associated
with those controller items.
Assumptions:
None
Return Value: The receiver.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
124
logoff
Description:
Stops access to the currently connected SUPRA SQL.
Assumptions:
None
Return Value: An object of class SupraDatabase or class Message.
Receiver Modified:
No
ok
Description:
Accepts input from the logon window and connects to the server.
Assumptions:
None
Return Value: An object of class SupraDatabase or class Message.
Receiver Modified:
Yes
openInitialization
Description:
Sets the lock mode to a default of 1, indicating NORMAL.
Assumptions:
None
Return Value: The receiver.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
125
SupraScrollableCursor class
The SupraScrollableCursor class provides the implementation details for SUPRA
SQL scrollable cursors.
Class summary
Module:
suprasc.cls
SuperClass:
ExtDbScrollableCursor
Description:
Support for SUPRA SQL scrollable cursors
Version:
1.2
Class hierarchy
Cursor (abstract class)
ExternalDatabaseCursor (abstract)
ExtDbScrollableCursor (abstract)
SupraScrollableCursor
Class usage information
The SUPRA SQL API supports absolute positioning of scrollable cursors.
Therefore, scrollable cursor positioning is performed by the SUPRA SQL
database. It is not simulated by ObjectStudio.
SupraScrollableCursor class variables
cursors
Description:
An object of class Array that contains database cursors.
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
126
SupraScrollableCursor instance variables
dataArea
Description:
Contains the SUPRA SQL SQLDA used internally by the SupraScrollableCursor
instance. This area is large (15K) and should be inspected with caution,
because it takes a long time to display (1–2 minutes).
parseFlag
Description:
Contains a Boolean object indicating whether reparsing is required if the
SupraScrollableCursor instance is repositioned.
parseId
Description:
Contains the SUPRA SQL parse ID associated with the SupraScrollableCursor
instance.
sessionNumber
Description:
Contains the SUPRA SQL session number for the SupraScrollableCursor instance.
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
127
SupraScrollableCursor 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 object of class Array 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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
128
SupraScrollableCursor 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 an object of class String 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
zero.
Assumptions:
None
Return Value: The receiver.
Receiver Modified:
No
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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
129
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
privateSetPositionTo: newPos (primitive)
Description:
Updates the position instance variable with the contents of the newPos
parameter.
Assumptions:
newPos must be an object of class Integer.
Return Value: The receiver or an error code of class Integer.
Receiver Modified:
Yes
refresh (primitive)
Description:
Closes the cursor and opens it again using the stored SQL string in the sqlString
instance variable . This is a time-consuming process and should be used only if
absolutely necessary.
Assumptions:
None
Return Value: The receiver.
Receiver Modified:
Yes
updateWith: newValueDict
Description:
Updates the value of all fields at the current cursor position that differ 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
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
130
SupraStringColumn class
The SupraStringColumn class provides the implementation of SUPRA SQL string
columns.
Class summary
Module:
string.cls
SuperClass:
Object
Description:
Support for SUPRA SQL string columns
Version:
1.2
Class hierarchy
Object (abstract class)
SupraStringColumn
Class usage information
SUPRA SQL string columns are supported by the SupraStringColumn class.
Tables containing string columns can be accessed by SupraTable and
SupraDatabaseCursor, but the data within the string column cannot be
accessed by these objects. Data in SUPRA SQL string columns is read or
modified using objects of SupraStringColumn.
SupraStringColumn class variables
None
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
131
SupraStringColumn instance variables
databaseIV
Description:
Contains the instance of class SupraDatabase to which the SupraStringColumn
belongs.
descriptorIV
Description:
Contains a ByteArray object that stores the SUPRA SQL string column descriptor
for the SupraStringColumn instance.
SupraStringColumn 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
new: database column: column key: key write: write
Description:
Creates a new instance of class SupraStringColumn.
Assumptions:
database is the name of the associated database and must be an object of class
SupraDatabase.
column is the name of the desired string column and must be an object of class
Symbol or String.
key specifies the necessary primary key and must be an object of class String.
write specifies whether the string column is opened in write mode and must be
an object of class Boolean.
Return Value: An object of class SupraStringColumn or class Message.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
132
SupraStringColumn instance methods
close (primitive)
Description:
Closes the string column.
Assumptions:
None
Return Value: The receiver or an object of class Message.
Receiver Modified:
No
copyTo: destColumn sourcePos: sourcePos destPos: destPos length: length
(primitive)
Description:
Copies a part of the receiver to another string column.
Assumptions:
destColumn must be an object of class StringColumn. The receiver object can
be specified, which allows data to be copied from one position to another in a
single string column.
sourcePos, destPos, and length must be objects of class Integer.
Return Value: An instance of class Integer, or an object of class Message. The integer
specifies the length actually copied, which may be less than the desired length
given in the length parameter.
Receiver Modified:
No
expandLength: length with: character (primitive)
Description:
Expands the receiver to the length given in length and fills it with the
character specified in character.
Assumptions:
length must be an object of class Integer.
character must be an object of class Character.
Return Value: The receiver or an object of class Message.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
133
length (primitive)
Description:
Returns the length of the receiver.
Assumptions:
None
Return Value: The length of the string column as an object of class Integer or class Message.
Receiver Modified:
No
privateOpenDatabase: database column: column key: key write: write
(primitive)
Description:
Opens a string column. This method should not be used by the application
developer.
Assumptions:
None
Return Value: The receiver or an object of class Message.
Receiver Modified:
No
readPos: position length: length (primitive)
Description:
Reads the contents of the string column.
Assumptions:
position and length must be objects of class Integer.
Return Value: An array or an object of class Message. The array consists of two entries:
♦
An object of class ByteArray containing the data.
♦
An object of class Integer specifying the actual length that was read. This
may be less than the size of the ByteArray object in entry 1.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
134
searchStartPos: startPos endPos: endPos string: string modePattern:
modePattern (primitive)
Description:
Searches the receiver for the occurrence of a string or a pattern. If
modePattern is true, the string in the string parameter is used as a search
pattern.
Assumptions:
startPos and endPos must be objects of class Integer.
string must be an object of class String.
modePattern must be an object of class Boolean.
Return Value: An array or an error message of class Message. The array consists of two
entries, both of which are instances of class integer:
♦
The starting position of the found string.
♦
The ending position of the found string.
Receiver Modified:
No
truncateLength: length (primitive)
Description:
Truncates the receiver to the length given in length.
Assumptions:
length must be an object of class Integer.
Return Value: The receiver or an object of class Message.
Receiver Modified:
No
writePos: position data: data (primitive)
Description:
Writes the contents of the string column.
Assumptions:
position must be an object of class Integer.
data must be an object of class ByteArray. The entire array is written.
Return Value: The receiver or an object of class Message.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
135
SupraTable class
The SupraTable class provides a Table object associated with objects of class
SupraDatabase.
Class summary
Module:
supratb.cls
SuperClass:
ExternalTable
Description:
Support for SUPRA SQL tables
Version:
1.2
Class hierarchy
Table (ObjectStudio internal table)
ExternalTable (abstract)
SupraTable
Class usage information
Consider the following:
♦
SUPRA SQL converts table and attribute (column) names to uppercase. You
should use uppercase when referencing SUPRA SQL tables and columns
(such as #CUSTOMER).
♦
Strings are limited to 32,767 bytes in ObjectStudio. Therefore, table
attributes/columns that map to the STRING class cannot exceed 32,767
bytes; otherwise, truncation occurs.
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
136
SupraTable class variables
typesSupported
Description:
An IdentityDictionary where:
♦
The first key/value set has #ExternalTypes as the key and an array of
symbols containing the types supported by the external database language
as the value.
♦
The second key/value set has #InternalTypes as the key and an array of
symbols containing the corresponding types supported by ObjectStudio as
the value.
SupraTable instance variables
None
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
137
SupraTable class methods
allowedModifications
Description:
Returns a list of allowed modifications to a database table.
Assumptions:
None
Return Value: An Array of Symbols.
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
externalTypeSupport
Description:
Assumptions:
Returns the class variable typesSupported. typesSupported is an
IdentityDictionary where:
♦
The first key/value set has #ExternalTypes as the key and an array of
symbols containing the types supported by the external database language
as the value.
♦
The second key/value set has #InternalTypes as the key and an array of
symbols containing the corresponding types supported by ObjectStudio as
the value.
None
Return Value: An object of class IdentityDictionary.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
138
initialize
Description:
Initializes and returns the class variable typesSupported. See the previous
method, externalTypeSupport, for more information on this variable.
Assumptions:
None
Return Value: An object of class IdentityDictionary.
Receiver Modified:
No
maxNameLength
Description:
Returns the maximum number of characters allowed for a SUPRA SQL table
name.
Assumptions:
None
Return Value: An object of class SmallInteger.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
139
SupraTable instance methods
addField: field type: type extType: extType format: format
Description:
Adds a new field to the receiver. Adds a nil field to all existing records in the
receiver.
Assumptions:
field is an object of class Symbol defining the new column name to be added to
the receiver.
type is an object of class Symbol defining the internal type for the new column.
extType is an object of class Symbol defining the external type for the new
column.
format is an object of class Array containing the format options. It is used by
ObjectStudio database tools.
Return Value: The receiver or an object of class Message.
Receiver Modified:
Yes
createTableFrom
Description:
Physically creates a table.
Assumptions:
None
Return Value: The receiver or an object of class Message.
Receiver Modified:
Yes
deleteField: fieldName
Description:
Deletes a table field.
Assumptions:
fieldName is the symbol for an existing table field.
Return Value: The receiver or an object of class Message.
Receiver Modified:
Yes
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
140
loadInfo
Description:
Loads information about a table in the form of an internal table.
Assumptions:
None
Return Value: The receiver.
Receiver Modified:
Yes
modifyField: field type: type extType: extType format: format
Description:
Modifies a receiver field.
Assumptions:
field is an object of class Symbol defining the column name of the receiver to
be modified.
type is an object of class Symbol defining the internal type for the modified
column.
extType is an object of class Symbol defining the external type for the
modified column.
format is an object of class Array containing format options. It is used by the
ObjectStudio database tools.
Return Value: The receiver or an object of class Message.
Receiver Modified:
Yes
print
Description:
Returns the string Table plus the dbname instance variable; for example, Table
Example.
Assumptions:
None
Return Value: An object of class String.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
141
printExternalTypeFor: aColName
Description:
Returns a printable representation of the external data type for aColName as it
would appear in the CREATE TABLE statement.
Assumptions:
aColName is the name of a column defined for the table.
Return Value: An object of class String.
Receiver Modified:
No
privateExternalTypeFor: aColName
Description:
Returns the external data type for aColName as it would appear in the CREATE
TABLE statement.
Assumptions:
aColName is the name of a column defined for the table.
Return Value: An object of class String.
Receiver Modified:
No
privateGetColumnLineField: aColName
Description:
Returns the column name, including the data type, as it would appear in the
CREATE TABLE statement.
Assumptions:
aColName is the name of a column defined for the table.
Return Value: An object of class String.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
142
privateGetWidthPrecFixedFor: aColumnName
Description:
Assumptions:
Returns an object of class Array containing format information about the
column specified by aColumnName. The array has three entries, each of which
is optional:
♦
The information for #Width
♦
The information for #Precision
♦
The information for #Fixed
aColName is the name of a column defined for the table.
Return Value: An object of class Array.
Receiver Modified:
No
privateLoad (primitive)
Description:
Creates a new instance of SupraTable and loads it with the structure of the
table. The table is identified by its name.
Assumptions:
None
Return Value: A new instance of class SupraTable, or an object of class Integer containing an
error code.
Receiver Modified:
No
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
143
remove: record using: keyArray
Description:
Removes all occurrences of a given record in a specified table based on the
criteria in the record and keyArray parameters.
Assumptions:
record must be an object of class Array. It specifies the contents of the fields
that will be used as keys for deletion.
keyArray must be an object of class Array. It gives the field names to be used
as a key for the deletion. Field names are of class String.
Return Value: The receiver.
Receiver Modified:
Yes
update: record using: keyArray
Description:
Updates all occurrences of a record in a specified table based on the criteria in
the record and keyArray parameters.
Assumptions:
record must be an object of class Array. It specifies the contents of the record.
keyArray must be an object of class Array. It gives the field names to be used
as a key for the update. Field names are of class String.
Return Value: The receiver.
Receiver Modified:
Yes
Database User's Guide, P40-3203-03
Chapter: SUPRA SQL
Section: SUPRA SQL class reference
144
8
UniSQL Server
Introduction
This chapter contains the following database information that is specific to
UniSQL Server support in ObjectStudio:
♦
Using the lock_timeout_in_secs_parameter. See “Using the
lock_timeout_in_secs_parameter” on page 146.
♦
Report editor considerations. See “Report editor considerations” on
page 146.
♦
UniSQL Server class reference. See “UniSQL Server class reference” on
page 147.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: Introduction
145
Using the lock_timeout_in_secs_parameter
The UniSQL Server lock_timeout_in_secs parameter should be set to a
reasonable value. The default is forever, which will make your PC appear to
stall. Refer to your UniSQL Server documentation for more information.
Report editor considerations
The report editor allows you to create reports via saved queries. If the saved
query contains table name qualifiers for the attributes of the query, the report
editor defines global variables for the attributes.
Global variables must begin with an uppercase character; because UniSQL
Server table names cannot contain uppercase characters, ObjectStudio
generates a warning indicating an undefined global variable is being accessed.
Generally, you can ignore this warning, unless the global variable name
generated conflicts with a global already defined for your application. If the
latter occurs, resolve the global variable name conflict.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: Using the lock_timeout_in_secs_parameter
146
UniSQL Server class reference
Introduction
This chapter provides the following kinds of information about each of the
UniSQL Server classes:
♦
Class summary
♦
Class hierarchy
♦
Class usage information
♦
Class variables
♦
Instance variables
♦
Class methods
♦
Instance methods
To support the UniSQL Server database wrapper, ObjectStudio provides the
UniSQL Server classes. The UniSQL Server classes are subclasses of the common
object model for all supported databases. Each instance of a UniSQL Server
class represents a Database, Table, or Cursor object that can receive messages.
This chapter describes each UniSQL Server class and where it fits into the
ObjectStudio Smalltalk database hierarchy.
The methods and variables described provide direct access to UniSQL Server
objects, via the UniSQL Server 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 UniSQL Server methods and variables, the common
object model should be used unless specific application requirements demand
otherwise.
Information on these method references is also available through the Class
Browser.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
147
ORDBDatabase class
The ORDBDatabase class implements the access layer for UniSQL Server
databases.
Class summary
Module:
ordbdb.cls
SuperClass:
ExternalDatabase
Description:
Support for a UniSQL Server database
Version:
2.0
Class hierarchy
Database (abstract)
ExternalDatabase (abstract)
ORDBDatabase
Class usage information
Consider the following:
♦
The ORDBDatabaseClass>>directory class method lists the database sources
found in the ordb.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 UniSQL Server database is case-sensitive.
♦
An attribute of a UniSQL Server database may be shared. These shared
attributes, however, are not supported by ObjectStudio.
♦
The UniSQL Server Application Programming Interface (API) does not
support creating and deleting UniSQL Server databases. Therefore, you
cannot create and delete UniSQL Server databases using the UniSQL Server
database wrapper.
ORDBDatabase class variables
None
ORDBDatabase instance variables
None
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
148
ORDBDatabase class methods
checkAccessName: extDbName
Description:
Checks whether the database specified by the extDbName parameter is active
and accessible.
Assumptions:
extDbName must be an object of class Symbol.
Return value: The receiver or an object of class Message.
Receiver modified:
No
dbTypeForClass: aClass
Description:
Determines the UniSQL Server 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 UniSQL Server database type for the requested class and
domain.
Assumptions:
None
Return value: An object of class Symbol.
Receiver modified:
No
defaultDBType
Description:
Retrieves the default type specified in DBCONV.INI for UniSQL Server.
Assumptions:
None
Return value: An object of class Symbol.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
149
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 ORDBDatabase.
Assumptions:
None
Return value: An object of class Boolean.
Receiver modified:
No
initialize
Description:
Defines the DLL module object and registers all primitive methods for the
UniSQL Server database.
Assumptions:
None
Return value: The receiver.
Receiver modified:
No
loginUser: username password: password (primitive)
Description:
Used by the login controller to log in the user. If no login is performed, the
database implicitly logs in the user as user public, provided that no password is
necessary.
Assumptions:
username and password must be objects of class String. password can be nil,
which specifies a password of null for the database.
Return value: The receiver or an error code (Integer).
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
150
logonView
Description:
Returns the UniSQL Server logon window controller.
Assumptions:
None
Return value: An object of class ORDBLogonController.
Receiver modified:
No
maxDatabaseNameLength
Description:
Returns the maximum number of characters allowed in a database identifier.
Assumptions:
None
Return value: An object of class SmallInteger.
Receiver modified:
No
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 UniSQL Server database, all options
are hidden since a new database cannot be created.
Assumptions:
None
Return value: An object of class Array.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
151
privateDirectory (primitive)
Description:
Gets a list of available databases. A database is available if it can be opened
and data can be retrieved with a SELECT statement. Only one database of type
ORDBDatabase can be available at a time.
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 class ORDBDatabase.
Assumptions:
None
Return value: An object of class Array.
Receiver modified:
No
supportsSize
Description:
Returns true because UniSQL Server supports sized database types.
Assumptions:
None
Return value: An object of class Boolean.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
152
tableClass
Description:
Returns an object of class ORDBTable. This is the table class belonging to class
ORDBDatabase.
Assumptions:
None
Return value: An object of class ORDBTable.
Receiver modified:
No
userName (primitive)
Description:
Returns a string containing the name of the user who is currently logged on.
Assumptions:
None
Return value: An object of class String.
Receiver modified:
No
validPrecisionTypes
Description:
Lists the UniSQL Server database types that have a precision characteristic.
Assumptions:
None
Return value: An object of class Array.
Receiver modified:
No
validSizedTypes
Description:
Lists the UniSQL Server 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
Chapter: UniSQL Server
Section: UniSQL Server class reference
153
validTypes
Description:
Lists the valid UniSQL Server database 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
Chapter: UniSQL Server
Section: UniSQL Server class reference
154
ORDBDatabase instance methods
byteArrayAsDBStringValue: value
Description:
Returns a string containing the hexadecimal representation of the value
parameter. If necessary, the string will be a binary representation when the
ByteArray contains one element and the value is less than 128.
Assumptions:
value must be an object of class ByteArray.
Return value: An object of class String.
Receiver modified:
No
commit (primitive)
Description:
Commits the changes made to any database table since the start of the
database or the latest commit or rollback.
Assumptions:
None
Return value: The receiver or an object of class Message.
Receiver modified:
No
databaseType
Description:
Returns the UniSQL Server database type.
Assumptions:
None
Return value: An object of class Symbol.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
155
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 ORDB, which identifies the database cursor.
Assumptions:
None
Return value: An object of class String.
Receiver modified:
No
isORDB
Description:
Returns true because the receiver is of class ORDBDatabase.
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
Chapter: UniSQL Server
Section: UniSQL Server class reference
156
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.
Receiver modified:
Yes
message (primitive)
Description:
Returns the last error message.
Assumptions:
None
Return value: An object of class Message.
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
Chapter: UniSQL Server
Section: UniSQL Server class reference
157
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.
Receiver modified:
No
privateLoadSql: sql
Description:
Works like privateLoadSql: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
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
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
158
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 ORDBDatabaseCursor 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 ORDBScrollableCursor or class Message.
Receiver modified:
No
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
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
159
privateStart (primitive)
Description:
Starts the database.
Assumptions:
None
Return value: The receiver.
Receiver modified:
No
privateStop (primitive)
Description:
Stops the database.
Assumptions:
None
Return value: The receiver.
Receiver modified:
No
rollback (primitive)
Description:
Rolls back the changes made to any table since the database was started or
since the latest commit or rollback.
Assumptions:
None
Return value: The receiver or an object of class Message.
Receiver modified:
No
sourceDirectory
Description:
Returns the string ORDB. 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
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
160
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
tsAsDBStringValue: value
Description:
Returns a string containing the timestamp specified by the value parameter.
Assumptions:
value must be an object of class Timestamp.
Return value: An object of class String.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
161
ORDBDatabaseCursor class
The ORDBDatabaseCursor class provides the implementation details for UniSQL
Server nonscrollable cursors.
Class summary
Module
ordbcr.cls
SuperClass
ExternalDatabaseCursor
Description
Support for UniSQL Server database nonscrollable cursors
Version
2.0
Class hierarchy
Cursor (abstract class)
ExternalDatabaseCursor (abstract)
ORDBDatabaseCursor
Class usage information
Consider the following:
♦
All cursors are closed if a transaction is terminated by issuing COMMIT
WORK or ROLLBACK WORK, which prevents the Data Manager in
ObjectStudio from continuing to scan through table data after a Save. To
circumvent this, click on the Refresh button in the Data Manager after
saving.
♦
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 500.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
162
ORDBDatabaseCursor class variables
cursors
Description:
Array of the UniSQL Server database (nonscrollable) cursors. Cursors in use will
be named; unused cursors will be nil.
ORDBDatabaseCursor instance variables
queryResult
Description:
Table (or array of tables) containing the results of the query.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
163
ORDBDatabaseCursor 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 ORDBDatabaseCursor, or nil if no cursor is available.
Receiver modified:
Yes
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
164
ORDBDatabaseCursor instance methods
at: name put: newValue
Description:
Updates the value of a field at the current cursor position. Valid only if the
cursor was opened using “for update of.”
Assumptions:
name must be an object of class Symbol. (name specifies the field whose
contents are to be changed.)
Return value: The receiver or an object of class Message.
Receiver modified:
No
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
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
165
privateDelete (primitive)
Description:
Deletes the record at the current cursor position.
Assumptions:
None
Return value: A return code of class Integer.
Receiver modified:
No
privateDeleteUpdate: update
Description:
Deletes the record at the current cursor position. The update parameter is
used to determine whether to send an update message to dependents.
Assumptions:
update must be an object of class Boolean.
Return value: The contents of the fieldValues instance variable, or an object of class
Message.
Receiver modified:
No
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
privateExecUpdate: sqlString (primitive)
Description:
Executes the SQL statement specified by the sqlString parameter.
Assumptions:
sqlString is an object of class String and should contain an UPDATE statement.
Return value: A return code of class Integer.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
166
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 the newValueDict parameter. 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
Chapter: UniSQL Server
Section: UniSQL Server class reference
167
ORDBLogonController class
The ORDBLogonController class provides the implementation details for the
UniSQL Server logon window.
Class summary
Module
logon.cls
SuperClass
LogonWindowController
Description
Support for the UniSQL Server database logon window.
Version
2.0
Class hierarchy
Object (abstract)
InterfacePart
Controller
ENFINController
LogonWindowController
ORDBLogonController
Class usage information
ORDBLogonController displays the UniSQL Server logon window. This window
allows you to enter a UniSQL Server user name and a password. The UniSQL
Server logon window displays on the ObjectStudio desktop when the UniSQL
Server database wrapper is loaded.
ORDBLogonController class variables
None
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
168
ORDBLogonController instance variables
Cancel
Description:
Cancel push-button controller item on the logon dialog box that cancels a
UniSQL Server logon attempt.
Logoff
Description:
Logoff push-button controller item on the logon dialog box that stops access to
the current UniSQL Server database.
OK
Description:
OK push-button controller item on the logon dialog box that proceeds to log in
to a UniSQL Server database with the specified user name and password.
password
Description:
Password entry-field text value from the logon dialog box.
userName
Description:
User name entry-field text value from the logon dialog box.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
169
ORDBLogonController 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 ORDBLogonController class is loaded into the system.
Initializes the UniSQL Server Logon dialog box.
Assumptions:
None
Return value: The receiver.
Receiver modified:
Yes
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
170
ORDBLogonController instance methods
createItems
Description:
Defines the forms, controller items, and methods for the UniSQL Server Logon
dialog box.
Assumptions:
None
Return value: The receiver.
Receiver modified:
Yes
database
Description:
Sets the default database to ORDBDatabase.
Assumptions:
None
Return value: ORDBDatabase, which represents the global variable for the UniSQL Server
database.
Receiver modified:
No
defaultMethod
Description:
Sets the default action for the controller to the loginUser:password: method.
Assumptions:
None
Return value: A symbol representing the loginUser:password: method.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
171
desktopWpObjIconSource
Description:
Returns a string containing the pathname for the ORDBLogonWindowView
object icon’s source.
Assumptions:
None
Return value: An object of class String.
Receiver modified:
No
desktopWpObjName
Description:
Returns the string “UniSQL Server” for the ORDBLogonWindowView object
name.
Assumptions:
None
Return value: An object of class String.
Receiver modified:
No
dropOnDesktop
Description:
Returns true indicating that this controller is to be shown on the ObjectStudio
desktop.
Assumptions:
None
Return value: An object of class Boolean.
Receiver modified:
No
initializeBindings
Description:
Creates the bindings between the controller items and the methods associated
with those controller items.
Assumptions:
None
Return value: The receiver.
Receiver modified:
Yes
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
172
logoff
Description:
Ignores input from the logon window and stops access to the currently
connected UniSQL Server.
Assumptions:
None
Return value: An object of class ORDBDatabase or class Message.
Receiver modified:
Yes
ok
Description:
Accepts input from the logon window and connects to the server.
Assumptions:
None
Return value: An object of class ORDBDatabase or class Message.
Receiver modified:
Yes
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
173
ORDBScrollableCursor class
The ORDBScrollableCursor class provides the implementation details for UniSQL
Server scrollable cursors.
Class summary
Module
ordbsc.cls
SuperClass
ExtDbScrollableCursor
Description
Support for UniSQL Server database scrollable cursors.
Version
2.0
Class hierarchy
Cursor (abstract class)
ExternalDatabaseCursor (abstract)
ORDBDatabaseCursor
ExtDbScrollableCursor (abstract)
ORDBScrollableCursor
Class usage information
The UniSQL Server API does not support absolute positioning of scrollable
cursors, which leads to inefficiency if the number of instances for a class is
large. Therefore, try to keep the number of instances for a class reasonable.
You can usually do this with the SQL WHERE clause.
ORDBScrollableCursor class variables
cursors
Description:
Array of the UniSQL Server scrollable cursors. Scrollable cursors in use will be
named; unused cursors will be nil.
ORDBScrollableCursor instance variables
queryResult
Description:
Table (or array of tables) containing the results of the query.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
174
ORDBScrollableCursor 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 ORDBDatabaseCursor, or nil if no cursor is available.
Receiver modified:
Yes
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
175
ORDBScrollableCursor instance methods
at: name put: newValue
Description:
Updates the value of a field at the current cursor position. Valid only if the
cursor was opened using “for update of.”
Assumptions:
name must be an object of class Symbol. (name specifies the field whose
contents are to be changed.)
Return value: The receiver or an object of class Message.
Receiver modified:
No
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.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
176
privateDelete (primitive)
Description:
Deletes the record at the current cursor position.
Assumptions:
None
Return value: A return code of class Integer.
Receiver modified:
No
privateDeleteUpdate: update
Description:
Deletes the record at the current cursor position. The update parameter is
used to determine whether to send an update message to dependents.
Assumptions:
update must be an object of class Boolean.
Return value: The contents of the fieldValues instance variable, or an object of class
Message.
Receiver modified:
No
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
privateExecUpdate: sqlString (primitive)
Description:
Executes the SQL statement specified by the sqlString parameter.
Assumptions:
sqlString is an object of class String.
Return value: A return code of class Integer.
Receiver modified: No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
177
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
privateSetPositionTo: newPos (primitive)
Description:
Updates the position instance variable with the contents of the newPos
parameter.
Assumptions:
newPos must be an object of class Integer.
Return value: The receiver or an error code of class Integer.
Receiver modified:
Yes
refresh (primitive)
Description:
Closes the cursor and opens it again using the stored SQL string in the sqlString
instance variable. This is a time-consuming process and should be used only if
absolutely necessary.
Assumptions:
None
Return value: The receiver.
Receiver modified:
Yes
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
Chapter: UniSQL Server
Section: UniSQL Server class reference
178
ORDBTable class
The ORDBTable class provides a Table object associated with objects of class
ORDBDatabase.
Class summary
Module
ordbtb.cls
SuperClass
ExternalTable
Description
Support for UniSQL Server database tables.
Version
2.0
Class hierarchy
Table (ObjectStudio internal table)
ExternalTable (abstract)
ORDBTable
Class usage information
Consider the following:
♦
Table names are converted to lowercase. Do not enter table names in
uppercase. Attributes (column names) are case-sensitive.
♦
UniSQL Server table attributes (columns) of type bitfield are mapped to
ByteArrays in ObjectStudio. The last unused bits of the last byte are 0, if
necessary. For example, BIT(10) can hold the value x‘FFC0’ if all bits are
set.
♦
An attribute of a UniSQL Server table may be shared. These shared
attributes, however, are not supported by ObjectStudio.
♦
Strings are limited to 32,767 bytes in ObjectStudio. Therefore, table
attributes/columns that map to the STRING class cannot exceed
32,767 bytes. Otherwise, truncation occurs.
ORDBTable class variables
typesSupported
Description:
A list of the UniSQL Server data types.
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
179
ORDBTable instance variables
None
ORDBTable class methods
allowedModifications
Description:
Returns a list of allowed modifications to a database table. All modifications,
except the delete modification, are supported by the ObjectStudio Database
Table Editor.
Assumptions:
None
Return value: An Array of Symbols.
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
externalTypeSupport
Description:
Assumptions:
Returns the class variable typesSupported. typesSupported is an
IdentityDictionary where:
♦
The first key/value set has #ExternalTypes as the key and an array of
symbols containing the types supported by the external database language
as the value.
♦
The second key/value set has #InternalTypes as the key and an array of
symbols containing the corresponding types supported by ObjectStudio as
the value.
None
Return value: An object of class IdentityDictionary.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
180
initialize
Description:
Initializes and returns the class variable typesSupported. See the method
reference for the externalTypeSupport method for more information on this
variable.
Assumptions:
None
Return value: An object of class IdentityDictionary.
Receiver modified:
No
maxNameLength
Description:
Returns the maximum number of characters allowed for a UniSQL Server class
identifier.
Assumptions:
None
Return value: An object of class SmallInteger.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
181
ORDBTable instance methods
addField: field type: type extType: extType format: format
Description:
Adds a new field to the receiver. Adds a nil field to all existing records in the
receiver.
Assumptions:
field is an object of class Symbol defining the new column name to be added to
the receiver.
type is an object of class Symbol defining the internal type for the new column.
extType is an object of class Symbol giving the external type for the new
column.
format is an object of class Array containing the format options. It is used by
ObjectStudio database tools.
Return value: The receiver or an object of class Message.
Receiver modified:
Yes
createTableFrom
Description:
Physically creates a table.
Assumptions:
None
Return value: The receiver or an object of class Message.
Receiver modified:
Yes
deleteField: fieldName
Description:
Deletes a table field.
Assumptions:
fieldName is the symbol for an existing table field.
Return value: The receiver or an object of class Message.
Receiver modified:
Yes
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
182
loadInfo
Description:
Loads information about a table in the form of an internal table.
Assumptions:
None
Return value: The receiver.
Receiver modified:
Yes
print
Description:
Returns the string “Table ” plus the dbname instance variable; for example,
Table Example.
Assumptions:
None
Return value: An object of class String.
Receiver modified:
No
printExternalTypeFor: aColName
Description:
Returns a printable representation of the external data type as it would appear
in a CREATE TABLE statement.
Assumptions:
aColName is the name of a column defined for the table.
Return value: An object of class String.
Receiver modified:
No
privateExternalTypeFor: aColName
Description:
Returns the external data type needed by the database; for example, in the
CREATE TABLE statement.
Assumptions:
aColName is the name of a column defined for the table.
Return value: An object of class String.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
183
privateGetColumnLineField: aColName
Description:
Returns the column name including the data type needed by the database; for
example, in the CREATE TABLE statement.
Assumptions:
aColName is the name of a column defined for the table.
Return value: An object of class String.
Receiver modified:
No
privateGetWidthPrecFixedFor: aColumnName
Description:
Assumptions:
Returns an array with format information about the column specified by
aColumnName. The array always has three entries, each of which is optional:
♦
The information for #Width
♦
The information for #Precision
♦
The information for #Fixed
aColName is the name of a column defined for the table.
Return value: An object of class Array.
Receiver modified:
No
privateLoad (primitive)
Description:
Creates a new instance and loads it with the structure of the table. The table is
identified by its name.
Assumptions:
None
Return value: A new instance of class ORDBTable, or an object of class Integer for the error
code.
Receiver modified:
No
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
184
privateTableCursorNotOpen
Description:
Overrides the ExternalDatabase>>privateTableCursorNotOpen instance method.
Assumptions:
None
Return value: An object of class String.
Receiver modified:
No
remove: record using: keyArray
Description:
Removes all occurrences of a given record in a specified table based on the
criteria in the record and keyArray parameters.
Assumptions:
record must be an object of class Array. It specifies the contents of the fields
that will be used as keys for the deletion.
keyArray must be an object of class Array. It gives the field names to be used
as a key for the deletion. Field names are of class String.
Return value: The receiver.
Receiver modified:
Yes
update: record using: keyArray
Description:
Updates all occurrences of a record in a specified table based on the criteria in
the record and keyArray parameters.
Assumptions:
record must be an object of class Array. It specifies the contents of the record.
keyArray must be an object of class Array. It gives the field names to be used
as a key for the update. Field names are of class String.
Return value: The receiver.
Receiver modified:
Yes
Database User's Guide, P40-3203-03
Chapter: UniSQL Server
Section: UniSQL Server class reference
185
9
Other databases
Introduction
This chapter describes how the support for the following databases differs from
the standard ObjectStudio database support:
♦
Oracle and Oracle OCI support
♦
ADABAS support
♦
SQL Server support
♦
Sybase OpenClient support
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Introduction
186
Oracle and Oracle OCI support
This section describes unique features of the following in ObjectStudio:
♦
Oracle support
♦
Oracle OCI support
Oracle support
ANSI and Oracle Mode loadable applications
There are two modes of operation for the Oracle database wrapper:
♦
ANSI Mode
♦
Oracle Mode
Each mode has its own loadable application.
ANSI Mode. ANSI Mode causes your embedded SQL program to operate
according to the ANSI SQL standard. Compliance with this standard causes the
following behavior:
♦
When you commit or rollback, explicit cursors are closed.
♦
You cannot open a cursor that is already open. Also, you cannot close a
cursor that is already closed.
To use this mode, load one of the following applications:
♦
Oracle Database Client 8.1.5
♦
Oracle Database Client 9.2
Oracle Mode. Oracle Mode causes your embedded SQL program to operate
according to Oracle practices. Compliance with these practices causes the
following behavior:
♦
When you commit or rollback, explicit cursors will not be closed.
♦
You can open a cursor that is already open, in order to prevent reparsing.
To use this mode, load one of the following applications:
♦
Oracle Database Client 8.1.5 (ORACLE Mode)
♦
Oracle Database Client 9.2 (ORACLE Mode)
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
187
Executing Oracle procedures
ObjectStudio provides methods that execute Oracle PL/SQL procedures. There
are two varieties of each of these methods, one that includes a block of code
that executes when an error occurs, and one that does not include the block.
Use one of the following methods to execute Oracle PL/SQL procedures:
♦
execProc: procStr paramTypes: paramTypes. Executes an Oracle PL/SQL
procedure using parameters and returns an instance of class Array
containing the output values from the procedure. The procStr parameter
contains a string with a PL/SQL procedure call that can contain output
variable placeholders. The paramTypes parameter is an array of instances
of class Symbol. Each Symbol represents the Oracle type for the output
variable placeholders. Valid paramTypes are: #VARCHAR2, #CHAR,
#INTEGER, #FLOAT, #LONG, and #DATE.
♦
execProc: procStr onError: errorBlock. Executes an Oracle PL/SQL
procedure. The procStr parameter contains a string with a PL/SQL
procedure call that can contain output variable placeholders. errorBlock is
an instance of BlockContext.
♦
execProc: procStr paramTypes: paramTypes onError: errorBlock.
Executes an Oracle PL/SQL procedure in a manner that combines the
features of execProc:paramTypes: and execProc:onError:.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
188
Examples of Oracle procedures
Consider these examples:
♦
The following is an example of the execProc:paramTypes: method:
a := oraDb execProc: 'Pckge.Proc(123,''test'',:1,:2,:3)'
paramTypes: {#VARCHAR2 #CHAR #DATE}.
♦
The following is an example of the execProc:onError: method:
a := oraDb execProc:
'Pckge.Proc(123,''test'',:1,:2,:3)'
onError: [ :error |
^ self processDbError: error.
].
♦
The following is an example of the execProc:paramTypes:onError: method:
a := oraDb execProc: 'Pckge.Proc(123,''test'',:1,:2,:3)'
paramTypes: {#VARCHAR2 #CHAR #DATE}
onError: [ :error |
^ self processDbError: error.
].
The following code shows the result for the previous examples:
a == {outVar1 outVar2 outVar3}.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
189
Executing Oracle functions
ObjectStudio provides the following methods to execute Oracle PL/SQL
functions:
♦
execFunc: funcStr returnType: returnType paramTypes: paramTypes.
Executes an Oracle PL/SQL function and returns an instance of class Array.
The first position contains the function return value. The remaining
positions contain the output values from the function.
The funcStr parameter is a string that contains a PL/SQL function call. The
string can contain output variable placeholders. The returnType parameter
specifies the Oracle type for the return value and must be one of the
previous paramTypes. The paramTypes parameter is an array of instances
of class Symbol. Each Symbol represents the Oracle type for the output
variable placeholders. Valid paramTypes are: #VARCHAR2, #CHAR,
#INTEGER, #FLOAT, #LONG, and #DATE.
♦
execFunc: funcStr onError: errorBlock. Executes an Oracle PL/SQL
function and returns an instance of class Array in the same manner as
execFunc:returnType:paramTypes:. In addition, the errorBlock specifies an
instance of BlockContext.
♦
execFunc: funcStr returnType: returnType paramTypes: paramTypes
onError: errorBlock. Executes an Oracle PL/SQL function in a manner that
combines the features of execFunc:returnType:paramTypes: and
execFunc:onError:.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
190
Examples of Oracle functions
Consider these examples:
♦
The following is an example of the execFunc:returnType:paramTypes:
method:
a := oraDb execFunc: 'Pckge.Func(123,''test'',:1,:2,:3)'
returnType: #VARCHAR2
paramTypes: {#VARCHAR2 #CHAR #DATE}.
♦
The following is an example of the execFunc:onError: method:
a := oraDb execFunc:
'Pckge.Func(123,''test'',:1,:2,:3)'
onError: [ :error |
^ self processDbError: error.
].
♦
The following is an example of the
execFunc:returnType:paramTypes:onError: method:
a := oraDb execFunc:
'Pckge.Func(123,''test'',:1,:2,:3)'
returnType: #VARCHAR2
paramTypes: {#VARCHAR2 #CHAR #DATE}
onError: [ :error |
^ self processDbError: error.
].
The following code shows the result for the previous examples:
a == {functionReturnVal outVar1 outVar2 outVar3}.
Array fetch
ObjectStudio uses the array fetch Oracle optimization for the execSql: and
loadSql: methods. For each fetch call made by ObjectStudio, array fetch allows
Oracle to pass multiple rows across the network, thereby reducing network
flows.
Set the number of rows to return with the OracleDatabase
setArrayFetchSizeTo: instance method. The default size used by ObjectStudio is
25. Using higher values requires more memory allocation to handle the
processing of execSql: and loadSql: messages, but it can increase performance.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
191
Oracle OCI support
This section describes how the support for Oracle OCI differs from the standard
ObjectStudio database support.
Cincom Support for Oracle OCI. This section provides information on using a
feature—the Oracle OCI database wrapper—that has been available since
ObjectStudio 6.4, but was not supported by Cincom until ObjectStudio 6.9.
This section contains information on:
♦
Accessing the Oracle OCI database wrapper
♦
Defining columns
♦
Working with Cursors and ScrollableCursors
♦
Marking statements as available
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
192
Accessing the Oracle OCI database wrapper
ObjectStudio’s Oracle OCI (Oracle Call Interface) database wrapper is
implemented entirely in Smalltalk. You can access it by using the standard
ExternalDatabase interface or by using a new interface.
Sample code for the two interfaces. Below is contrasting sample code for the
two interfaces:
♦
Sample code for use with the standard ExternalDatabase interface. To
access the Oracle OCI database wrapper through the standard
ExternalDatabase interface, execute a statement similar to the following
sample statement:
| database result |
database := ExternalDatabase accessName: #OracleDatabase
result := database execSql: 'Select * from DEMO.EMPLOYEE'
result inspect.
♦
Sample code for use with the new interface. To access the Oracle OCI
database wrapper through its new interface, execute a statement similar
to the following sample statement:
| database statement result |
database := ExternalDatabase accessName: #OracleDatabase
statement := OracleOCIStatement newForSession: database
session database: database.
statement prepare: 'Select * from DEMO.EMPLOYEE'.
statement getDefineColumns
statement execute
result := statement generateTableOnError: [ :err| err out].
result inspect.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
193
Advantage of using the new interface—reduced work. Initially, accessing the
Oracle OCI database wrapper through its new interface appears to require
much more work than accessing it through the old interface. However, if you
assign to a variable the sample statement that accesses the database wrapper,
you need only execute the “execute” and “generateTableOnError” portions of
the statement:
statement execute.
result := statement generateTableOnError: [err| err out].
Performing the steps described above is much easier than using the standard
ExternalDatabase interface, which requires you to allocate a statement,
prepare the statement, execute the statement, and free the statement each
time you wish to access the database wrapper. With a stored statement that
uses the new interface, you will not need to allocate a new statement when
you wish to access the database wrapper again, and you will not need to
prepare this statement over again. You can simply execute the stored
statement.
Marking statements as available. If you no longer need the stored statement,
mark it as available (see “Marking statements as available” on page 195).
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
194
Defining columns
The column definitions are implemented entirely in Smalltalk. They are defined
in class OracleOCIColumns and its subclasses.
Enhancing columns. If you would like to enhance the columns, perform the
following:
1. Create a new subclass of OracleOCI8Column.
2. In your new subclass, add the desired new behavior to the initialize class
method.
The initialize class method maps native datatypes to Smalltalk types.
Working with Cursors and ScrollableCursors
Executing a statement with parameters. For a description of the code
required to execute a statement with parameters, refer to the
OracleOCIDatabaseCursor>>privateExecSql:vars method.
Performing more than one insert. To perform more than one insert, perform
the following:
1. Update the data inside the params array.
2. Bind again.
Remember that after step 2, all addresses will have changed.
Marking statements as available
If you no longer need a statement, mark it as available. This allows an
allocated statement to be reused. For example:
myStatement := OracleOCIStatement new.
...
myStatement available.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: Oracle and Oracle OCI support
195
ADABAS support
Because ObjectStudio implements the ADABAS database support using the
Oracle API, see the “Oracle” section on page 187.
SQL Server support
This section describes how the support for SQL Server differs from the standard
ObjectStudio database support.
Logging on using Windows Authentication
If you log on to a SQL Server database without providing a user name and a
password, the SQL Server database wrapper automatically uses Windows
Authentication. If you log on with a user name and a password, the SQL Server
database wrapper uses SQL Server authentication.
Looking for SQL Server databases
You can set the EnfinGetSQLServers environment variable to 0 to prevent
ObjectStudio from looking on the network for available SQL Servers during
logon, or to 1 to look for the available SQL Servers during logon. To set the
environment variable, use the following format:
SET EnfinGetSqlServers=n
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: ADABAS support
196
Message and error blocks
The SQL Server API allows a program to install error and message callback
functions. While processing statements, the SQL Server engine can call back to
the application program with an error or message. Stored procedures can also
send messages to the callback with the RAISERROR Transact-SQL statement. For
more information, refer to the Microsoft SQL Server Programmer’s Reference.
In ObjectStudio, you can establish a BlockContext to be called each time either
a message or an error is received by the ObjectStudio API-support layer.
Execute the following code to install a message block into SQL Server support:
SQLServerDatabase setMessageBlockTo: [
:cursorName :messageNumber :messageState
:messageSeverity :messageText |
...
"your processing goes here"
...
]."end MessageBlock"
Execute the following code to install an error block into ObjectStudio’s SQL
Server support:
SQLServerDatabase setErrorBlockTo: [
:cursorName :messageSeverity :dbErrorNumber
:osErrorNumber :dbErrorString :osErrorString |
...
"your processing goes here"
...
]."end ErrorBlock"
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: SQL Server support
197
The following table describes the parameters in the previous examples:
Block parameter
Description
cursorName
ObjectStudio’s name of the cursor that caused the
message.
messageSeverity
Severity of the message as a number. See the codes
described previously for the message block.
dbErrorNumber
Current error’s identifying number.
osErrorNumber
Current error’s operating system-specific number.
This number describes the cause of the error and is
specific to the network or the operating system. It
is −1 if there is no relevant operating system error.
dbErrorString
Text of the database error as a String object.
osErrorString
Text of the operating system error as a String
object.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: SQL Server support
198
MicroDecisionware access
ObjectStudio supports the MicroDecisionware gateway through its SQL Server
application. The current support does not include updateable cursors because
MicroDecisionware does not support Browse mode. In other words, update links
are not supported.
Also, consider the following:
♦
When you connect to a MicroDecisionware gateway, there is a single
accessible SQL Server database called MDI.
♦
The SQLServerDatabase class supports the serverType instance method that
returns the String DB2 if you are connected to a MicroDecisionware
gateway.
Microsoft SQL Server wrapper sets local host name
When you use the “MS SQL Server Database” wrapper to log on to a SQL Server
database, ObjectStudio automatically sets the local host name.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: SQL Server support
199
SYBASE OpenClient support
This section describes how the support for SYBASE differs from the standard
ObjectStudio database support.
Message and error blocks
The SYBASE API allows a program to install error and message callback
functions. While processing statements, the SYBASE engine can call back to the
application program with an error or message. Stored procedures can also send
messages to the callback with the RAISERROR Transact-SQL statement.
In ObjectStudio, you can establish a BlockContext to be called each time either
a message or an error is received by the ObjectStudio API-support layer.
Execute the following code to install a message block into ObjectStudio’s
SYBASE support for client messages:
SybaseDatabase setMessageBlockTo: [
:cursorName :messageNumber :messageState
:messageSeverity :messageText |
...
"your processing goes here"
...
]."end MessageBlock"
Execute the following code to install an error block into ObjectStudio’s SYBASE
support for server error messages:
SYBASE error block differs from SQL Server error block. In ObjectStudio’s
SYBASE support, the error block has only five arguments. However, in
ObjectStudio’s SQL Server support, the error block has six arguments.
SybaseDatabase setErrorBlockTo: [
:cursorName :messageSeverity :messageNumber
:messageState :messageText |
...
"your processing goes here"
...
]."end ErrorBlock"
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: SYBASE OpenClient support
200
The following table describes the parameters in the previous examples:
Block parameter
Description
CursorName
ObjectStudio’s name of the cursor that caused the
message.
MessageSeverity
Severity of the message as a number. See the codes
described previously for the message block.
messageNumber
Current error’s identifying number.
MessageState
State of the message as a number.
MessageText
Text of the database error as a String object.
Database User's Guide, P40-3203-03
Chapter: Other databases
Section: SYBASE OpenClient support
201
10
Database Notebook
Introduction
This chapter describes the Database Notebook, which provides access to all
databases, both internal and external.
With the Database Notebook, you can:
♦
Create a database, create and modify a table, and save Internal Database
changes
♦
Enter data
♦
Manage data
♦
Create SQL queries
♦
Preview and print data using a default report format
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Introduction
202
Using the Database Notebook
This section describes:
♦
Database Notebook pop-up menu
♦
Creating a new database
♦
Creating and modifying a table
♦
Saving changes to the Internal Database
Database Notebook pop-up menu
Press mouse button 2 on the background of the Database Notebook page to
display the Database Notebook pop-up menu.
The following table describes the options on the Database Notebook pop-up
menu:
Option
Allows you to
Refresh
Update the display of the Database Notebook if you
have made changes.
Help
Open ObjectStudio Help files.
SQL Browser
Open the SQL Queries dialog box (SQL Browser) to
create a new query or to edit, execute, or display
existing queries.
SQL Window
Open the SQL Window, which allows you to type SQL
queries directly into the window.
Create Database
Use the Create Database dialog box to create a new
external database.
Drop Database
Remove the selected database from the Database
Notebook.
Create Table
Open the Table Name Entry Form dialog box to create a
new table in the current database.
Commit
Commit a database transaction that has been entered.
Rollback
Roll back database transactions and return the database
to its state when it was accessed or its state after the
last commit.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
203
Creating a new database
To create a new database:
1. Select Tools ⇒ Database Notebook from the Desktop menu.
The Database Notebook opens, as shown here:
For each external database that is loaded, a tab appears at the bottom of
the notebook page.
2. Press mouse button 2 on the background of the Database Notebook page to
display the Database Notebook pop-up menu.
3. Select Create Database from the Database Notebook pop-up menu.
The Create Database dialog box displays.
Capabilities of the Internal Database. Although you cannot create new
databases with the Internal Database, you can create, modify, and delete
tables. You can also create, modify, delete, preview, and print data.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
204
4. Select the type of database you want to create from the Select database
type drop-down list box.
5. Enter the database name in the Name entry field.
Additional data entry. Depending on the options available for the
selected database type, ObjectStudio may give you the chance to enter
drive information and an optional comment.
6. Enter a drive specification in the Drive entry field.
7. Enter a comment in the Comment entry field.
8. Click OK to close the Create Database dialog box.
A tab for the new database appears along the bottom of the Database
Notebook.
Privileges for database creation. You must have appropriate privileges for
your DBMS before you can create a database using ObjectStudio.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
205
Creating and modifying a table
The Database Notebook allows you to create new tables with the Table
Definition dialog box. ObjectStudio dynamically creates this dialog box,
depending on the field types and attributes supported by your underlying
database. The ability to enter comments, field lengths, and so on, depends on
the underlying database and the selected field type.
The Internal Database will be used for illustration in this section.
Internal Database
The Internal Database displays the following field types on the Table Definition
dialog box:
♦
Symbol
♦
String (default length 20)
♦
Number
♦
SmallInteger
♦
LongInteger
♦
Float
♦
Object
♦
Decimal (default length 8, decimal places 2)
♦
Boolean
♦
Date
♦
Time
♦
Timestamp field
The Internal Database displays the following attributes on the Table Definition
dialog box:
♦
Computed
♦
Mandatory
♦
Unique
♦
Key
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
206
Table pop-up menu
Press mouse button 2 on the background of the Table Notebook page to display
the Table pop-up menu. The following table describes the options on the Table
pop-up menu:
Option
Allows you to
Open
Open the SQL Result window to view all records in
the table.
Help
Open ObjectStudio Help files.
Create Table
Display the Table Name Entry Form dialog box to
create a table in the current database.
Edit Table
Open the Table Definition dialog box to display
and edit the table definition.
Drop Table
Remove the selected table from the database.
Data Entry
Open the Data Entry dialog box to add new
records to the database.
Data Manager
Display a default Data Manager dialog box for the
table.
Data Manager Form
Load the default Data Manager form for the
current table into the Designer.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
207
Creating a new table
To create a new table:
1. Select Tools ⇒ Database Notebook to open the Database Notebook.
2. Select the database in which to create the table by clicking the appropriate
tab along the bottom of the Notebook window.
3. Press mouse button 2 on the background of the Database Notebook page to
display the Database Notebook pop-up menu.
4. Select Create Table from the pop-up menu.
The Table Name Entry dialog box displays, as shown here:
5. Type a name in the Table name entry field.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
208
6. Click OK.
The Table Definition dialog box opens.
7. Create a field:
A. Type a field name in the Field name entry field.
B. Select a field type from the Types list box.
C. Select an attribute from the Attributes list box, if necessary.
D. If comment, length, and/or decimal places fields appear, enter the
appropriate information.
E. Click Add to save the information.
F. Repeat steps A–E to define all of the fields in the table.
8. Click Save to create the table and close the Table Definition dialog box.
Modifying an entry
To modify an existing entry:
1. Select the entry that you want to modify.
2. Type new information in the appropriate entry field.
3. Click Modify to enter the new information.
Deleting a field
To delete a field, select the field and click Delete.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
209
Saving changes to the Internal Database
Unlike when working with an external database, changes made to the Internal
Database are not saved to the disk automatically.
Saving the database
If you change the Internal Database structure or add data and you want to save
those changes permanently, save the ObjectStudio image file as described in
the ObjectStudio User’s Guide, P40-3201.
Saving tables
To save changes to an individual Internal Database table, use class (.cls) files,
as described in the following steps:
1. Select Tools ⇒ Workspace from the Desktop menu to open the Workspace.
You can also select Workspace ⇒ Open from the System Transcript menu.
2. Enter the appropriate code. For example:
(InternalDatabase getNamed: #tablename) saveAs:
'filename.cls'.
3. Click Smalltalk Execute on the Workspace toolbar to execute the code and
save the data to a file.
This code uses the getNamed:method to get the values stored in
InternalDatabase #tablename. Then it uses the saveAs: method to write the
data to a Smalltalk class file (filename.cls). The system assumes #tablename is
the valid name of an Internal Database table.
The next time you run ObjectStudio, load the class file using any of the
methods described in the ObjectStudio User’s Guide, P40-3201.
Image saving not recommended for Internal Database data storage. When
you save an ObjectStudio image, ObjectStudio saves data, recorded in the
Internal Database, in the ObjectStudio image file. Because table data changes
frequently, but is saved only when you save the ObjectStudio image, Cincom
does not recommend this method of data storage.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Using the Database Notebook
210
Entering data
The Database Notebook dynamically creates a default data entry form for each
table available to the system. This form only allows you to add records. You
cannot use it to edit or delete data. For more information, see “Managing
data” on page 214.
Accessing the default data entry form
To access the default data entry form for a table:
1. Select Tools ⇒ Database Notebook to open the Database Notebook.
2. Use the notebook tabs and/or the arrow tabs to display the appropriate
table, as shown here:
3. Press mouse button 2 outside the white display area to display the Table
pop-up menu for the selected page.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Entering data
211
4. Select Data Entry from the Table pop-up menu to display the Data Entry
dialog box.
The following illustration shows the Data Entry dialog box for the Employee
table of the Internal Database:
You can type new information in any of the entry fields.
Blank button. You can clear the entry fields by clicking the Blank button.
5. To navigate through the database:
A. Press the TAB key to move from field to field.
B. Click Next to display the next record. Click Previous to go back to a
previous record.
6. Click Enter to enter the record into the database.
Additional step if the database supports transaction processing. If the
underlying database supports transaction processing, commit the changes to
the database by clicking the Commit button.
7. Click Close when you are finished entering data.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Entering data
212
Customizing the Data Entry dialog box
You can select Data Entry Form from the Table pop-up menu to build the
default data entry form for the displayed table and load it into the Designer.
This feature eliminates the need to create your own data entry form and allows
you to customize and save the form.
For example, you may want to modify the form to include error checking and
to provide default values. These changes then are available whenever you
access the form.
After saving the form to a class (.cls) file, you can load it into ObjectStudio and
use it in your application.
For more information on using the Designer, refer to the ObjectStudio User
Interface Guide, P40-3205.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Entering data
213
Managing data
The Database Notebook dynamically creates a default Data Manager form for
each table available to the system. Unlike the Data Entry dialog box, which
only allows you to add records, the Data Manager allows you to enter new
records, edit or delete existing records, and preview and print data.
Opening the default Data Manager
You can open the Data Manager from the SQL Browser, the Database Notebook,
or the SQL Editor. If you open it from the Database Notebook, the system
makes the entire contents of the table available to you. If you open it from the
SQL Browser or SQL Editor, the system limits access to the results of the active
query.
To open the default Data Manager for a table:
1. Select Tools ⇒ Database Notebook to open the Database Notebook.
2. Use the notebook tabs and/or the arrow tabs to display the appropriate
table.
3. Press mouse button 2 to display the Table pop-up menu for the selected
page.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Managing data
214
4. Select Data Manager from the Table pop-up menu to display the Data
Manager dialog box.
The following illustration shows the Data Manager for the Employee table
of the Internal Database:
You can type new information in any of the entry fields.
5. Do one of the following:
♦
Click New to create a new record in the table.
♦
Click Next to go to the next record, or click Previous to go back to a
previous record.
♦
Click Refresh to return the record to its original state if you decide that
you do not want to make changes to the record.
♦
Click Select to open the Data Manager Selection dialog box for the
current table. Double-click the record that you want to edit and click
Close to return to the Data Manager.
6. Click Save to save any changes.
7. Select File ⇒ Exit to close the Data Manager dialog box.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Managing data
215
Customizing the Data Manager Form
Select Data Manager Form from the Table pop-up menu to build the default
Data Manager form for the displayed table and load it into the ObjectStudio
Designer. This feature eliminates the need to create your own data
management form and allows you to customize and save the form. For
example, you may want to modify the form to include error checking and to
provide default values. These changes then are available whenever you access
the form.
After saving the form to a class (.cls) file, you can load it into ObjectStudio and
use it in your application.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Managing data
216
Creating a SQL query
ObjectStudio provides two ways to create queries in the Database Notebook.
You can use:
♦
♦
SQL tools
-
SQL Editor
-
SQL Window
SQL Browser
Using the SQL tools
The SQL tools include the SQL Editor and the SQL Window.
SQL Editor
The SQL Editor features a point-and-click interface to help you create SQL
statements embedded in Smalltalk class files. You can create parametric
queries and assign the return value of a Smalltalk statement or the current
value of an entry field as the parameter. Once you create these queries, you
can incorporate them into your applications.
You can access the SQL Editor from the SQL Browser or from the ObjectStudio
Desktop (File ⇒ New ⇒ Query).
SQL Window
The SQL Window allows you to create quick, text-based queries for prototyping
and testing purposes. You can save, load, and execute these queries in the SQL
Window, or you can export them as text files to use in other applications.
You can access the SQL Window from the Database Notebook or from the
ObjectStudio Desktop (Tools ⇒ SQL Window).
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Creating a SQL query
217
Using the SQL Browser
The SQL Browser allows you to create and edit SQL queries. You can also
display query results and access the Data Manager.
When you access the SQL Browser from the Database Notebook, ObjectStudio
assumes that you want to query the currently displayed database.
The following table describes the buttons on the SQL Browser:
Button
Allows you to
Edit
Open the SQL Editor and edit the selected query.
Display
Display the SQL Result Display with results of the
query. You can save the results in an ASCII or a
delimited file.
Data Manager
Display a default Data Manager dialog box for the
table.
Data Manager Form
Load the default Data Manager form for the current
table into the Designer.
Create
Open the SQL Editor to create a new query.
To open the SQL Browser from the Database Notebook:
1. Select Tools ⇒ Database Notebook from the ObjectStudio Desktop menu.
The Database Notebook displays.
2. Select the database that you want to query.
3. Press mouse button 2 on the background of the Database Notebook page to
open the Database Notebook pop-up menu.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Creating a SQL query
218
4. Select SQL Browser from the Database Notebook pop-up menu.
The SQL Queries dialog box opens, as shown here:
5. Click Create to create a new query.
6. Click Close to close the SQL Queries dialog box.
Database User's Guide, P40-3203-03
Chapter: Database Notebook
Section: Creating a SQL query
219
11
SQL tools
Introduction
This chapter describes two ObjectStudio tools that enable you to create SQL
statements:
♦
SQL Editor
♦
SQL Window
SQL Editor
The SQL Editor allows you to:
♦
Create SQL statements by using ObjectStudio’s point-and-click interface, or
by typing statements directly
♦
Verify SQL statements before they are executed
♦
Execute SQL statements and view the results in the SQL Editor
♦
Create parametric queries and associated Smalltalk statements that allow
you to base queries on information available at run time
♦
Set the SQL Editor to commit database changes automatically or manually
♦
Save SQL statements as Smalltalk class files for inclusion in your
applications
♦
Import and export SQL statements as text files for reuse in the SQL Editor
or SQL Window
You can use the SQL Editor’s point-and-click options to specify the elements of
an SQL statement. ObjectStudio then constructs the SQL statement, which
provides the correct syntax automatically.
You also can type SQL statements directly into the editor. The SQL Editor
provides a statement type (DIRECT) that permits you to do so.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: Introduction
220
Creating an SQL statement
To create an SQL statement:
1. Select File ⇒ New ⇒ Query from the Desktop menu to open the SQL Editor.
You also can open the editor from the Database Notebook. For more
information, see “Database Notebook” on page 202.
The SQL Editor displays, as shown here:
The Selection dialog box also opens, as shown here:
2. Select a Type at the top of this box and define the type of query. For more
information, see “Using the Selection dialog box” on page 224.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
221
3. Select Actions ⇒ Verify from the SQL Editor menu to validate the syntax of
the statement.
If the statement contains an error, correct the syntax and repeat this step.
4. Select Actions ⇒ Run Statement to execute the statement.
5. Select File ⇒ Save to save the statement in a Smalltalk class file.
You also can select File ⇒ Export to text file to save the statement in a
text file for later use.
Another way to create a new SQL statement is to use the SQL Browser. See
“Using the SQL Browser” on page 218.
The following options are on the SQL Editor menu:
♦
File menu. The options on the File menu allow you to save queries and to
import and export queries to and from a file.
♦
Statement menu. The options on the Statement menu correspond to SQL
clauses, as described in the following table:
Option
Allows you to
Section
Selection
Specify the type of SQL statement,
including SELECT, INSERT, UPDATE,
DELETE, and DIRECT, and to
specify the database and table on
which to base the statement.
“Using the Selection dialog box” on
page 224
Search condition
Construct a WHERE clause.
“Defining a WHERE clause” on
page 234
Join condition
Construct a WHERE clause as a
Table Join.
“Defining a JOIN clause” on
page 236
Grouping
Construct a GROUP BY clause.
“Defining a GROUP BY clause” on
page 238
Having
Construct a HAVING clause. This
option is also available as a button
on the Grouping dialog box.
“Defining a HAVING clause” on
page 238
Order
Construct an ORDER BY clause.
“Defining an ORDER BY clause” on
page 239
Values
Construct a VALUES clause. This
option is also available as a button
on the Selection dialog box.
“Using the Selection dialog box” on
page 224
Parameters
Create parametric SQL statements.
“Creating parametric SQL
statements” on page 240
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
222
♦
Actions menu. The Actions menu contains options to verify and run SQL
statements. It also contains options to open the Report Editor and the Data
Manager. For more information, see “Executing a statement” on page 233.
♦
Transactions menu. The options on the Transactions menu are available if
the available external databases support transaction processing. The
options allow you to commit and roll back SQL transactions. For more
information, see “Committing changes” on page 242.
♦
Options menu. The Options menu allows you to select display options.
Check marks appear next to the selected options. The following options are
available:
♦
-
Show database—Displays the name of the database on which the
statement is based.
-
Show status line—Displays helpful information in the status line at the
bottom of the form.
-
Word wrap—Toggles the word wrap feature. Turning off word wrap
places each clause on a separate line.
Help menu. The Help menu contains options to get help about the SQL
Editor and ObjectStudio.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
223
Using the Selection dialog box
The Selection dialog box allows you to specify the statement type and define
which database, tables, and columns to use. The Selection dialog box appears
immediately if you are creating a new statement. If you are editing an existing
statement, select Statement ⇒ Selection from the SQL Editor menu (shown in
“Creating an SQL statement” on page 245).
Options on the Selection dialog box
The following table describes the options on the Selection dialog box. Some of
the options that appear depend on the type of SQL statement that you are
creating.
Option
Allows you to
Type radio buttons
Specify the statement type. The Selection dialog box
changes dynamically to present only those options
available for the chosen statement type.
Database type/name list boxes
Specify the database on which to base the statement.
Table/columns list boxes
Specify the tables and columns on which to base the
statement.
Selected columns list box
Select columns on which to base the statement.
The SQL Editor uses the information in the Selected
Columns list box to create the FROM clause automatically.
To specify a table in the FROM clause without specifically
selecting any of its columns, edit the FROM clause
manually in the main SQL Editor window.
Arrow buttons
Add or remove selected columns. Single arrows add or
remove selected columns; double arrows add or remove all
columns.
Distinct results check box
Exclude duplicate records from the result set.
Define Alias button
Define shorter or more recognizable column names.
The Internal Database does not support aliases.
Calculated Column button
Define columns whose values are calculated from data
values stored in other columns.
Values button
Replace existing row data in an UPDATE statement or
define the new row in an INSERT statement.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
224
Defining SELECT statements
To define a SELECT statement:
1. Select Statement ⇒ Selection from the SQL Editor menu.
The Selection dialog box displays, as shown here:
2. Select a database from the Database type/name drop-down list box.
3. Select a table on which to base the SQL statement from the Table/columns
drop-down list box.
The column names for the table appear in the list box.
4. Select a column on which to base the SQL statement from the list box.
Click > to add the column to the Selected Columns list box. If you want to
add all of the columns, click >>.
5. Check Distinct results if you want to exclude duplicate results from the
result set.
6. Repeat steps 2–5 until you have selected all of the tables and columns
required for the statement.
7. Click OK to close the Selection dialog box and return to the SQL Editor
after you have made your selections.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
225
The following illustration shows an example of how an SQL statement appears
in the SQL Editor:
The following sections describe how to define an alias and how to create
calculated columns.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
226
Defining an alias
To define a column alias:
1. Click Define Alias on the Selection dialog box.
The Define Alias dialog box displays, as shown here:
2. Select a table name from the Table drop-down list box.
3. Type an alias for the selected table in the Alias name entry field.
4. Click Add to create a new alias.
5. Click OK to close the Define Alias dialog box.
The table name in the list changes to the alias you specified.
Modifying an alias
To modify an existing alias:
1. Select the alias that you want to change from the Defined aliases list box.
See the preceding section, “Defining an alias”.
2. Type a new alias in the Alias name entry field. You also can select a
different table from the Table drop-down list box.
3. Click Modify.
Deleting an alias
To delete a defined alias, select the alias and click Remove.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
227
Calculating columns
To calculate a column:
1. Click Calculated Columns on the Selection dialog box.
The Calculated Column dialog box opens, as shown here:
2. Type an expression in the entry field.
You can also create the expression by:
A. Double-clicking a function in the Function list box to adding it to the
expression entry field.
B. Selecting a table and a column from the Table/Column list box.
C. Selecting a mathematical function, the open or close parenthesis, or
the DISTINCT indicator from the Keypad.
D. Repeating steps a–c until the calculated column is defined.
3. Click OK to save the expression and return to the Selection dialog box.
4. To create multiple calculated columns, repeat steps 1 and 2 as necessary.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
228
Creating UPDATE or INSERT statements
To create an SQL UPDATE or INSERT statement:
1. Select Update on the Selection dialog box to define an UPDATE/SET clause.
Select Insert to define an INSERT/INTO clause. These statement types use
the same dialog box.
The Selection dialog box for INSERT and UPDATE opens, as shown here:
2. Select the column that you want to update or in which the statement
should insert new data.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
229
3. Click Values.
The Values dialog box opens, as shown here:
4. Select the column and value from the synchronized list box.
5. Enter the new column value in the Value entry field.
6. Click Apply.
Repeat steps 4–6 until you have entered data for all of the column values.
7. Click OK to close the Values dialog box.
You also can access the Values dialog box by selecting Statement ⇒ Values
from the SQL Editor menu.
You must have appropriate database rights to perform UPDATE and INSERT
statements.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
230
Defining DELETE statements
To define an SQL DELETE statement:
1. Select Delete on the Selection dialog box.
You must have appropriate database rights to perform DELETE statements.
2. Define your DELETE statement by selecting options similar to those shown
here:
3. Click OK to close the Selection dialog box and enter the DELETE statement
in the SQL Editor.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
231
Typing directly in the SQL Editor window
If you select Direct on the Selection dialog box, you can type an SQL statement
directly in the SQL Editor window. You can enter any valid SQL statement,
including those that are not defined by the Statement menu (for example,
CREATE TABLE, DROP, or GRANT). The SQL Editor provides a verification utility
to make sure your statement is syntactically correct before it executes.
To create or modify an SQL statement by typing directly in the Editor:
1. Select Direct from the Selection dialog box.
The Selection dialog box opens, as shown here:
2. Select the database type and database name to be used in the direct query
from the Database type/name list boxes.
3. Click OK to return to the SQL Editor.
4. Type your SQL statement at the cursor.
The Internal Database does not support statements created using this
option.
Opening the Data Manager
To open the Data Manager from the SQL Editor:
1. Define a query.
2. Select Actions ⇒ Data Manager.
The Data Manager displays and contains columns and data that correspond
to your query.
For more information on the Data Manager, see “Managing data” on page 214.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
232
Executing a statement
When you execute a SELECT statement, the results appear in an SQL Result
Display window. Other statement types return a message indicating success or
failure.
The Internal Database displays a result set generated from UPDATE, DELETE, or
INSERT statements. External databases do not display a result set. (To view the
results, create a SELECT statement to retrieve these records.)
To execute a statement:
1. Select Actions ⇒ Verify from the SQL Editor menu.
The status line displays a message that tells you if the statement is
syntactically correct. An error message box appears if there is a problem
with the statement.
2. Select Actions ⇒ Run Statement from the SQL Editor menu.
The SQL Result Display window displays, as shown here:
3. If you want to save the results:
♦
Select File ⇒ Save as to save the results to a file.
♦
Select File ⇒ Save Table to convert the results to an internal table.
♦
Select File ⇒ Export to delimited to save the table in a delimited file.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
233
Defining a WHERE clause
You can define a WHERE clause in the Search Condition dialog box.
To define a WHERE clause:
1. Select Statement ⇒ Search condition from the SQL Editor menu.
The Search Condition dialog box displays, as shown here:
2. Select an expression from the first Expression drop-down list box (for
example, Customer.status). You can also type an expression in the list box
entry field.
3. Select an operator from the Operator drop-down list box (for example, =).
You can also type an operator in the list box entry field.
If you select the EXISTS or NOT EXISTS operator, the first Expression dropdown list box is disabled. If you select the BETWEEN or NOT BETWEEN
operator, an AND drop-down list box appears.
4. Select a conjunction to link the next condition. The default conjunction is
AND.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
234
5. Select the second expression (or pair of expressions) from the second
Expression drop-down list box (for example, MARRIED). You can also type
an expression in the list box.
6. Click Apply to add the condition to the Conditions list box.
Repeat Steps 2–6 until you have defined or modified all parts of the WHERE
clause.
7. Optional. Group conditions by selecting conditions as needed and clicking
Group.
The Group option changes the order in which the statement applies the
selected condition; for example:
♦
Grouping A:
WHERE (customer.name = 'Smith' AND
product.name = 'chair') OR
saleperson.name = 'Fred'
Retrieves all of the records where the customer named Smith bought
chairs, and all records where Fred is the salesperson.
♦
Grouping B:
WHERE customer.name = 'Smith' AND
(product.name = 'chair' OR
saleperson.name = 'Fred')
Retrieves all of the records where the customer name is Smith, and all
of the records where Fred sold chairs.
8. Optional. Negate one or more conditions by selecting the conditions to be
negated and clicking Negate. NOT appears on the line before the selected
conditions.
9. Click OK to close the Search Condition dialog box.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
235
Defining a JOIN clause
Naming two or more tables in the FROM clause results in an implicit join of
those tables. If you do not specify the point at which the join should be made,
the statement results include every possible combination of rows. This result is
called a Cartesian product and is usually undesirable.
You can specify explicit table joins in the WHERE clause (for example, WHERE
customer.name=orders.custname), or by including a JOIN statement in the
FROM clause.
To join tables:
1. Create a SELECT statement (see “Using the Selection dialog box” on
page 224). You must select at least two tables to create a JOIN clause.
2. Select Statement ⇒ Join condition from the SQL Editor menu.
The Table Join dialog box displays, as shown here:
3. Drag a column name icon from one table and drop it onto the equivalent
column name in another table. Joined columns are indicated by combining
the table colors within the icons.
Repeat as needed to join the necessary columns.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
236
4. The default join condition is equals (=). Change the operators used to
define the join:
A. Double-click the join circle to be adjusted. The Join Details dialog box
opens, as shown here:
B. If you joined the table to more than one other table, select the table
column for which the operator should be changed.
C. Select a new operator under Operator (the default is equals (=).
D. Click OK.
5. Click OK to close the Table Join dialog box.
The JOIN function does not recognize table aliases. If you create a join in
which one or more tables were assigned aliases, edit the JOIN statement in the
main SQL Editor window to replace the table name with the appropriate alias.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
237
Defining a GROUP BY clause
To define a GROUP BY clause:
1. Select Statement ⇒ Grouping from the SQL Editor menu.
The Grouping dialog box opens, as shown here:
2. Select the table that contains the column in which you want to group data
from the Table/Columns drop-down list box.
3. Select the appropriate columns from the list box.
4. Repeat steps 2 and 3 until the GROUP BY clause is defined.
5. Click OK to close the Grouping dialog box.
The Having button opens the Having dialog box, which allows you to define a
HAVING clause. For more information on the Having dialog box, see “Defining a
HAVING clause” that follows.
Defining a HAVING clause
An SQL HAVING clause performs similar functions within a group (see the
preceding section, “Defining a GROUP BY clause”) that a WHERE clause does
for the entire statement. That is, it filters the records included in the result
set groups based on the GROUP BY clause.
The Having dialog box contains the same elements as the Search Condition
dialog box, and the clause is constructed in the same way.
For more information, see “Defining a WHERE clause” on page 234.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
238
Defining an ORDER BY clause
Use the Order dialog box to create an ORDER BY clause, which determines the
sort order for the result set. Rows are sorted according to the values within the
first selected column. If you select more than one column, rows with duplicate
data in the first column are sorted further by the values in succeeding columns.
You can order the statement result by any field, even if that field does not
appear in the SELECT clause. For example, you can sort the data by the order
date column, even if you do not display the order date in the result set.
To define an ORDER BY clause:
1. Select Statement ⇒ Order from the SQL Editor menu.
The Order dialog box opens, as shown here:
2. Select the table that contains the column by which to order data from the
Table/Columns drop-down list box.
3. Select the column by which you want to order data from the list box.
4. Click > to copy your selection to the Ordered by list box. Click >> to copy
all of the columns to the Ordered by list box.
5. Choose a sort direction (ASC, ascending, or DESC, descending) for the
selected column. The default sort direction is ASC.
Numeric columns sort in cardinal order (for example, 1, 2, 3). Alphabetic
columns sort according to the character set’s collation sequence (usually
ASCII).
6. Repeat steps 1–5 until the ORDER BY clause is defined completely.
7. Click OK to close the Order dialog box.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
239
Creating parametric SQL statements
Parametric queries allow you to build queries based on information that is
available only at run time. ObjectStudio allows you to build queries with
replaceable parameters and get the value for the parameter from a data entry
window, a report, or any executable Smalltalk code.
To enter a replaceable parameter in an SQL statement, define a WHERE clause
that contains a question mark (?); for example:
WHERE City = ?
You can enter any number of replaceable parameters into an SQL statement.
However, you must define a parameter value for each question mark entered
into the statement. ObjectStudio replaces the embedded question marks, in
the order in which they appear in the statement, with the parameter value
definitions, in the order in which they are defined.
Replaceable parameters without corresponding parameter definitions can
cause unpredictable results.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
240
To create a parametric SQL statement:
1. Select Statement ⇒ Parameters from the SQL Editor menu.
The Query Parameters dialog box opens, as shown here:
Options on the dialog box change depending on which Source you select.
2. Select Window to select an item from any currently open data entry
window, and then:
A. Select a window from the Window drop-down list box.
B. Select a form item from the Item drop-down list box.
C. Click Insert to add the item to the Parameters list box.
3. Select Report to select an item from any currently open report, and then:
A. Select a report from the Report drop-down list box.
B. Select a form item from the Item drop-down list box.
C. Click Insert to add the item to the Parameters list box.
4. Select Special to enter executable Smalltalk code to define the parameter
value.
5. Repeat steps 2–4 until all parameter values are defined.
6. Click OK to close the Query Parameters dialog box.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
241
Committing changes
You can set up the SQL Editor to commit database changes automatically when
you run a statement, or manually when you select a menu option.
Commit, Rollback, and Auto Commit options are available only if the
underlying database supports transaction processing.
The Internal Database does not support transaction processing.
To commit changes to the database manually (the default), select
Transaction ⇒ Commit from the SQL Editor menu.
To commit database changes automatically as you run each statement, select
Transaction ⇒ Auto Commit from the SQL Editor menu. A check mark appears
next to the menu option.
Rolling back changes
To roll back the database to its state when you accessed it or its state
immediately after the last commit action, select Transaction ⇒ Rollback from
the SQL Editor window.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
242
Importing and exporting statements
ObjectStudio allows you to import SQL statements created with other
applications and export SQL statements created in ObjectStudio for use in
other applications. ObjectStudio provides import and export access to SQL
statements in ASCII format.
Importing statements
To import a statement from a text file:
1. Select File ⇒ Import from text file from the SQL Editor menu.
The Open dialog box displays.
2. Select the folder where the text file is stored.
3. Select or type the file name.
4. Click Open to load the file and return to the SQL Editor.
Exporting statements
To export a statement to a text file:
1. Select File ⇒ Export to text file from the SQL Editor menu.
The Save As dialog box opens.
2. Select a folder in which to save the file.
3. Type a file name for the statement in the File name entry field.
ObjectStudio uses the default extension .sql.
4. Click Save to save the statement and return to the SQL Editor.
Creating a report for the statement
Select Actions ⇒ Report editor to access the Report Editor directly from the
SQL Editor with the current SELECT statement already linked to a report
template. This option is available only for SELECT statements. For more
information on the Report Editor, see “Report Editor” on page 246.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Editor
243
SQL Window
The SQL Window allows you to:
♦
Type SQL statements directly into a window
♦
Import and export SQL statements as text files for reuse in the SQL Editor
or SQL Window
♦
Scroll forward and backward through a series of up to five SQL statements
♦
Create and execute multiple batches of SQL statements
When you open the SQL Window, the system assumes that you want to query
the currently displayed database. However, you can select any other available
database on which to base the query.
File menu
The following table describes the File menu options:
Option
Allows you to
Load
Bring an existing statement into the SQL Window.
Save as
Save the currently displayed SQL statement as a text file (the
default extension is .sql).
Exit
Close the SQL Window. Displays the Save As dialog box if the
system detects unsaved changes to the currently displayed
SQL statement.
Actions menu
The following table describes the Actions menu options:
Option
Allows you to
Execute
Perform the statement displayed in the SQL Window.
New
Clear the statement displayed in the SQL Window so you can
enter a new one.
Previous
Scroll backward through the last five statements entered in
the SQL Window.
Next
Scroll forward through the next five statements entered in
the SQL Window.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Window
244
Creating an SQL statement
To create an SQL statement in the SQL Window:
1. Select Tools ⇒ SQL Window from the Desktop menu.
You can also open the SQL Window from the Database Notebook (see
“Database Notebook” on page 202).
The SQL Window opens, as shown here:
The status of the current SQL statement appears in the status line located
at the bottom of the window.
2. Select the database that you want to query from the Database drop-down
list box.
3. Type one or more SQL statements directly in the SQL Window. Separate
multiple statements with a semicolon (;).
4. Do one of the following:
♦
Select Actions Execute to execute the statements and display the
results (if a SELECT statement) or a Successful status (if any other
statement type).
♦
Select Actions Previous to return to the previously executed SQL
statements (if applicable)
♦
Select Actions
Next to move to the next statement to be executed
5. Select File ⇒ Save as to save the currently displayed statement.
6. Select File ⇒ Exit to close the SQL Window.
Loading an ASCII text file into the SQL Window
You can load an ASCII file containing one or more SQL statements into the SQL
Window and edit or execute it. For more information on loading SQL text files,
see “Importing and exporting statements” on page 243.
Database User's Guide, P40-3203-03
Chapter: SQL tools
Section: SQL Window
245
12
Report Editor
Using the Report Editor
The Report Editor allows you to create free form or standard reports and
include them in your applications. The Report Editor includes the following
features:
♦
Full text and graphics capabilities, allowing you to select fonts, font sizes,
icons, bitmaps, and four types of graphs
♦
Full mathematical capabilities, including aggregate functions, expressions,
and numeric formatting based on country
♦
Full database management functions, including access to queries
♦
Screen previewing with report data, allowing you to test your queries and
expressions and to verify the placement of text, numbers, and graphics in
the report
♦
Full printer support, including time-delayed printing, color printing, and
printing to files
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Using the Report Editor
246
Creating a report
Before you create a report in ObjectStudio, you may want to plan it on paper.
This plan can help you define which fields to add, which queries to use or to
create, and what calculations, such as subtotals or percentages, should be
performed.
After you create and save a report, see “Formatting, previewing, and printing a
report” on page 272 for information on editing, previewing, or printing an
existing report.
To create a new report:
1. Select File ⇒ New ⇒ Report from the Desktop menu.
The Create New Report dialog box displays, as shown here:
2. Enter a report name in the Name entry field.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Using the Report Editor
247
3. Specify the report format:
A. Select Table or Query to choose a data source for the report.
B. Select Default or Blank to start your report with either a default report
format, or a blank format on which you place fields manually.
C. Click New Query to create a query on which to base the report. For
more information on the SQL Editor, see “SQL Editor” on page 220.
D. Click Page Setup to format the page (for example, to select paper size
and margins).
E. Click Default Font to select a standard font and font size for your
report.
Setting default font options. You can save time by setting the default
font options from the Create New Report dialog box. Once you enter the
Report Editor, you can change the font and size for individual report items
only.
4. Click OK to close the Create New Report dialog box.
The Report Editor opens, as shown here. If you selected the default report
form, the system also displays fields from the database table or query.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Using the Report Editor
248
Saving reports
To save a report:
1. Select File ⇒ Save As from the Report Editor menu.
You can also select File ⇒ Exit or double-click the System Menu.
The Save As dialog box opens.
2. Select a folder in which to save the file.
3. Type a file name in the File name entry field.
4. Click Save to save the file.
The Report Editor creates an icon on the work area of the Desktop. The name
under the icon is the same as the name you entered in the Create New Report
dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Using the Report Editor
249
Working with report sections
Reports typically have several sections, each of which contains specific types of
information, as described in the following table:
Section name
Includes
Placement
Report Header
Information that applies to the entire
report (such as the report name).
Top of the first page, before the
page header (if any).
Page Header
Information that applies to each
report page (such as column headers
and field names).
Top of each page.
Page Body
Information that makes up the main
part of the report.
Middle of each page, repeated
for each record in the table.
Page Footer
Information that applies to each
report page (such as subtotals or
page numbers).
Bottom of each page.
Report Footer
Information that applies to the entire
report (such as grand totals or the
print date).
Bottom of the last page, before
page footer (if any).
Report sections function independently. Format settings made in one section
have no effect on the others. Similarly, and with few exceptions, items (fields)
placed in one section have no effect on items in other sections.
Level breaks
Level breaks allow you to group information and summarize data. For more
information on level breaks, see “Using level breaks” on page 252.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report sections
250
Adding or removing sections
When you access the Report Editor, the system displays a report header, page
header, and page body by default. Use the Sections menu to add and delete
sections from your report.
To suppress a section from the report preview and printout, set its height to
zero as described in the next section; otherwise, the system leaves space for
the item on the page.
Formatting sections
Format options for sections affect only height and grid size. The settings have
no effect on items you place in the section, other than alignment to the grid.
To format a section:
1. Select Format ⇒ Sections from the Report Editor menu.
The Format Section dialog box displays, as shown here:
2. Select a section from the Section drop-down list box.
3. Select a unit of measure.
The unit of measure affects the position of report items. When designing a
report for screen display, select tenths of millimeters to provide the
greatest compatibility across hardware platforms and operating systems.
4. Uncheck Show Grid if you do not want to use the grid.
If you want to use the grid, you can change the grid resolution in the X Grid
Res and Y Grid Res entry fields.
5. Uncheck Snap Items to Grid if you do not want to align report items to the
grid.
6. Click OK to save the settings and close the Format Section dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report sections
251
Using level breaks
Level breaks group and summarize report data. They appear as part of the
report body when you preview or print the report, but they appear as separate
sections in the Report Editor. Use level breaks to apply aggregate functions and
expressions, or to include information from additional queries to specific
subgroups of report data.
The report illustrated here shows product revenues and sales costs per quarter,
sorted by salesperson:
Note the following about the level breaks shown in the previous figure:
♦
The first level break is based on the salesperson field. It contains the
salesperson’s name and an instruction to print at the top of each group.
♦
The second level break is based on the quarter field and contains sales
figures.
♦
The third level break is also based on the salesperson field and summarizes
the sales figures for each salesperson.
♦
You can use several level breaks in the same report.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report sections
252
Subqueries
Level breaks can also include subqueries. A subquery can be any query created
in the SQL Editor. First, create the report and define the expressions and
variables you want to use. Second, save the report; then access the SQL Editor
and define your subquery. Finally, return to the Report Editor and select the
subquery you want to use in the level break. For more information on the SQL
Editor, see “SQL Editor” on page 220.
Subqueries often use parameters from your report. Using the example shown in
the figure above, suppose you want to list salespersons’ cities next to their
names. Assume your database contains a table called Employee, which contains
a field called City. Construct the following query:
select * from Employee where name = ?
Assume the name of the report is SalesRpt and that Report Item 7 is linked to
the name field. In the SQL Editor, select Statement ⇒ Parameters and add the
following parameter:
(Report report: #SalesRpt at #reportItem7
asString
Save the query and return to the Report Editor. Link the first level break to the
subquery, which then allows you to place fields, such as the City field, from
the subquery into the report. (Instructions for placing report items are
provided in “Copying or moving report items” on page 259.)
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report sections
253
Adding or modifying level breaks
To add or modify a level break:
1. Select Sections ⇒ Level Breaks from the Report Editor menu.
The Level Breaks dialog box opens, as shown here:
2. Select a field, on which to base the level break, from the Fields list box.
The system automatically names the break for the field and attaches a
numeric identifier.
You can also select an existing level break. The system highlights any
options previously chosen for the selected level break.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report sections
254
3. Format the level break:
A. Select ASC (ascending) or DESC (descending) to order the data in the
level break.
B. Select Group Header or Group Footer to place the level break before or
after its related data in the body of the report.
C. Check Trigger lower breaks to reset and reprint information when using
multiple level breaks.
D. Check Page break before or Page break after to put a page break
before or after a level break.
E. Check Merge nested breaks to combine the data from level breaks that
are linked by subqueries.
4. Repeat steps 2 and 3 as needed to define additional level breaks.
5. Click OK to return to the Report Editor.
6. Add, change, or remove report items to each level break, as needed.
You can insert any report item into a level break, including a graph. For
information on creating a graph, see “Defining and formatting graphs and graph
legends” on page 268.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report sections
255
Working with report items
Report items can be text strings, graphic elements, or data fields:
♦
Text strings can be used as titles, headers, or other identifying labels in the
report.
♦
Graphic elements include lines, boxes, graphs, or bitmaps.
♦
Data fields contain values from the selected table or query. Data fields can
also contain values from calculations, such as the numeric value of a grand
total placed at the end of a report.
You can place items in any section of the report. After you place the items, you
can delete, move, resize, or copy them.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report items
256
Adding report items
To add an item to a report:
1. Select Edit ⇒ New Item from the Report Editor menu.
The New Item dialog box opens, as shown here:
2. Enter a name for the item in the Name entry field or keep the default
name.
3. Select a section from the Section drop-down list box.
4. Select a type from the Type list box.
5. Select a Field from the Field list box.
6. Check Link to Field to link the report item to a specific field in the table or
query. When you select the field, the system automatically selects the
correct field type.
7. Check Add Page Title to insert a column header in the page header section.
Check Select Add Page Total to insert a total in the page footer section.
To create a graph, link to a number field and then select the Graphics field
type. For more information on using graphs, see “Defining and formatting
graphs and graph legends” on page 268.
8. Click OK to save your changes and close the New Item dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report items
257
Resizing report items
To resize a report item:
1. Select the report item that you want to resize.
2. Hold mouse button 1 and grab one of the report item handles.
3. Drag the report item in the appropriate direction until the item is the size
that you want and release mouse button 1.
Deleting report items
To delete a report item:
1. Select the item you want to delete from the report section in the Report
Editor.
2. Select Edit ⇒ Delete Item from the Report Editor menu.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report items
258
Copying or moving report items
To copy an item and/or move it to a different section:
1. Select the item that you want to copy or move.
2. Select Edit ⇒ Copy/Move Item from the Report Editor menu.
The Copy/Move dialog box opens, as shown here:
3. Enter the destination name in the Destination Name entry field.
4. Select a section from the Destination Section drop-down list box.
5. Select a page to which the selected item should be moved or copied from
the Destination Page drop-down list box.
6. Optional. Enter new X and Y positions and a new height for the copied or
moved item. The units of measure refer only to measurements in the
Copy/Move dialog box. When you change units, the values for position and
size convert automatically.
7. Click Copy or Move to confirm your changes and return to the Report
Editor.
You also can select a report item and use mouse button 1 to drag the item to a
new location on the report page.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Working with report items
259
Formatting report items
Report items have different formatting options, depending on the information
they contain. For example, the formatting options for a text string differ from
those for a pie chart.
After placing string and numeric items on your report, you can format them or
change their function.
To format a report item:
1. Double-click the report item that you want to change.
You can also select the item, then select Format ⇒ Selected Item from the
Report Editor menu.
The Report Item Options dialog box opens, as shown here:
The Value field displays information that appears in the report (for
example, the text in a column header, columnar data, or an expression).
2. To enter a new string value, such as a column header, type the new string
in the Value field.
3. Select Expression to define an expression in the Value entry field (uncheck
Link to Field if necessary).
Select fields and operators from the Field and Operators list boxes. The
expression appears in the Value field.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting report items
260
4. Link to Field allows you to link an item to a specific field from the table or
query on which the report is based. To link an item to a field, check Link to
Field; then select a field.
You also can use a linked field for aggregate functions. Check Link to Field;
then select one of the Functions (Count, Sum, Average, Minimum, or
Maximum).
5. Check Multi-Line String if you want to format an item that occupies more
than one line of the report (for example, lengthy comment fields).
The Options button appears on the form. For more information on
formatting multi-line strings, see “Formatting multi-line string items” on
page 262.
6. Display Options allows you to hide a box that surrounds items, suppress
repeated data in a column, or prevent an item from appearing on the
screen. For example, you might want to hide repeated data, such as sales
order numbers, so that they print only once (for example, when the
numbers change).
7. Click Format to display the String, Numeric, or Date Display Format dialog
box. The dialog box that opens depends on the type of report item you
select:
♦
String item format options include such settings as font, font size,
justification, and style (for example, bold or italic).
♦
Numeric item format options include those available for string options,
plus international currency and decimal settings, precision, and
leading-character options.
♦
Date item format options include those available for string options,
plus a variety of date and time settings.
For more information on these formatting dialog boxes, refer to the
ObjectStudio User Interface Guide, P40-3205.
8. Click OK to save your changes and close the Report Item Options dialog
box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting report items
261
Formatting multi-line string items
Multi-line string items can contain up to 8,192 characters.
To access formatting options for multi-line strings:
1. Select the report item to be used as a multi-line string.
2. Use the mouse to size the item appropriately.
3. Double-click the item to display the Report Item Options dialog box.
4. Check Multi-Line String.
5. Click Options.
The Multiple Line Item Options dialog box displays, as shown here:
6. Max Height determines how the multi-line string uses space on the report
page. Select one of the following options:
♦
Size Field Dynamically adjusts the size of the item to accommodate the
field contents.
♦
Size field up to max height adjusts the item to the size you set in step
1. (Field contents that exceed the maximum height are truncated.)
♦
Always use max height allows the full size that you set in step 1,
whether or not the field contents need the space.
7. Select one of the measures of units.
8. Check User-defined line spacing to define how much space appears
between each line of text. Type a value in the appropriate unit of measure
in the Line Spacing entry field.
9. Click OK to close the Multiple Line Item Options Dialog Box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting report items
262
Formatting graphic items
The Report Editor offers numerous graphic elements that enhance the
appearance and readability of your reports. You can add any of the following
items:
♦
Horizontal or vertical lines.
♦
Boxes with square or rounded corners.
♦
Bitmaps, such as your company’s logo.
♦
Bar graphs, line charts, pie charts, and scatter graphs. For more
information on graphs, see “Defining and formatting graphs and graph
legends” on page 268.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting graphic items
263
Formatting lines and topic boxes
Use vertical lines to separate columns of data, or a horizontal line to separate
a column header or footer from the page body. Add topic boxes to a report to
highlight or surround special information.
To create and format a line item:
1. Select Line from the Type list box on the New Item dialog box and add it to
the form.
2. Double-click the line item on the report page to open the Report Line
Options dialog box, as shown here:
3. Select a Format.
4. Type a line width in the Line Width entry field.
Line widths are measured in tenths of millimeters.
5. Select a color from the Line Color list box.
A sample of the line appears in the Example area.
6. Click OK to return to the Report Editor.
7. Use mouse button 1 (or the Copy/Move dialog box) to size the line or topic
box, if necessary.
The steps for creating and formatting a topic box are similar to the previous
steps for creating and formatting a line.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting graphic items
264
Creating and formatting bitmapped images
The Report Editor allows you to insert one or more bitmaps into your reports.
For example, for an inventory listing, you might want to display your
company’s logo in the report header and an image of a clipboard at the left
side of the page body. Keep in mind that the quality of the images depends on
your printer and monitor.
If you plan to use the same file image repeatedly in many reports, register the
image in ObjectStudio (see “Registering a graphics file” on page 267).
Creating a bitmap
To create a bitmap:
1. Select Edit ⇒ New Item from the Report Editor menu.
The New Item dialog box opens.
2. Select Bitmap from the Type list box on the New Item dialog box.
3. Click OK to close New Item dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting graphic items
265
Formatting the bitmap
To format the bitmap:
1. Double-click the bitmap report item.
The Report Bitmap Options dialog box opens, as shown here:
2. Type a new name in the Name entry field, or you can keep the default
name.
3. Select the type of bitmap under Type:
♦
If you select Icon or Bitmap, you can select the type of bitmap from
the Icons drop-down list box.
♦
The Example field displays an example of the bitmap that you selected.
♦
If you select File, you must select a file to create the bitmap:
A. Click Search to open the Open dialog box.
B. Select the file from the Open dialog box.
C. Click Open.
4. Click OK to close the Report Bitmap Options dialog box.
5. Move, copy, and resize the image as needed.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting graphic items
266
Registering a graphics file
If you use the same graphics files regularly, you can register them as bitmaps
or icons.
To register a graphics file:
1. Select Tools ⇒ Workspace from the Desktop menu.
2. Define the image as a temporary variable. For example, to register a file
called marble.bmp, enter the following in the Workspace:
bmp :=bitmap loadFile: 'c:\marble.bmp'.
bmp registerAs: #Marble.
3. Select Actions ⇒ Execute from the Workspace menu.
4. Select File ⇒ Quit to close the Workspace and return to the Report Editor.
As long as ObjectStudio is open, you can select the new bitmap by selecting
Bitmap on the Report Bitmap Options dialog box. Save the image to store the
bitmap permanently.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting graphic items
267
Defining and formatting graphs and graph legends
The Report Editor can generate the following types of charts:
♦
Bar
♦
Line
♦
Scatter
♦
Pie
The New Item dialog box contains two types of graphic report items. The
Graphics Field option appears after you select the Link to field option and
choose a numeric field. The graphics field item contains the actual graph,
which you format after creating and placing the item. The Graphics Legend
option can be selected like a string item and can be used to replace a field
name in a graph with a more descriptive label. For more information on
graphics legends, see “Formatting graphics legends” on page 271.
Placing a graphics field
The report section in which you place a graph determines its content:
♦
In the page body, a separate graph appears for each record
♦
In the page footer, the graph incorporates data from each page
♦
In a level break, the graph shows results for the break
♦
In the report footer, the graph includes data from the entire report
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Defining and formatting graphs and graph legends
268
Defining a graphics field
To define a graphics field:
1. Double-click the graphics field item to display the Report Graph Options
dialog box.
2. Select the following options as needed:
♦
Assign a graph name that you can remember easily. If you use graph
legends, you must link them to the correct graph.
♦
Select the type of graph under Type.
♦
Check Enable Label Link to choose a field name for the X-axis label.
♦
Select additional fields for the graph, if needed; then click Insert. For a
scatter graph, select fields for the X- and Y-axis.
♦
Check Hide Item Borders to display or hide an outline around the graph.
3. Click OK to save your changes and return to the Report Editor
4. Move and resize the graph as needed.
Formatting graphics fields
The Report Editor offers full formatting capabilities for your graphs. Color
selections appear in the report preview and in printouts if your printer supports
the selected colors. For information on previewing and printing, see
“Formatting, previewing, and printing a report” on page 272.
To format a graphics field:
1. Double-click the graphics field item to display the Report Graph Options
dialog box.
2. Click Format to open the Display Format dialog box for the type of graph
you selected.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Defining and formatting graphs and graph legends
269
3. Select options as needed.
The system displays your settings in the Example box. Confirm your changes
when you are ready to return to the Report Editor. (The X- and Y- label
format buttons present the String or Numeric Display Format dialog box, as
appropriate.)
Specific formatting options for each type of graph are:
♦
♦
♦
♦
Bar graph format options:
-
A color and a pattern for each graph level (bar) and for the X- and
Y-axis labels
-
Whether the bars should be grouped or stacked
-
Display formats and colors for the X- and Y-axis labels
-
Minimum and maximum numbers to display in the X- and Y-axes
Line graph format options:
-
A color, pattern, and width (in millimeters) for each graph level
(line)
-
Display formats and colors for the X- and Y-axis labels
-
Minimum and maximum numbers to display in the X- and Y-axes
Scatter graph format options:
-
A color and shape for each graph level (marker)
-
Display formats and colors for the X- and Y-axis labels
-
Minimum and maximum numbers to display in the X- and Y-axes
Pie chart format options:
-
A color and pattern for each graph level (section)
-
Minimum and maximum numbers to display in the X-axis
-
A display format for the X-axis
Although you can set the X- and Y-axes colors, the selections have
no effect on a pie chart.
-
The number of columns per group (for example, repetition of colors
and patterns)
Two graph levels are used in a pie chart, but you can select
additional levels as needed by choosing the number of columns per
group.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Defining and formatting graphs and graph legends
270
Formatting graphics legends
Graphics legends list fields selected from the table or query on which the graph
is based. Use the legends to substitute appropriate labels for your graph. For
example, you might substitute Sales Rep for a field named srname. Create
graphics legends just like string fields.
Graphics legends work with bar, line, and scatter graphs but not with pie
charts.
To format a graphics legend:
1. Double-click the graphics legend report item.
The Report Legend Options dialog box opens, as shown here:
2. Select a graph to which you want to link the graph legend from the Link to
graph drop-down list box.
3. Click Label Format to display the String Display Format dialog box. Make
changes as needed.
4. Click OK to close the Report Legend Options dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Defining and formatting graphs and graph legends
271
Formatting, previewing, and printing a report
After you finish adding items and graphics to your report, you can preview and
print the report.
Formatting report pages
Before you preview or print your report, set page format parameters:
1. Click Page Setup in the Create New Report dialog box, or select
Format ⇒ Page Setup in the Report Editor.
The Page Setup dialog box opens, as shown here:
2. Select the page-size setting from the Page Size entry field.
The page-size settings allow you to select the paper size and print
orientation (portrait or landscape) for your report. To define custom-cut
paper stock, select User Defined in the Page Size list box. Enter a page
height, width, and margins in the appropriate units.
3. Select a Value to determine the units to use for setting the margins.
The unit of measure refers only to the margin settings. When you change
the unit of measure, the margin settings convert automatically.
4. Click OK to close the Page Setup dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting, previewing, and printing a report
272
Horizontal and vertical pages. The Report Editor aligns reports on a grid of
horizontal and vertical pages, as shown here:
Horizontal pages display report items and data in columns, as in a spreadsheet.
When you select the Default radio button on the Create New Report dialog box,
the system automatically places each field in a column. If your table or query
has several columns, your default report will have two or more horizontal
pages. Use the Horizontal Pages menu in the Report Editor to add, display, or
delete horizontal pages.
Vertical pages display data according to the column alignment of the horizontal
pages. The number of vertical pages in your report depends on the number of
records and the number of required page breaks. Use the Pages menu in the
Report Preview to move to another vertical or horizontal page.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting, previewing, and printing a report
273
Previewing a report
Previewing a report on the screen allows you to verify the placement and
content of report items. You can also print a single page to check a sample
from your printer.
To preview a report:
1. Select File ⇒ Screen Preview from the Report Editor menu.
The Report Preview opens, as shown here:
It shows one formatted page at a time. You can resize the Report Preview
window as needed and use the Pages menu to display additional report
pages. (The system displays the current vertical and horizontal page in the
title bar.)
2. Select File ⇒ Exit to close the Report Preview window and return to the
Report Editor.
Printing from the Report Preview
To print from the Report Preview:
1. Select File ⇒ Print current page or File ⇒ Print all pages from the Report
Preview menu.
2. Select the appropriate settings for your printer from the Print dialog box.
3. Click OK to print the report.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting, previewing, and printing a report
274
Setting the report timer
You can set the report timer to print a report at specific times. The timer
starts when you activate it and save the report (see “Saving reports” on
page 249). As long as ObjectStudio is open, the timer counts down until the
report prints.
In an application, the following actions start the timer:
♦
Double-clicking the report icon on the Desktop and selecting Report
printing options from the Print dialog box.
♦
Loading a report from a file (if you saved the report with an activated
timer).
♦
Closing the Report Output Options dialog box.
Opening the Report Output Options dialog box or modifying the report in the
Report Editor stops an activated timer.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting, previewing, and printing a report
275
To set the report timer:
1. Select File ⇒ Timer from the Report Editor menu.
The Report Timer dialog box opens, as shown here:
The options available on the Report Timer dialog box depend on the Mode
you select.
2. Do the following as needed:
♦
For a daily report, enter the time.
♦
For a weekly report, select the day of the week and enter the time.
♦
For an interval report, enter a period in hundredths of a second. (For
example, to print the report every two hours, enter 720,000.)
♦
For a one-time-only report, enter the date and time.
♦
Select Activate to begin the timer countdown.
♦
Select Deactivate to keep the timer settings but disable the
countdown.
3. Click OK to close the Report Timer dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting, previewing, and printing a report
276
Setting output options
Report output options allow you to select page-printing options for your report.
To set report output options:
1. Select File ⇒ Output Options from the Report Editor menu.
The Report Output Options dialog box displays, as shown here:
2. Select one of the following options:
♦
Select “Do not prompt for printer setup” to disable a printer setup
dialog box. (The contents of the setup dialog box depend on your
operating system.)
♦
Select “Pause between vertical pages” to give the user time to load
special paper, such as letterhead, between horizontal and vertical
pages. (This option is best suited for local printers rather than centrally
located network printers.)
♦
Select “Page breaks after each record” to start each record on a new
page.
♦
Select “Disable FormFeed for page breaks” to disable the normal form
feed for page breaks.
3. Click OK to save the options and return to the Report Editor.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting, previewing, and printing a report
277
Printing or previewing a report
To print or preview an existing report from the Desktop:
1. Double-click the report icon on the work area of the Desktop.
If the report’s icon does not appear on the work area, select
File ⇒ Load Application and select the file name for the report from the
Applications dialog box. The icon for the report then appears in the work
area.
The Report Editor opens and displays the Report Output dialog box.
2. Select a page size from the Page Size list box.
3. Select an output destination from Output.
If you select Printer or File, you must supply a printer or file name. If you
select Preview, the report appears on the screen.
4. Check Plain text to create an ASCII text file.
5. Click OK to close the Report Output dialog box.
Database User's Guide, P40-3203-03
Chapter: Report Editor
Section: Formatting, previewing, and printing a report
278
A
Cross-platform development
Windows character set conversion
By default, ObjectStudio assumes that all database data is stored using the
ASCII character set. The character set used within the Windows operating
environment, however, is the ANSI character set. ObjectStudio, therefore,
automatically performs ASCII-to-ANSI conversions on all database reads and
ANSI-to-ASCII conversions on all database writes to ensure that extended
characters are displayed correctly.
If your database data is actually stored in ANSI, you can turn off these
conversions, individually by database type, using an available class method. For
example, the following code turns off conversion for Oracle databases:
OracleDatabase setCharSetTo: #ANSI.
This method affects only the specific database class and has no effect on
FileStream I/O or any other databases.
Database User's Guide, P40-3203-03
Chapter: Cross-platform development
Section: Windows character set conversion
279
Index
?
?, and parameters 76
A
accessing databases 45
accessName: class method 45,
95
ADABAS databases
classes
AdabasDatabase 25
AdabasDatabaseCursor 33
AdabasScrollableCursor 35
AdabasTable 30
specifications 19
support 196
AdabasDatabase class 25
AdabasDatabaseCursor class 33
AdabasScrollableCursor class
35
AdabasTable class 30
add: instance method 58
addField:type:extType:format
: instance method
in ORDBTable class 182
in SupraTable class 140
adding
conditions 235
level breaks 254
page titles 257
page totals 257
parameters to statements
240
records 211, 214
report
items 257
sections 251
aliases 52
allowedModifications class
method
in ORDBTable class 180
in SupraTable class 138
AND conjunction 234
ANSI conversion 279
Database User's Guide, P40-3203-03
Index
ANSI Mode loadable
applications for Oracle
187
API
SUPRA 100
Application Programming
Interface. See API
applications, packaging 63
ASCII
column designation,
consideration for SUPRA
SQL 98
conversion 279
text files
exporting SQL statements
to 243
importing SQL statements
from 243
asDBStringFor: instance
method 51
asFloat instance method 77
asInteger instance method 77
asInternalTable instance
method 54
asString instance method 77
at:put: instance method
in ORDBDatabase class 165
in ORDBScrollableCursor
class 176
attributes, assigning to fields
209
B
bar graphs, generating 268
beginTran instance method 48
binary large objects, working
with in ODBC. See BLOBs,
working with in ODBC
BIND command 89
binding the DB2 files manually
87
bitmapped images, registering
267
BLOBs, working with in ODBC
82
blobSupport: instance method
82
280
BYTE column designation,
consideration for SQL
SUPRA 98
byteArrayAsDBStringValue:
instance method
in ORDBDatabase class 155
in SupraDatabase class 107
C
calculated columns 228
Cancel instance variable 121,
169
Cartesian product 236
cataloging DB2 databases 91
changed: instance method 60,
61
character set conversion 279
check instance method
(primitive) 107
checkAccessName: class
method
in ORDBDatabase class 149
in SupraDatabase class 101
class methods
accessName: 45, 95
allowedModifications
in ORDBTable class 180
in SupraTable class 138
checkAccessName:
in ORDBDatabase class
149
in SupraDatabase class
101
dbTypeForClass:
in ORDBDatabase class
149
in SupraDatabase class
101
dbTypeForClass:is:
in ORDBDatabase class
149
in SupraDatabase class
101
defaultDBType
in ORDBDatabase class
149
in SupraDatabase class
102
Database User's Guide, P40-3203-03
Index
description
in ORDBDatabase class
150
in ORDBDatabaseCursor
class 164
in ORDBLogonController
class 170
in ORDBScrollableCursor
class 175
in ORDBTable class 180
in SupraDatabase class
102
in SupraDatabaseCursor
class 116
in SupraLogonController
class 122
in SupraScrollableCursor
class 128
in SupraStringColumn
class 132
in SupraTable class 138
directory 45, 148
ESDatabase 91
externalTypeSupport
in ORDBTable class 180
in SupraTable class 138
getNamed: 210
getServers 26, 43
hasLogonView
general description 42
in ORDBDatabase class
150
in SupraDatabase class
102
281
class methods (cont.)
initialize
general description 42
in ORDBDatabase class
150
in ORDBDatabaseCursor
class 164
in ORDBLogonController
class 170
in ORDBScrollableCursor
class 175
in ORDBTable class 181
in SupraDatabase class
102
in SupraDatabaseCursor
class 116
in SupraLogonController
class 122
in SupraScrollableCursor
class 128
in SupraTable class 139
initModule 64
loginUser:password:
(primitive) 150
loginUser:password:lock:tim
eout: 103
logonView
general description 42
in ORDBDatabase class
151
in SupraDatabase class
103
packaging applications
and 63
maxCursors (primitive)
in ORDBDatabaseCursor
class 164
in ORDBScrollableCursor
class 175
in SupraDatabaseCursor
class 116
in SupraScrollableCursor
class 128
maxDatabaseNameLength
in ORDBDatabase class
151
in SupraDatabase class
103
Database User's Guide, P40-3203-03
Index
maxNameLength
in ORDBTable class 181
in SupraTable class 139
new: 37
new:column:key:write: 132
nextCursor
in ORDBDatabaseCursor
class 164
in ORDBScrollableCursor
class 175
in SupraDatabaseCursor
class 116
in SupraScrollableCursor
class 128
parseString: 37, 38
privateDBCreateHideOptions
in ORDBDatabase class
151
in SupraDatabase class
104
privateDirectory (primitive)
in INFDatabase class 95
in ORDBDatabase class
152
in SupraDatabase class
104
setDataLoadLimitTo: 24, 50
supportedFeatures
in ORDBDatabase class
152
in SupraDatabase class
104
supportsSize
in ORDBDatabase class
152
in SupraDatabase class
104
tableClass
in ORDBDatabase class
153
in SupraDatabase class
105
type:precision:scale:nullable
77
userName (primitive) 105,
153
282
class methods (cont.)
validPrecisionTypes
in ORDBDatabase class
153
in SupraDatabase class
105
validSizedTypes
in ORDBDatabase class
153
in SupraDatabase class
105
validTypes
in ORDBDatabase class
154
in SupraDatabase class
106
version (primitive)
in ORDBDatabase class
154
in SupraDatabase class
106
visibleTablesAt:put: 46, 62
class variables
cursors
in ORDBDatabaseCursor
class 163, 164
in ORDBScrollableCursor
class 174
in SupraDatabaseCursor
class 114
in SupraScrollableCursor
class 126
dataLoadLimit 50
henv 70
typesSupported
in ORDBTable class 179,
180
in SupraTable class 137,
138, 139
classes
AdabasDatabase 25
Cursor 33
Database 23
ESDatabase 25
ExtDbScrollableCursor 34
ExternalDatabase 24
ExternalDatabaseCursor 33
ExternalTable 30
INFDatabase 26
Database User's Guide, P40-3203-03
Index
InternalDatabase 27
LocalCursor 35
LocalDatabase 24
LocalDatabase 27
ODBCDatabase 24, 68
ODBCScrollableCursor 34
OracleDatabase 25
ORDBDatabase 27, 148
ORDBDatabaseCursor 162
ORDBLogonController 168
ORDBScrollableCursor 174
ORDBTable 179
Query 37
SAGSqlConnection 70
SqlDirect 37
SqlParse 37
SqlSelect 39
SQLServerDatabase 26
SqlSubSelect 39
SqlUpdate 39
SupraDatabase 26, 100
SupraDatabaseCursor 114
SupraLogonController 119
SupraScrollableCursor 126
SupraStringColumn 131
SupraTable 136
SybaseDatabase 26
Table 28, 29
VectorTable 30, 50
close instance method
(primitive) in class
SupraStringColumn 133
general description 54
columns
adding titles 257
calculated 228
excluding from FROM clause
224
total 257
commit instance method
(primitive) in ORDBDatabase
class 155
general description 48
COMMIT WORK RELEASE
statement, consideration
for SUPRA SQL 98
conditions 234–37
conjunctions (AND, OR) 234
283
connecting to a database 42–
44, 95
copy instance method 54
copyTo:sourcePos:destPos:len
gth: instance method
(primitive) 133
createItems instance method
in ORDBLogonController
class 171
in SupraLogonController
class 123
createTableFrom instance
method
in ORDBTable class 182
in SupraTable class 140
creating
calculated column 228
condition clause 234
DELETE statement 231
DIRECT statement 232
field 209
FROM clause 224
graph field in report 269
GROUP BY clause 238
HAVING clause 238
INSERT statement 229
INTO clause 229
new database 204
query, from Database
Notebook 217
report
from ObjectStudio
Desktop 247
from SQL Editor 243
SELECT statement 225
SET clause 229
SQL statement 245
table 206
table join 236
UPDATE statement 229
WHERE clause 234
cross-platform development
279
Cursor
class 13, 32, 33
objects, processing result
sets 14
Database User's Guide, P40-3203-03
Index
cursors
DB2 86
linking to 59
methods 54, 62
nonscrollable 33, 55, 114,
162
ODBC example 80
scrollable 34–35, 174
SQL, using, vs. using cursors
52
working with 53
cursors class variable
in ORDBDatabaseCursor class
163, 164
in ORDBScrollableCursor
class 174
in SupraDatabaseCursor class
114
in SupraScrollableCursor
class 126
customizing
default data entry form 213
default Data Manager form
214
D
data
entering 211
entry form, default
accessing 211
customizing 213
type
conversion 77
mapping, ODBC 73
Data Manager
form 216
opening
from Database Notebook
214
from SQL Editor 232
dataArea instance variable
in SupraDatabaseCursor class
115
in SupraScrollableCursor
class 127
284
database
accessing 45
applications, loading 40
autocommitting changes 242
classifications 12
committing changes 242
connecting to 42–44, 95
delaying initialization of DLL
until user starts 64
delaying login to 65
external
accessing 40
creating 204
cursors, using 31
ExternalDatabase class 24
loading support 40
tables, creating 206
messages 62
methods 45
names, showing in SQL
Editor 223
object framework 13
objects 13
rolling back changes 242
sessions, multiple,
considerations for SUPRA
SQL 98
support
features 12
implementation 17
tools 15
using SQL to query 49
Database class 13, 22
database instance method
in ORDBLogonController
class 171
in SupraLogonController
class 123
database management
systems. See external
databases
Database Notebook
creating external databases
204
data entry forms 211
opening
from Data Manager 214
SQL Browser 218
pop-up menu 203
Database User's Guide, P40-3203-03
Index
databaseIV instance variable
132
databaseType instance
method
in ORDBDatabase class 155
in SupraDatabase class 107
dataLoadLimit class variable
50
dateAsDBStringValue: instance
method
in ORDBDatabase class 156
in SupraDatabase class 108
DB2 databases
cataloging 91
classes
ESDatabase 25
ESDatabaseCursor 33
ESScrollableCursor 35
ESTable 30
cursors 86
executing stored procedures
92
extended services 86
manually binding the DB2
files 87
specifications 19
uncataloging 92
DBMS. See database
dbName instance variable 141
dbrecords instance variable
49, 50
dbTables instance method 58
dbTablesAt: instance method
28, 58
dbTypeForClass: class method
in ORDBDatabase class 149
in SupraDatabase class 101
dbTypeForClass:is: class
method
in ORDBDatabase class 149
in SupraDatabase class 101
defaultDBType class method
in ORDBDatabase class 149
in SupraDatabase class 102
285
defaultMethod instance
method
in ORDBLogonController
class 171
in SupraLogonController
class 123
defaults, Data Manager form
215
DELETE statements 231, 233
deleteField: instance method
in ORDBTable class 182
in SupraTable class 140
deleting
object from dependency list
61
records 214
report sections 251
dependency
lists 60, 61
description class method
in ORDBDatabase class 150
in ORDBDatabaseCursor class
164
in ORDBLogonController
class 170
in ORDBScrollableCursor
class 175
in ORDBTable class 180
in SupraDatabase class 102
in SupraDatabaseCursor class
116
in SupraLogonController
class 122
in SupraScrollableCursor
class 128
in SupraStringColumn class
132
in SupraTable class 138
descriptorIV instance variable
132
desktopWpObjIconSource
instance method
in ORDBLogonController
class 172
in SupraLogonController
class 124
Database User's Guide, P40-3203-03
Index
desktopWpObjName instance
method
in ORDBLogonController
class 172
in SupraLogonController
class 124
DIRECT statements 232
directory class method 45, 148
displaying statement results
233
DLL
delaying initialization of 64
loading support for 64
driverName instance method
in ORDBDatabase class 156
in SupraDatabase class 108
dropOnDesktop instance
method
in ORDBLogonController
class 172
in SupraLogonController
class 124
E
EBCDIC column designation,
consideration for SUPRA
SQL 98
editing
level breaks 254
records 214
EnfinGetSQLServers
environment variable 196
enhancing performance 62
entering data 211
environment variables
EnfinGetSQLServers 196
InformixHOST 95
InformixSERVER 95
286
error
blocks
SQLServer databases 197
SYBASE 200
codes 49
handling, ODBC databases 85
message, returning the last
error message
with
SupraScrollableCursor
class 129
ESDatabase class 25
ESDatabase class method 91
ESDatabaseCursor class 33
ESScrollableCursor class 35
ESTable class 30
execFunc:onError: instance
method 190, 191
execFunc:returnType:paramTy
pes instance method 190,
191
execFunc:returnType:paramTy
pes:onError: instance
method 190, 191
execProc:onError: instance
method 188, 189
execProc:paramTypes:
instance method 188, 189
execProc:paramTypes:onError:
instance method 188, 189
execSql: instance method 29,
49, 191
execSql:onError: instance
method 50
execute instance method 38
executing stored procedures
DB2 92
Informix 96
execution methods, SQL 49
expandLength:with: instance
method (primitive) 133
exporting SQL statements 243
expressions
for report items 260
in calculated column 228
in WHERE condition 235
ExtDbScrollableCursor class 34
extended services, DB2 86
Database User's Guide, P40-3203-03
Index
external database
accessing 40
creating 204
cursors, using 31
ExternalDatabase class 24
loading support 40
tables, creating 206
ExternalDatabase class 24
ExternalDatabaseCursor class
33
ExternalTable class 30
ExternalTableForeignKey class
74
ExternalTableIndexKey class
74
ExternalTableKey class 74
ExternalTableUniqueKey class
74
externalTypeSupport class
method
in ORDBTable class 180
in SupraTable class 138
F
fields
assigning attributes to 209
creating 209
graphics fields 269
linking to report items 257
fieldValues instance variable
166, 177
FLOAT columns, consideration
for SUPRA SQL 98
footers, report 250
foreignKeys instance method
74
formal parameters,
representing 76
formatting
graphics fields 269
lines 264
multi-line string items 262
report
items 260–62
sections 251
topic box items 264
287
forms
default data entry 211
default Data Manager 215
forward-fetching cursors. See
nonscrollable cursors
freeModule instance method
64
FROM clause
creating 224
specifying tables in 224
G
gateway. See database
getNamed: class method 210
getServers class method 26, 43
global variables
ModuleDictionary 64
StartStopAnnouncementList
24, 65
GRANT command 90
graphics
fields 269
files, registering as bitmap
files or icons 267
items, formatting in reports
263
graphs 268
grids 251
GROUP BY clause 238
grouping conditions 235
Grouping dialog box 238
I
IBM DB2 databases. See DB2
databases
icons, registering 267
images, including login
controllers 63
indexKeys instance method 74
INFDatabase class 26
INFDatabaseCursor class 33
Informix databases
classes
INFDatabase 26
INFDatabaseCursor 33
INFScrollableCursor 35
INFTable 30
connecting to 95
executing stored procedures
96
looking for 95
specifications 20
transaction processing 95
updateable cursors support
55
InformixHOST environment
variable 95
InformixSERVER environment
variable 95
INFScrollableCursor class 35
INFTable class 30
H
hasLogonView class method
general description 42
in ORDBDatabase class 150
in SupraDatabase class 102
HAVING clause, creating 238
Having dialog box 238
headers for report 250
height, for report sections 251
henv class variable 70
horizontal pages 273
host name, local,
automatically setting for
SQL Server 199
Database User's Guide, P40-3203-03
Index
288
initialize class method
general description 42
in ORDBDatabase class 150
in ORDBDatabaseCursor class
164
in ORDBLogonController
class 170
in ORDBScrollableCursor
class 175
in ORDBTable class 181
in SupraDatabase class 102
in SupraDatabaseCursor class
116
in SupraLogonController
class 122
in SupraScrollableCursor
class 128
in SupraTable class 139
initializeBindings instance
method
in ORDBLogonController
class 172
in SupraLogonController
class 124
initModule class method 64
INSERT statements 229
instance methods
add: 58
addField:type:extType:form
at:
in ORDBTable class 182
in SupraTable class 140
asDBStringFor: 51
asFloat 77
asInteger 77
asInternalTable 54
asString 77
at:put:
in ORDBDatabase class
165
in ORDBScrollableCursor
class 176
beginTran 48
blobSupport: 82
byteArrayAsDBStringValue:
in ORDBDatabase class
155
in SupraDatabase class
107
Database User's Guide, P40-3203-03
Index
changed: 60, 61
check (primitive) 107
close
(primitive) in class
SupraStringColumn 133
general description 54
commit
(primitive) in
ORDBDatabase class 155
general description 48
copy 54
copyTo:sourcePos:destPos:le
ngth: (primitive) 133
createItems
in ORDBLogonController
class 171
in SupraLogonController
class 123
createTableFrom
in ORDBTable class 182
in SupraTable class 140
database
in ORDBLogonController
class 171
in SupraLogonController
class 123
databaseType
in ORDBDatabase class
155
in SupraDatabase class
107
dateAsDBStringValue:
in ORDBDatabase class
156
in SupraDatabase class
108
dbTables 58
dbTablesAt: 28, 58
defaultMethod
in ORDBLogonController
class 171
in SupraLogonController
class 123
deleteField:
in ORDBTable class 182
in SupraTable class 140
289
instance methods (cont.)
desktopWpObjIconSource
in ORDBLogonController
class 172
in SupraLogonController
class 124
desktopWpObjName
in ORDBLogonController
class 172
in SupraLogonController
class 124
driverName
in ORDBDatabase class
156
in SupraDatabase class
108
dropOnDesktop
in ORDBLogonController
class 172
in SupraLogonController
class 124
execFunc:onError: 190, 191
execFunc:returnType:param
Types: 190, 191
execFunc:returnType:param
Types:onError: 190, 191
execProc:onError: 188, 189
execProc:paramTypes: 188,
189
execProc:paramTypes:onErr
or: 188, 189
execSql: 29, 49, 191
execSql:onError: 50
execute 38
expandLength:with:
(primitive) 133
foreignKeys 74
freeModule 64
indexKeys 74
initializeBindings
in ORDBLogonController
class 172
in SupraLogonController
class 124
isORDB 156
isSupra 108
lastError 85
length (primitive) 134
Database User's Guide, P40-3203-03
Index
load (primitive)
in ORDBDatabase class
156
in SupraDatabase class
108
loadInfo
in ORDBDatabase class
157
in ORDBTable class 183
in SupraDatabase class
109
in SupraTable class 141
loadSql: 30, 50, 191
loadSql:onError: 50
logoff
in ORDBLogonController
class 173
in SupraLogonController
class 125
maxLength: 84
message
(primitive) in
ORDBDatabase class 157
(primitive) in
ORDBDatabaseCursor
class 165
(primitive) in
ORDBScrollableCursor
class 176
(primitive) in
SupraDatabase class 109
(primitive) in
SupraDatabaseCursor
class 117
(primitive) in
SupraScrollableCursor
class 129
general description 62
modifyField:type:extType:fo
rmat: 141
290
instance methods (cont.)
name (primitive)
in ORDBDatabaseCursor
class 165
in ORDBScrollableCursor
class 176
in SupraDatabaseCursor
class 117
in SupraScrollableCursor
class 129
next 54
nextStamp (primitive) 109
ok
in ORDBLogonController
class 173
in SupraLogonController
class 125
openInitialization 125
openScrollableCursorSQL:for
UpdateOf: 54
position 54
previous 54
primaryKey 74
print
in ORDBTable class 183
in SupraTable class 141
printExternalTypeFor:
in ORDBTable class 183
in SupraTable class 142
privateClose (primitive)
in ORDBDatabaseCursor
class 165
in ORDBScrollableCursor
class 176
in SupraDatabaseCursor
class 117
in SupraScrollableCursor
class 129
privateDelete (primitive)
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
privateDeleteUpdate:
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
Database User's Guide, P40-3203-03
Index
privateExecNoSelect:
(primitive)
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
in SupraDatabaseCursor
class 117
in SupraScrollableCursor
class 129
privateExecSql:
in ORDBDatabase class
157
in SupraDatabase class
109
privateExecSql:onError:
(primitive)
in ORDBDatabase class
158
in SupraDatabase class
110
privateExecUpdate:
(primitive)
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
privateExternalTypeFor:
in ORDBTable class 183
in SupraTable class 142
privateGetColumnLineField:
in ORDBTable class 184
in SupraTable class 142
privateGetWidthPrecFixedFo
r:
in ORDBTable class 184
in SupraTable class 143
privateLoad (primitive)
in ORDBTable class 184
in SupraTable class 143
privateLoadSql:
in ORDBTable 158
in SupraDatabase class
110
291
instance methods (cont.)
privateLoadSql:onError:
(primitive)
in ORDBDatabase class
158
in SupraDatabase class
111
privateNext (primitive)
in ORDBDatabaseCursor
class 167
in ORDBScrollableCursor
class 178
in SupraDatabaseCursor
class 118
in SupraScrollableCursor
class 130
privateOpenCursorSql:
(primitive)
in ORDBDatabase class
159
in SupraDatabase class
111
privateOpenDatabase:colum
n:key:write: (primitive)
134
instance methods
privateOpenScrollableCursor
Sql: (primitive)
in ORDBDatabase class
159
in SupraDatabase class
111
privateSelectCountSql:
(primitive)
in ORDBDatabase class
159
in SupraDatabase class
112
privateSetPositionTo:
(primitive)
in ORDBScrollableCursor
class 178
in SupraScrollableCursor
class 130
privateStart (primitive)
in ORDBDatabase class
160
in SupraDatabase class
112
Database User's Guide, P40-3203-03
Index
privateStop (primitive)
in ORDBDatabase class
160
in SupraDatabase class
112
privateTableCursorNotOpen
185
readPos:length: (primitive)
134
refresh
(primitive) in
ORDBScrollableCursor
class 178
(primitive) in
SupraScrollableCursor
class 130
general description 39
remove:using:
in ORDBTable class 185
in SupraTable class 144
removeDependencyFor: 112
rollback
(primitive) in
ORDBDatabase class 160
general description 48
saveAs: 210
searchStartPos:endPos:string
:modePattern:
(primitive) 135
serverType 199
setPositionTo: 54
size: 54
sourceDirectory
in ORDBDatabase class
160
in SupraDatabase class
113
startAccessForUpdate: 30
startAccessForUpdate:scrolla
ble: 39
storedProcedure: 96
storedProcedureNames 96
292
instance methods (cont.)
timeAsDBStringValue:
in ORDBDatabase class
161
in SupraDatabase class
113
truncateLength: (primitive)
135
tsAsDBStringValue: 161
uniqueKeys 74
update:using:
in ORDBTable class 185
in SupraTable class 144
update:with:with:with: 60
updateWith:
in ORDBDatabaseCursor
class 167
in ORDBScrollableCursor
class 178
in SupraDatabaseCursor
class 118
in SupraScrollableCursor
class 130
writePos:data: (primitive)
135
instance variables
Cancel
in ORDBLogonController
class 169
in SupraLogonController
class 121
dataArea
in SupraDatabaseCursor
class 115
in SupraScrollableCursor
class 127
databaseIV 132
dbName 141
dbrecords 49, 50
descriptorIV 132
fieldValues 166, 177
lockmode 121
Logoff
in ORDBLogonController
class 169
in SupraLogonController
class 121
Database User's Guide, P40-3203-03
Index
OK
in ORDBLogonController
class 169
in SupraLogonController
class 121
parseFlag 127
parseId
in SupraDatabaseCursor
class 115
in SupraScrollableCursor
class 127
password
in ORDBLogonController
class 169
in SupraLogonController
class 121
position 130, 178
queryResult
in ORDBDatabaseCursor
class 163
in ORDBScrollableCursor
class 174
record 54, 55
sessionNumber
in SupraDatabase class
101
in SupraDatabaseCursor
class 115
in SupraScrollableCursor
class 127
sqlString 130, 178
timeout 121
userName
in ORDBLogonController
class 169
in SupraLogonController
class 121
Internal Database
saving 210
specifications 21
InternalDatabase class 27
INTO clause 229
isORDB instance method 156
isSupra instance method 108
293
J
JOIN clause, defining 236
Join dialog box 236
joining table operators 237
L
lastError instance method 85
length instance method
(primitive) 134
level breaks, using 252–55
line graphs, generating 268
line items, formatting in
reports 264
linking
fields to report items 257
programmatically 59
to cursors 59
to tables 59
load instance method
(primitive)
in ORDBDatabase class 156
in SupraDatabase class 108
loadInfo instance method
in ORDBDatabase class 157
in ORDBTable class 183
in SupraDatabase class 109
in SupraTable class 141
loading
database applications 40
DLL support 64
SQL statements from text
files 243
loadSql: instance method 30,
50, 191
loadSql:onError: instance
method 50
local
databases, executing SQL
with 52
host name, automatically
setting for SQL Server
199
LocalCursor class 35
LocalDatabase class 24, 27
Database User's Guide, P40-3203-03
Index
lock mode
instance variable for
selected lock mode value
121
setting 103
setting to default of one 125
lock_timeout_in_secs
parameter and UniSQL
Server database 146
lockmode instance variable
121
login
controllers, including in
application image 63
default 65
delaying 65
loginUser:password: class
method (primitive) 150
loginUser:password:lock:timeo
ut: class method 103
logoff instance method
in ORDBLogonController
class 173
in SupraLogonController
class 125
Logoff instance variable
in ORDBLogonController
class 169
in SupraLogonController 121
logonView class method
general description 42
in ORDBDatabase class 151
in SupraDatabase class 103
packaging applications and
63
294
M
manually binding the DB2 files
87
maxCursors class method
(primitive)
in ORDBDatabaseCursor class
164
in ORDBScrollableCursor
class 175
in SupraDatabaseCursor class
116
in SupraScrollableCursor
class 128
maxDatabaseNameLength
class method
in ORDBDatabase class 151
in SupraDatabase class 103
maxLength: instance method
84
maxNameLength class method
in ORDBTable class 181
in SupraTable class 139
message blocks
in SQL Server databases 197
SYBASE 200
message instance method
(primitive) in ORDBDatabase
class 157
(primitive) in
ORDBDatabaseCursor
class 165
(primitive) in
ORDBScrollableCursor
class 176
(primitive) in SupraDatabase
class 109
(primitive) in
SupraDatabaseCursor
class 117
(primitive) in
SupraScrollableCursor
class 129
general description 62
Database User's Guide, P40-3203-03
Index
methods
accessing databases 45
accessName: class method
45, 95
add: instance method 58
addField:type:extType:form
at: instance method
in ORDBTable class 182
in SupraTable class 140
allowedModifications class
method
in ORDBTable class 180
in SupraTable class 138
asDBStringFor: instance
method 51
asFloat instance method 77
asInteger instance method
77
asInternalTable instance
method 54
asString instance method 77
at:put: instance method
in ORDBDatabase class
165
in ORDBScrollableCursor
class 176
beginTran instance method
48
blobSupport: instance
method 82
byteArrayAsDBStringValue:
instance method
in ORDBDatabase class
155
in SupraDatabase class
107
changed: instance method
60, 61
check instance method
(primitive) 107
checkAccessName: class
method
in ORDBDatabase class
149
in SupraDatabase class
101
295
methods (cont.)
close instance method
(primitive) in class
SupraStringColumn 133
general description 54
commit instance method
(primitive) in
ORDBDatabase class 155
general description 48
copy instance method 54
copyTo:sourcePos:destPos:le
ngth: (primitive)
instance method
(primitive) 133
createItems instance
method
in ORDBLogonController
class 171
in SupraLogonController
class 123
createTableFrom instance
method
in ORDBTable class 182
in SupraTable class 140
database instance method
in ORDBLogonController
class 171
in SupraLogonController
class 123
databaseType instance
method
in ORDBDatabase class
155
in SupraDatabase class
107
dateAsDBStringValue:
instance method
in ORDBDatabase class
156
in SupraDatabase class
108
dbTables instance method
58
dbTablesAt: instance
method 28, 58
Database User's Guide, P40-3203-03
Index
dbTypeForClass: class
method
in ORDBDatabase class
149
in SupraDatabase class
101
dbTypeForClass:is: class
method
in ORDBDatabase class
149
in SupraDatabase class
101
defaultDBType class method
in ORDBDatabase class
149
in SupraDatabase class
102
defaultMethod instance
method
in ORDBLogonController
class 171
in SupraLogonController
class 123
deleteField: instance
method
in ORDBTable class 182
in SupraTable class 140
description class method
in ORDBDatabase class
150
in ORDBDatabaseCursor
class 164
in ORDBLogonController
class 170
in ORDBScrollableCursor
class 175
in ORDBTable class 180
in SupraDatabase class
102
in SupraDatabaseCursor
class 116
in SupraLogonController
class 122
in SupraScrollableCursor
class 128
in SupraStringColumn
class 132
in SupraTable class 138
296
methods (cont.)
desktopWpObjIconSource
instance method
in ORDBLogonController
class 172
in SupraLogonController
class 124
desktopWpObjName instance
method
in ORDBLogonController
class 172
in SupraLogonController
class 124
directory class method 45,
148
driverName instance method
in ORDBDatabase class
156
in SupraDatabase class
108
dropOnDesktop instance
method
in ORDBLogonController
class 172
in SupraLogonController
class 124
ESDatabase class method 91
execFunc:onError: instance
method 190, 191
execFunc:returnType:param
Types: instance method
190, 191
execFunc:returnType:param
Types:onError: instance
method 190, 191
execProc:onError: instance
method 188, 189
execProc:paramTypes:
instance method 188,
189
execProc:paramTypes:onErr
or: instance method 188,
189
execSql: instance method
49, 191
execSql:onError: instance
method 50
execute instance method 38
Database User's Guide, P40-3203-03
Index
expandLength:with: instance
method (primitive) 133
externalTypeSupport class
method
in ORDBTable class 180
in SupraTable class 138
foreignKeys instance method
74
freeModule instance method
64
getNamed: class method 210
getServers class method 26,
43
hasLogonView class method
general description 42
in ORDBDatabase class
150
in SupraDatabase class
102
indexKeys instance method
74
initialize class method
general description 42
in ORDBDatabase class
150
in ORDBDatabaseCursor
class 164
in ORDBLogonController
class 170
in ORDBScrollableCursor
class 175
in ORDBTable class 181
in SupraDatabase class
102
in SupraDatabaseCursor
class 116
in SupraLogonController
class 122
in SupraScrollableCursor
class 128
in SupraTable class 139
initializeBindings instance
method
in ORDBLogonController
class 172
in SupraLogonController
class 124
initModule class method 64
isORDB instance method 156
297
methods (cont.)
isSupra instance method 108
lastError instance method 85
length instance method
(primitive) 134
load instance method
(primitive)
in ORDBDatabase class
156
in SupraDatabase class
108
loadInfo instance method
in ORDBDatabase class
157
in ORDBTable class 183
in SupraDatabase class
109
in SupraTable class 141
loadSql: instance method 50,
191
loadSql:onError: instance
method 50
loginUser:password: class
method (primitive) 150
loginUser:password:lock:tim
eout: class method 103
logoff instance method
in ORDBLogonController
class 173
in SupraLogonController
class 125
logonView class method
general description 42
in ORDBDatabase class
151
in SupraDatabase class
103
packaging applications
and 63
maxCursors class method
(primitive)
in ORDBDatabaseCursor
class 164
in ORDBScrollableCursor
class 175
in SupraDatabaseCursor
class 116
in SupraScrollableCursor
class 128
Database User's Guide, P40-3203-03
Index
maxDatabaseNameLength
class method
in ORDBDatabase class
151
in SupraDatabase class
103
maxLength: instance method
84
maxNameLength class
method
in ORDBTable class 181
in SupraTable class 139
message instance method
(primitive) in
ORDBDatabase class 157
(primitive) in
ORDBDatabaseCursor
class 165
(primitive) in
ORDBScrollableCursor
class 176
(primitive) in
SupraDatabase class 109
(primitive) in
SupraDatabaseCursor
class 117
(primitive) in
SupraScrollableCursor
class 129
general description 62
modifyField:type:extType:fo
rmat: instance method
141
name instance method
(primitive)
in ORDBDatabaseCursor
class 165
in ORDBScrollableCursor
class 176
in SupraDatabaseCursor
class 117
in SupraScrollableCursor
class 129
nativeScrollableCursors 34
new:column:key:write: class
method 132
next instance method 54
298
methods (cont.)
nextCursor class method
in ORDBDatabaseCursor
class 164
in ORDBScrollableCursor
class 175
in SupraDatabaseCursor
class 116
in SupraScrollableCursor
class 128
nextStamp instance method
(primitive) 109
ok instance method
in ORDBLogonController
class 173
in SupraLogonController
class 125
openCursorSQL:forUpdateOf:
instance method 54
openInitialization instance
method 125
openScrollableCursorSQL:for
UpdateOf: instance
method 54
parseString: class method
37, 38
position instance method 54
previous instance method 54
primaryKey instance method
74
print instance method
in ORDBTable class 183
in SupraTable class 141
printExternalTypeFor:
instance method
in ORDBTable class 183
in SupraTable class 142
privateClose instance
method (primitive)
in ORDBDatabaseCursor
class 165
in ORDBScrollableCursor
class 176
in SupraDatabaseCursor
class 117
in SupraScrollableCursor
class 129
Database User's Guide, P40-3203-03
Index
privateDBCreateHideOptions
class method
in ORDBDatabase class
151
in SupraDatabase class
104
privateDelete instance
method (primitive)
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
privateDeleteUpdate:
instance method
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
privateDirectory class
method (primitive)
in INFDatabase class 95
in ORDBDatabase class
152
in SupraDatabase class
104
privateExecNoSelect:
instance method
(primitive)
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
in SupraDatabaseCursor
class 117
in SupraScrollableCursor
class 129
privateExecSql: instance
method
in ORDBDatabase class
157
in SupraDatabase class
109
privateExecSql:onError:
instance method
(primitive)
in ORDBDatabase class
158
in SupraDatabase class
110
299
methods (cont.)
privateExecUpdate: instance
method (primitive)
in ORDBDatabaseCursor
class 166
in ORDBScrollableCursor
class 177
privateExternalTypeFor:
instance method
in ORDBTable class 183
in SupraTable class 142
privateGetColumnLineField:
instance method
in ORDBTable class 184
in SupraTable class 142
privateGetWidthPrecFixedFo
r: instance method
in ORDBTable class 184
in SupraTable class 143
privateLoad instance method
(primitive)
in ORDBTable class 184
in SupraTable class 143
privateLoadSql: instance
method
in ORDBTable 158
in SupraDatabase class
110
privateLoadSql:onError:
instance method
(primitive)
in ORDBDatabase class
158
in SupraDatabase class
111
privateNext instance method
(primitive)
in ORDBDatabaseCursor
class 167
in ORDBScrollableCursor
class 178
in SupraDatabaseCursor
class 118
in SupraScrollableCursor
class 130
Database User's Guide, P40-3203-03
Index
privateOpenCursorSql:
instance method
(primitive)
in ORDBDatabase class
159
in SupraDatabase class
111
privateOpenDatabase:colum
n:key:write: instance
method (primitive) 134
privateOpenScrollableCursor
Sql: instance method
(primitive)
in ORDBDatabase class
159
in SupraDatabase class
111
privateSelectCountSql:
instance method
(primitive)
in ORDBDatabase class
159
in SupraDatabase class
112
privateSetPositionTo:
instance method
(primitive)
in ORDBScrollableCursor
class 178
in SupraScrollableCursor
class 130
privateStart instance
method (primitive)
in ORDBDatabase class
160
in SupraDatabase class
112
privateStop instance method
(primitive)
in ORDBDatabase class
160
in SupraDatabase class
112
privateTableCursorNotOpen
instance method 185
300
methods (cont.)
readPos:length: instance
method (primitive) 134
refresh instance method
(primitive) in
ORDBScrollableCursor
class 178
(primitive) in
SupraScrollableCursor
class 130
general description 39
remove:using: instance
method
in ORDBTable class 185
in SupraTable class 144
removeDependencyFor:
instance method 112
rollback instance method
(primitive) in
ORDBDatabase class 160
general description 48
saveAs: instance method 210
searchStartPos:endPos:string
:modePattern: instance
method (primitive) 135
serverType instance method
199
setDataLoadLimitTo: class
method 24, 50
setPositionTo: instance
method 54
size instance method: 54
sourceDirectory instance
method
in ORDBDatabase class
160
in SupraDatabase class
113
startAccessForUpdate:
instance method 30
startAccessForUpdate:scrolla
ble: instance method 39
storedProcedure: instance
method 96
storedProcedureNames
instance method 96
Database User's Guide, P40-3203-03
Index
supportedFeatures class
method
in ORDBDatabase class
152
in SupraDatabase class
104
supportsSize class method
in ORDBDatabase class
152
in SupraDatabase class
104
tableClass class method
in ORDBDatabase class
153
in SupraDatabase class
105
timeAsDBStringValue:
instance method
in ORDBDatabase class
161
in SupraDatabase class
113
truncateLength: instance
method (primitive) 135
tsAsDBStringValue: instance
method 161
type:precision:scale:nullable
class method 77
uniqueKeys instance method
74
update:using: instance
method
in ORDBTable class 185
in SupraTable class 144
update:with:with:with:
instance method 60
updateWith: instance
method
in ORDBDatabaseCursor
class 167
in ORDBScrollableCursor
class 178
in SupraDatabaseCursor
class 118
in SupraScrollableCursor
class 130
userName class method
(primitive) 105, 153
301
methods (cont.)
validPrecisionTypes class
method
in ORDBDatabase class
153
in SupraDatabase class
105
validSizedTypes class
method
in ORDBDatabase class
153
in SupraDatabase class
105
validTypes class method
in ORDBDatabase class
154
in SupraDatabase class
106
version class method
(primitive)
in ORDBDatabase class
154
in SupraDatabase class
106
visibleTablesAt:put: class
method 46, 62
writePos:data: instance
method (primitive) 135
MicroDecisionware access in
SQL Server databases 199
Microsoft
ODBC. See ODBC
SQL Server databases. See
SQL Server databases
Model View Controller
interface. See MVC
interface
modifyField:type:extType:for
mat: instance method 141
ModuleDictionary global
variable 64
multi-line string items,
formatting 262
multiple database sessions,
considerations for SUPRA
SQL 98
MVC interface 14, 59
Database User's Guide, P40-3203-03
Index
N
name instance method
(primitive)
in ORDBDatabaseCursor class
165
in ORDBScrollableCursor
class 176
in SupraDatabaseCursor class
117
in SupraScrollableCursor
class 129
nativeScrollableCursors
method 34
negating conditions 235
new: class method 37
new:column:key:write: class
method 132
next instance method 54
nextCursor class method
in ORDBDatabaseCursor class
164
in ORDBScrollableCursor
class 175
in SupraDatabaseCursor class
116
in SupraScrollableCursor
class 128
nextStamp instance method
(primitive) 109
nonscrollable cursors 33, 55,
114, 162
normal cursors. See
nonscrollable cursors
NOT conjunction 235
O
object framework 13
objects
adding to dependency lists
60
Cursor 14
Query 14
removing from dependency
lists 61
Table 14
update link, adding 61
302
ODBC databases
classes
ODBCConnection 70
ODBCCursor 33
ODBCDatabase 24, 68
ODBCScrollableCursor 34
ODBCStatement 70
ODBCTable 30
SQGSqlConnection 70
SQGSqlStatement 70
data type mapping 73
handling errors with lowlevel ODBC support 85
illustration of a typical
session 71
ODBC conformance levels 67
ODBC elements 66
specifications 17
system catalog access 74
using cursors 55
working with BLOBs 82
ODBCConnection class 70
ODBCCursor class 33
ODBCDatabase class 24, 68
ODBCScrollableCursor class 34
ODBCStatement class 70
ODBCTable class 30
ok instance method
in ORDBLogonController
class 173
in SupraLogonController
class 125
OK instance variable
in ORDBLogonController
class 169
in SupraLogonController
class 121
openCursorSQL:forUpdateOf:
instance method 54
openInitialization instance
method 125
openScrollableCursorSQL:forU
pdateOf: instance method
54
operators
in WHERE condition 235
joining 237
OR conjunction 234
Database User's Guide, P40-3203-03
Index
Oracle databases
ANSI and Oracle mode
loadable applications 187
classes
OracleDatabase 25
OracleDatabaseCursor 33
OracleScrollableCursor 35
OracleTable 30
executing
PL/SQL functions 190
PL/SQL procedures 188
Oracle OCI
accessing database
wrapper through old
and new interfaces 193
defining columns 195
introduction 192
marking statements as
available 195
note on database wrapper
18
working with Cursors and
ScrollableCursors 195
specifications 18
Oracle Mode loadable
applications for Oracle
187
OracleDatabase class 25
OracleDatabaseCursor class 33
OracleScrollableCursor class
35
OracleTable class 30
ORDBDatabase class 27, 148
ORDBDatabaseCursor class 33,
162
ORDBLogonController class 168
ORDBScrollableCursor class 35,
174
ORDBTable class 30, 179
output options in reports 277
303
P
packaging applications 63
pages
body 250
footers 250
headers 250, 257
horizontal vs. vertical 273
moving between 273
titles, adding 257
totals, adding 257
parameters
adding to statements 240
question marks and 76
parametric SQL statements
240
parametric SQL statements in
ODBC databases 76
parseFlag instance variable
127
parseId instance variable
in SupraDatabaseCursor class
115
in SupraScrollableCursor
class 127
parseString: class method 37,
38
password instance variable
in ORDBLogonController
class 169
in SupraLogonController
class 121
performance, enhancing 62
pie charts
generating 268
PL/SQL
functions 190
procedures 188
position instance method 54
position instance variable 130,
178
previewing
records 214
reports 274
previous instance method 54
primaryKey instance method
74
Database User's Guide, P40-3203-03
Index
print instance method
in ORDBTable class 183
in SupraTable class 141
printExternalTypeFor:
instance method
in ORDBTable class 183
in SupraTable class 142
printing
records 214
reports, output options 277
privateClose instance method
(primitive)
in ORDBDatabaseCursor class
165
in ORDBScrollableCursor
class 176
in SupraDatabaseCursor class
117
in SupraScrollableCursor
class 129
privateDBCreateHideOptions
class method
in ORDBDatabase class 151
in SupraDatabase class 104
privateDelete instance method
(primitive)
in ORDBDatabaseCursor class
166
in ORDBScrollableCursor
class 177
privateDeleteUpdate: instance
method
in ORDBDatabaseCursor class
166
in ORDBScrollableCursor
class 177
privateDirectory class method
(primitive)
in INFDatabase class 95
in ORDBDatabase class 152
in SupraDatabase class 104
304
privateExecNoSelect: instance
method (primitive)
in ORDBDatabaseCursor class
166
in ORDBScrollableCursor
class 177
in SupraDatabaseCursor class
117
in SupraScrollableCursor
class 129
privateExecSql: instance
method
in ORDBDatabase class 157
in SupraDatabase class 109
privateExecSql:onError:
instance method
(primitive)
in ORDBDatabase class 158
in SupraDatabase class 110
privateExecUpdate: instance
method (primitive)
in ORDBDatabaseCursor class
166
in ORDBScrollableCursor
class 177
privateExternalTypeFor:
instance method
in ORDBTable class 183
in SupraTable class 142
privateGetColumnLineField:
instance method
in ORDBTable class 184
in SupraTable class 142
privateGetWidthPrecFixedFor:
instance method
in ORDBTable class 184
in SupraTable class 143
privateLoad instance method
(primitive)
in ORDBTable class 184
in SupraTable class 143
privateLoadSql: instance
method
in ORDBTable 158
in SupraDatabase class 110
Database User's Guide, P40-3203-03
Index
privateLoadSql:onError:
instance method
(primitive)
in ORDBDatabase class 158
in SupraDatabase class 111
privateNext instance method
(primitive)
in ORDBDatabaseCursor class
167
in ORDBScrollableCursor
class 178
in SupraDatabaseCursor class
118
in SupraScrollableCursor
class 130
privateOpenCursorSql:
instance method
(primitive)
in ORDBDatabase class 159
in SupraDatabase class 111
privateOpenDatabase:column:
key:write: instance
method (primitive) 134
privateOpenScrollableCursorSq
l: instance method
(primitive)
in ORDBDatabase class 159
in SupraDatabase class 111
privateSelectCountSql:
instance method
(primitive)
in ORDBDatabase class 159
in SupraDatabase class 112
privateSetPositionTo: instance
method (primitive)
in ORDBScrollableCursor
class 178
in SupraScrollableCursor
class 130
privateStart instance method
(primitive)
in ORDBDatabase class 160
in SupraDatabase class 112
privateStop instance method
(primitive)
in ORDBDatabase class 160
in SupraDatabase class 112
privateTableCursorNotOpen
instance method 185
305
Q
queries
creating from Database
Notebook 217
display 233
parametric 240
Query
class 13, 36, 37
objects 14
querying databases using SQL
49
queryResult instance variable
in ORDBDatabaseCursor class
163
in ORDBScrollableCursor
class 174
question mark, and
parameters 76
R
readPos:length: instance
method (primitive) 134
record instance variable 54,
55
records 211–16, 231
refresh instance method
(primitive) in
ORDBScrollableCursor
class 178
(primitive) in
SupraScrollableCursor
class 130
general description 39
registering graphics files 267
remove:using: instance
method
in ORDBTable class 185
in SupraTable class 144
removeDependencyFor:
instance method 112
Database User's Guide, P40-3203-03
Index
report
creating 247
creating from SQL Editor 243
defining graphics fields in
269
header 250
items
formatting 260–62
working with 256–59
level breaks 252–55
output options 277
pages 272–73
previewing 274
printing 274
sample report using level
breaks 252
saving 249
sections and graphs 268
sections, working with 250
timer 275
Report Editor
formatting
graphic items 263
graphics fields 269
graphics legends 271
lines 264
report items 260–62
topic boxes 264
graphs and graph legends
268
Report Timer dialog box 276
sample report using level
breaks 252
using 246
Report Editor considerations
for UniSQL Server 146
Report Preview 274
result sets
creating reports from 243
cursor objects 14
displaying 233
rollback instance method
(primitive) in ORDBDatabase
class 160
general description 48
ROLLBACK WORK RELEASE
statement, consideration
for SUPRA SQL 98
rows, replacing data in 224
306
S
SAGSqlConnection class 67, 70
SAGSqlStatement class 67, 70
saveAs: instance method 210
saving
Internal Database 210
reports 249
SQL statements 222, 243
scatter graphs, generating 268
scrollable cursors 34–35, 55
scrollable cursors in ODBC
databases 80
Search Condition dialog box
234
search condition. See WHERE
clause
searchStartPos:endPos:string:
modePattern: instance
method (primitive) 135
SELECT statement
creating 225
creating reports from 243
displaying results 233
Selection dialog box 224
serverType instance method
199
session number of SUPRA SQL
101
sessionNumber instance
variable
in SupraDatabase class 101
in SupraDatabaseCursor class
115
in SupraScrollableCursor
class 127
SET clause 229
setDataLoadLimitTo: class
method 24, 50
setPositionTo: instance
method 54
size instance method 54
snap to grid 251
sourceDirectory instance
method
in ORDBDatabase class 160
in SupraDatabase class 113
Database User's Guide, P40-3203-03
Index
SQL
clause
FROM 224
GROUP BY 238
HAVING 238
INTO 229
SET 229
WHERE
adding condition 235
conjunctions (AND, OR)
234
grouping 235
parameters 240
creating strings containing
SQL code 51
cursors, using, vs. using SQL
52
DELETE query 38
execution methods 49
INSERT query 38
local database, executing
SQL with 52
querying databases 49
SELECT query 38
statement
creating in SQL Window
245
importing 243
saving 222
SUBSELECT query 38, 52
UPDATE query 38
SQL Browser 218
307
SQL Editor
Actions menu 223
creating
query 217
reports from 243
database names, showing
223
exporting statements to text
files 243
File menu 222
functions 220
Grouping dialog box 238
Having dialog box 238
Help menu 223
importing statements from
text files 243
Join dialog box 236
opening 221
opening Data Manager from
232
Options menu 223
parametric statements 241
Search Condition dialog box
234
Selection dialog box 224
Statement menu 222
status line, showing or
hiding 223
text files
exporting statements to
243
importing statements
from 243
Transactions menu 223
word wrap 223
SQL Queries dialog box 219
SQL Result Display 233
Database User's Guide, P40-3203-03
Index
SQL Server databases
automatically setting local
host name 199
classes
SQLServerDatabase 26
SQLServerDatabaseCursor
33
SQLServerScrollableCursor
35
SQLServerTable 30
logging on using Windows
Authentication 196
looking for 196
message and error blocks
197
MicroDecisionware access
199
specifications 20
updateable cursors support
55
SQL Window
Actions menu 244
creating queries 217
File menu 244
SQL_BIGINT data type 77
SQL_BIT data type 77
SQL_CHAR data type 77
SQL_DATE data type 77
SQL_DOUBLE data type 77
SQL_FLOAT data type 77
SQL_INTEGER data type 77
SQL_REAL data type 77
SQL_SMALLINT data type 77
SQL_TIME data type 77
SQL_TIMESTAMP data type 77
SQL_VARCHAR data type 77
SqlDelete class 38
SqlDirect class 37
308
SqlInsert class 38
SqlParse class 37
SqlSelect class 38, 39
SQLServerDatabase class 26
SQLServerDatabaseCursor class
33
SQLServerScrollableCursor
class 35
SQLServerTable class 30
sqlString instance variable
130, 178
SqlSubSelect class 38, 39
SqlUpdate class 38, 39
startAccessForUpdate:
instance method 30
startAccessForUpdate:scrollabl
e: instance method 39
StartStopAnnouncementList
global variable 24, 65
statements
adding parameters 240
DELETE 231
DIRECT 232
executing 233
exporting 243
importing 243
INSERT 229
joining tables 236
parametric 240
SELECT 225
SQL 245
UPDATE 229
WHERE clause 234
status line in SQL Editor,
showing or hiding 223
storedProcedure: instance
method 96
storedProcedureNames
instance method 96
string
columns 98, 133–35
containing SQL code,
creating 51
items, multi-line, formatting
262
size limit in ObjectStudio
179
subqueries and level breaks
253
Database User's Guide, P40-3203-03
Index
SUBSELECT statements 38, 52
supportedFeatures class
method
in ORDBDatabase class 152
in SupraDatabase class 104
supportsSize class method
in ORDBDatabase class 152
in SupraDatabase class 104
SUPRA SQL databases
ASCII/EBCDIC/BYTE
designations and SUPRA
SQL character columns
98
avoiding COMMIT WORK
RELEASE and ROLLBACK
WORK RELEASE 98
classes
introduction 99
SupraDatabase 26, 100
SupraDatabaseCursor 33,
114
SupraLogonController 119
SupraScrollableCursor 35,
126
SupraStringColumn 131
SupraTable 30, 136
FLOAT precision 98
specifications 21
using multiple database
sessions 98
working with string columns
98
SupraDatabase class 26, 100
SupraDatabaseCursor class 33,
114
SupraLogonController class
119
SupraScrollableCursor class
35, 126
SupraStringColumn class 131
SupraTable class 30, 136
309
SYBASE OpenClient databases
classes
SybaseDatabase 26
SybaseDatabaseCursor 33
SybaseScrollableCursor 35
SybaseTable 30
message and error blocks
200
specifications 20
SybaseDatabase class 26
SybaseDatabaseCursor class 33
SybaseScrollableCursor class
35
SybaseTable class 30
T
Table
class 13, 28, 29
objects 14
pop-up menu 207
tableClass class method
in ORDBDatabase class 153
in SupraDatabase class 105
tables
general
aliasing 52
creating 206
joining 236
linking to 59
methods 58
specifying in FROM clause
224
working with 58
SUPRA
creating 140
deleting field from 140
loading information about
in form of internal table
141
maximum length allowed
for name 139
modifying field 141
removing record from 144
updating record in 144
Database User's Guide, P40-3203-03
Index
timeAsDBStringValue: instance
method
in ORDBDatabase class 161
in SupraDatabase class 113
timeout instance variable 121
timer, setting for reports 275
topic boxes, formatting items
in reports 264
transaction processing,
Informix 95
transactions 48, 242
truncateLength: instance
method (primitive) 135
tsAsDBStringValue: instance
method 161
type:precision:scale:nullable
class method 77
typesSupported class variable
in ORDBTable class 179, 180
in SupraTable class 137, 138,
139
U
uncataloging DB2 databases 92
uniqueKeys instance method
74
UniSQL Server databases
classes
introduction 147
ORDBDatabase 27, 148
ORDBDatabaseCursor 33,
162
ORDBLogonController 168
ORDBScrollableCursor 35,
174
ORDBTable 30, 179
Report Editor considerations
146
specifications 21
using the
lock_timeout_in_secs
parameter 146
update link, creating 61
UPDATE statement
creating 229
displaying results 233
values 224
310
update:using: instance
method
in ORDBTable class 185
in SupraTable class 144
update:with:with:with:
instance method 60
updateable cursors 55
updateWith: instance method
in ORDBDatabaseCursor class
167
in ORDBScrollableCursor
class 178
in SupraDatabaseCursor class
118
in SupraScrollableCursor
class 130
userName class method
(primitive) 105, 153
userName instance variable
in ORDBLogonController
class 169
in SupraLogonController
class 121
V
validPrecisionTypes class
method
in ORDBDatabase class 153
in SupraDatabase class 105
validSizedTypes class method
in ORDBDatabase class 153
in SupraDatabase class 105
validTypes class method
in ORDBDatabase class 154
in SupraDatabase class 106
values
for report items 260
in UPDATE statements 224
Database User's Guide, P40-3203-03
Index
variables
Cancel instance variable
121, 169
cursors class variable
in ORDBDatabaseCursor
class 163, 164
in ORDBScrollableCursor
class 174
in SupraDatabaseCursor
class 114
in SupraScrollableCursor
class 126
dataArea instance variable
in SupraDatabaseCursor
class 115
in SupraScrollableCursor
class 127
databaseIV instance variable
132
dataLoadLimit class variable
50
dbName instance variable
141
dbrecords instance variable
49, 50
descriptorIV instance
variable 132
EnfinGetSQLServers
environment variable 196
fieldValues instance variable
166, 177
henv class variable 70
InformixHOST environment
variable 95
InformixSERVER environment
variable 95
lockmode instance variable
121
Logoff instance variable
in ORDBLogonController
class 169
in SupraLogonController
121
ModuleDictionary global
variable 64
311
variables (cont.)
OK instance variable
in ORDBLogonController
class 169
in SupraLogonController
class 121
parseFlag instance variable
127
parseId instance variable
in SupraDatabaseCursor
class 115
in SupraScrollableCursor
class 127
password instance variable
in ORDBLogonController
class 169
in SupraLogonController
class 121
position instance variable
130, 178
queryResult instance
variable
in ORDBDatabaseCursor
class 163
in ORDBScrollableCursor
class 174
record instance variable 54,
55
sessionNumber instance
variable
in SupraDatabase class
101
in SupraDatabaseCursor
class 115
in SupraScrollableCursor
class 127
sqlString instance variable
130, 178
StartStopAnnouncementList
global variable 24, 65
timeout instance variable
121
Database User's Guide, P40-3203-03
Index
typesSupported class
variable
in ORDBTable class 179,
180
in SupraTable class 137,
138, 139
userName instance variable
in ORDBLogonController
class 169
in SupraLogonController
class 121
VectorTable class 30, 50
version class method
(primitive)
in ORDBDatabase class 154
in SupraDatabase class 106
vertical pages 273
visibleTablesAt:put: class
method 46, 62
W
WHERE clause
adding conditions 235
conjunctions (AND, OR) 234
defining 234
grouping 235
negating 235
parameters 240
Windows Authentication, using
it to log on to SQL Server
databases 196
word wrap, setting in SQL
Editor 223
writePos:data: instance
method (primitive) 135
312