Concurrent C and PRO*C Program Tutorial (Doc ID 113428.

1)

CONCURRENT C and PRO*C PROGRAM TUTORIAL

---------------------------------------

1. Introduction
------------

This article is a tutorial on writing C and Pro*C programs to work in

the context of Oracle Applications, Version 10.7, 11.0.x and 11i.
The intended audience consists of programmers working in the context
of the Oracle Applications with knowledge of the C programming
language, Unix operating system and "vi" text editor.

You will find that the article layout is broken down into the twelve
major areas, each identified by a number. The areas are listed below
in a table of contents and span general coding concepts, paradigms
in Oracle Applications and known issues linked to writing C and Pro*C
code. All code examples have been grouped together in Section 10 and
they are referred to in the article as program sample [10.1] et cetera.
Also, references are in Section 12 and they are referred to in the
article as reference [12.1] et cetera for Oracle documentation and
as reference [G.1] et cetera for general references to the C programming
language and "vi" text editor. For clarity, the English notational
style of placing commas and periods outside of the quotes is adopted
in this paper to avoid any syntatical confusion.

Table of Contents
-----------------

# Section Heading
-- ---------------
1 Introduction
2 Definition of Process
3 Creating Concurrent C Programs
4 Creating Concurrent Pro*C Programs
5 Compiling Objects
6 Archiving Subroutines into Product Libraries
7 File and Version Control Suggestions
8 Linking Objects (through "adrelink")
9 Registering Programs
10 Sample Code Repository
11 Known Issues
12 References

Before attempting to test this on your system, you should first

 verify that you have a working compiler that is accessible to you
and that you have installed Oracle Pro*C against the Oracle home
supporting your target instance. You can confirm whether the C
compiler is installed by writing a "Hello World" program, example
below, and executing a compilation with the syntax in the same
directory where your C program exists (e.g., reference [G.1]).

Example "Hello World" Program

-----------------------------

#include <stdio.h>

main()
{
printf("Hello World.\n");
}

Example Syntax for Compiling a C Program

----------------------------------------

cc -o hello hello.c

2. Definition of Process
---------------------

The process of developing C and Pro*C concurrent processing programs

is qualified in Chapter 9 of the Oracle Application Object Library
Reference Manual [12.2] and Chapter 19 of the Oracle Applications
Developer's Guide [12.6][12.11]. You will find that the references
cite two sample programs -- EXMAIN.c and EXPROG.c program samples.
The concept presented is that you develop subroutines that will
become part of an archive file stored in your customer product
top (e.g., $CUS_TOP/lib/libcus.a), if you follow the compilation
and linking examples provided in Appendix B of the Oracle
Applications Installation Manual [12.3][12.7]. You will then link
your main program module to the product top library and the Oracle
Application Object Libraries by using the "adrelink" tool, which
is consistent with the standard application code modules.

The process for compiling and linking your code modules is covered
in Appendix B of the Oracle Applications Installation Manual [12.6]
[12.11] and Oracle Applications Developer's Manual [12.11]. The
approach taken in the article is to follow this standard. Therefore,
there are two programs for each executable, a main program and a
subroutine program. The combination of the two program components
make an executable program when linked by using the "adrelink" tool.
Once the two are linked, you have an executable program in your
product top's executable directory - $CUS_TOP/bin Note.115016.1.
These executables can then be made accessible by registering them
within the standard Oracle Applications forms from either the System
Administration or Application Developer responsibilities, see
Section 9 below. The two executables for this article are:
 1. The first executable is a slightly modified form of the
EXMAIN.c and EXPROG.c programs and simply prints a set of
test lines to the log and report files. The subroutine
program [10.1] manages the printing of the file and the
main program [10.2] becomes the executable that calls
the library function, which is the compiled and archived
subroutine program [10.1], within the "libfnd.a" archive.

2. The second executable is a slightly modified form of the

EXMAIN.c and the "Unified Concurrent Program" example
found on pages 9-46,47 in the Oracle Application Object
Library Reference Manual [12.2]. This executable spawns
a concurrent program, which in this case is the first
executable in the article. The subroutine program [10.3]
manages the spawning of the concurrent program and the
main program [10.4] becomes the executable that calls
the library function, which is the compiled and archived
subroutine program [10.3], within the "libfnd.a" archive.
The spawning executable spawns the first executable
referenced in the article and basically demonstrates the
method for spawned C or Pro*C programming.

In a general "global demo" or production environment, you

may encounter some setup issues trying to compile the programs.
Section 11 below qualifies known issues that you may encounter.
If you encounter new problems that are not covered in this
article, please search metalink to determine if they have been
reported to Oracle Worldwide Support. If they have not been
reported, please email me the information so that I can update
the article (mmclaugh@us.oracle.com).

* NOTE
----
If the concept of a custom product top is unfamiliar please
check Chapter 2 of the Oracle Applications Installation Manual
[12.3] and [12.7] or Note.115016.1.

3. Creating Concurrent C Programs

------------------------------

Creating the concurrent C programs is very similar to writing

generalized C programs, except you have two header files that must
be included in your programs for Oracle Applications 10.7 based on
the Oracle Application Object Library Reference Manual [12.2].
The two header files are the "afpub.h" and "afcp.h" files, which
are found in the $FND_TOP/include directory. However, in Oracle
Applications 11.x and 11i, you must include six header files in
your program examples as qualified in Chapter 19 of the Oracle
Applications Developer's Guide [12.5][12.11]. The six header
files are the "afpub.h", "afcp.h", "afuxit.h", "afufld.h",
"fddutl.h" and "fdpopt.h" files, which are found in the
$FND_TOP/include directory. The header files are explained in
 Chapter 10 of the Oracle Application Object Library Reference
Manual [12-2] and Chapter 19 of the Oracle Applications
Developer's Guide [12-5.][12.11]. Standard C programming syntax
and knowledge of the C programming language is required [G.1][G.2]
[G.3], along with a working knowledge of Unix and "vi" editor [G.8].

4. Creating Concurrent Pro*C Programs

----------------------------------

Creating the concurrent Pro*C programs is very similar to writing

generalized C programs, except you have three header files that must
be included in your programs in Oracle Applications 10.7 and seven
header files that must be included in your programs in Oracle
Applications 11.x and 11i. The Oracle Applications specific header
files are covered in Section 3 above. The third or seventh header
file is the "sqlca.h" file and is referenced in the Programmer's
Guide to the Oracle Precompilers [12.5], the Programmer's Guide to
the Pro*C/C++ Precompiler [12.10] and Pro*C/C++ Precompiler,
Programmer's Guide, Volume 1 [12.14].
The "sqlca.h" file is required for writing embedded SQL commands.
Standard C programming syntax and knowledge of the C programming
language is required [G.1][G.2][G.3], along with a working knowledge
of Unix and "vi" editor [G.8].

5. Compiling Objects
-----------------

In the context of Oracle Applications, you must follow the instructions

below to guarantee correct behavior of your concurrent C or Pro*C
programs [12.3][12.7]. The "adrelink" tool, covered in Section 8,
eliminates confusion in finding the correct Oracle link environment,
which can cause linking failures.

In the example case, you should create a directory for source code
in your $FND_TOP directory. Oracle Applications standards would
name that the $FND_TOP/src directory. (NOTE: For the sake of a
simplified test case, we are using an existing library and part of
the standard directory tree; however, you should delete these after
completing your test. Please note the discussion in Section 7 if
you are unsure about directory structures within the context of
Oracle Applications.

Your environment for compiling custom code depends on the file

$FND_TOP/usrxit/devenv. If you change this file, you should
source it into your development environment (e.g., in Korn shell
you would source the environment file by the command ". ./devenv").

You compile your C or Pro*C programs into object modules using

the $FND_TOP/usrxit/Makefile. You then link your programs using
"adrelink" utility. As noted in Appendix B of the Oracle
Applications Installation Manual on page B-12 [12-3]for Oracle
Applications 10.7 and on page B-9 [12-7] for Oracle Applications
11.x, "We do not support both compiling and linking executables
 using a single makefile or utility."

You should compile your programs using the following syntax

from the source control directory where you store your programs.
For example, the programs found in this article can be compiled
as follows for the code modules found in Section 10 below. The
commands must be executed as the "applmgr" user.

Example 10.1
------------
$ make -f $FND_TOP/usrxit/Makefile hello.o

Example 10.2
------------
$ make -f $FND_TOP/usrxit/Makefile hello_main.o

Example 10.3
------------
$ make -f $FND_TOP/usrxit/Makefile submit_hello.o

Example 10.4
------------
$ make -f $FND_TOP/usrxit/Makefile sample_main.o

It is possible to compile all four examples on a single line, but

generally you should do one at a time to identify and correct
any errors as you write them. The combined example below compiles
the three C and one Pro*C programs.

Combined Example 10.1, 10.2, 10.3 and 10.4

------------------------------------------
$ make -f $FND_TOP/usrxit/Makefile hello.o hello_main.o submit_hello.o sample_main.o

6. Archiving Subroutines into Product Libraries

--------------------------------------------

The compiled object files will be written to the local directory

from which you executed the $FND_TOP/usrxit/Makefile command, which
should be $FND_TOP/src for the example and $CUS_TOP/src for your real
customizations. You need to move them to your $CUS_TOP/lib directory
before archiving or linking with the "adrelink" utility. Please note
the discussion of file and version control for a brief description of
your $CUS_TOP and directory structure in Section 7 below.

If we assume the test case of this article, you will execute the
following commands to move the files.

Example 10.1
 ------------
$ mv $FND_TOP/src/hello.o $FND_TOP/lib/.

Example 10.2
------------
$ mv $FND_TOP/src/hello_main.o $FND_TOP/lib/.

Example 10.3
------------
$ mv $FND_TOP/src/submit_hello.o $FND_TOP/lib/.

Example 10.4
------------
$ mv $FND_TOP/src/sample_main.o $FND_TOP/lib/.

Then, confirm that you have successfully moved the files by changing to
the $FND_TOP/lib directory and listing the files (e.g., with the "ls"
utility). When you have confirmed that the files are where they should
be in the $FND_TOP/lib directory, you will need to archive the subroutine
objects into the libfnd.a library file.

General Syntax
--------------
$ ar ruvs <library_name> <subroutine_name.o>

Example Syntax 10.1

-------------------
$ ar ruvs libfnd.a hello.o

Example Syntax 10.3

-------------------
$ ar ruvs libfnd.a submit_hello.o

* NOTE
----
Please remember you should remove these objects from the libfnd.a
library after testing. The syntax for removing them is noted below.

General Syntax
--------------
$ ar d <library_name> <subroutine_name.o>

Example Syntax 10.1

-------------------
$ ar d libfnd.a hello.o
 Example Syntax 10.3
-------------------
$ ar d libfnd.a submit_hello.o

7. File and Version Control Suggestions

------------------------------------

If you follow the guidelines for Oracle Applications, you will have
a custom top directory structure as a child directory from your
$APPL_TOP directory. For example, if your customer directory is "CUS",
then you will have an $APPL_TOP/cus directory. You will define an
environment variable for $CUS_TOP for your custom directory.
(Naturally, the "CUS" will be whatever is meaningful in your
environment.)

Within your $CUS_TOP, you will have the following directories. However,
you may exclude some of these if you define a common log repository
under an $APPLCSF environment variable or choose not to develop SQL
reports et cetera. You should check the Oracle Application Installation
Manual for Unix for reference to the directory structure noted [12.3].

$CUS_TOP Directories
--------------------
admin include mesg patchsc reports sql
bin lib out resource src
forms log patch rpt srw

8. Linking Objects (thru "adrelink")

---------------------------------

You need to link your executable files now that your subroutines are
archived as objects within the libfnd.a library. You do this by
running the "adrelink" utility to link the executables. (Please check
the Oracle Applications Installation Manual [12.3][12.7], if you have
any questions about running the "adrelink" utility.) Please remember
that you should edit the $FND_TOP/lib/fnd.mk file to include your
custom program as qualified below in Section 11.5 Note.113490.1.

General Syntax
--------------

$ adrelink force=y ranlib=y "<application_short_name> <program_name>"

Example Syntax 10.2

-------------------
$ adrelink force=y ranlib=y "FND hello"
 Example Syntax 10.4
-------------------
$ adrelink force=y ranlib=y "FND sample_main"

9. Registering Programs
--------------------

Navigation Steps for 10.7 Character

-----------------------------------

The instructions supporting these navigation steps is found in

Chapter 9 of the Oracle Application Object Library Reference
Manual [12.3]. Please refer to the manual for more detailed
instructions. The navigation is available under the System
Administrator Responsibility.

1. Register the concurrent executable:

=> Navigate => Concurrent => Program => Executable

2. Register the concurrent program:

=> Navigate => Concurrent => Program => Define

3. Register the concurrent program in a request group:

=> Navigate => Security => Responsibility => Report => Groups

Navigation Steps for 10.7 SmartClient/NCA, 11.x and 11i

-------------------------------------------------------

The instructions supporting these navigation concepts is found in

Chapter 9 of the Oracle Application Object Library Reference
Manual [12.3]. Please refer to the manual for more detailed
instructions; however, the screens will be GUI as opposed to
character based. The navigation is available under the System
Administrator Responsibility.

1. Register the concurrent executable:

=> Concurrent => Program => Executable

2. Register the concurrent program:

=> Concurrent => Program => Define

3. Register the concurrent program in a request group:

=> Security => ORACLE => DataGroups

Testing your concurrent programs

--------------------------------
 You have two options in testing your Concurrent C and Pro*C programs.
First, you can run programs directly from the command-line, provided
they DO NOT spawn other concurrent programs Note.113429.1. This
is a suggested work around because of a bug with submitting spawning
Concurrent C and Pro*C programs from the command-line Bug:1314923.
You can test them by using a call to the CONCSUB utility Note.113429.1
found in Appendix B of the Oracle Applications Installation Manual
[12.3][12.7]. Second, you can run your programs from within the Oracle
Applications forms without encountering the bug.

General Syntax
--------------
PROGRAM orauser/pwd 0 Y [parameter1] [parameter2] ...

Example Syntax
--------------
$FND_TOP/bin/hello APPS/APPS 0 Y

10. Sample Code Repository

----------------------

You will find four sample programs in this article; however, more
examples of Concurrent Manager C and Pro*C code may be found in
the Oracle Application Object Library Reference Manual [12.2] and
Note.115016.1. Equivalents to the sample programs section do not
exist in the Oracle Applications Developer's Guide.

The programs noted below have the following names, enclosed in

parentheses following the description. The header files included
are consistent with the Oracle Application Object Library Reference
Manual [12.2] for space considerations in the article.

10.1 Hello World Subroutine (hello.c)

--------------------------------------

/*
|| This is a concurrent program that uses the example
|| code provided in the $FND_TOP/usrxit/EXPROG.c
|| program.
||
|| Modified: Michael McLaughlin
|| Date: 06/07/2000
*/

#ifndef AFPUB
#include <afpub.h>
#endif

#ifndef AFCP
#include <afcp.h>
 #endif

FDRCSID("$Header: hello.c 1.0 00/06/21 09:00:00 porting ship $");

boolean hello(argc, argv, reqinfo)

int argc;
text *argv[];
dvoid *reqinfo;

/*
|| This is the beginning of an example program.
*/

int i;
text buffer[241];

fdpwrt(AFWRT_LOG | AFWRT_NEWLINE, "Hello World.");

fdpwrt(AFWRT_LOG | AFWRT_NEWLINE, "Hello World.");
fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, "This is a test! Take one.");
fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, "This is a test! Take two.");
fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, "-------------------------");

for ( i = 0; i < argc; i++ )

{
sprintf(buffer, "argv[%d]: %s", i, argv[i]);
fdpwrt(AFWRT_OUT | AFWRT_NEWLINE, buffer);
}

/*
|| For successful completion.
*/

return(afpend(FDP_SUCCESS, reqinfo, ""));

}

10.2 Main Routine for Hello World (hello_main.c)

-------------------------------------------------

/*
|| This is a concurrent program that uses the example
|| code provided in the $FND_TOP/usrxit/EXMAIN.c
|| program.
||
|| Modified: Michael McLaughlin
|| Date: 06/07/2000
*/

#ifndef AFPUB
#include <afpub.h>
#endif
 #ifndef AFCP
#include <afcp.h>
#endif

FDRCSID("$Header: hello_main.c 1.0 00/06/21 09:30:00 porting ship $");

AFP_FUNCS hello;

int main(argc, argv)

int argc;
char *argv[];

{
afsqlopt options;
return(afprcp(argc, argv, (afsqlopt *)NULL, (afpfcn *)hello));
}

10.3 Spawning Pro*C Subroutine (submit_hello.pc)

-------------------------------------------------

/*
|| This is a concurrent program that uses the example
|| code provided in the $FND_TOP/usrxit/EXPROG.c
|| program and modified pursuant to the example code
|| found in the Oracle Application Object Library
|| Reference Manual, Concurrent Processing, pages
|| 9-46 through 9-47 (A12534-6).
||
|| Modified: Michael McLaughlin
|| Date: 06/07/2000
*/

#ifndef AFPUB
#include <afpub.h>
#endif

#ifndef AFCP
#include <afcp.h>
#endif

/*
|| Even though this does not appear on page 9-46 of
|| Manual, it should. Please check documentation
|| Bug:1338680 for any questions.
*/

#include <sqlca.h>

FDRCSID("$Header: submit_hello.c 1.0 00/06/21 13:20:00 porting ship $");

boolean submit_hello(argc, argv, reqinfo)

int argc;
text *argv[];
dvoid *reqinfo;
 {

char note[1024];

/*
|| This is the beginning of an example program.
*/

EXEC SQL BEGIN DECLARE SECTION;

VARCHAR reqstart[20]; /* Start date and time */

EXEC SQL END DECLARE SECTION;

text command[100]; /* Command to submit request */
text request_id[12]; /* Passed back from fdpscr() */
text errbuf[241]; /* Passed back from fdpscr() */

EXEC SQL SELECT TO_CHAR(sysdate,'DD-MON-YY HH24:MI:SS')

INTO :reqstart
FROM DUAL;

reqstart.arr[reqstart.len] = '\0';
sprintf(command,"CONCURRENT FND HELLO_MAIN START=\"%s\" ",reqstart.arr);
fdpwrt(AFWRT_LOG | AFWRT_NEWLINE,command);
if(!fdpscr(command,request_id,errbuf))

/* For unsuccessful completion */

{
sprintf(note,"Request ID * value * = * %s * ", request_id);
fdpwrt(AFWRT_LOG | AFWRT_NEWLINE,note);
fdpwrt(AFWRT_LOG | AFWRT_NEWLINE,"Failed to submit concurrent request");
fdpwrt(AFWRT_LOG | AFWRT_NEWLINE,errbuf);
return(afpend(FDP_ERROR,reqinfo,"Failed to submit concurrent request"));
}

else

/* For unsuccessful completion */

{
EXEC SQL COMMIT WORK;
sprintf(note,"Request ID * value * = * %s * ", request_id);
fdpwrt(AFWRT_LOG | AFWRT_NEWLINE,note);
return(afpend(FDP_SUCCESS,reqinfo,"Submitted Successfully"));
}
}

10.4 Main Routine for Hello World (sample_main.c)

------------------------------------------------

/*
|| This is a concurrent program that uses the example
|| code provided in the $FND_TOP/usrxit/EXMAIN.c
 || program.
||
|| Modified: Michael McLaughlin
|| Date: 06/07/2000
*/

#ifndef AFPUB
#include <afpub.h>
#endif

#ifndef AFCP
#include <afcp.h>
#endif

FDRCSID("$Header: sample_main.c 1.0 00/06/21 09:30:00 porting ship $");

AFP_FUNCS submit_hello;

int main(argc, argv)

int argc;
char *argv[];
{
afsqlopt options;
return(afprcp(argc, argv, (afsqlopt *)NULL, (afpfcn *)submit_hello));
}

11. Known Issues

------------

11.1 Problems with $ORACLE_HOME/rdbms/demo/oratypes.h file:

Note.113453.1 INCORRECT "#typedef" IN $ORACLE_HOME/rdbms/demo/oratypes.h FILE

11.2 Problems with $FND_TOP/usrxit/devenv file.

Note.113452.1 PCC-W-02109 | PCC-S-02015: $FND_TOP/usrxit/devenv File is Incomplete

11.3 Spawning Concurrent Program fails during command-line testing.

Note.113430.1 APP-01174 ERROR SUBMITTING SPAWNED CONCURRENT PROGRAM

11.4 Spawning Concurrent Program Fails to Spawn a Child Process.

Note.113429.1 SPAWNING CONCURRENT MANAGER FAILS TO SPAWN OR RETURN CHILD

REQUEST_ID VALUE

11.5 The "adrelink" does not complete normally because the

$FND_TOP/lib/fnd.mk file was not edited to include your
custom program.
 Note.113490.1 RELINKING ERROR "make: Warning: Don't know how to make

12. References
----------

Oracle References
-----------------

Your principal reference material to support C and Pro*C programs,

run as concurrent programs, may be found in the following Oracle
manuals. Any page numbers used or referenced may change because
of slight release version discrepancies between these manuals.
The release version is the number following the dash after the
Oracle part number were used to compose this article.

Version 10.7
------------
[12.1] Oracle Application Object Library Reference Manual, Release 10,
Volume 1 (A12532-6)
[12.2] Oracle Application Object Library Reference Manual, Release 10,
Volume 2 (A12534-6)
[12.3] Oracle Applications Installation Manual, Release 10.7 for Unix,
Appendix B (A47542-1)
[12.4] Oracle Call Interface, Release 7.3, Programmer's Guide
(A32546-1)
[12.5] Programmer's Guide to the Oracle Precompilers, Release 1.8
(A42526-1)

Version 11.x
------------
[12.6] Oracle Applications Developer's Guide, Release 11 (A58187-01)
[12.7] Oracle Applications Installation, Release 11 for Unix,
Appendix B (A57983-02)
[12.8] Programmer's Guide to the Oracle Call Interface, Release 8,
Volume I: OCI Concepts (A54657-1)
[12.9] Programmer's Guide to the Oracle Call Interface, Release 8,
Volume II: OCI Reference (A54655-01)
[12.10] Programmer's Guide to the Pro*C/C++ Precompiler, Release 8
(A54661-01)

Version 11i*
-----------
[12.11] Oracle Applications Developer's Guide, Release 11i (A83705-02)
[12.12] Oracle Call Interface, Programmer's Guide, Volume 1, Release 8.1.6,
(A76977-01)
[12.13] Oracle Call Interface, Programmer's Guide, Volume 2, Release 8.1.6,
(A76978-01)
[12.14] Pro*C/C++ Precompiler, Programmer's Guide, Volume 1, Release 8.1.6,
(A76943-01)
[12.15] Pro*C/C++ Precompiler, Programmer's Guide, Volume 2, Release 8.1.6,
(A76944-01)
* NOTE: Documentation on compiling and linking Concurrent C and Pro*C
programs found in Appendix B of [12.2] and [12.6] is now only
covered in Chapter 19 of [12.10].

General References
------------------

Your principal reference material to support C programs, may be found in

these and other books covering the C programming language. Oracle does
not make any endorsement of these references but provide a brief list
of references on the C programming language. You should search any of
the various websites that sell books to find reference books on the
C programming language. A reference to the "vi" editor is noted for
your convenience; however, Oracle does not make any endorsement of the
reference and suggests you search the various websites that sell books
to find a "vi" reference book that meets your needs.

[G.1] C Programming Language, 2nd Ed., 1988, Brian W. Kernighan and

Dennis M. Ritchie, Prentice Hall, ISBN 0131103709.

[G.2] Practical C Programming, 3rd Ed., 1997, Steve Oualline, O'Reilly,

ISBN 1565923065.

[G.3] Comprehensive C, 1992, David Spuler, Prentice Hall, ISBN 0131565141.

[G.4] Checking C Programs with lint, 1988, Ian F. Darwin, O'Reilly,

ISBN 0937175307.

[G.5] The UNIX Programming Environment, 1984, Brian W. Kernighan and

Robert Pike Prentice Hall, ISBN 013937681X.

[G.6] UNIX Systems Programming for SVR4, 1996, David A. Curry, O'Reilly,
ISBN 1565921631.

[G.7] Interprocess Communications in UNIX, 2nd Ed., 1998, John Shapley

Gray, Prentice Hall PTR, ISBN 0138995923.

[G.8] Learning the vi Editor, 6th Ed., 1998, Linda Lamb and Arnold
Robbins, ISBN 1565924266.