Connecting to a database manager
Some terms and concepts that you need to understand before connecting to a database include: "database manager", "connection specification", "alias", and "access set."
Database managers
The interface between VA Smalltalk and a DBMS is called a database manager. To use VA Smalltalk's database support, you connect to a database through a VA Smalltalk database manager. VA Smalltalk uses the following database managers:
IBM Database 2 -- CLI
The native interface between VA Smalltalk and the IBM DB2 DBMS. This is available when you load the IBM Database feature.
ODBC
The ODBC interface between VA Smalltalk and your DBMS. This is available when you load the ODBC Support feature.
Oracle - Native
The native interface between VA Smalltalk and your ORACLE DBMS. This is available when you load the Native Oracle Database feature.
Connections, connection specifications, and aliases
A database connection is a connection from VA Smalltalk to a database through a database manager. You can establish more than one database connection at a time if your DBMS allows multiple connections.
To keep track of your database connections, VA Smalltalk uses something called connection specifications. A connection specification associates an alias, which is a name that you make up to refer to your database, with a VA Smalltalk database manager and a database name or ODBC data source. You might use the alias SampleConSpec, for example, to refer to a connection to the SAMPLE database through DB2. A connection specification serves several purposes:
It points to the database manager and database to use for database operations.
It lets you develop your application independent of a specific database. This independence is helpful if you need to use one database to develop and test your application, and another for production use of your application.
It keeps track of whether or not you are connected to your database manager.
You can define a connection specification once and use it over and over again in more than one application. If you change the database that an alias points to, then you can automatically update all parts that use that alias. In the sample application that you will build in this chapter, for example, you will create a connection specification called SampleConSpec that uses the IBM Database 2 - CLI database manager and the SAMPLE database. You can change this connection specification to use the ODBC database manager instead. After you edit the connection specification to make this change, you do not have to change the parts in your application. They adopt the new database manager automatically.
Note:
You should be careful about changing the database manager associated with an alias. VA Smalltalk can manage a change in databases more easily than a change in database managers. You may need to migrate your application to the new database manager if you change the database manager that a connection specification points to. See the VA Smalltalk Migration Guide for information on using the VA Smalltalk database application migration tool.
Access sets
An access set is a special part that you define and package with your application to store connection specifications, database query definitions, and stored procedure definitions. An access set tells your application which connection specifications, queries, and stored procedures it can use.
Note:
VA Smalltalk stores all specifications (connection, query, and stored procedure) in an access set with method categories that are used by VA Smalltalk. Do not change a method category for a connection, query, or stored procedure specification. You can add the selector to other categories if you want.
To make a connection between your application and a database, you need to do the following. (The following sections explain how to do each of these steps.)
1. Define an access set for your application.
2. Create a connection specification for your database and add the connection specification to the access set.
3. Establish a database connection using the connection specification.
 
Tip
If connecting to a database sounds complicated right now, don't worry! Most of the time, VA Smalltalk can detect if you have missed a step and either prompts you to do it or does it for you.
 
Defining an access set
VA Smalltalk saves queries, stored procedures, and connection specifications in access sets. An access set can be packaged with your application, much like the classes that define your visual and nonvisual parts. An access set can hold many queries, stored procedures, and connection specifications, and can be shared by different applications.
To define an access set, follow these steps. Make sure your database application is selected in the Organizer.
1. From the basic Parts menu, select New.
2. In the Part class field, type a name for your access set.
For the sample application, type SampleDatabaseAccessSet.
3. From the Part type drop-down list, select Database access set.
4. Select OK.
The new access set is added to the list of parts for your application.
If you use only one database manager, you can use the same access set for storing all of the queries, stored procedures, and connection specifications in an application. If you use more than one database manager, such as DB2 and ODBC, create an access set for each database manager. Though using separate access sets is not a requirement, it helps you to determine appropriate prerequisites when you package your application. VA Smalltalk attempts to maintain prerequisites according to the connection specifications defined in an application.
Creating a connection specification
To define a connection specification, follow these steps:
1. From the Options menu in the Organizer, select Database connections.
The Database connection specifications window is displayed. You use this window to define, update, or delete connection specifications, and to add existing connection specifications to an application. The top portion of this window contains a list of connection specifications currently defined in your image. The push button below this list shows the name of the application you are currently working with.
The bottom portion of the window contains all connection specifications that have already been added to the application you are working with. The push buttons below this list let you create new connection specifications, update the selected one, or delete the selected one. Each time you change a connection specification, VA Smalltalk changes the prerequisites according to the connection specifications currently defined for the application.
Connetion Specifications window
2. To define a new connection specification, select the New push button.
The New database connection specification window is displayed. You use this window to associate an alias with a database manager and a database.
New Connection Specification window
3. In the Connection alias field, type an alias for the database manager and database. The alias must be a valid method name: SampleConSpec is valid, but Sample Connection Spec is not.
For the sample application, type SampleConSpec.
4. From the Access set drop-down list, select the access set to store the connection specification in.
For the sample application, select SampleDatabaseAccessSet.
5. From the Database Manager drop-down list, select the database manager you want to use.
For the sample application, select IBM Database 2 - CLI.
Note:
If no database managers appear in the drop-down list, then you need to load a database support feature, as explained in Loading database features.
6. From the Database name (or Data source name for ODBC) drop-down list, select the name of your database or data source.
For the sample application, select SAMPLE.
7. To prompt users for their database logon ID and password, select the Prompt for logon information check box.
8. After you complete the fields, select OK. The connection specification is saved, and you are returned to the Database connection specifications window.
Your new connection specification appears in both lists in the Database connection specifications window, and the prerequisites for the application are updated. Now that you have a connection specification for the database, go to Defining a database query to continue work on the sample application.
Adding a connection specification to an access set
When you create a new connection specification as part of your application development process, VA Smalltalk adds the specification to your access set for you. But you can also use connection specifications that were created outside of your application and add them to your access set.
After you have created an access set and a connection specification, putting them together is easy. Simply select the connection specification that you want to use in the top portion of the Database connection specifications window and then select the <<Add push button. This button adds the connection specification to the access set.
Note:
If your application has more than one access set, the New database connection specification window displays so that you can select the access set to add the connection specification to.
Establishing a database connection
To connect to a database manager, follow these steps:
1. Select a connection specification from the Database connection specifications window.
2. Press mouse button 2 to display the connection menu and then select Connect.
If you have selected Prompt for logon information, the Database logon window is displayed. You use this window to establish a database connection.
3. If the particular database manager you are using requires a User ID, Password, and Server, enter the appropriate values and select the Logon push button.
Note:
If you want to use the default user ID and password for DB2, type USERID and PASSWORD in these fields.
4. Close the Database Connection Specifications window.
Changing the database (or data source) name in the .ini configuration file
You can change the Database name (or Data source name for ODBC) of a connection specification by changing the .ini configuration file. Changing the database (or data source) name in the .ini file allows you to change the database (or data source) without changing and repackaging the Smalltalk code. The new value in the .ini file overrides the value saved in the connection specification.
The .ini configuration file is a series of keywords and values that are processed when you start your image. The installation process should have created a working configuraiton file for you. The deault configuration file is abt.ini. To edit the .ini configuration file, open it in a text editor.
The database name keywords and values in the .ini file are located under the heading for the AccessSetName:
[AccessSetName]
connectionAlias=dataSourceName
For example, if you are using the access set SampleDatabaseAccessSet and want to change the connection alias called SampleConSpec to connect to the Production database, change the .ini file as follows:
[SampleDatabaseAccessSet]
SampleConSpec=Production
 
Note:
If you override the Database name (or Data source name for ODBC) in the .ini file and then edit the connection specification, the Database connection specifications window displays the .ini file value. You will continue to connect to the .ini file value until you remove this override value from the .ini file and restart your image.
Last modified date: 05/20/2020