Oracle Pro*C/C++(TM) Getting Started for Windows Platforms Release 8.0 A53634-01

Library Product Contents Index

3
Building Pro*C/C++ Applications

This chapter describes how to build Oracle database applications with Pro*C/C++ using the sample programs included with this release. It includes:

• Building and Running Sample Programs
• Building Multi-Threaded Programs

Building and Running Sample Programs

When you install Pro*C/C++, the installation procedure copies a set of sample programs and their corresponding files to the ORACLE_HOME\PRO80\C\SAMPLES subdirectory. Oracle recommends that you build and run these sample programs to verify that Pro*C/C++ is installed successfully and is operating correctly. You can delete the programs after you use them.

.DSP and .IDE Files

.DSP and .IDE files help you build application programs. They guide and control the steps necessary to precompile, compile, and link sample programs. Sample .DSP files in this release, are created with Microsoft Visual C++ Version 5.0, while sample .IDE files in this release are created with Borland C++ Version 5.0.

Sample Pro*C/C++ Programs

When built, the sample programs that Oracle provides in Pro*C/C++ produce .EXE executables. For some sample programs, you must run the SQL script(s) in the sample directories before you precompile and run the sample program. The SQL scripts set up the correct tables and data so that the sample programs run successfully.

Also, some samples require OTT (Object Type Translator) to be executed before precompilation. OTT is used to create header files with C-struct representations of Abstract Data Types (ADTs) which have been created and stored in an Oracle8 database. The sample programs are described below.

COLDEMO1.PC

Fetches census information for certain California County or Counties. This sample demonstrates a number of ways to navigate through collection-typed database columns.

CPPDEMO1.PC

Prompts the user for an employee number, then queries the EMP table for the employee's name, salary, and commission. It uses indicator variables (in an indicator struct) to determine if the commission is NULL.

CPPDEMO2.PC

Retrieves the names of all employees in a given department from the EMP table (Dynamic SQL Method 3).

CPPDEMO3.PC

An example of C++ Inheritance, this program finds all salespeople and prints their names and their total earnings (including commissions).

CV_DEMO.PC

Fetches from the EMP table, using a cursor variable. The cursor is opened in the stored PL/SQL procedure open_cur, in the EMP_DEMO_PKG package.

LOBDEMO.PC

Fetches and adds crime records to the database based on the person's social security number. This sample demonstrates the mechanisms for accessing and storing LOBs (Large OBjects) to tables and manipulating LOBs through the stored procedures available via the dbms_lob package.

MLTTHRD1.PC

This program shows how to use threading in conjunction with precompilers. The program creates as many sessions as there are threads.

Each thread executes zero or more transactions, that are specified in a transient structure called, "records". The program requires a table,

"ACCOUNTS" to be in the schema scott/tiger. The description of ACCOUNTS is:

SQL> desc accounts

For proper execution, the table should be filled with the accounts 10001 to 10008.

OBJDEMO1.PC

Demonstrates the use of objects. This sample manipulates the object types "person" and "address".

ORACA.PC

Demonstrates how to use the ORACA to determine various performance parameters at runtime.

PLSSAM.PC

Demonstrates the use of embedded PL/SQL blocks in a Pro*C/C++ application. This program prompts you for an employee name that already resides in a database. It then executes a PL/SQL block, which returns the results of four SELECT statements.

For example, if you enter the name SMITH, the following information is displayed:

SMITH's job is:  CLERK

Hired on:  17-DEC-80

0 people have served longer

Salary is: 800

15 people have a higher salary

Department number is: 20

6 people in the department

If you enter a name that does not reside in the database, the following message is displayed, where ename is the name you entered:

ename does not work for the company

SAMPLE.PC

Adds new employee records to the personnel database and checks database integrity. The employee numbers in the database are automatically selected using the current maximum employee number +10. The program asks you to enter the following data:

• employee name
• employee job
• employee salary
• employee department

If the record has been inserted successfully, the following is printed:

ename added to department dname as employee # nnnnnn

where ename is the employee name you entered, dname is the department name, and nnnnn is the automatically generated employee number.

SAMPLE1.PC

Logs on to an Oracle database, prompts the user for an employee number, queries the database for the employee's name, salary, and commission, and displays the result. It continues until you enter a 0 (zero) as the employee number.

SAMPLE2.PC

Logs on to an Oracle database, declares and opens a cursor, fetches the names, salaries, and commissions of all salespeople, displays the results, then closes the cursor.

SAMPLE3.PC

Logs on to an Oracle database, declares and opens a cursor, fetches in batches using arrays, and prints the results using the function print_rows().

SAMPLE4.PC

Features an in-depth example of Datatype Equivalencing. After logging in, it creates a new table in the SCOTT account IMAGE, and simulates placement of bitmap images of employees. Later, when an employee number is entered, the associated bitmap is selected from the IMAGE table, and "pseudo-displayed" on the screen.

SAMPLE5.PC

Prompts the user for an account number and a debit amount. It verifies that the account number is valid and that there are sufficient funds to cover the withdrawal before it debits the account.

SAMPLE6.PC

Creates a table, inserts a row, commits the insert, and drops the table (Dynamic SQL Method 1).

SAMPLE7.PC

Inserts two rows into the EMP table and deletes them (Dynamic SQL Method 2).

SAMPLE8.PC

Retrieves the names of all employees in a given department from the EMP table (Dynamic SQL Method 3).

SAMPLE9.PC

Connects to an Oracle database using the SCOTT/TIGER account. The program declares several host arrays and calls a PL/SQL stored procedure (GET_EMPLOYEES in the CALLDEMO package) that fills the table OUT parameters. The PL/SQL procedure returns up to ASIZE values. SAMPLE9 keeps calling GET_EMPLOYEES, getting ASIZE arrays each time, and printing the values, until all rows have been retrieved. GET_EMPLOYEES sets the done_flag to indicate no more data.

SAMPLE10.PC

Connects to an Oracle database using your username and password and prompts for an SQL statement. You can enter any legal SQL statement, but you must use regular SQL syntax, not embedded SQL. Your statement is processed. If it is a query, the rows fetched are displayed (Dynamic SQL Method 4).

SQLVCP.PC

Demonstrates how you can use the sqlvcp() function to determine the actual size of a VARCHAR struct. The size is then used as an offset to increment a pointer that steps through an array of VARCHARs.

This program also demonstrates how to use the sqlgls() function to get the text of the last SQL statement executed.

WINSAM.PC

This GUI version of the SAMPLE.PC program adds new employee records to the personnel database and checks database integrity. You can enter as many employee names as you want and perform the SQL commands by selecting the appropriate buttons in the Employee Record box.

Creating a Sample Program

Follow these steps to precompile, compile, and link a sample program:

1. Integrate Pro*C/C++ into the development environment. (See appendices A and B.)

2. Open a sample project file.

For example, open WINSAM.DSP for Microsoft Visual C++ or open WINSAM.IDE for Borland C++. Check the paths and filenames in the project file to make sure that they correspond to the configuration of your system. If they do not, change the paths and filenames accordingly. Your system may produce error messages if the paths to all components are not correct.

If Borland C++ is used, some samples require SQL scripts and OTT to be executed individually before precompilation.

3. For the samples that require SQL scripts to be executed, do the following at the command line:

  plus80 @<demo>.sql

where <demo> can be replaced by a name of any sample that has a SQL script. SQL scripts for samples can be found in its respective sample directory.

For the samples the require OTT to be executed, namely coldemo1 and objdemo1, do the following at the command line to produce .h and intype files:

ott int=<demo>.typ out=out.typ hfile=<demo>.h code=c user=scott/tiger

where <demo> is coldemo1 or objdemo1. When precompiling these two samples, be sure to set intype=out.typ, parse=full, and include directory to where <demo>.h is located.

4. Select Pro*C/C++ from the Tools menu.

5. The Pro*C/C++ Application window appears with the project file (for example, WINSAM.PRE) already loaded.

6. Select Run from the Toolbar to precompile the sample file.

7. Once the precompile process is successfully completed, go back to your development environment, and create the sample application by running the build process.

Running a Sample Program

To run a sample program (in this case, WINSAM) after building it, follow these steps:

1. From your development environment, run WINSAM.EXE.
2. Select Connect from the Oracle menu.
3. Enter SCOTT in the User ID box and TIGER in the Password box (or the connect string if connecting remotely). Choose OK.

A dialog box appears notifying you whether the connection is successful.

4. To enter employee data, select Employees from the Oracle menu.

An Employee Record dialog box appears. You can use SQL buttons such as SELECT, FETCH, or INSERT to manipulate the sample tables.

5. Choose Exit from the Employee Record dialog box. Then, choose Disconnect from the Oracle menu.
6. A dialog box notifies you whether the disconnect is successful.
7. Choose Exit to quit the program.

Note: All sample programs are written to be run on the local database. To connect to a remote database, use the LOCAL variable in the Windows NT or Windows 95 Registry.

Building the Demonstration Tables

To run the Pro*C/C++ sample programs, you must have a database account with the username SCOTT and the password TIGER and a database with the demonstration tables EMP and DEPT. This account is included in the seed database (named ORACLE) that is shipped with your Oracle server. If no such account exists on your database, install one before running the sample program.

Dynamic Link Libraries (DLLs)

The Pro*C/C++ 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 make sure that the DLL files are installed on the workstation that is running your Pro*C/C++ application.

Applications linked with DLLs provide the following benefits over static libraries:

• Multiple applications can share the same DLL module, conserving disk space and memory.
• Import libraries can load more than one DLL module.
• You can update DLL modules by overwriting the DLL files. When you do this, it is not necessary to relink applications that access the DLL module.

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.

Building Multi-Threaded Programs

Build multi-threaded applications if you are planning to perform concurrent database operations.

Windows NT and Windows 95 schedules and allocates 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. Multi-threaded applications use the resources of a process to coordinate the activities of individual threads.

Reentrant Functions

When building a multi-threaded 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 multi-threaded and non-reentrant functions, one thread may potentially modify information that is required by another thread.

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

Prev Next

Copyright © 1997 Oracle Corporation. All Rights Reserved.

Library Product Contents Index