Skip Headers

Pro*C/C++ Getting Started
Release 9.2 for Windows

Part Number A96111-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

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

This chapter contains these topics:

2.1 Using the Graphical User Interface

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

2.2 Starting Pro*C/C++ Graphical Interface

To start the graphical user interface, choose Start Programs > Oracle - HOME_NAME Application Development > Pro C-C++. Figure 2-1 shows the four elements of the Pro*C/C++ precompile environment.

Figure 2-1 Pro*C/C++ Precompile Environment Elements

Description of appwin1.gif is in surrounding text

2.2.1 Title Bar

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

2.2.2 Menu Bar

The menu bar contains the following menus. Table 2-1 lists and describes the menus.

Table 2-1 Menu Bar 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.

2.2.3 Toolbar

The Toolbar enables you to execute commands by choosing a button. Figure 2-2 shows the Toolbar buttons.

Figure 2-2 Toolbar Buttons

Description of toolbar.gif is in surrounding text

Table 2-2 describes the Toolbar buttons in order, from left to right.

Table 2-2 Toolbar Buttons

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

2.2.4 Information Pane

Figure 2-3 shows the four elements of the information pane.

Figure 2-3 Information Pane Elements

Description of appwin2.gif is in surrounding text

Table 2-3 lists and describes the Information Pane elements.

Table 2-3 Information Pane 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 after the precompile process is complete.

  • A green check indicates that the file precompiled successfully.

  • A yellow check indicates that the file precompiled successfully, but there are one or more warnings.

  • A red X indicates that the file did not precompile successfully.

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.

2.2.5 Status Bar

The status bar at the bottom of the window 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.

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

This section describes the steps involved in creating and precompiling a Pro*C/C++ project. After starting the Pro*C/C++ application, perform the following steps:

2.3.1 Opening 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 File > New Project.

  • To open an existing project, choose File > Open Project.


    Note:

    A project created by a prior release cannot be opened by Oracle9i. It results in an Unexpected File Format error. You must re-create the project.

2.3.2 Setting the Default Extension of Output Files

Use the Preferences menu to determine the default extension of the output files. Figure 2-4 shows the Preferences menu.

Figure 2-4 Preferences Menu

Description of prefs.gif is in surrounding text

This setting only affects input files that you add later. An existing output filename will not change. However, you can change an existing output filename 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 filename for the file selected. After you select or enter a filename, it appears in the Output File area of the information pane.

2.3.3 Changing the Name of an Existing Input or Output File

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

  1. Double-click the filename in the Input File or Output File area of the information pane. The Input File or Output File dialog box appears.

Description of output.gif is in surrounding text
  1. Replace the old filename with the new filename.

  2. Choose Open.

2.3.4 Adding Files to the Project

To add files to the project:

  1. Choose Edit > Add. The Input File dialog box appears.

Description of input.gif is in surrounding text
  1. Select one or more .pc files. Use the Ctrl key and the mouse to select files that are not adjacent.

  2. Choose Open. The selected files appear in the information pane.

2.3.5 Deleting Files from the Project

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 Edit > Delete.

  3. Choose Yes.

2.3.6 Setting the Precompiler Options

The Precompiler options 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. Select one or more files in the Input File list.

  2. Choose Edit > Options. The Options dialog box appears.

Description of options.gif is in surrounding text

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. For additional information on options, see "Precompiler Options".

  1. To change the format of the output list file that the precompiler writes to disk, choose the Listing/Errors button. The Listing/Errors dialog box appears.

Description of listerr.gif is in surrounding text

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, choose OK.

2.3.7 Specifying Database Connection Information

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 File > Connect. The Connect dialog box appears.

Description of connect.gif is in surrounding text
  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 checking with SQLCHECK.

  2. The Connect dialog box appears automatically at precompile time if you have not previously responded. Enter the username, the password, and the network service name (database alias). The network service name is 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. Choose OK.

2.3.8 Precompiling a Pro*C/C++ Project

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

To precompile:

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

  2. Choose File > Precompile.

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

  3. Choose OK.


    Note:

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

2.3.9 Checking 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.

2.3.10 Fixing Errors

If you see a yellow check or a red X, double-click the icon in status bar. The Precompilation Status dialog box appears. This dialog box lists warning messages or reasons why the precompilation failed. For example:

Figure 2-5 Precompilation Status

Description of error.gif is in surrounding text

Switch to your development environment to fix the problem(s). After you correct the errors, 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.


2.3.11 Exiting Pro*C/C++

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


Caution:

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.

2.4 Using Pro*C/C++ at the Command Prompt

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

C:\> proc iname=filename.pc

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

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

2.5 Header Files

The ORACLE_BASE\ORACLE_HOME\precomp\public directory contains the Pro*C/C++ header files. Table 2-4 lists and describes the header files.


See Also:

Pro*C/C++ Programmer's Guide for more information about oraca.h, sqlca.h, and sqlda.h.

Table 2-4 Header Files

Header Files 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 Oracle9i 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.
oraca.h Contains the Oracle Communications Area (ORACA), which helps you to diagnose runtime errors and to monitor your program's use of various Oracle9i 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.

2.6 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 orasql9.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.

2.7 Multithreaded Applications

Build multithreaded applications if you are planning to perform concurrent database operations.

Windows NT, Windows 2000, and Windows 98 schedule and allocate threads belonging to processes. A thread is a path of a program's execution. It consists of a kernel stack, the state of the CPU registers, a thread environment block, and a users stack. Each thread shares the resources of a process. Multithreaded applications use the resources of a process to coordinate the activities of individual threads.

When building a multithreaded application, make sure that your C/C++ code is reentrant. This means that access to static or global data must be restricted to one thread at a time. If you mix multithreaded and non-reentrant functions, one thread can modify information that is required by another thread.

The Pro*C/C++ precompiler automatically creates variables on the local stack of the thread. This ensures that each thread using the Pro*C/C++ function has access to a unique set of variables and is reentrant.


See Also:

Pro*C/C++ Programmer's Guide for additional information on how to write multithreaded applications with Pro*C/C++

2.8 Precompiler Options

This section highlights issues related to Pro*C/C++ for Windows platforms.


See Also:

"Precompiler Options" of Pro*C/C++ Programmer's Guide

2.8.1 Configuration File

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

For this release, the system configuration file is called pcscfg.cfg. This file is located in the ORACLE_BASE\ORACLE_HOME\precomp\admin directory.

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

2.8.3 DBMS

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

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

2.8.5 PARSE

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

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

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

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.

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

Table 2-5 Oracle XA Library Components and Locations

Component Location
oraxa9.lib ORACLE_BASE\ORACLE_HOME\rdbms\xa
xa.h ORACLE_BASE\ORACLE_HOME\rdbms\demo

2.9.1 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
    oraxa9.lib ORACLE_BASE\ORACLE_HOME\rdbms\xa
    oci.lib ORACLE_BASE\ORACLE_HOME\oci\lib\msvc
    orasql9.lib ORACLE_BASE\ORACLE_HOME\precomp\lib\msvc

  1. Run filename.exe.

2.9.2 XA Dynamic Registration

Oracle 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 Oracle 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:

2.9.2.1 Adding an Environmental Variable for the Current Session

Adding an environmental variable at the command prompt affects only the current 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 command prompt:

    C:\> set ORA_XA_REG_DLL = vendor.dll
    
    

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

2.9.2.2 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 command prompt:

    C:\> regedt32
    
    

    The Registry Editor window appears.

  3. Go to HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\HOMEID.

  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. Choose 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. Choose OK.

    The Registry Editor adds the parameter.

  10. Choose Exit from the Registry menu.

    The registry exits.

2.9.3 XA and TP Monitor Information

Refer to the following for more information about XA and TP monitors: