OBJECTSTUDIO. Database User's Guide P

Transcription

1 OBJECTSTUDIO Database User's Guide P

2 Release information for this manual ObjectStudio Database User's Guide, P , is dated vember 1, This document supports Release 6.9 of ObjectStudio. Cincom Technical Support for ObjectStudio All customers Web: USA customers Phone: Fax: (513) Attn: ObjectStudio Support Mail: Cincom Systems, Inc. Attn: ObjectStudio Support 55 Merchant Street Cincinnati, OH USA Outside of USA All: Visit the support links at to find contact information for your nearest Customer Service Center.

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

4 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 tebook Describes the Database tebook, 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

5 Contents Overview of database support How ObjectStudio supports databases Database classifications Database object framework Database objects Table objects Query objects Cursor objects Database tools How ObjectStudio implements database support Introduction Supported databases ODBC database Oracle database ADABAS database IBM DB2 database Microsoft SQL Server database SYBASE OpenClient database Informix database SUPRA SQL database UniSQL Server database Internal Database Database classes Database class hierarchy Database class ExternalDatabase class ODBCDatabase class OracleDatabase class AdabasDatabase class ESDatabase class SQLServerDatabase class SybaseDatabase class INFDatabase class SupraDatabase class Database User's Guide, P Contents

6 ORDBDatabase class LocalDatabase class InternalDatabase class Table classes Table class hierarchy Table class ExternalTable class VectorTable class Cursor classes Cursor class hierarchy Cursor class nscrollable cursors Scrollable cursors LocalCursor class Query classes Query class SqlDirect class SqlParse class SQL Query classes SqlSelect class SqlSubSelect class SqlUpdate class Working with databases Introduction Loading external database support Connecting to a DBMS Connecting options Database-specific connection information Accessing a database accessname: directory visibletablesat:put: Performing transactions Using SQL to query databases Methods for executing SQL statements Creating strings containing SQL code Using SQL versus using cursors Executing SQL with a local database Database User's Guide, P Contents

7 Working with cursors Data format returned Cursor messages Methods for cursor support Types of cursors Using cursors with ODBC Using cursors with SQL Server Using cursors with Informix Selecting multiple tables to create a cursor, in all databases except UniSQL Selecting multiple tables to create a cursor, in UniSQL Working with tables Linking to cursors and tables Types of links Creating a normal link Creating an update link Enhancing performance Handling errors Packaging applications Including login controllers in the image Delaying initialization of the DLL Delaying a database login ODBC Introduction ODBC elements ODBC conformance levels API conformance levels ODBC SQL grammar conformance levels ObjectStudio supports all ODBC conformance levels ObjectStudio ODBCDatabase and driver conformance-level dependencies Low-level ODBC support Additional ODBC classes Typical session Data type mapping System catalog access Example of using stored procedures Parametric SQL statements Cursors and scrollable cursors Working with Binary Large Objects (BLOBs) Enabling ODBC Support Using chunks Handling errors Database User's Guide, P Contents

8 DB Introduction Extended services Cursors ORDER BY clause and Extended Services database cursors Support for DB2 and Cursors with Hold Manually binding the DB2 files Descriptions of the bind file pairs to use in manual binding Performing the manual binding Granting database access to users other than yourself Cataloging databases Uncataloging databases Executing stored procedures Methods to execute DB2 procedures Considerations for parameters used by stored procedures Examples of DB2 stored procedures Informix Introduction Looking for Informix databases Connecting to Informix databases Transaction processing: commit and rollback Executing stored procedures SUPRA SQL Introduction Working with SUPRA SQL string columns ASCII/EBCDIC/BYTE designations and SUPRA SQL character columns FLOAT precision in SUPRA SQL Avoiding COMMIT WORK RELEASE and ROLLBACK WORK RELEASE Using multiple SUPRA SQL sessions SUPRA SQL class reference Introduction SupraDatabase class SupraDatabaseCursor class SupraLogonController class SupraScrollableCursor class SupraStringColumn class SupraTable class Database User's Guide, P Contents

9 UniSQL Server Introduction Using the lock_timeout_in_secs_parameter Report editor considerations UniSQL Server class reference Introduction ORDBDatabase class ORDBDatabaseCursor class ORDBLogonController class ORDBScrollableCursor class ORDBTable class Other databases Introduction Oracle and Oracle OCI support Oracle support Oracle OCI support ADABAS support SQL Server support Logging on using Windows Authentication Looking for SQL Server databases Message and error blocks MicroDecisionware access Microsoft SQL Server wrapper sets local host name SYBASE OpenClient support Message and error blocks Database tebook Introduction Using the Database tebook Database tebook pop-up menu Creating a new database Creating and modifying a table Saving changes to the Internal Database Entering data Accessing the default data entry form Customizing the Data Entry dialog box Managing data Opening the default Data Manager Customizing the Data Manager Form Creating a SQL query Using the SQL tools Using the SQL Browser Database User's Guide, P Contents

10 SQL tools Introduction SQL Editor Creating an SQL statement Using the Selection dialog box Executing a statement Defining a WHERE clause Defining a JOIN clause Defining a GROUP BY clause Defining a HAVING clause Defining an ORDER BY clause Creating parametric SQL statements Committing changes Rolling back changes Importing and exporting statements Creating a report for the statement SQL Window File menu Actions menu Creating an SQL statement Loading an ASCII text file into the SQL Window Report Editor Using the Report Editor Creating a report Saving reports Working with report sections Level breaks Adding or removing sections Formatting sections Using level breaks Working with report items Adding report items Resizing report items Deleting report items Copying or moving report items Formatting report items Formatting multi-line string items Formatting graphic items Formatting lines and topic boxes Creating and formatting bitmapped images Registering a graphics file Database User's Guide, P Contents

11 Defining and formatting graphs and graph legends Placing a graphics field Defining a graphics field Formatting graphics fields Formatting graphics legends Formatting, previewing, and printing a report Formatting report pages Previewing a report Printing from the Report Preview Setting the report timer Setting output options Printing or previewing a report Cross-platform development Windows character set conversion Index Database User's Guide, P Contents

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

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

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

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

16 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 tes, P Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Introduction

17 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: Subclass of Database: Subclass of Table: Subclass of Cursor: ODBC ODBCDatabase ODBCTable ODBCCursor ODBCScrollableCursor Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Supported databases

18 Oracle database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: Oracle Database Client Oracle Database Client (ORACLE Mode) Oracle Database Client 9.2 Oracle Database Client 9.2 (ORACLE Mode) Oracle Database Client (OCI) OracleDatabase OracleTable OracleDatabaseCursor OracleScrollableCursor ANSI and Oracle Mode database wrappers. See ANSI and Oracle Mode loadable applications on page 187 for information on: Oracle Database Client loadable application vs. Oracle Database Client (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 te: Oracle is the first Oracle release with which the Oracle OCI database wrapper will work. However, the Oracle OCI database wrapper should work with subsequent releases of Oracle. Unsupported Oracle database wrappers that are still available as goodies. Cincom has removed the following loadable applications from ObjectStudio s loadable application list: Oracle Database Client 7.3 Oracle Database Client 7.3 (ORACLE Mode) Oracle Database Client 8.0 Oracle Database Client 8.0 (ORACLE Mode) Cincom no longer supports the databases wrappers loaded by these applications. However, these loadable applications are still available in the Goodies folder. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Supported databases

19 ADABAS database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: Adabas Database AdabasDatabase AdabasTable AdabasDatabaseCursor AdabasScrollableCursor IBM DB2 database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: 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) ESDatabase ESTable ESDatabaseCursor ESScrollableCursor Cursor with Hold loadable applications. According to the ANSI standard, a database must close and destroy a Cursor when you perform a commit on the database. However, when you use a Cursor with Hold loadable application for DB2 6.1 or 7.2, DB2 can both keep open and update a database Cursor when you perform a commit. When DB2 does this, you may see a performance improvement over the ANSI standard behavior. Unsupported DB2 database wrapper that is still available as a goody. Cincom has removed the DB2 Database Version 5.0 loadable application from ObjectStudio s loadable application list. Although Cincom no longer supports the database wrapper loaded by this application, this loadable application is still available in the Goodies folder. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Supported databases

20 Microsoft SQL Server database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: MS SQL Server Database SQLServerDatabase SQLServerTable SQLServerDatabaseCursor SQLServerScrollableCursor You can use the MS SQL Server Database wrapper with SQL Server 6.5, 7.0, or 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 SYBASE OpenClient database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: SYBASE OpenClient Version 11.5 SYBASE OpenClient Version 12.5 SybaseDatabase SybaseTable SybaseDatabaseCursor SybaseScrollableCursor Informix database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: Informix Client Version 7.12 Informix Client Version 7.3 INFDatabase INFTable INFDatabaseCursor INFScrollableCursor Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Supported databases

21 SUPRA SQL database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: SUPRA SQL 2720 SUPRA SQL 2800 SUPRA SQL 2900 SupraDatabase SupraTable SupraDatabaseCursor SupraScrollableCursor UniSQL Server database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: UniSQL ORDBDatabase ORDBTable ORDBDatabaseCursor ORDBScrollableCursor Internal Database Loadable application/package: Subclass of Database: Subclass of Table: Subclass of Cursor: ne (already loaded) InternalDatabase t applicable t applicable Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Supported databases

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

23 Database class The Database class is an abstract class, which defines the basic functions for its subclasses. All subclasses of Database inherit the following features from Database: Ability to track all accessible databases Logon and Logoff functions (if they are needed) Ability to track the database types that are loaded in ObjectStudio An instance of the Database class: Contains instances of subclasses of class Table that represent each table in the physical database. Executes an SQL string. Creates a cursor as part of executing an SQL SELECT statement (optionally). The cursor, which is a direct connection to the result set, allows the user to update the database. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Database classes

24 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, P Class ExternalDatabase uses the variable DataLoadLimit to restrict the number of rows returned by an SQL query. The default maximum number of rows is 500. To change the value, send the setdataloadlimitto: class message. ExternalDatabase allows you to use the Visible Tables feature to tell ObjectStudio with which tables you want to work. You can use this feature when the database has a large number of tables to prevent ObjectStudio from querying the physical database to determine the name of each table. For more information on this feature, see Enhancing performance on page 62. ODBCDatabase class The ODBCDatabase class implements the access layer for the complete Microsoft ODBC Version 2.5 Application Programming Interface (API). It provides you with easy access to the X/Open-compliant Call Level Interface (CLI) to SQL databases and to Microsoft extensions to this standard, as specified in the ODBC Version 2.5 specification document. From ObjectStudio, you can use either high-level support or low-level support for ODBC. High-level support works with the ODBCDatabase class. You may want to use high-level support if you have already implemented database code in ObjectStudio. With low-level support, you program directly to the SQL Access Group (SAG) CLI. For more information on low-level support, see Low-level ODBC support on page 69. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Database classes

25 OracleDatabase class The OracleDatabase class implements the access layer for Oracle databases. In addition to the features it inherits, this class supports: Execution of PL/SQL blocks, stored procedures, and functions Ability to set the number of records retrieved using arrayfetch with execsql: and loadsql: Ability to set the maximum number of characters returned for a LONG column Logon methods and the name of an ObjectStudio Controller to use for logging in to the database Ability to gain access to an instance of OracleDatabase on login AdabasDatabase class The AdabasDatabase class implements the access layer for ADABAS databases using the Oracle API. See the preceding OracleDatabase class section for access layer information. ESDatabase class The ESDatabase class implements the access layer for the IBM DB2 database. In addition to the features it inherits, this class supports: Ability to execute stored procedures. Inserting the user ID and password in the class so that you can log in to the database without using a login window. For NT servers, you must include the user ID and password. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Database classes

26 SQLServerDatabase class The SQLServerDatabase class implements the access layer for the Microsoft SQL Server database. In addition to the features it inherits, this class supports: Ability to execute stored procedures and retrieve multiple result sets. Logon methods and the name of an ObjectStudio Controller to use for logging in to the database. With Microsoft SQL Server, you log in to a server rather than to a particular database. All databases on that server become available through ObjectStudio as instances of this class. A getservers method to return all known SQL Servers on the network. Each of these servers is queried for their available databases. This method is used primarily by the logon Controller. SybaseDatabase class The SybaseDatabase class implements the access layer for the SYBASE OpenClient database. In addition to the features it inherits, this class supports: Ability to execute stored procedures and retrieve multiple result sets. Logon methods and the name of an ObjectStudio controller to use for logging in to the database. With SYBASE OpenClient databases, you log in to a server rather than to a particular database. All databases on that server become available through ObjectStudio as instances of this class. INFDatabase class The INFDatabase class implements the access layer for the Informix database. In addition to the features it inherits, this class supports the ability to execute stored procedures. SupraDatabase class The SupraDatabase class implements the access layer for the SUPRA SQL database. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Database classes

27 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 tebook, as described in Using the Database tebook on page 203. The InternalDatabase class supports a collection of instances of class Table. In every ObjectStudio environment, there is a single instance of the InternalDatabase class, called EnfinInternalDb. If an instance of class Table is a member of this database, it can be included in SQL queries against the Internal Database. The InternalDatabase class implements the tablelocations variable. When an instance of the InternalDatabase class is asked for a particular table, it first looks to see if the table exists. If the table does not exist, it looks in tablelocations to see if the table is referenced there. If it exists, it uses the tablelocations variable to load a class that recreates the table. This variable allows internal tables to be loaded on demand. ObjectStudio supplies several example tables that work with the Internal Database and are handled this way. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Database classes

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

29 Table class hierarchy The Table class hierarchy is: Table (ObjectStudio Internal Table) ExternalTable (Abstract Class) ADABASTable ESTable INFTable ODBCTable OracleTable ORDBTable SQLServerTable SupraTable SybaseTable VectorTable The remainder of this section describes the classes in the Table class hierarchy. Table class The Table class is an internal ObjectStudio abstract class that supports a table structure. It provides methods for table creation and modification, record insertion, record deletion, and record modification. Tables can also be saved to and loaded from disk. Subclasses of Table inherit its methods. To create a Table, send the execsql: method to an instance of class InternalDatabase or ExternalDatabase. The method returns an instance of Table. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Table classes

30 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 ADABAS DB2 Informix ODBC Oracle SQL Server SUPRA SYBASE UniSQL Subclass of ExternalTable ADABASTable ESTable INFTable ODBCTable OracleTable SQLServerTable SupraTable SybaseTable ORDBTable VectorTable class The VectorTable class is a special type of internal table class that stores table data by column rather than by row. VectorTable stores numeric columns as vectors and stores nonnumeric columns as arrays. This strategy saves space because numeric columns can be stored as single objects. The interfaces to VectorTable and Table are nearly identical. Therefore, you can use the two classes interchangeably. At times, using VectorTable is more efficient because accessing data by row can be slower than accessing a Table object. This is because the rows must be constructed as needed. One way to create an instance of VectorTable is to use the return value (a VectorTable) of loadsql: (a message that you send to an instance of Database). Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Table classes

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

32 Cursor class hierarchy The Cursor class hierarchy is: Cursor (Abstract Class) ExternalDatabaseCursor (Abstract Class) AdabasDatabaseCursor ESDatabaseCursor ExtDbScrollableCursor (Abstract Class) ADABASScrollableCursor ESScrollableCursor INFScrollableCursor ODBCScrollableCursor OracleScrollableCursor ORDBScrollableCursor SQLServerScrollableCursor SupraScrollableCursor SybaseScrollableCursor INFDatabaseCursor ODBCCursor OracleDatabaseCursor ORDBDatabaseCursor SQLServerDatabaseCursor SupraDatabaseCursor SybaseDatabaseCursor LocalCursor (Abstract Class) The remainder of this section describes the classes in the Cursor class hierarchy. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Cursor classes

33 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. nscrollable 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 ADABAS DB2 Informix ODBC Oracle SQL Server SUPRA SYBASE UniSQL Subclass of ExternalDatabaseCursor AdabasDatabaseCursor ESDatabaseCursor INFDatabaseCursor ODBCCursor OracleDatabaseCursor SQLServerDatabaseCursor SupraDatabaseCursor SybaseDatabaseCursor ORDBDatabaseCursor Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Cursor classes

34 Scrollable cursors This section describes classes that implement scrollable cursors. ExtDbScrollableCursor class The ExtDbScrollableCursor class is an abstract class that implements features for external database scrollable cursors. In addition to the features it inherits, it implements features that: Add records Perform positioned updates and deletes Ask for the size of the result set Move the record pointer to any position in the result set ODBCScrollableCursor class The ODBCScrollableCursor class uses native scrollable cursors (that is, cursors that are supplied by the database driver) if the data source offers the following features: ODBC API call SQLExtendedFetch Two fetch options: - SQL_FD_FETCH_NEXT - SQL_FD_FETCH_PREV At least one of the following scroll options: - SQL_SO_KEYSET_DRIVEN - SQL_SO_DYNAMIC - SQL_SO_MIXED Otherwise, ObjectStudio provides a simulated scrollable cursor, which is based on native fetch-forward-only cursors. To determine whether the database driver complies with the features described in the previous list, send the message nativescrollablecursors to class ODBCDatabase. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Cursor classes

35 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 ADABAS DB2 Informix ODBC Oracle SQL Server SUPRA SYBASE UniSQL Subclass of ExtDbScrollableCursor ADABASScrollableCursor ESScrollableCursor INFScrollableCursor ODBCScrollableCursor OracleScrollableCursor SQLServerScrollableCursor SupraScrollableCursor SybaseScrollableCursor ORDBScrollableCursor LocalCursor class The LocalCursor class is an abstract class that implements cursors for local database cursors. The class implements methods that: Add records Perform positioned updates and deletes Move the record pointer to any position in the result set Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Cursor classes

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

37 Query class The Query class is an abstract class that implements the basic features of queries. Primarily, it keeps track of all instances of its subclasses. SqlDirect class The SqlDirect class provides the ability to create an SQL object for a string that cannot be parsed by ObjectStudio. This includes all non-ansi-standard SQL statements such as stored procedure access for SQL Server and PL/SQL for Oracle. SqlDirect implements a creation routine, the new: class method, which takes the SQL string as a parameter. SqlParse class The SqlParse class is an abstract class that provides features for all query types that can be parsed by ObjectStudio. The class includes the query parser and some default behavior. To create an instance of SqlParse (or one of its subclasses), send the parsestring: class method. This method takes an SQL string and, depending on the type of SQL statement, either generates an error or an instance of one of the SqlParse subclasses. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Query classes

38 SQL Query classes The following table lists the SQL Query classes and the SQL queries that they represent: Query class SqlDelete SqlInsert SqlSelect SqlSubSelect SqlUpdate te the following about SQL Query classes: Query type SQL DELETE SQL INSERT SQL SELECT SQL SUBSELECT SQL UPDATE The easiest way to create an instance of each of these classes is to use the SQL Editor, which is described in SQL Editor on page 220. You can create an SQL object by sending the parsestring: message to the Query class or to one of its subclasses. The parameter is an SQL string. To execute an SQL query, send execute to an instance of the Query class or one of its subclasses. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Query classes

39 SqlSelect class In addition to using the execute message, you can use one of the opencursor or openscrollablecursor messages to pass an SQL SELECT statement to a DBMS. You can also use the Designer to link to an SqlSelect object. You can associate a cursor with an SqlSelect instance. The first time the startaccessforupdate:scrollable: message is sent to an SqlSelect object, a cursor is opened and returned. You can specify that a cursor is updateable or scrollable in the original startaccess method, or you can change the cursor in subsequent sends. The cursor is shared with all callers of the startaccessforupdate:scrollable: message. Add dependencies to the cursor rather than to the SqlSelect object. This ensures that all objects using the query are using a common cursor and that updates to the cursor are reflected in all objects using it. A refresh message is also supported by SqlSelect objects; it rebuilds the associated cursor and updates all its dependencies. SqlSubSelect class Instances of the SqlSubSelect class provide for subselects within SQL statements. Generally, they are used internally only within other SQL objects. SqlUpdate class Instances of the SqlUpdate class provide for the SQL INSERT statement. Use the execsql: message to pass an SqlUpdate query to a database. Database User's Guide, P Chapter: How ObjectStudio implements database support Section: Query classes

40 3 Working with databases Introduction This chapter provides information on techniques to use when you work with databases. These techniques apply to all database platforms. Where appropriate, there is additional information necessary for working with a specific database. Loading external database support Before you can work with an external database, you must load an application that supports access to a specific DBMS into the ObjectStudio environment. The Internal Database is already loaded into the ObjectStudio environment. For more information on the Internal Database, see Internal Database on page 21 and InternalDatabase class on page 27. After loading the application that supports your underlying database, you have complete access to the databases and tables associated with your database management system (to the limits defined by your database administrator). For a complete list of supported databases and gateways, see Supported databases on page 17. Database User's Guide, P Chapter: Working with databases Section: Introduction

41 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, P Database User's Guide, P Chapter: Working with databases Section: Loading external database support

42 Connecting to a DBMS This section describes how to log in to a DBMS from ObjectStudio. Logging in involves identifying the server on which the database is installed and initializing communications to that server. Each database has its own login procedure. ObjectStudio provides methods that you can use with most of the databases that ObjectStudio supports. After you log in to a database, select the specific database that you want to access. For a description of this process, see Accessing a database on page 45. You do not need to log in to the Internal Database. For more information on the Internal Database, see Internal Database on page 21 and InternalDatabase class on page 27. Connecting options There are two ways in which you can connect to a database: Programmatically With a controller Connecting programmatically You can log in to a database programmatically, without using the ObjectStudiosupplied login controller. To do so, use the Class Browser to search for the login messages for the database you are using. Connecting with a controller For most DBMSs, you can display a login controller (a user interface) that prompts for a user name, a password, and a server name. ObjectStudio provides the following Database class methods that allow you to work with a login controller for the DBMS with which you are working: haslogonview. Returns a Boolean value indicating whether the database has a controller for logging in associated with it. logonview. Returns the controller that allows a user to log in to a database. Include this controller in the image that you create for the application. initialize. Opens the login controller for the database. When the user clicks OK on the controller, ObjectStudio logs the user in to the database. Database User's Guide, P Chapter: Working with databases Section: Connecting to a DBMS

43 Database-specific connection information Each database has a specific login procedure: Oracle. When you log in to an Oracle database, type an SQL*Net connect string in the server entry field. If you do not provide an SQL*Net string, a local connection is assumed. ADABAS. When you log in to an ADABAS database, type an SQL*Net connect string in the server entry field. If you do not provide an SQL*Net string, a local connection is assumed. IBM DB2. When you send the directory message to the ESDatabase class, it returns an instance of the class ESDatabase for each database that has been cataloged on the workstation. Only one of these databases can be active at a time. SQL Server. The SQLServerDatabase class provides a getservers method that returns a list of all SQL Servers available on the network. The login controller uses this method to display a list of available servers. The login controller provides a list of SQL Servers found only on Windows. For more information, see Looking for SQL Server databases on page 196. SYBASE OpenClient. When you log in to a SYBASE OpenClient database, enter the name of the SYBASE Server in the server entry field. You also need to enter a user name and a password. The database name will be case-sensitive. Informix. Informix-Online Workgroup Server must be installed either on your computer or on another computer to which your computer is connected over a network. Informix automatically verifies your user ID and password. It uses the information you selected in the Informix client software program SetNet32. After the Informix application is loaded, use the ExternalDatabase>>accessName: method to establish a connection. Here is an example that will connect to the stores7 database on server demo : INFDatabase accessname: #'stores7@demo'. If a connection fails, verify that the user ID and the password are defined to the Informix Online Workgroup server with the required privileges. Database User's Guide, P Chapter: Working with databases Section: Connecting to a DBMS

44 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, P , for more information on each of these variables. UniSQL Server. Consider the following: - With UniSQL Server database wrapper support, you log in to one database server at a time. This login records the user name and password, which are used later when you access the database. If you do not enter a user name and password, the UniSQL Server default user name and a password are used. - From the UniSQL Server Logon window, you can reset the user name and password back to the UniSQL Server default by pressing the OK button without specifying a user name and password. - Sending the directory message to the ORDBDatabase class provides a list of available databases you can access. - The database name will be case-sensitive. Internal Database. You do not need to log in to the Internal Database. Database User's Guide, P Chapter: Working with databases Section: Connecting to a DBMS