2
Using Pro*C/C++

This chapter provides an overview of how to use Pro*C/C++ release 8.1.5 for Windows NT and Windows 95/98.

Specific topics discussed are:

• Directory Structure
• Using the Graphical User Interface
• Using Pro*C/C++ at the Command Line
• Header Files
• Library Files
• Precompiler Options
• Using Pro*C/C++ with the Oracle XA Library

Directory Structure

When you install Pro*C/C++ release 8.1.5, Oracle Universal Installer creates a directory called \PRECOMP in your ORACLE_BASE\ORACLE_HOME directory.

Note: The \PRECOMP directory can contain files for other products, such as Pro*COBOL.

The \PRECOMP directory contains the following directories:

Directory Name	Contents
\ADMIN	Configuration files
\DEMO	Sample programs
\PROC	for Pro*C/C++
\DOC	Readme files
\PROC	for Pro*C/C++
\GUI	GUI Help files
\Ifa	for IFA
\Proc	for Pro*C/C++
\LIB	Library files
\MSVC	for Pro*C/C++
\MESG	Message files
\PUBLIC	Header files
\HELP	Help files for Pro*C/C++
\PROC	for Pro*C/C++
\MISC	Miscellaneous files for Pro*C/C++
\PROC	for Pro*C/C++

Using the Graphical User Interface

This section describes how to use the Pro*C/C++ graphical user interface.

Specific topics discussed are:

• Starting the Graphical User Interface
• Interface Elements
• Creating a Pro*C/C++ Project
• Setting the Default File Extension of Output Files
• Adding Files to a Pro*C/C++ Project
• Deleting Files from a Pro*C/C++ Project
• Changing the Name of an Existing Input File or Output File
• Changing the Value of Precompiler Options
• Specifying Database Connection Information
• Precompiling a Pro*C/C++ Project
• Checking the Results

Starting the Graphical User Interface

To start the graphical user interface:

• Choose Start > Programs > Oracle - HOME_NAME > Application Development > Pro C_C++ 8.1.

Interface Elements

The Pro*C/C++ graphical user interface 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 new Pro*C/C++ project, open an existing Pro*C/C++ project, save the active Pro*C/C++ project under the same name or under a different name, specify a connect string to an Oracle database, precompile a Pro*C/C++ project, and exit the application
Edit	Contains commands to add files to a Pro*C/C++ project, delete files from a Pro*C/C++ project, and display or change precompiler options
Preferences	Contains commands to set the default file extension of 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 Pro*C/C++ project
Open	Open an existing Pro*C/C++ project
Save	Save the active Pro*C/C++ project under the same name
Add	Add files to a Pro*C/C++ project
Delete	Delete files from a Pro*C/C++ project
Options	Display or change precompiler options
Precompile	Precompile a Pro*C/C++ project

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 input files of a Pro*C/C++ project
Output File	Shows the output files of a Pro*C/C++ project
Options	Displays precompiler options that are different from the default options

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 a Pro*C/C++ Project

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

• To create a new project, choose New Project from the File menu.

 

 
 
 

Note: To open an existing project, choose Open Project from the File menu.

Setting the Default File Extension of Output Files

Use the Preferences menu to set the default file extension of output files:

• If you choose Default Output C File Name, the default file extension of output files is .C.
• If you choose Default Output C++ File Name, the default file extension of output files is .CPP.
• If you clear both Default Output C File Name and Default Output C++ File Name, the Output Filename dialog box appears when you add an input 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.




Note: Changing the default file extension does not change the file extension of existing output files.

Adding Files to a Pro*C/C++ Project

To add files to a Pro*C/C++ project:

1. Choose Add from the Edit menu.



The Input File dialog box appears:

2. Select one or more .PC files. Use the Ctrl key and your mouse to select files that are not adjacent.
3. Click Open.

The selected files appear in the information pane.

Deleting Files from a Pro*C/C++ Project

If you need to, you can easily delete one or more files from a Pro*C/C++ project.

To delete files from a Pro*C/C++ project:

1. Highlight one or more files in the information pane.
2. Choose Delete from the Edit menu.
3. Click Yes when prompted to confirm the deletion.

Changing the Name of an Existing Input File or Output File

To change the name of an existing input file 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:

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

Changing the Value of Precompiler Options

Precompiler options enable you to control such things as how resources are used, how errors are reported, how input and output are formatted, and how cursors are managed.

If you change the default value of a precompiler option, 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.

To change the value of precompiler options:

1. Highlight one or more files in the Input File area of the information pane.
2. Choose Options from the Edit menu.

The Options dialog box appears:

3. Change the value of one or more options.
4. To change the format of the output list file that the precompiler writes to disk, do the following:
1. Click Listing / Errors in the Options dialog box.

The Listing/Errors dialog box appears:


1. Change the value of one or more options.
2. Click OK.
5. Click OK in the Options dialog box.



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

Specifying Database Connection Information

If you selected semantics or full from the SQL Check drop-down list box in the Options dialog box, you may need to specify database connection information for 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:

2. Use this dialog box to specify the 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.
3. The Connect dialog box appears automatically at precompile time if you have not specified the database connection information. Enter the user name, the password, and (if connecting to a remote database) the connect string.
4. If you want to save the database 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.
5. Click OK.

Precompiling a Pro*C/C++ Project

You can precompile any number of files in the Input File area of the information pane.

To precompile a Pro*C/C++ project:

1. Highlight one or more files in the Input File area of the information pane. You can use the Ctrl key and your mouse to highlight files that are not adjacent to each other (for example, the first and third files).
2. Choose Precompile from the File menu.

A message box appears during the precompilation process. You can click Cancel to stop the precompilation.


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

When precompiling is completed, the message box indicates "Precompiling Finished!".

3. Click OK.

Checking the Results

Look for one of the following icons in the Precompilation Status Bar once the precompile process is complete:

If you see a yellow check or a red X, double-click the icon. The Precompilation Status dialog box appears. This dialog box provides detailed information on the reason for a yellow check or a red X. For example:

Switch to your development environment to fix any problems. Then, precompile again.

Note: If you receive a PCC-S-02014 error (syntax error at line num, column colnam, file name), do the following: Copy the batch files MOD_INCL.BAT and ADD_NEWL.BAT from the  ORACLE_BASE\ORACLE_HOME\PRECOMP\MISC\PROC directory to the directory that contains the problematic INCLUDE file. Run MOD_INCL.BAT.

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

To precompile a file at the command line, enter the following command:

C:\> PROC INAME=FILENAME.PC
where FILENAME.PC is the name of the file.

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

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

Header Files

The ORACLE_BASE\ORACLE_HOME\PRECOMP\PUBLIC 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.

Header File	Description
ORACA.H	Contains the Oracle Communications Area (ORACA), which helps you to diagnose runtime errors and to monitor your program's use of various Oracle8 resources.
SQL2OCI.H	Contains 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	Contains ANSI prototypes for externalized functions that can be used in conjunction with OCI.
SQLCA.H	Contains the SQL Communications Area (SQLCA), which helps you to diagnose runtime errors. The SQLCA is updated after every executable SQL statement.
SQLCPR.H	Contains 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	Contains the SQL Descriptor Area (SQLDA), which is a data structure required for programs that use dynamic SQL Method 4.
SQLKPR.H	Contains K&R prototypes for externalized functions that can be used in conjunction with OCI.
SQLPROTO.H	The SQLPROTO.H header file 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_BASE\ORACLE_HOME\PRECOMP\PUBLIC directory.

Library Files

The ORACLE_BASE\ORACLE_HOME\PRECOMP\LIB\MSVC directory contains the library file that you use when linking Pro*C/C++ applications.

The library file is called ORASQL8.LIB.

Pro*C/C++ application program interface (API) calls are implemented in DLL files provided with your Pro*C/C++ software. To use the DLLs, you must link your application with the import libraries (.LIB files) that correspond to the Pro*C/C++ DLLs. Also, you must ensure that the DLL files are installed on the computer that is running your Pro*C/C++ application.

Microsoft provides you with three libraries: LIBC.LIB, LIBCMT.LIB, and MSVCRT.LIB. The Oracle DLLs use the MSVCRT.LIB runtime library. You must link with MSVCRT.LIB rather than the other two Microsoft libraries.

Precompiler Options

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

Configuration File

A configuration file is a text file that contains precompiler options.

For release 8.1.5, the system configuration file is called PCSCFG.CFG. This file is located in the ORACLE_BASE\ORACLE_HOME\PRECOMP\ADMIN directory.

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

For the Pro*C/C++ graphical user interface, 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 "INCLUDE=" 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 in a different location, 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.

Using Pro*C/C++ with the Oracle XA Library

The XA Application Program Interface (API) is typically used to enable an Oracle8 database to interact with a transaction processing (TP) monitor, such as:

• BEA Tuxedo
• IBM Transarc Encina
• IBM CICS

The Oracle XA Library is automatically installed as part of Oracle8 Enterprise Edition. The following components are created in your Oracle home directory:

Component	Location
ORAXA8.DLL	ORACLE_BASE\ORACLE_HOME\BIN
ORAXA8.LIB	ORACLE_BASE\ORACLE_HOME\RDBMS\XA
XA.H	ORACLE_BASE\ORACLE_HOME\RDBMS\XA

You can also use TP monitor statements in your client programs. The use of the XA API is also supported from both Pro*C/C++ and OCI. In either case, ORAXA8.DLL must be contained in the execution path of the calling program.

Compiling and Linking a Pro*C/C++ Program with XA

To compile and link a Pro*C/C++ program with XA:

1. Precompile FILENAME.PC using Pro*C/C++ to generate FILENAME.C.
2. Compile FILENAME.C, making sure to include ORACLE_BASE\ORACLE_HOME\RDBMS\XA in your path.
3. Link FILENAME.OBJ with the following libraries:




Library	Location
ORAXA8.LIB	ORACLE_BASE\ORACLE_HOME\RDBMS\XA
OCI.LIB	ORACLE_BASE\ORACLE_HOME\OCI\LIB\MSVC
ORASQL8.LIB	ORACLE_BASE\ORACLE_HOME\PRECOMP\LIB\MSVC

4. Run FILENAME.EXE. (The program makes the function calls to ORAXA8.DLL.)

 

XA Dynamic Registration

The Oracle8 database supports the use of XA dynamic registration. XA dynamic registration improves the performance of applications that interface with XA-compliant TP monitors.

For TP monitors to use XA dynamic registration with an Oracle8 database on Windows NT, you must add either an environmental variable or a registry variable to the Windows NT computer on which your TP monitor is running. See either of the following sections for instructions:

• Adding an Environmental Variable for the Current Session
• Adding a Registry Variable for All Sessions

After adding this variable, see Oracle8 Application Developer's Guide - Fundamentals for information on using XA dynamic registration.

Adding an Environmental Variable for the Current Session

Adding an environmental variable at the MS-DOS command prompt affects only the current MS-DOS session.

To add an environmental variable for the current session:

1. Go to the computer where your TP monitor is installed.
2. Enter the following at the MS-DOS command prompt:

C:\> SET ORA_XA_REG_DLL = VENDOR.DLL

where VENDOR.DLL is the TP monitor DLL provided by your vendor.

Adding a Registry Variable for All Sessions

Adding a registry variable affects all sessions on your Windows NT computer. This is useful for computers where only one TP monitor is running.

To add a registry variable for all sessions:

1. Go to the computer where your TP monitor is installed.
2. Enter the following at the MS-DOS command prompt:
C:\> REGEDIT
The Registry Editor window appears.
3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE.
4. Choose the Add Value option in the Edit menu.

The Add Value dialog box appears.
5. Enter ORA_XA_REG_DLL in the Value Name field.
6. Select REG_EXPAND_SZ from the Data Type drop-down list box.
7. Click OK.

The String Editor dialog box appears.
8. Enter VENDOR.DLL in the String field, where VENDOR.DLL is the TP monitor DLL provided by your vendor.
9. Click OK.

The Registry Editor adds the parameter.
10. Choose Exit from the Registry menu.

The registry exits.

XA and TP Monitor Information

See the following general information about XA and TP monitors:

• Distributed TP: The XA Specification published by X/Open (now part of OpenGroup). Visit:

http://www.rdg.opengroup.org/public/pubs/catalog
• Transaction Processing XPG4 X/Open CAE Specification XO/CAE/91/300 or C193 2/92
• Your specific TP monitor documentation

For more information about the Oracle XA Library, see Oracle8 Application Developer's Guide - Fundamentals.