database user's guide - cincom smalltalk · objectstudio 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

Outside of USA All: Visit the support links at http://www.cincom.com to find contact information for your nearest Customer Service Center.

http://supportweb.cincom.com/

http://www.cincom.com/

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 5 Contents

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


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


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


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


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


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


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 12 Chapter: Overview of database support Section: How ObjectStudio supports databases

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 13 Chapter: Overview of database support Section: Database object framework

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 14 Chapter: Overview of database support Section: Database object framework

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 15 Chapter: Overview of database support Section: Database tools

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 16 Chapter: How ObjectStudio implements database support Section: Introduction

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 17 Chapter: How ObjectStudio implements database support Section: Supported databases

Oracle database


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)



Cincom no longer supports the databases wrappers loaded by these applications. However, these loadable applications are still available in the Goodies folder.


ADABAS database


Adabas Database

Subclass of Database: AdabasDatabase

Subclass of Table: AdabasTable

Subclass of Cursor: AdabasDatabaseCursor AdabasScrollableCursor

IBM DB2 database


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


Microsoft SQL Server database


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


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


Informix Client Version 7.12 Informix Client Version 7.3

Subclass of Database: INFDatabase

Subclass of Table: INFTable

Subclass of Cursor: INFDatabaseCursor INFScrollableCursor


SUPRA SQL database


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


UniSQL 3.5.3

Subclass of Database: ORDBDatabase

Subclass of Table: ORDBTable

Subclass of Cursor: ORDBDatabaseCursor ORDBScrollableCursor

Internal Database


None (already loaded)

Subclass of Database: InternalDatabase

Subclass of Table: Not applicable

Subclass of Cursor: Not applicable


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 22 Chapter: How ObjectStudio implements database support Section: Database classes

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.


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.


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.


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.


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.


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 28 Chapter: How ObjectStudio implements database support Section: Table classes

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.


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


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 31 Chapter: How ObjectStudio implements database support Section: Cursor classes

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.


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


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


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


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


♦ Move the record pointer to any position in the result set


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 36 Chapter: How ObjectStudio implements database support Section: Query classes

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.


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.


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.


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. Formore information on the Internal Database, see “Internal Database” on page 21and “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 40 Chapter: Working with databases Section: Introduction

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 41 Chapter: Working with databases Section: Loading external database support

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 ObjectStudio-supplied 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 42 Chapter: Working with databases Section: Connecting to a DBMS

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.


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


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 45 Chapter: Working with databases Section: Accessing a database

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'


The following table lists variations on the array parameter:

Variation Use

Array of symbols

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.

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


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 48 Chapter: Working with databases Section: Performing transactions

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 49 Chapter: Working with databases Section: Using SQL to query databases

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


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


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


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 53 Chapter: Working with databases Section: Working with cursors

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.


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.


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.


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


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 58 Chapter: Working with databases Section: Working with tables

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 59 Chapter: Working with databases Section: Linking to cursors and tables

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 Description

objLinkedTo The object that is changed. field The field that is changed or the symbol #All. position The current row position of objLinkedTo. type 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.


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:


position The new position if type is #Position. If type is #Value, the position at which the value is changed (the current position).

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


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 62 Chapter: Working with databases Section: Enhancing performance

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 63 Chapter: Working with databases Section: Packaging applications

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.


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.


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 66 Chapter: ODBC Section: Introduction

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 CLI-compliant 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 67 Chapter: ODBC Section: ODBC conformance levels

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 68 Chapter: ODBC Section: ODBC conformance levels

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 69 Chapter: ODBC Section: Low-level ODBC support

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.

InputParameters

Has lastError

SAGSqlError

SAGSqlStatement

SAGSqlColumnDescription

Has lastError

ResultSetColumns

Has Active StatementsSAGSqlConnection

The ODBCConnection and ODBCStatement classes implement the Microsoft-specific extensions of the SAG CLI. Therefore, they are subclasses of SAGSqlConnection and SAGSqlStatement as shown here:

Has Active Statements

ODBCConnection

SAGSqlStatement

ODBCStatement

SAGSqlConnection

Database User's Guide, P40-3203-03 70 Chapter: ODBC Section: Additional ODBC classes

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 71 Chapter: ODBC Section: Typical session

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 72 Chapter: ODBC Section: Typical session

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 73 Chapter: ODBC Section: Data type mapping

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 74 Chapter: ODBC Section: System catalog access

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 pwd: #xy.

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


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.


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.


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.


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


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:


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


♦ The following example shows how to use a scrollable cursor:


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


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 82 Chapter: ODBC Section: Working with Binary Large Objects (BLOBs)

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.


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 thefirst 32K of data as a String object.


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 85 Chapter: ODBC Section: Handling errors

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 86 Chapter: DB2 Section: Introduction

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 87 Chapter: DB2 Section: Manually binding the DB2 files

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.



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



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


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


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


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


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


GRANT EXECUTE ON PACKAGE OSDB261s TO PUBLIC GRANT EXECUTE ON PACKAGE OSDB261c TO PUBLIC


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.


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:


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 another machine

cmtCodePage The code page used for the comment as a SmallInteger, or nil for default code page on the application machine

Database User's Guide, P40-3203-03 91 Chapter: DB2 Section: Cataloging databases

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 92 Chapter: DB2 Section: Uncataloging databases

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 93 Chapter: DB2 Section: Executing stored procedures

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 94 Chapter: DB2 Section: Executing stored procedures

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 95 Chapter: Informix Section: Introduction

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 96 Chapter: Informix Section: Executing stored procedures

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 97 Chapter: SUPRA SQL Section: Introduction

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 98 Chapter: SUPRA SQL Section: Working with SUPRA SQL string columns

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 99 Chapter: SUPRA SQL Section: SUPRA SQL class reference

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


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.


dbTypeForClass: aClass is: domain

Description: Determines the SUPRA SQL database type for the requested class and domain.

Assumptions: None




defaultDBType

Description: Retrieves the default type specified in DBCONV.INI for SUPRA SQL.

Assumptions: None



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



hasLogonView

Description: Returns true for objects of class SupraDatabase.

Assumptions: None

Return Value: true


initialize

Description: Defines the DLL module object and registers all primitive methods for the SUPRA SQL database.

Assumptions: None




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


logonView

Description: Returns the SUPRA SQL logon window controller.

Assumptions: None

Return Value: An object of class SupraLogonController.


maxDatabaseNameLength

Description: Returns the maximum length, in characters, of a database identifier.

Assumptions: None

Return Value: An object of class SmallInteger.



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.


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.


supportedFeatures

Description: Returns an array of the supported database features for SupraDatabase.

Assumptions: None



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.



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.


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.


validPrecisionTypes

Description: Lists the SUPRA SQL database types that have a precision characteristic.

Assumptions: None



validSizedTypes

Description: Lists the SUPRA SQL database types that have a size characteristic.

Assumptions: None




validTypes

Description: Lists the valid SUPRA SQL database data types.

Assumptions: None



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.



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.


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.


databaseType

Description: Responds with the SUPRA SQL database type.

Assumptions: None




dateAsDBStringValue: value

Description: Returns a string containing the date specified by the value parameter.

Assumptions: value must be an object of class Date.



driverName

Description: Returns the string SUPRA, which identifies the database in use.

Assumptions: None



isSupra

Description: Returns true because the receiver is of class SupraDatabase.

Assumptions: None



load (primitive)

Description: Loads information about all tables in the database.

Assumptions: None




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.


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.


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




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.


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




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.


Return Value: An object of class VectorTable.


privateOpenCursorSql: sqlString (primitive)

Description: Gets the next available cursor and assigns data to its instance variables based on the contents of sqlString.


Return Value: An object of class SupraDatabaseCursor or class Message.


privateOpenScrollableCursorSql: sqlString (primitive)

Description: Gets the next available scrollable cursor and fills it with data based on the contents of sqlString.


Return Value: An object of class SupraScrollableCursor or class Message.



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.


privateStart (primitive)

Description: Starts the database.

Assumptions: None

Return Value: The receiver or an error message of class Message.


privateStop (primitive)

Description: Stops the database and logs the user out.

Assumptions: None

Return Value: The receiver or an error message of class Message.


removeDependencyFor: dependentObject

Description: Removes the dependency for the object specified in the dependentObject parameter.

Assumptions: None




sourceDirectory

Description: Returns the string SUPRA. It is used to specify the name of the source directory in the ObjectStudio tree.

Assumptions: None



timeAsDBStringValue: value

Description: Returns a string containing the time specified by the value parameter.

Assumptions: value must be an object of class Time.




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


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


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.


SupraDatabaseCursor class methods description


Assumptions: None



initialize

Description: Assigns an empty array object to the class variable cursors. This variable is used to store database cursors.

Assumptions: None



maxCursors (primitive)

Description: Returns the maximum number of cursors that can be opened concurrently.

Assumptions: None



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.



SupraDatabaseCursor instance methods message (primitive)


Assumptions: None



name (primitive)

Description: Returns a string object containing the name of the cursor.

Assumptions: None



privateClose (primitive)

Description: Frees allocated resources for the cursor and initializes the cursor position to 0.

Assumptions: None



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.



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.


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




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


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


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.


SupraLogonController class methods description


Assumptions: None



initialize

Description: Executes when the SupraLogonController class is loaded into the system. Initializes the SUPRA SQL Logon dialog box.

Assumptions: None




SupraLogonController instance methods createItems

Description: Defines the forms, controller items, and methods for the SUPRA SQL Logon dialog box.

Assumptions: None



database

Description: Sets the default database to SupraDatabase.

Assumptions: None

Return Value: SupraDatabase, which represents the global variable for the SUPRA SQL database.


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.



desktopWpObjIconSource

Description: Returns a string containing the pathname for the SupraLogonWindowView object icon’s source.

Assumptions: None



desktopWpObjName

Description: Returns the string Supra Logon for the SupraLogonWindowView object name.

Assumptions: None



dropOnDesktop

Description: Returns true indicating that this controller is to be shown on the ObjectStudio desktop.

Assumptions: None



initializeBindings

Description: Creates the bindings between the controller items and the methods associated with those controller items.

Assumptions: None




logoff

Description: Stops access to the currently connected SUPRA SQL.

Assumptions: None

Return Value: An object of class SupraDatabase or class Message.


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.


openInitialization

Description: Sets the lock mode to a default of 1, indicating NORMAL.

Assumptions: None




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



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.


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.


SupraScrollableCursor class methods description


Assumptions: None



initialize

Description: Assigns an empty object of class Array to the class variable cursors. This variable is used to store database cursors.

Assumptions: None





Assumptions: None



nextCursor


Assumptions: None

Return Value: An object of class SupraDatabaseCursor, or nil if no cursor is available.



SupraScrollableCursor instance methods message (primitive)


Assumptions: None



name (primitive)

Description: Returns an object of class String containing the name of the cursor.

Assumptions: None




Description: Frees allocated resources for the cursor and initializes the cursor position to zero.

Assumptions: None











Assumptions: None

Return Value: An object of class Dictionary, or an error code of class Integer.


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.



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




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




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


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


Assumptions: None



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.



SupraStringColumn instance methods close (primitive)

Description: Closes the string column.

Assumptions: None



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.


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.




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.


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



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.



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.


truncateLength: length (primitive)

Description: Truncates the receiver to the length given in length.

Assumptions: length must be an object of class Integer.



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.




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


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


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


SupraTable class methods allowedModifications

Description: Returns a list of allowed modifications to a database table.

Assumptions: None

Return Value: An Array of Symbols.


description


Assumptions: None



externalTypeSupport

Description: Returns the class variable typesSupported. typesSupported is an IdentityDictionary where:



Assumptions: None

Return Value: An object of class IdentityDictionary.



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.


maxNameLength

Description: Returns the maximum number of characters allowed for a SUPRA SQL table name.

Assumptions: None




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.



createTableFrom

Description: Physically creates a table.

Assumptions: None



deleteField: fieldName

Description: Deletes a table field.

Assumptions: fieldName is the symbol for an existing table field.




loadInfo

Description: Loads information about a table in the form of an internal table.

Assumptions: None



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.



print

Description: Returns the string Table plus the dbname instance variable; for example, Table Example.

Assumptions: None




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.



privateExternalTypeFor: aColName

Description: Returns the external data type for aColName as it would appear in the CREATE TABLE statement.




privateGetColumnLineField: aColName

Description: Returns the column name, including the data type, as it would appear in the CREATE TABLE statement.





privateGetWidthPrecFixedFor: aColumnName

Description: 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




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.



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.



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.




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 145 Chapter: UniSQL Server Section: Introduction

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 146 Chapter: UniSQL Server Section: Using the lock_timeout_in_secs_parameter

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 147 Chapter: UniSQL Server Section: UniSQL Server class reference

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


♦ 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


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.


dbTypeForClass: aClass is: domain

Description: Determines the UniSQL Server database type for the requested class and domain.

Assumptions: None



defaultDBType

Description: Retrieves the default type specified in DBCONV.INI for UniSQL Server.

Assumptions: None




description


Assumptions: None

Return value: The receiver.


hasLogonView

Description: Returns true for objects of class ORDBDatabase.

Assumptions: None

Return value: An object of class Boolean.


initialize

Description: Defines the DLL module object and registers all primitive methods for the UniSQL Server database.

Assumptions: None



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



logonView

Description: Returns the UniSQL Server logon window controller.

Assumptions: None

Return value: An object of class ORDBLogonController.


maxDatabaseNameLength

Description: Returns the maximum number of characters allowed in a database identifier.

Assumptions: None

Return value: An object of class SmallInteger.


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.



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.


supportedFeatures

Description: Returns an array of the supported database features for class ORDBDatabase.

Assumptions: None



supportsSize

Description: Returns true because UniSQL Server supports sized database types.

Assumptions: None




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.


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.


validPrecisionTypes

Description: Lists the UniSQL Server database types that have a precision characteristic.

Assumptions: None



validSizedTypes

Description: Lists the UniSQL Server database types that have a size characteristic.

Assumptions: None




validTypes

Description: Lists the valid UniSQL Server database types.

Assumptions: None



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.



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.



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



databaseType

Description: Returns the UniSQL Server database type.

Assumptions: None




dateAsDBStringValue: value

Description: Returns a string containing the date specified by the value parameter.

Assumptions: value must be an object of class Date.



driverName

Description: Returns the string ORDB, which identifies the database cursor.

Assumptions: None



isORDB

Description: Returns true because the receiver is of class ORDBDatabase.

Assumptions: None



load (primitive)

Description: Loads information about all tables in the database.

Assumptions: None




loadInfo

Description: Creates a set of tables that corresponds to the tables in the database. Only basic information is loaded.

Assumptions: None


Receiver modified: Yes

message (primitive)


Assumptions: None

Return value: An object of class Message.


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




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.


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.


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



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.



Return value: An object of class VectorTable.



privateOpenCursorSql: sqlString (primitive)

Description: Gets the next available cursor and assigns data to its instance variables based on the contents of sqlString.


Return value: An object of class ORDBDatabaseCursor or class Message.


privateOpenScrollableCursorSql: sqlString (primitive)

Description: Gets the next available scrollable cursor and fills it with data based on the contents of sqlString.


Return value: An object of class ORDBScrollableCursor or class Message.


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.



privateStart (primitive)

Description: Starts the database.

Assumptions: None



privateStop (primitive)

Description: Stops the database.

Assumptions: None



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



sourceDirectory

Description: Returns the string ORDB. It is used to specify the name of the source directory in the ObjectStudio tree.

Assumptions: None




timeAsDBStringValue: value

Description: Returns a string containing the time specified by the value parameter.

Assumptions: value must be an object of class Time.



tsAsDBStringValue: value

Description: Returns a string containing the timestamp specified by the value parameter.

Assumptions: value must be an object of class Timestamp.




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



ORDBDatabaseCursor


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


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.


ORDBDatabaseCursor class methods description


Assumptions: None



initialize

Description: Assigns an empty array object to the class variable cursors.. This variable is used to store database cursors.

Assumptions: None





Assumptions: None



nextCursor


Assumptions: None

Return value: An object of class ORDBDatabaseCursor, or nil if no cursor is available.



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



message (primitive)


Assumptions: None



name (primitive)


Assumptions: None





Assumptions: None




privateDelete (primitive)

Description: Deletes the record at the current cursor position.

Assumptions: None

Return value: A return code of class Integer.


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.





Return value: The receiver or an error code of class Integer.


privateExecUpdate: sqlString (primitive)


Assumptions: sqlString is an object of class String and should contain an UPDATE statement.






Assumptions: None

Return value: An object of class Dictionary, or an error code of class Integer.



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




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


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.


ORDBLogonController class methods description


Assumptions: None



initialize

Description: Executes when the ORDBLogonController class is loaded into the system. Initializes the UniSQL Server Logon dialog box.

Assumptions: None




ORDBLogonController instance methods createItems

Description: Defines the forms, controller items, and methods for the UniSQL Server Logon dialog box.

Assumptions: None



database

Description: Sets the default database to ORDBDatabase.

Assumptions: None

Return value: ORDBDatabase, which represents the global variable for the UniSQL Server database.


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.



desktopWpObjIconSource

Description: Returns a string containing the pathname for the ORDBLogonWindowView object icon’s source.

Assumptions: None



desktopWpObjName

Description: Returns the string “UniSQL Server” for the ORDBLogonWindowView object name.

Assumptions: None



dropOnDesktop

Description: Returns true indicating that this controller is to be shown on the ObjectStudio desktop.

Assumptions: None



initializeBindings

Description: Creates the bindings between the controller items and the methods associated with those controller items.

Assumptions: None




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.


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.



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



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.


ORDBScrollableCursor class methods description


Assumptions: None



initialize

Description: Assigns an empty array object to the class variable cursors. This variable is used to store database cursors.

Assumptions: None





Assumptions: None



nextCursor


Assumptions: None

Return value: An object of class ORDBDatabaseCursor, or nil if no cursor is available.



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



message (primitive)


Assumptions: None



name (primitive)


Assumptions: None





Assumptions: None




privateDelete (primitive)

Description: Deletes the record at the current cursor position.

Assumptions: None



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.







privateExecUpdate: sqlString (primitive)


Assumptions: sqlString is an object of class String.






Assumptions: None

Return value: An object of class Dictionary, or an error code of class Integer.


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.



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




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




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


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


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.


description


Assumptions: None



externalTypeSupport

Description: Returns the class variable typesSupported. typesSupported is an IdentityDictionary where:



Assumptions: None

Return value: An object of class IdentityDictionary.



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.


maxNameLength

Description: Returns the maximum number of characters allowed for a UniSQL Server class identifier.

Assumptions: None




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.



createTableFrom

Description: Physically creates a table.

Assumptions: None



deleteField: fieldName

Description: Deletes a table field.

Assumptions: fieldName is the symbol for an existing table field.




loadInfo

Description: Loads information about a table in the form of an internal table.

Assumptions: None



print

Description: Returns the string “Table ” plus the dbname instance variable; for example, Table Example.

Assumptions: None



printExternalTypeFor: aColName

Description: Returns a printable representation of the external data type as it would appear in a CREATE TABLE statement.




privateExternalTypeFor: aColName

Description: Returns the external data type needed by the database; for example, in the CREATE TABLE statement.





privateGetColumnLineField: aColName

Description: Returns the column name including the data type needed by the database; for example, in the CREATE TABLE statement.




privateGetWidthPrecFixedFor: aColumnName

Description: 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




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.



privateTableCursorNotOpen

Description: Overrides the ExternalDatabase>>privateTableCursorNotOpen instance method.

Assumptions: None



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.



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.




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 186 Chapter: Other databases Section: Introduction

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 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)


Database User's Guide, P40-3203-03 187 Chapter: Other databases Section: Oracle and Oracle OCI support

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


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


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


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.


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


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.


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


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.


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 196 Chapter: Other databases Section: ADABAS support

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 197 Chapter: Other databases Section: SQL Server support

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.


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.


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 200 Chapter: Other databases Section: SYBASE OpenClient support

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 201 Chapter: Other databases Section: SYBASE OpenClient support

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 202 Chapter: Database Notebook Section: Introduction

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 203 Chapter: Database Notebook Section: Using the Database Notebook

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.


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.


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


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:


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.


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.


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.


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.


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:


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 211 Chapter: Database Notebook Section: Entering data

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.


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.


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:


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 214 Chapter: Database Notebook Section: Managing data

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.


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.


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 217 Chapter: Database Notebook Section: Creating a SQL query

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.


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.


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 220 Chapter: SQL tools Section: Introduction

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 221 Chapter: SQL tools Section: SQL Editor

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


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


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.


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.


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.


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.


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.


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.


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.


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.


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.


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.


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.


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 drop-down 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.


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.


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.


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.


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.


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.


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.


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.


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.


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.


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:


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:


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 244 Chapter: SQL tools Section: SQL Window

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 245 Chapter: SQL tools Section: SQL Window

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 246 Chapter: Report Editor Section: Using the Report Editor

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.


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.


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.


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 250 Chapter: Report Editor Section: Working with report sections

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


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.


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


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.


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.


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 256 Chapter: Report Editor Section: Working with report items

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.


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.


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.


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 260 Chapter: Report Editor Section: Formatting report items

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.


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.


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 263 Chapter: Report Editor Section: Formatting graphic items

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.


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.


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.


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.


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 268 Chapter: Report Editor Section: Defining and formatting graphs and graph legends

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.


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)



♦ Scatter graph format options:

- A color and shape for each graph level (marker)



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


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.


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 272 Chapter: Report Editor Section: Formatting, previewing, and printing a report

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.


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.


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.


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.


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.


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.


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 279 Chapter: Cross-platform development Section: Windows character set conversion

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

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

Database User's Guide, P40-3203-03 280 Index

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


101 defaultDBType



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


getNamed: 210 getServers 26, 43 hasLogonView

general description 42 in ORDBDatabase class


102


class methods (cont.) initialize










initModule 64 loginUser:password:

(primitive) 150 loginUser:password:lock:tim

eout: 103 logonView



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


103

maxNameLength in ORDBTable class 181 in SupraTable class 139

new: 37 new:column:key:write: 132 nextCursor





parseString: 37, 38 privateDBCreateHideOptions



privateDirectory (primitive) in INFDatabase class 95 in ORDBDatabase class


104 setDataLoadLimitTo: 24, 50 supportedFeatures



supportsSize in ORDBDatabase class


104 tableClass



type:precision:scale:nullable 77

userName (primitive) 105, 153


class methods (cont.) validPrecisionTypes



validSizedTypes in ORDBDatabase class


105 validTypes



version (primitive) in ORDBDatabase class


106 visibleTablesAt:put: 46, 62

class variables cursors

in ORDBDatabaseCursor class 163, 164




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

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


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 123 createTableFrom instance


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

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




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

databaseIV instance variable 132

databaseType instance method


dataLoadLimit class variable 50

dateAsDBStringValue: instance method


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


dbTypeForClass:is: class method


defaultDBType class method in ORDBDatabase class 149 in SupraDatabase class 102


defaultMethod instance method



defaults, Data Manager form 215

DELETE statements 231, 233 deleteField: instance method


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 175 in ORDBTable class 180 in SupraDatabase class 102 in SupraDatabaseCursor class

116 in SupraLogonController


class 128 in SupraStringColumn class

132 in SupraTable class 138

descriptorIV instance variable 132

desktopWpObjIconSource instance method



desktopWpObjName instance method



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



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


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:paramTypes: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

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


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


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

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

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


initialize class method general description 42 in ORDBDatabase class 150 in ORDBDatabaseCursor class

164 in ORDBLogonController


class 175 in ORDBTable class 181 in SupraDatabase class 102 in SupraDatabaseCursor class

116 in SupraLogonController



initializeBindings instance method



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:



beginTran 48 blobSupport: 82 byteArrayAsDBStringValue:



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



createTableFrom in ORDBTable class 182 in SupraTable class 140

database in ORDBLogonController


class 123 databaseType



dateAsDBStringValue: in ORDBDatabase class


108 dbTables 58 dbTablesAt: 28, 58 defaultMethod



deleteField: in ORDBTable class 182 in SupraTable class 140


instance methods (cont.) desktopWpObjIconSource



desktopWpObjName in ORDBLogonController


class 124 driverName



dropOnDesktop in ORDBLogonController


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



isORDB 156 isSupra 108 lastError 85 length (primitive) 134

load (primitive) in ORDBDatabase class


108 loadInfo


in ORDBTable class 183 in SupraDatabase class


loadSql: 30, 50, 191 loadSql:onError: 50 logoff



maxLength: 84 message


(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


instance methods (cont.) name (primitive)





next 54 nextStamp (primitive) 109 ok



openInitialization 125 openScrollableCursorSQL:for

UpdateOf: 54 position 54 previous 54 primaryKey 74 print


printExternalTypeFor: in ORDBTable class 183 in SupraTable class 142

privateClose (primitive) in ORDBDatabaseCursor


class 176 in SupraDatabaseCursor


class 129 privateDelete (primitive)



privateDeleteUpdate: in ORDBDatabaseCursor


class 177

privateExecNoSelect: (primitive) in ORDBDatabaseCursor




class 129 privateExecSql:



privateExecSql:onError: (primitive) in ORDBDatabase class


110 privateExecUpdate:

(primitive) in ORDBDatabaseCursor


class 177 privateExternalTypeFor:


privateGetColumnLineField: in ORDBTable class 184 in SupraTable class 142

privateGetWidthPrecFixedFor: 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


instance methods (cont.) privateLoadSql:onError:

(primitive) in ORDBDatabase class


111 privateNext (primitive)





privateOpenCursorSql: (primitive) in ORDBDatabase class


111 privateOpenDatabase:colum

n:key:write: (primitive) 134

instance methods privateOpenScrollableCursor

Sql: (primitive) in ORDBDatabase class


111 privateSelectCountSql:



112 privateSetPositionTo:

(primitive) in ORDBScrollableCursor


class 130 privateStart (primitive)



privateStop (primitive) in ORDBDatabase class


112 privateTableCursorNotOpen

185 readPos:length: (primitive)

134 refresh



general description 39 remove:using:


removeDependencyFor: 112 rollback


general description 48 saveAs: 210 searchStartPos:endPos:string

:modePattern: (primitive) 135

serverType 199 setPositionTo: 54 size: 54 sourceDirectory



startAccessForUpdate: 30 startAccessForUpdate:scrolla

ble: 39 storedProcedure: 96 storedProcedureNames 96


instance methods (cont.) timeAsDBStringValue:



truncateLength: (primitive) 135

tsAsDBStringValue: 161 uniqueKeys 74 update:using:


update:with:with:with: 60 updateWith:





writePos:data: (primitive) 135

instance variables Cancel



dataArea in SupraDatabaseCursor


class 127 databaseIV 132 dbName 141 dbrecords 49, 50 descriptorIV 132 fieldValues 166, 177 lockmode 121 Logoff



OK in ORDBLogonController


class 121 parseFlag 127 parseId



password in ORDBLogonController


class 121 position 130, 178 queryResult



record 54, 55 sessionNumber




sqlString 130, 178 timeout 121 userName



Internal Database saving 210 specifications 21

InternalDatabase class 27 INTO clause 229 isORDB instance method 156 isSupra instance method 108


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)


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

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:timeout: class method 103

logoff instance method in ORDBLogonController


class 125 Logoff instance variable


in SupraLogonController 121 logonView class method

general description 42 in ORDBDatabase class 151 in SupraDatabase class 103 packaging applications and

63


M

manually binding the DB2 files 87

maxCursors class method (primitive)





maxDatabaseNameLength class method


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





general description 62

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



beginTran instance method 48

blobSupport: instance method 82

byteArrayAsDBStringValue: instance method in ORDBDatabase class


107 changed: instance method

60, 61 check instance method

(primitive) 107 checkAccessName: class

method in ORDBDatabase class


101


methods (cont.) close instance method

(primitive) in class SupraStringColumn 133

general description 54 commit instance method


general description 48 copy instance method 54 copyTo:sourcePos:destPos:le

ngth: (primitive) instance method (primitive) 133

createItems instance method in ORDBLogonController


class 123 createTableFrom instance


database instance method in ORDBLogonController


class 123 databaseType instance



107 dateAsDBStringValue:

instance method in ORDBDatabase class


108 dbTables instance method

58 dbTablesAt: instance

method 28, 58

dbTypeForClass: class method in ORDBDatabase class


101 dbTypeForClass:is: class



101 defaultDBType class method



defaultMethod instance method in ORDBLogonController


class 123 deleteField: instance


description class method in ORDBDatabase class








class 128 in SupraStringColumn



methods (cont.) desktopWpObjIconSource

instance method in ORDBLogonController


class 124 desktopWpObjName instance

method in ORDBLogonController


class 124 directory class method 45,

148 driverName instance method



dropOnDesktop instance method in ORDBLogonController


class 124 ESDatabase class method 91 execFunc:onError: instance

method 190, 191 execFunc:returnType:param

Types: instance method 190, 191

execFunc:returnType:paramTypes: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 49, 191

execSql:onError: instance method 50

execute instance method 38

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



102 indexKeys instance method

74 initialize class method










initializeBindings instance method in ORDBLogonController


class 124 initModule class method 64 isORDB instance method 156


methods (cont.) isSupra instance method 108 lastError instance method 85 length instance method

(primitive) 134 load instance method



108 loadInfo instance method


in ORDBTable class 183 in SupraDatabase class


loadSql: instance method 50, 191

loadSql:onError: instance method 50

loginUser:password: class method (primitive) 150

loginUser:password:lock:timeout: class method 103

logoff instance method in ORDBLogonController


class 125 logonView class method



103 packaging applications

and 63 maxCursors class method





class 128

maxDatabaseNameLength class method in ORDBDatabase class


103 maxLength: instance method

84 maxNameLength class


message instance method (primitive) in

ORDBDatabase class 157 (primitive) in

ORDBDatabaseCursor class 165





general description 62 modifyField:type:extType:fo

rmat: instance method 141

name instance method (primitive) in ORDBDatabaseCursor




class 129 nativeScrollableCursors 34 new:column:key:write: class

method 132 next instance method 54


methods (cont.) nextCursor class method





nextStamp instance method (primitive) 109

ok instance method in ORDBLogonController


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


printExternalTypeFor: instance method in ORDBTable class 183 in SupraTable class 142

privateClose instance method (primitive) in ORDBDatabaseCursor




class 129

privateDBCreateHideOptions class method in ORDBDatabase class


104 privateDelete instance

method (primitive) in ORDBDatabaseCursor


class 177 privateDeleteUpdate:

instance method in ORDBDatabaseCursor


class 177 privateDirectory class

method (primitive) in INFDatabase class 95 in ORDBDatabase class


104 privateExecNoSelect:

instance method (primitive) in ORDBDatabaseCursor




class 129 privateExecSql: instance



109 privateExecSql:onError:

instance method (primitive) in ORDBDatabase class


110


methods (cont.) privateExecUpdate: instance

method (primitive) in ORDBDatabaseCursor


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 privateLoadSql:onError:



111 privateNext instance method





class 130

privateOpenCursorSql: instance method (primitive) in ORDBDatabase class


111 privateOpenDatabase:colum

n:key:write: instance method (primitive) 134

privateOpenScrollableCursorSql: instance method (primitive) in ORDBDatabase class


111 privateSelectCountSql:



112 privateSetPositionTo:

instance method (primitive) in ORDBScrollableCursor


class 130 privateStart instance

method (primitive) in ORDBDatabase class


112 privateStop instance method



112 privateTableCursorNotOpen

instance method 185


methods (cont.) readPos:length: instance

method (primitive) 134 refresh instance method



general description 39 remove:using: instance


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



113 startAccessForUpdate:

instance method 30 startAccessForUpdate:scrolla

ble: instance method 39 storedProcedure: instance

method 96 storedProcedureNames

instance method 96

supportedFeatures class method in ORDBDatabase class


104 supportsSize class method



tableClass class method in ORDBDatabase class


105 timeAsDBStringValue:

instance method in ORDBDatabase 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


update:with:with:with: instance method 60

updateWith: instance method in ORDBDatabaseCursor




class 130 userName class method

(primitive) 105, 153


methods (cont.) validPrecisionTypes class



105 validSizedTypes class



105 validTypes class method



version class method (primitive) in ORDBDatabase 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:format: 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

N

name instance method (primitive)





nativeScrollableCursors method 34

negating conditions 235 new: class method 37 new:column:key:write: class

method 132 next instance method 54 nextCursor class method





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


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 low-

level 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



OK instance variable in ORDBLogonController


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

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


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


class 127 parseString: class method 37,

38 password instance variable



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

print instance method in ORDBTable class 183 in SupraTable class 141

printExternalTypeFor: instance method


printing records 214 reports, output options 277

privateClose instance method (primitive)





privateDBCreateHideOptions class method


privateDelete instance method (primitive)



privateDeleteUpdate: instance method



privateDirectory class method (primitive)

in INFDatabase class 95 in ORDBDatabase class 152 in SupraDatabase class 104


privateExecNoSelect: instance method (primitive)





privateExecSql: instance method


privateExecSql:onError: instance method (primitive)


privateExecUpdate: instance method (primitive)



privateExternalTypeFor: instance method


privateGetColumnLineField: instance method


privateGetWidthPrecFixedFor: instance method


privateLoad instance method (primitive)


privateLoadSql: instance method

in ORDBTable 158 in SupraDatabase class 110

privateLoadSql:onError: instance method (primitive)


privateNext instance method (primitive)





privateOpenCursorSql: instance method (primitive)


privateOpenDatabase:column:key:write: instance method (primitive) 134

privateOpenScrollableCursorSql: instance method (primitive)


privateSelectCountSql: instance method (primitive)


privateSetPositionTo: instance method (primitive)



privateStart instance method (primitive)


privateStop instance method (primitive)


privateTableCursorNotOpen instance method 185


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



general description 39 registering graphics files 267 remove:using: instance


removeDependencyFor: instance method 112

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


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


class 127 SET clause 229 setDataLoadLimitTo: class

method 24, 50 setPositionTo: instance

method 54 size instance method 54 snap to grid 251 sourceDirectory instance


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


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

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


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

SUBSELECT statements 38, 52 supportedFeatures class


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


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

timeAsDBStringValue: instance method


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


update:using: instance method


update:with:with:with: instance method 60

updateable cursors 55 updateWith: instance method





userName class method (primitive) 105, 153

userName instance variable in ORDBLogonController


class 121

V

validPrecisionTypes class method


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

variables Cancel instance variable

121, 169 cursors class variable

in ORDBDatabaseCursor class 163, 164




dataArea instance variable in SupraDatabaseCursor


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 SupraLogonController 121

ModuleDictionary global variable 64


variables (cont.) OK instance variable



parseFlag instance variable 127

parseId instance variable in SupraDatabaseCursor


class 127 password instance variable



position instance variable 130, 178

queryResult instance variable in ORDBDatabaseCursor


class 174 record instance variable 54,

55 sessionNumber instance

variable in SupraDatabase class



class 127 sqlString instance variable

130, 178 StartStopAnnouncementList

global variable 24, 65 timeout instance variable

121

typesSupported class variable in ORDBTable class 179,

180 in SupraTable class 137,

138, 139 userName instance variable



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


database user's guide - cincom smalltalk · objectstudio database user's guide,...

Documents