2
Creating a Starter Application

This chapter describes how to create a starter application with Oracle AppWizard for Microsoft Visual C++.

Specific topics discussed are:

• Overview

• Starting Oracle AppWizard for Microsoft Visual C++

• Creating a Single- or Multiple-Record Display Application

• Creating a Master-Detail Display Application

• Building the Executable

• Running the Executable

Overview

After starting Oracle AppWizard for Microsoft Visual C++, you complete a series of steps in which you specify which of three application types you want to create:

Application Type	Description
Single-Record Display Form	Enables your application to display one record from one or more tables at a time.
Multiple-Record Display Form	Enables your application to display more than one record from one or more tables at a time.
Master-Detail Display Form	Enables your application to display records from tables that have a master-detail relationship to each other.

The first three steps are the same whether you create a single-record, multiple-record, or a master-detail display.

When you finish the last step, Oracle AppWizard for Microsoft Visual C++ generates the application. Application files include the following:

• Source files

• Header files

• Resource files

• Standard MFC project files

• A ReadMe.file describing all the files comprising your application

You then build and run the executable, using Microsoft Visual C++.

Starting Oracle AppWizard for Microsoft Visual C++

To start Oracle AppWizard for Microsoft Visual C++:

1. Start Microsoft Visual C++ 5.0 or 6.0.

2. Choose File > New.

   The New dialog box appears.

3. Click the Projects tab.

4. Select Oracle AppWizard for MFC (exe) from the list of project types.

5. Specify the project name and location.

6. Click OK.

   Oracle AppWizard for Microsoft Visual C++ starts.

   Note: If Oracle AppWizard for Microsoft Visual C++ cannot be loaded successfully, ensure that you have installed Oracle Objects for OLE (OO4O) and that the following directory has been created: ORACLE_BASE\ORACLE_HOME\BIN

Creating a Single- or Multiple-Record Display Application

This section describes how to create a single- or multiple-record display application.

Welcome Window

The Welcome window appears when you start Oracle AppWizard for Microsoft Visual C++.

Click Next to continue.

Connecting to an Oracle Database

In the Connection window, you connect to an Oracle database.

To connect to the Oracle database:

1. Enter your user name in the User Name text box.

2. Enter your password in the Password text box.

3. If connecting to a remote database, type the database alias in the Database Alias text box. If connecting to a local default database, leave the text box blank.

   For more information about database aliases, refer to the Net8 Administrator's Guide.

4. Click Next.

Specifying the Type of Form

Use the Form Type window to name your form, generate a specific type of database form, and to specify the database privileges for users.

To complete the Form Type window:

1. Enter the name of the form in the Form Name text box. Each form name must be unique and the first character of the form name must be a letter. The rest of the form name must be alphanumeric. For example:

   a1b3eux
   

2. Forms can be single-record, multiple-record, or master-detail display. Select the database form type you want to generate for the application:

   If You Want to Create a...	Then Select...
   Single-record display form that displays one record at a time on a form	Single-Record Display Form
   Multiple-record display form that displays multiple records on a form	Multiple Record Display Form
   Master-detail display form that displays infromation in master-detail format	Master Detail Display Form and see section "Creating a Master-Detail Display Application"

3. Select the database options permitted by the form:

   If You Want Users to Be Able to...	Then Select the...
   Add records	Add new records checkbox
   Change records	Change existing records checkbox
   Delete records	Delete existing records checkbox

   If you select any or all permitted database operations for your users, Oracle AppWizard generates code for this purpose. This enables methods that allow the users of your application to update data. If you do not select any permitted database operations, Oracle AppWizard does not generate code for this purpose and the form will be read-only.

4. Click Next.

Selecting Tables and Columns

In the Tables/Columns Selection window, you select columns from the tables you want the form to reference. The tables available to you appear in the list.

To complete the Tables/Columns Selection window:

1. Select one or more tables from the list to appear in your application. By default, all the columns of the table you select are also automatically selected unless you manually deselect them by clicking them.

   The Add, Change, and Delete options, specified in the Form Type window, work only with a single table. If you select multiple tables and have checked these options, the following error message appears:

   Add, Change, and Delete are supported in applications using a single table. 
   You have selected multiple tables.
   Database Functionality defaults to Read Only.
   

   If necessary, expand the table you selected and select additional columns that should be displayed in the application.

2. Click Next.

Specifying One or More Joins (Optional)

Oracle AppWizard for Microsoft Visual C++ automatically creates a simple join (also called an equi-join) between two tables, or views, based on a Primary Key and a Foreign Key.

Joins are used in the WHERE clause of a SELECT statement to avoid a Cartesian product, which would combine every row in one table with every row in another table. For example, a 90-row table combined with a 100-row table would produce a 9000-row result.

Note: If you only specify one table, Oracle AppWizard for Microsoft Visual C++ skips the table join step.

Additional Information: See the description of the SELECT command in Oracle8i SQL Reference for more information about various types of joins and Cartesian products.

Tip: When selecting tables or columns, use the Ctrl key and your mouse to select items that are not adjacent. Also, you can use the Ctrl key and your mouse to deselect an item.

The Oracle AppWizard Table Join window displays a join in the following format for single or multiple tables:

SCHEMA.TABLE_NAME.COLUMN_NAME [DATA_TYPE] joins 
          SCHEMA.TABLE_NAME.COLUMN_NAME [DATA_TYPE] 

If you do not want to use the suggested join created by Oracle AppWizard for Microsoft Visual C++ (shown in the previous illustration), you can delete it and create a new join. You can also do this by modifying the WHERE clause of a query statement in the source file generated by Oracle AppWizard for Microsoft Visual C++.

To accept the default join:

1. Click Next.

To delete the default join:

1. Highlight the default join displayed in the Table joins list.

2. Click the Delete Join button.

   Oracle AppWizard for Microsoft Visual C++ deletes the join.

To create a new a join:

1. Highlight two columns from different tables that you want to join by using your mouse and the Ctrl key.

   The join appears in the Table joins list with the following syntax:

   SCHEMA.TABLE.COLUMN [DATA_TYPE] joins SCHEMA.TABLE.COLUMN [DATA_TYPE]
   

   Note: You can specify more than one join.

2. Click Next.
   Oracle AppWizard for Microsoft Visual C++ prompts you to build another form. If you decide to create a new form, you cannot go back and use Oracle AppWizard for Microsoft Visual C++ to modify the form you have already created.

   If you want to build another form, click Yes and Oracle AppWizard returns you to the Application Type window.

   If you do not want to build another form, click No.

Specifying the Application Type and User Language

When you are finished building forms and click Next, you can specify the application type and user language.

Note: If you are using Microsoft VC++ 6.0, there is an additional option for Document/View architecture support. See "Microsoft Visual C++ 6.0 Limitations".

To complete the Application Type window:

1. Indicate the type of application you are creating:
   • Single document

   • Multiple documents

   • Dialog-based

     Note: Dialog-based applications are not supported in this release.

2. Select the language appropriate for your application or accept the default language in the list box.

3. Click Next.

Completing the Remaining MFC Windows

Complete the remaining standard MFC windows as appropriate until you reach the window illustrated below. For more information about MFC windows, refer to your MSVC++ documentation.

Viewing the Application Classes

In the Class Information window, Oracle AppWizard for Microsoft Visual C++ displays the classes it creates for your application, including their names, header files, base classes, and the implementation file:

To complete the Class Information window:

1. Review the list for completeness and accuracy.

2. If you are not satisfied with the listed classes, click Back to go to the appropriate previous dialog box to make changes.

3. Depending on which class you have selected, you may change the class name, header file name, and the implementation file name. If you rename these files, the first character must be a letter. The rest of the name must be alphanumeric.

4. When you are satisfied with the result, click Finish.
   The New Project Information window appears.

Viewing the Specifications for the New Application

The New Project Information window displays the specifications for the new skeleton application you are creating.

• If the specifications appear to be correct, click OK.

  Oracle AppWizard generates the files for your single-record or multiple-record application.

• If the specifications are not correct, click Cancel.

  
  

Creating a Master-Detail Display Application

This section describes how to create an application that can display records from two or more tables that have a master-detail relationship.

The first three windows are completed in the same way as those described in "Creating a Single- or Multiple-Record Display Application", except that, for a master-detail display, you will complete the Application Type window as follows:

• Select Master-Detail Display Form as the database form type

• Optionally, you can permit the user of your application to perform the database operations listed in the Application Type window by selecting any or all of the three check boxes.

Specifying the Type of Form

In the Form Type window, type the name you want to give the form, select the type of form, and the database privileges that your application requires.

Selecting Master Tables and Columns

In the Master Table/Column Selection window, the available master tables appear in a list:

To complete the Master Table/Column Selection window:

1. Select the master table columns from the list. In the example above, the Sales Order table is the master table. All the columns from the Sales Order table have been selected.

2. If necessary, expand the table you selected by clicking the '+' to the left of the table name and change which columns are to be displayed in the application.

3. Click Next.

   Note: The master table is created as a read-only table in your application.

Selecting Detail Tables and Columns

In the Detail Table/Column Selection window, the available detail tables appear in a list. Select the detail tables and the columns you want displayed in the application.

To complete the Detail Table/Column Selection window:

1. Select columns from one or more detail tables in the list. In the illustration above, the Item table is the detail table. The Iten table and all of its columns have been selected.

2. If necessary, expand the table you selected by clicking the '+' to the left of the table name, and change which columns are to be displayed in the application.

3. Click Next.

Building a Join Clause

After you select the tables between which to set up a master-detail relationship, use the Master/Detail Table Join window to specify how to join the columns from each of the tables selected in the last two windows.

Oracle AppWizard for Microsoft Visual C++ automatically creates a simple join (also called an equi-join) between two tables, or views, based on a Primary Key and a Foreign Key.

Such joins are used in the WHERE clause of a SELECT statement to avoid a Cartesian product, which combines every row in one table with every row in an other table. For example, a 90-row table combined with a 100-row table would produce a 9000-row result.

If you do not want to use the default join created by Oracle AppWizard for Microsoft Visual C++ (shown in the previous illustration), you can delete it and create a new join. Alternatively, you can also do this by modifying the WHERE clause of a query statement in the source file generated by Oracle AppWizard.

If you want to create more than one join, choose one column from the master table and one column from the detail table to create each additional join clause.

To accept the default join in the Master/Detail Table Join window:

1. Click Next.

To delete the default join:

1. Highlight the default join displayed in the Master and Detail Table Joins list in the Master/Detail Table Join window.

2. Click the Delete Join button.

   Oracle AppWizard for Microsoft Visual C++ deletes the join.

To create a new join:

1. Select one column from the master column list.

2. Select one column from the detail column list.

   The join appears in the Master and Detail Table Joins list with the following syntax:

   Master - SCHEMA.TABLE_NAME.COLUMN_NAME [DATA_TYPE] joins Detail - 
   SCHEMA.TABLE_NAME.COLUMN_NAME [DATA_TYPE] 
   

3. If you want to create multiple joins, repeat Steps 1 and 2.

   If

4. Click Next. Oracle AppWizard asks you whether or not you would like to build another form.

5. If you want to build another form, click Yes, and Oracle AppWizard for Microsoft Visual C++ returns you to the Form Type window.

6. If you do not want to build another form, click No.

Specifying the Application Type and User Language

When you are finished building forms and click Next, you are ready to specify the application type and the user language.

Note: If you are using Microsoft VC++ 6.0, there is an additional option for Document/View architecture support. See "Microsoft Visual C++ 6.0 Limitations".

To complete the Application Type window:

1. Indicate the type of application you are creating by clicking the appropriate option:
   • Single document

   • Multiple documents

   • Dialog-based

     Note: Dialog-based applications are not supported in the current release.

2. Select the language appropriate for your application or accept the default language in the list box.

3. Click Next to proceed to the standard MFC windows.

   
   

Completing the Remaining MFC Windows

Complete the remaining standard MFC windows as appropriate until you reach the window illustrated below. For more information about MFC windows, refer to your MSVC++ documentation.

Viewing the Application Classes

In the Class Information window, Oracle AppWizard for Microsoft Visual C++ displays the classes it will create for your application, including their names, header files, base classes, and the implementation file.

To complete the Class Information window:

1. Review the list for completeness and accuracy.

2. If you are not satisfied with the listed classes, click Back to go to the appropriate previous dialog box to make changes.

3. Depending on which class you have selected, you may change the class name, header file name, and implementation file name. If you rename these files, the first character must be a letter. The rest of the name must be alphanumeric.

4. When you are satisfied with the result, click Finish.

   The New Project Information window appears.

Viewing the Specifications for the New Application

The New Project Information window displays the specifications for the new skeleton application you are creating.

1. If the specifications are correct, click OK.

   Oracle AppWizard for Microsoft Visual C++ creates the files for your master-detail application.

2. If the specifications are not correct, click Cancel.

   
   

Building the Executable

After Oracle AppWizard generates the application, you can build an executable.

Note: You may want to check the project settings to see if they are correct for your configuration. Choose Settings from the Project menu to view the project settings.

To build the executable:

1. Choose Build <executable name> from the Build menu.
   Oracle AppWizard compiles and links your project.

Running the Executable

You are now ready to execute your application.

Note: By default, the active project configuration is the debug version. To change the active project configuration, choose Set Active Configuration from the Build menu.

To run the executable:

1. Choose Execute <executable name> from the Build menu.

   The Connect to Oracle dialog box appears.

2. Enter your User Name and Password.

   Note: The user name must be a database user who has privileges for accessing the tables in this application.

3. If connecting to a remote database, type its alias into the Database Alias text box.

   
   

   Note: If you click Cancel, an empty form appears. This is in accordance with Microsoft ODBC application behavior. You can close this empty form.

   After your application connects to the database successfully, the form you generated appears showing data retrieved from the database. The following illustration is a sample of what your form can look like, although the appearance of your actual form and data varies based on the database information you select.

   
   

   By design, no toolbar for inserting, updating, and deleting records is available. This is because the master table is read-only. If you have a single detail table, you can edit the fields by making a change and clicking on a different row to commit the change.