2
Using Pro*C/C++

This chapter explains how to create and precompile a project. It also describes the Pro*C/C++ graphical user interface, from which you execute commands with Windows menus and icons or with keyboard equivalents, and using Pro*C/C++ at the command line.

Specific topics discussed are:

• Oracle Directory Structure
• Using the Graphical User Interface
• Creating and Precompiling a Pro*C/C++ Project
• Using Pro*C/C++ at the Command Line
• Header Files
• Using the Precompiler Options

Oracle Directory Structure

Installing Oracle software creates a directory structure on your hard drive for your Oracle products. A main directory--the Oracle home directory--contains the Oracle subdirectories and files that are necessary to run Pro*C/C++.

The subdirectories in ORACLE_HOME contain the Pro*C/C++ executable files and library files.

In the following table, the letters nn represent the version of the product installed. For example, if you previously installed Pro*C/C++ version 2.2, you have a \PRO22 subdirectory under ORACLE_HOME. If you now install Pro*C/C++ version 8.0, Oracle Installer adds a \PRO80 subdirectory.

Directory Name	Contents
\RDBMSnn	Oracle8 server message, resource, README, and database files.
\BIN	Executable programs, batch files, and dynamic link libraries (DLLs).
\PROnn	Subdirectories that contain files and subdirectories for Pro*C/C++.
\ORAINST	Oracle Installer utilities and other files.
\PLSQLnn	Message files, SQL scripts, and demonstration files for PL/SQL.
\DBS	Files for Toolkit II and message files for products created for Oracle Installer.
\OCInn	Executable programs and files for the Oracle Call Interface.

Based on the supported products that you install, Oracle Installer also creates the appropriate product subdirectory. When you install Pro*C/C++ version 8.0, Oracle Installer creates the \PRO80 subdirectory, which contains the following subdirectories:

Directory Name	Contents
\C	Contains the INCLUDE and SAMPLES subdirectories.
\INCLUDE	Contains header files for Pro*C/C++.
\SAMPLES	Contains one subdirectory for each sample program.
\LIB	Contains the BORLAND and MSVC subdirectories.
\BORLAND	Contains Pro*C/C++ libraries that are compatible with Borland C++ 5.0.
\MSVC	Contains Pro*C/C++ libraries that are compatible with Microsoft Visual C++ 5.0.

The Pro*C/C++ installation procedure copies a set of 32-bit sample programs and their corresponding make files to the ORACLE_HOME\PRO80\C\SAMPLES directory. Samples can be found in their corresponding subdirectories. Oracle recommends that you build and run these sample programs to verify that Pro*C/C++ has been installed successfully and operates correctly.

Additional Information:  See "Building and Running Sample Programs" in Chapter 3.

Using the Graphical User Interface

Before you follow the instructions for creating and precompiling a Pro*C/C++ project, you may want to familiarize yourself with the basic commands, dialog boxes, menus, and buttons of the Pro*C/C++ graphical user interface.

To start the graphical user interface, do one of the following:

• Choose Start > Programs > Oracle for Windows NT - [HOME_NAME] (or Oracle for Windows 95/98 - [HOME_NAME]) > Oracle Pro C_C++ 8.0.
• Enter procui80.exe at the MS-DOS command prompt.

The Pro*C/C++ precompile environment contains five elements:

 

Title Bar

Displays the name of the Pro*C/C++ project. If you have not assigned a name to the current project, the word "Untitled" appears instead.

Menu Bar

Contains the following menus:

Menu	Description
File	Contains commands to create a project, open an existing project, save a project under the same name or under a different name, specify a connect string to an Oracle database, precompile a project, or exit the application.
Edit	Contains commands to add files to a project, delete files from a project, and change options for the selected file(s).
Preferences	Contains commands to choose the manner in which a name is assigned to the output files.
Help	Contains the About Pro*C/C++ command, which displays the version number of the application and copyright information.

Toolbar

Enables you to execute commands by clicking a button:

Button	Description
New	Create a new project file.
Open	Open an existing project file.
Save	Save the active project file to disk.
Add	Add files to the precompile list.
Delete	Delete files from the precompile list.
Options	Display or change precompile options.
Precompile	Precompile the selected file(s).

Information Pane

Consists of four elements:

Element	Description
Precompilation Status Bar	Indicates whether the precompilation for a file was successful or unsuccessful.
Input File	Shows the files of a Pro*C/C++ project to be precompiled.
Output File	Shows the output files of a Pro*C/C++ project after precompilation.
Options	Displays precompile options that are different from the default options.

Look for one of the three status icons in the precompilation status bar once the precompile process is complete.

 

Double clicking a status icon opens the Precompilation Status dialog box. This dialog box provides detailed information on the reason for a warning or failure.

Status Bar

Displays information about the progress of a precompilation. The status bar also identifies the purpose of a toolbar button or menu command when you place the mouse pointer over the toolbar button or menu command.

Creating and Precompiling a Pro*C/C++ Project

This section describes the steps involved in creating and precompiling a Pro*C/C++ project.

First, start the Pro*C/C++ application by doing one of the following:

• Choose Start > Programs > Oracle for Windows NT - [HOME_NAME] (or Oracle for Windows 95/98 - [HOME_NAME]) > Oracle Pro C_C++ 8.0.
• Enter procui80.exe at the MS-DOS command prompt.

Then, perform the following steps:

• Step 1: Open a Project
• Step 2: Set the Default Output File Name (Optional)
• Step 3: Add Files to the Project
• Step 4: Delete Files from the Project (Optional)
• Step 5: Set the Precompile Options (Optional)
• Step 6: Specify Database Connection Information (Optional)
• Step 7: Precompile
• Step 8: Check the Results
• Step 9: Fix Any Errors

The remainder of this section describes each of these steps in detail.

Step 1: Open a Project

Pro*C/C++ opens only one project at a time. A project consists of one or more precompilable files. Project files have an extension of .PRE.

• To create a new project, choose New Project from the File menu.
• To open an existing project, choose Open Project from the File menu.

Step 2: Set the Default Output File Name (Optional)

Use the Preferences menu to choose the manner in which a name is assigned to the output files.

 

This setting only affects input files that you add later. An existing output file name will not change. However, you can change an existing output file name by double-clicking the output file and entering a new name.

• If you select Default Output C File Name, the default extension of the output files is .C.
• If you select Default Output C++ File Name, the default extension of the output files is .CPP.
• If you deselect both Default Output C File Name and Default Output C++ File Name, the Output File dialog box appears when you add an output file.

Enter an output file name for the file selected. Once you select or enter a file name, it appears in the Output File area of the information pane.

To change the name of an existing input or output file:

1. Double-click the file name in the Input File or Output File area of the information pane.

The Input File or Output File dialog box appears.

1. Replace the old file name with the new file name.
2. Click Open.

Step 3: Add Files to the Project

A Pro*C/C++ project consists of one or more precompilable files.

To add files to the project:

1. Choose Add from the Edit menu.

The Input File dialog box appears.

1. Select one or more file names.
2. Click Open.

The selected file appears in the information pane.

Step 4: Delete Files from the Project (Optional)

If you need to, you can easily delete one or more files from the project.

To delete files from the project:

1. Highlight the file(s) in the information pane.
2. Choose Delete from the Edit menu.
3. Click Yes.

Step 5: Set the Precompile Options (optional)

Many useful options are available. They enable you to control how resources are used, how errors are reported, how input and output are formatted, and how cursors are managed.

To set the precompile options:

1. Highlight one or more files in the Input File list.

1. Choose Options from the Edit menu.

The Options dialog box appears.

1. Default options are in effect for all newly added files. When you change an option's default setting, a description of the change appears in the Option String edit field (at the bottom of the Options dialog box) and in the Options area of the information pane.
2. To change the format of the output list file that the precompiler writes to disk, click the Listing / Errors button.

The Listing/Errors dialog box appears.

The settings include the type of error information generated and the name of the list file.

1. After you set the options in the Options dialog box, click OK.

 

Additional Information:  See Chapter 9 in the Pro*C/C++ Precompiler Programmer's Guide for a description of the precompiler options. In addition, click the Help button in the Options dialog box for a condensed version of the information in Chapter 9.  See "Using the Precompiler Options", later in this chapter, for issues that are related to Pro*C/C++ for Windows NT and Windows 95/98.

   

Step 6: Specify Database Connection Information (Optional)

If you selected semantics or full for the SQL Check option in the Options dialog box, you may need to specify database connection information to the Oracle database. You do not need to connect to the Oracle database if every table referenced in a data manipulation statement or PL/SQL block is defined in a DECLARE TABLE statement.

To specify database connection information:

1. Choose Connect from the File menu.

The Connect dialog box appears.

1. Use this dialog box to specify database connection information prior to precompiling. No database connection is performed at this time. Only one set of database connection information can be specified for all files requiring semantic or full SQLCHECKing.
2. The Connect dialog box appears automatically at precompile time if you have not previously responded. Enter the user name, the password, and the connect string (not required for a local database).
3. If you want to save the connection information between Pro*C/C++ sessions, select the Save Connect String to Disk check box. If you do not select the check box, you must enter this information each time you precompile.
4. Click OK.

Step 7: Precompile

You can precompile any number of files in the Input File list.

To precompile:

1. Highlight one or more files in the Input File list. You can use the Ctrl button to highlight files that are not adjacent to each other (for example, the first and third files in a list).

1. Choose Precompile from the File menu.

When precompiling is completed, the message in the dialog box indicates "Precompiling Finished!", and the Cancel button changes to OK.

2. Click OK.

 

Note:  Although Cancel does not interrupt the precompile for a file already in process, it does halt the precompile chain for remaining files.

Step 8: Check the Results

Precompiling can result in success, success with warning(s), or failure. When precompiling is finished, check the Precompilation Status Bar.

• A green check indicates that the file compiled successfully.
• A yellow check indicates that the file compiled successfully, but there are one or more warnings.
• A red X indicates that the file did not compile successfully.

Step 9: Fix Any Errors

Double-click the yellow check or red X to display the Precompilation Status dialog box, which lists warning messages or reasons why the precompilation failed.

 

Switch to your development environment to fix the problem(s). After you correct the errors, precompile again.

To exit Pro*C/C++, choose Exit from the File menu. If your project changed in any way, you are prompted to save it.

Suggestion:  If you want to keep an original file, as well as a version of the file with your changes, choose the Save As command. The Save command overwrites the previous version.

Using Pro*C/C++ at the Command Line

If you perform most of your programming tasks at the command line, it is recommended that you run Pro*C/C++ at the command line.

To precompile an application with Pro*C/C++, enter the following command:

C:\>PROC INAME=filename.pc

where filename.pc is the name of the source file.

Pro*C/C++ generates filename.c, which can be compiled by your C compiler.

If the source file is not within your current working directory, include the file's full path after the INAME argument.

Header Files

The ORACLE_HOME\PRO80\C\INCLUDE directory contains the Pro*C/C++ header files.

Additional Information:  See the Pro*C/C++ Precompiler Programmer's Guide for more information about ORACA.H, SQLCA.H, and SQLDA.H.

ORACA.H

Consists of an extended set of diagnostic tools for runtime errors and status changes. ORACA handles Oracle communications. Note that using the ORACA adds to runtime overhead.

SQL2OCI.H

Consists of SQLLIB functions that enable the Oracle Call Interface (OCI) environment handle and OCI service context to be obtained in a Pro*C/C++ application.

SQLAPR.H

Consists of ANSI prototypes for externalized functions that can be used in conjunction with OCI.

SQLCA.H

Consists of the host language data structure. Oracle updates the SQLCA after every executable SQL statement (values are undefined after a declarative statement). By checking Oracle return codes stored in the SQLCA, your application can determine the outcome of a SQL statement.

SQLCPR.H

Provides platform-specific ANSI prototypes for SQLLIB functions that are generated by Pro*C/C++. By default, Pro*C/C++ does not support full-function prototyping of SQL programming calls. If you need this feature, include SQLCPR.H before any EXEC SQL statements in your application source file.

SQLDA.H

Consists of the host program data structure that contains descriptions of select-list items or input host variables. SQLDA files differ among host languages and operating systems.

SQLKPR.H

Consists of K&R prototypes for externalized functions that can be used in conjunction with OCI.

SQLPROTO.H

SQLPROTO.H was obsoleted in Pro*C/C++ release 8.0.3. Use SQLCPR.H instead of SQLPROTO.H. However, applications that were built using SQLPROTO.H can be created without modification: a dummy SQLPROTO.H file that includes SQLCPR.H has been provided in the ORACLE_HOME\PRO80\C\INCLUDE directory.

If You Receive a PCC-S-02014 Error...

If you receive a PCC-S-02014 error when precompiling, copy the batch files MOD_INCL.BAT and ADD_NEWL.BAT from the ORACLE_HOME\PRO80\C\INCLUDE directory to the directory that contains the problematic include file and run MOD_INCL.BAT.

Using the Precompiler Options

Chapter 9 of the Pro*C/C++ Precompiler Programmer's Guide describes the Pro*C/C++ options. This section highlights issues that are related to Pro*C/C++ for Windows NT and Windows 95/98.

CODE

The CODE option has a default setting of ANSI_C. Pro*C/C++ for other operating systems may have a default setting of KR_C.

DBMS

DBMS=V6_CHAR is not supported when using CHAR_MAP=VARCHAR2. Instead, use DBMS=V7.

INCLUDE

Use the Include Directories field of the Options dialog box to enter INCLUDE path directories. If you want to enter more than one path, separate each path with a semicolon, but do not insert a space after the semicolon. This causes a separate "includes=" string to appear in front of each directory.

For sample programs that precompile with PARSE=PARTIAL or PARSE=FULL, an include path of C:\PROGRAM FILES\DEVSTUDIO\VC\INCLUDE has been added. If Microsoft Visual C++ has been installed at a different location or if Borland C++ is used, modify the Include Directories field accordingly for the sample programs to precompile correctly.

PARSE

The PARSE option has a default setting of NONE. Pro*C/C++ for other operating systems may have a default setting of FULL.

VER

The VER option is a Windows-specific option.

It takes the first and second most significant digits of the version number of Pro*C/C++ you want to use. This option is an alternative to changing the PROC_DFLT value in the registry.

For a previously installed Pro*C/C++ 2.2 to precompile SAMPLE1.PC, for example, type the following:

PROC.EXE VER=22 SAMPLE1.PC

Note:  This option can only be used to execute previously installed Pro*C/C++ release 2.2.2.0.1 or later. Simply running proc.exe will execute the most recently installed version of Pro*C/C++.

PROC_DFLT

When Pro*C/C++ is installed, PROC_DFLT is set to PROC80 by default in the registry. If multiple versions of Pro*C/C++ are installed, simply resetting the value to a valid Pro*C/C++ version number will allow a different version to be the default when proc.exe is executed at the MS-DOS command prompt. For example, setting PROC_DFLT to PROC22 will make Pro*C/C++ 2.2 the default. This feature applies only to command line Pro*C/C++.

---