In Oracle E-Business Suite, concurrent processing simultaneously executes programs running in the background with online operations to fully utilize your hardware capacity. You can write a program (called a "concurrent program") that runs as a concurrent process. Typically, you create concurrent programs for long-running, data-intensive tasks, such as posting a journal or generating a report.
For more information on concurrent processing from a user's viewpoint, see the Oracle E-Business Suite User's Guide and the Oracle E-Business Suite Setup Guide.
You can use PL/SQL to create a stored procedure concurrent program. In addition, any PL/SQL procedure you develop-whether it runs on the client, or on the server as a stored procedure or a database trigger-can submit a concurrent request to run a concurrent program. For more information, see: PL/SQL APIs for Concurrent Processing.
Oracle Application Object Library Concurrent Processing provides you with all the features you need to satisfy the following application development needs:
Ensure consistent response time, regardless of the variability of data your applications process
Allow end users to keep working at their terminals while long-running processes run concurrently
Allow you to fully use all the capacity of your hardware by executing many application tasks at once
You and your end users can submit requests from forms to start any concurrent program. Once your request has been submitted, the concurrent managers immediately take over and complete the task with no further online involvement.
Oracle Application Object Library automatically schedules requests based on when they were submitted, their priority, and their compatibility with programs that are already running. As a developer, you can define which programs in your application should not run simultaneously. A request for a program that is incompatible with a currently running program does not start until the incompatible program completes.
You and your end users can control certain runtime options for each of your concurrent requests. Profile options allow you to determine printing decisions such as which printer to use and how many copies to print.
Your end users can review the progress of their concurrent requests online. Once the request completes, they can view the report output and log files from their concurrent requests. They can see the status of a concurrent request without printing out the entire report by selecting Requests from the default help menu.
Concurrent managers are components of Concurrent Processing that monitor and run time-consuming, non-interactive tasks without tying up your terminal. Whenever you or your users submit a request to run a task, a concurrent manager processes that request and does the work in the background, giving you the ability to run multiple tasks simultaneously.
Oracle Application Object Library predefines the Internal Concurrent manager, which functions as the "boss" of all other managers. The Internal Concurrent Manager starts up, verifies the status of, resets, and shuts down the individual managers. It also enforces program incompatibility rules by comparing program definitions for requested programs with those programs already running in an Oracle username designated as a logical database.
After installation, the system administrator can create and tailor the concurrent managers as needed. The system administrator chooses the number of requests that each concurrent manager can process simultaneously and what types of requests it can process. Concurrent managers provide total control over the job mix and throughput in your application.
Simultaneous Queuing lets requests wait in many queues at once to ensure that the first available concurrent manager starts your request. Use Oracle System Administration to set up Concurrent Processing so that requests can be run by more than one concurrent manager. When the first available concurrent manager starts a request, it automatically removes the request from all the other queues.
Concurrent program executables allow you to use the same execution file for multiple concurrent programs. To create specialized versions of a concurrent program, either define a new concurrent program using the same executable, or copy the concurrent program. You can specialize a concurrent program by required printers, specialization rules, or application name so that the concurrent programs run using the same execution file but with different parameters.
Concurrent programs can be integrated with the Business Event System in Oracle Workflow. Business events can be raised at key points of the life cycle of a request to run a concurrent program. Users can subscribe to the business events and create their own business processes interacting with the concurrent programs.
For more information on the Business Event System, see the Oracle Workflow documentation.
The Unified C API afprcp() function allows you to write C or Pro*C programs using a standard format and use your programs with either the spawned or immediate execution method. The same execution file can run both as a spawned process or as a subroutine of the concurrent manager.
A concurrent program is an instance of an execution file, along with parameter definitions and incompatibilities. Concurrent programs use concurrent program executables to locate the correct execution file. Several concurrent programs may use the same execution file to perform their specific tasks, each having different parameter defaults and incompatibilities.
A concurrent program executable links an execution file or and the method used to execute it with a defined concurrent program. Under Concurrent Processing, an execution method may be a program written in a standard language, a reporting tool, or an operating system language.
An execution method can be a PL/SQL Stored Procedure, an Oracle Tool such as Oracle Reports or SQL*Plus, a spawned process, or an operating system host language.
A concurrent program execution file is an operating system file or database stored procedure which contains your application logic and can be executed by either invoking it directly on the command line or by invoking a program which acts upon it. For example, you run a Pro*C program by invoking it on the command line. You run a SQL script by running SQL*Plus and passing the name of the SQL script without the .sql extension.
A concurrent program subroutine is a Pro*C routine which contains your application logic and is linked in with the Concurrent Manager code.
The execution method identifies the concurrent program executable type and the method Oracle Application Object Library uses to execute it.
An execution method can be a PL/SQL Stored Procedure, an Oracle Tool such as Oracle Reports or SQL*Plus, a spawned process, or an operating system host language.
A concurrent program written in Oracle Reports, PL/SQL, SQL*Loader, or SQL*Plus.
A concurrent program that runs in a separate process (on most operating systems) than that of the concurrent manager that starts it. You write spawned concurrent programs as C or Pro*C stand-alone executable files. On some operating systems, you can also write spawned concurrent programs in your operating system language.
Spawned concurrent programs are the recommended execution method for new C or Pro*C execution files.
A concurrent program that runs in the same process as the concurrent manager that starts it. You write immediate concurrent programs as C or Pro*C subroutines and link them in with a concurrent manager.
Important: The immediate concurrent program functionality is provided for backward compatibility only. You should not be creating new immediate concurrent programs.
A program library is a set of linked immediate concurrent programs that are assigned to concurrent managers. A concurrent manager can run any spawned or Oracle Tool concurrent programs, but only immediate concurrent programs in its own program library. Use Oracle E-Business Suite System Administration to further restrict what concurrent programs a concurrent manager can run when defining a concurrent manager with specialization rules.
You register your program library with Oracle Application Object Library. List the short names of the immediate concurrent programs in your program library. Then, use Oracle E-Business Suite System Administration to assign program libraries to concurrent managers.
You can include an immediate concurrent program in different libraries. Each concurrent manager that runs immediate concurrent programs must have a program library, although several managers can share the same library.
A request type groups similar concurrent programs to save time in defining and maintaining concurrent managers.
A parent request is a concurrent request that submits another concurrent request. In the case of Standard Request Submission, a report set is a parent. When you submit a report set, the report set submits the reports or programs that you have included in the report set. A parent request may be sequential or parallel which determines whether the requests it submits run one at a time or all at once.
A child request is a concurrent request submitted by another concurrent request. When you submit a concurrent request to run a report set, the report set submits the reports in the set for concurrent processing. The requests submitted by the report set are child requests.
A logical database is a set of logically related data stored in one or more ORACLE IDs. Concurrent managers use logical databases to determine the scope of concurrent program compatibilities.
When you define a concurrent program, you specify what programs are incompatible with this program and cannot run together with this program in the same logical database. A user in a logical database submits a concurrent request to run a concurrent program. If a concurrent manager that can process your request finds that there are no incompatible programs currently running in the user's logical database, then the concurrent manager processes the concurrent request. Concurrent managers use logical databases to ensure that incompatible programs do not run together.
Any program or any portion of a form that can be separately constructed to be non-interactive could potentially be run as a concurrent process. Generally, you should consider making any application function that could tie up your end user's terminal into a concurrent program. Among the functions that best take advantage of concurrent processing are reports and functions that perform many database operations.
You should design your concurrent program to use the features and specifications of concurrent processing most efficiently. Your program should expect values to be passed as concurrent program parameters, and should handle failure gracefully, allowing the concurrent manager to restart your program without creating data integrity problems. If you want to generate error messages and output, you should instruct your program to write to separate log and output files. This makes diagnosing any problems much easier. If you are writing programs under a custom application, ensure that the custom application is in the Standard data group. Finally, if your program access custom tables you build, implement your tables to accept Who column values.
Users submit concurrent requests using Standard Request Submission or from a form by performing an action that initiates a trigger step in the form. If you want your users to submit your program through Standard Request Submission, you must check the "Use in SRS" check box" and register your program parameters when you define your concurrent program. To let your users submit a concurrent request for your program from a form, you call an Oracle Application Object Library user exit from a trigger step and specify the name of your program and its arguments. Typically, your program takes arguments from fields on your form. You can also submit a concurrent request from within a program. Oracle Application Object Library provides a standard interface between the calling form or program and your concurrent program that is independent of the operating system you are using.
When a user submits a concurrent request, the request waits in the queue of each concurrent manager defined to be able to run the user's concurrent request. Use Oracle System Administration to set the priority of requests that a user submits and change the priority of individual requests. The request's priority affects the request's position in the queues.
The first available concurrent manager that can process the user's request looks at predefined data groups in Oracle Application Object Library tables. The data group assigned the user's responsibility contains a list of application names and their corresponding ORACLE IDs. The concurrent manager automatically uses the ORACLE ID associated with the concurrent program's application to run the program.
When you write and define your concurrent program, you define what programs are incompatible to run with your program in the same logical database.
If no concurrent manager is currently running an incompatible program in the same logical database as the user's concurrent request, the concurrent manager removes the user's concurrent request from any other queues and runs your concurrent program. Your concurrent program writes to a report output file and a log file. The concurrent manager automatically prints the report output if you defined your program to print output. The system administrator or user can specify printing information such as the printer destination and the number of copies using user profiles, in this case "Printer" and "Concurrent:Report Copies". If the program is submitted using Standard Request Submission, the user can specify printing and submission information at runtime.
You can write different types of concurrent programs: Oracle Tool programs written in SQL*Plus, PL/SQL, SQL*Loader, or Oracle Reports; programs written in C or Pro*C, or host language programs.
The basic process of creating a concurrent program is the same regardless of the execution method. The steps you take include:
Write your program execution file and place it in the appropriate location for your operating system.
Define the concurrent program executable with Oracle Application Object Library to specify an execution file and an execution method for your program.
Define the concurrent program with Oracle Application Object Library, define program parameters if necessary, and define any incompatibilities with other concurrent programs
Request your program from the Run Reports form, from a trigger step in an application form, or from an Pro*C concurrent program.
The concurrent manager processes up to 100 arguments for a concurrent program. Each argument can be no longer than 240 characters. For spawned Pro*C concurrent programs, the concurrent manager can process arguments that are longer than 240 characters if you use extended syntax to submit your program. When using extended syntax, the concurrent manager can process a total argument string (the length of all your arguments combined) of up to 24,000 characters.
If a concurrent manager terminates abnormally while it is processing requests (for example, if your system crashes), it remembers the requests that are running at the time of the failure. When you restart the concurrent managers, they automatically restart those requests. To ensure that your concurrent program handles system failures properly, you should design your program so that a concurrent manager can restart it from the beginning without your program creating data inconsistencies or receiving errors such as "duplicate key in index" errors.
The simplest way to do this is to avoid committing transactions until the last step in your program. If this is not feasible due to the amount of data your program could potentially process, you have several alternatives.
You can commit intermediate transactions to temporary tables, and then perform one final transaction at the end of your program to transfer data from your temporary tables to your main tables. When your program starts, it should delete any data from the temporary tables that might have resulted from a previous system crash.
Another alternative is to include a special status column in your tables that you update in your program to indicate the rows that are "being processed." You can then set the column to "done" in the last transaction in your program. You should ensure that your other application programs ignore rows with the value "being processed" in the status column.
You can write concurrent programs using a variety of execution methods. For example, you can use Oracle Tools, programming languages such as Pro*C, or PL/SQL procedures to create the execution files that your concurrent programs invoke.
This section concentrates on using PL/SQL procedures as execution files and on calling your concurrent programs from PL/SQL procedures.
See later chapters for detailed information on writing concurrent programs using other execution methods.
Spawned and immediate concurrent programs are programs written in C or Pro*C. On some operating systems, you can write your spawned concurrent programs in your operating system command language.
While spawned concurrent programs run in an independent spawned process, immediate programs run as a subroutine of the concurrent manager's process. If you use the Unified C API afprcp(), you can use the same execution file with both the spawned and immediate execution methods.
If you use the immediate execution method, you must complete extra steps before submitting your concurrent request.
Create or modify a program library that includes your immediate concurrent programs.
Rebuild your program library with Oracle Application Object Library and then link it.
Assign new program libraries to concurrent managers using Oracle E-Business Suite System Administration.
You can implement your concurrent program as a stored procedure. Beginning with Release 11, file I/O operations are supported for stored procedures.
A benefit of developing your concurrent program as a stored procedure is that it runs as part of the concurrent manager's database connection and does not cause an additional process to be spawned, as do other concurrent processing execution methods. Therefore, the “Stored Procedure" execution method is appropriate for frequently-executed concurrent programs (including those you develop to replace immediate concurrent programs from prior releases of Oracle E-Business Suite).
Stored procedure concurrent programs accept input parameters only, and are submitted with the FND_REQUEST package. Following is an example specification of a PL/SQL procedure you could create to run as a concurrent program:
REM /* Beginning of SQL Script */
REM
CREATE PROCEDURE FND60.SAMPLE_PROC (ERRBUF OUT VARCHAR2,
RETCODE OUT VARCHAR2,
ARGUMENT1 IN VARCHAR2,
ARGUMENT2 IN VARCHAR2,
ARGUMENT3 IN VARCHAR2,
.
.
.
.
ARGUMENT100 IN VARCHAR2,
)
Your stored procedure concurrent program is restricted to 100 parameters in addition to the first two parameters, which are required and must be specified exactly as indicated in the example above. (You must take these two parameters into account when you create your stored procedure.) Use errbuf to return any error messages, and retcode to return completion status. The parameter retcode returns 0 for success, 1 for success with warnings, and 2 for error. After your concurrent program runs, the concurrent manager writes the contents of both errbuf and retcode to the log file associated with your concurrent request.
Important: You should restart your concurrent managers whenever you create or reinstall a stored procedure concurrent program.
The easiest way to test your concurrent program is to submit the program for concurrent processing using the CONCSUB utility. You also have the option to submit the request from the Submit Request form if you are developing your concurrent program for Standard Request Submission. Another way to test your program is to use the form that submits it. Monitor the progress of the request until it completes, then check its completion message and output. If your process completes abnormally, the log file can give you the information you need to take corrective action.
From the operating system, use CONCSUB to submit a concurrent program. By using the WAIT token, the utility checks the request status every 60 seconds and returns you to the operating system prompt upon completion of the request. Your concurrent manager does not abort, shut down, or start up until the concurrent request completes.
If your concurrent program is compatible with itself, you can check it for data integrity and deadlocks by submitting it many times so that it runs concurrently with itself.
Your PL/SQL procedures can submit a request to run a program as a concurrent process by calling FND_REQUEST.SUBMIT_REQUEST. Before submitting a request, your procedure can optionally call three functions to set concurrent request attributes that determine printing and resubmission behavior:
FND_REQUEST.SET_OPTIONS
FND_REQUEST.SET_REPEAT_OPTIONS
FND_REQUEST.SET_PRINT_OPTIONS
If any of these functions should fail, all setup function parameters are reset to their default values.
In addition, before you call FND_REQUEST.SUBMIT_REQUEST from a database trigger, you must call FND_REQUEST.SET_MODE.
When you call FND_REQUEST.SUBMIT_REQUEST, you pass any arguments required by the concurrent program you are requesting. FND_REQUEST.SUBMIT_REQUEST returns the ID of the submitted request if successful, and 0 otherwise.
Upon completion of the FND_REQUEST.SUBMIT_REQUEST function, all the setup function parameters are reset to their default values. It is up to the caller to perform a commit to complete the request submission.
The FND_REQUEST functions are fully described in the Concurrent Processing APIs for PL/SQL Procedures section of this chapter.
Concurrent requests do not submit until they are committed. It is sometimes desirable to immediately commit the requests, bet be aware that there is no way to commit the request without committing all other changes in the form. Do not attempt to commit just the server side, because this releases any locks the user has. To avoid getting a "no changes to commit" message when the user doesn't have any changes (check SYSTEM.FORM_STATUS), use the APP_FORM.QUIET_ COMMIT routine.
See: PL/SQL APIs for Concurrent Processing
Your PL/SQL procedure can check the status of a concurrent request by calling FND_CONCURRENT.GET_REQUEST_STATUS.
FND_CONCURRENT.GET_REQUEST_STATUS returns the current status of a concurrent request. If the request has already completed, FND_CONCURRENT.GET_REQUEST_STATUS also returns the completion message associated with the request.
The FND_CONCURRENT.WAIT_FOR_REQUEST function waits for request completion, and then returns the request's phase/status and completion message to the caller. This function sleeps for a developer-specified interval between checks for request completion.
The FND_CONCURRENT functions are fully described in the PL/SQL APIs for Concurrent Processing section.
See: PL/SQL APIs for Concurrent Processing
Oracle Application Object Library for Windows comes with a user interface program which can be used to start and view the results of concurrent programs. The interface for "Start Concurrent Programs" is modelled on the Run dialog in the Program Manager.
The dialog contains fields for the path to a concurrent program, a database connect string and optional arguments. There is also a combo box which lists concurrent programs which have been installed. To use the program:
Select a concurrent program to run, either by typing a path into the Path field, using the Browse button to select a program, or by selecting one of the concurrent programs listed in the Program combo box.
Enter a valid database connect string including username and password in the Connect String field.
Click on the Run button. A "Working..." message should appear in the bottom left corner of the dialog. When the program finishes, a Done message will appear. At this point you may view the log and output files (if any) for the concurrent program by pressing the View Log or View Output buttons.
If you type an invalid connect string, an alert will appear saying ABNORMAL PROGRAM TERMINATION. Click on Close, fix the connect string and try again.
Important: The program for Start Concurrent Program (startcp.exe) and the associated program item are installed only if you install the development Application Object Library.
You can construct your application so that your end user is unaware of concurrent processing. Even after a user or form submits a concurrent request, your end user can keep working at the terminal without interruption. However, your end user can modify a request's concurrent processing options up until it starts running. For example, your user can change which printer prints a report.
Your end user can monitor the progress of a concurrent request using the Requests window. For example, your end user can see when a request starts running and then view the completion status and a completion message for a concurrent request.
Oracle Application Object Library uses the values of user profile options as default values to apply to all concurrent requests that a user submits.
Number of report copies to print of a report
Save report output to a file in your operating system
Printer on which to print a report
Start date and time for a concurrent request
Run requests sequentially
Hold a request temporarily
Priority of a concurrent request
Who can view the report
Users can set some of these options for an entire login session using user profiles, and they can change some of these values at any time. If the request is submitted through Standard Request Submission, they can change printing and submission information when submitting the request. After users submit a concurrent request, they or your system administrator can modify these processing options for a concurrent request up until the time it starts running. Use the Requests form to modify the request's concurrent options. During runtime, you can use the Oracle Application Object Library utility afpoput in your Pro*C concurrent programs to change user profile options.
This change is only effective during the runtime of your concurrent programs.
Your end user can check on a request to find out whether it is running, waiting to be started, has completed successfully, or has terminated with an error. You can build your concurrent programs so that if they fail to complete successfully, the concurrent manager displays an error message indicating the problem. If a request is pending normally, your user can determine how soon it will start by reviewing the request's position in the queues of the various concurrent managers that can run that particular request.
Concurrent processing is an important component for your day-to-day operation of Oracle E-Business Suite. You can operate your Oracle E-Business Suite smoothly if you understand how concurrent managers react to different kinds of unforeseen situations. Your concurrent manager can detect concurrent programs or concurrent processes that terminate abnormally. It is also capable of automatically recovering from abnormal situations like operating system or internal failures such as segmentation faults. This section describes the actions the concurrent manager takes to recover from typical system problems.
After you or your user submit a concurrent request, there may be situations where you want to terminate the running request. You can terminate a running request by changing the status to Completed in the Requests form. You should always terminate running requests from these forms whenever possible so that your concurrent manager can update the status of these requests accordingly.
The Requests form only allows you to cancel programs that you submitted and that are in your report security group. Use the privileged System Administration form Concurrent Requests Summary to cancel other requests as necessary.
If a concurrent request process is interrupted by a system signal or segmentation fault, your concurrent manager detects the disruption of the running request and updates the request phase/status to Completed/Error. Your concurrent manager then goes on to process other pending concurrent requests. If the disrupted request is a sub-request, your concurrent manager updates its status to Error and restarts the parent request. The parent request then communicates with your concurrent manager whether to abort or continue processing its remaining sub-requests. No other recovery procedures are required to resume concurrent processing.
When you start up your concurrent processing facility, the internal concurrent manager starts up all the concurrent manager processes defined. The internal concurrent manager monitors the operation of these concurrent manager processes to make sure they function as defined. If any of these processes exits abnormally, the internal concurrent manager starts up a new process to ensure the correct number of concurrent manager processes are running. This monitoring process is completely invisible to you or your users.
Typically, if a concurrent manager process terminates abnormally while running a request, the request then completes with a phase/status of Complete/Error. If the running request is a sub-request (such as a member of a report set), the request completes with an Error status. When the parent request (such as a report set) restarts and detects the failure of the report, it notifies the concurrent manager process whether to abort or continue processing other sub-requests. If the running request is a parent request (such as a report set), the request completes with an Error status and the status of its sub-requests are all updated to Error.
If the failing concurrent manager process is an internal concurrent manager process, all you need to do is to restart your concurrent processing facility. Although the internal concurrent manager terminates abnormally, other concurrent manager processes continue to operate and newly submitted concurrent requests keep going into other available concurrent manager queues.
The only concurrent requests affected by a failure of the internal concurrent manager process are run alone concurrent programs and concurrent programs that have incompatibilities. If these concurrent requests are submitted after the internal concurrent manager exits abnormally, they remain in pending status until you restart the internal concurrent manager process. If these concurrent requests are submitted before the internal concurrent manager's abnormal exit, they remain pending and hold up all other concurrent requests belonging to the same logical database unless you put these affected requests on hold. Once your internal concurrent manager is running again, it resumes the duty of monitoring other concurrent manager processes and coordinating the processing of concurrent programs that are run alone or have incompatibilities.
Unusual operating system exits and abnormal database shutdowns are two common reasons that cause concurrent manager processes to fail. In these situations, all the concurrent manager processes are terminated without any notice and the phase and status of your concurrent requests remain as they are. All you have to do to resume normal concurrent processing is restart your concurrent processing facility. Once you restart your concurrent processing facility, your concurrent managers rerun all the requests that were running at the time the concurrent manager processes failed. After processing the previously running requests, the concurrent managers then process other pending concurrent requests.
Oracle Application Object Library provides printer drivers that correspond to print styles for concurrent program output. These drivers provide the four print styles for a variety of printers.
L (Landscape)
P (Portrait)
A (A4)
W (Landwide)
First the concurrent manager looks for a printer driver you can define with the name of printer type concatenated with the print style. The printer type is associated with the printer. The print style is associated with the concurrent program. For Oracle Reports, every printer driver is associated with an Oracle Reports driver of the form (L.prt). These Oracle Reports drivers contain printer specific formatting characters such as bold, italic, underline and new page markers.
When you review your reports on line, reports that use the Oracle Application Object Library printer drivers display correctly. Reports that use custom printer drivers may not display correctly on certain terminals.
To build applications that take advantage of concurrent processing, you should understand aspects common to all types of concurrent programs as well as how to implement each type.
Oracle Application Object Library provides several different implementation methods for concurrent programs:
Oracle Tool concurrent programs
Pro*C concurrent programs
Host language concurrent programs
Before you begin writing your program, you should weigh the advantages of each method and choose the one that best fits your needs.
Oracle Reports, PL/SQL, SQL*Loader, and SQL*Plus programs are the simplest to write and integrate with Oracle Application Object Library. You can also write PL/SQL stored procedures as concurrent programs.
See: Concurrent Processing with Oracle Reports
You can write either spawned or immediate concurrent programs in C and Pro*C. Spawned concurrent programs are stand-alone programs that run in a separate process. (On some operating systems, you can also write spawned concurrent programs in your operating system command language. See the Oracle E-Business Suite Setup Guide for specific details.) Immediate concurrent programs run as subroutines of a concurrent manager.
Spawned concurrent programs are not linked with a concurrent manager. On most operating systems, concurrent managers start spawned concurrent programs in a separate operating system process than the concurrent manager. Spawned concurrent programs therefore require more system resources. In a spawned concurrent program, your SQL statements do not remain parsed between separate invocations of the program.
Immediate concurrent programs run as subroutines in C or Pro*C. You build a program library of immediate concurrent programs and assign the program library to concurrent managers. To call an immediate concurrent program, a concurrent manager invokes a subroutine call.
Immediate concurrent programs execute in the same operating system process as the concurrent manager on most operating systems. Since the concurrent manager is already connected to the database, your program does not have to explicitly connect. Additionally, because the process does not end when your program ends, the SQL statements in your program can remain parsed after the first invocation of the program. Subsequent invocations of the same program can run faster because the database does not have to parse the SQL statements.
However, immediate programs are also harder to maintain and support. Since they run as a subroutine of the concurrent manager, failures can sometimes affect the manager itself. We recommend implementing new Pro*C concurrent programs as spawned. In future releases, we will only support Pro*C programs as spawned, as PL/SQL stored procedures provide a mechanism for running concurrent programs in the same process as the concurrent manager.
Important: The immediate concurrent program functionality is provided for backward compatibility only. You should not create new immediate concurrent programs.
Depending on which operating system you are using, you implement host language concurrent programs in different ways.
You can use host language programs to integrate an external program or package with Oracle E-Business Suite. For example, on some platforms you can create a shell script as a host language program. Your script can call a third-party program and then determine whether that program completes successfully. The host program then passes this information back to the concurrent manager.
Since your concurrent programs run non-interactively, they must print output to files. Your Pro*C program should write report output to the an out file and debugging or other technical messages to an FND log file. For more information, see Custom Concurrent Programs, Oracle E-Business Suite Setup Guide.
There are three types of log files:
Output log (for the end user)
Request log (for the end user)
FND log (for the system administrator, support representative, and/or development)
Tip: Writing error messages to a log file rather than to an output file makes it easier for users and system administrators to find reports and diagnostic information, and does not confuse novice users who may be unprepared to see technical error messages when they review their reports online.
There are several methods to write to a standard log file or report output file.
The first method is the easiest method. It is also the only portable method across platforms. You call an Oracle Application Object Library utility routine from your C or Pro*C concurrent program:
| Variable | Description |
|---|---|
| fdpwrt() | Writes a message to a standard log or report output file. Oracle Application Object Library names this file in the standard naming convention. |
We highly recommend this method as the simplest to support and the most robust across platform and release changes.
The second method is to use standard C functions such as fopen() or fclose() to write to files. If you use this method, you must use the Oracle Application Object Library standard naming convention for your file names. Oracle Application Object Library uses the standard naming convention to find your report and log files to display online in the View Requests form and to automatically print your report output.
See Reviewing Requests, Request Log Files, and Report Output Files, Oracle E-Business Suite Setup Guide for the location of the log and out directories and the standard naming conventions for these files on your operating system. The Oracle E-Business Suite Setup Guide also contains information on how to change the default file protection on your report output and log files.
This second method exists for compatibility with concurrent programs written with prior versions of Oracle Application Object Library. When writing new concurrent programs, choose the first method and use the fdpwrt() utility routine.
When you define your concurrent program, you can specify whether the report output prints automatically and the maximum and minimum row and columns it needs. You can also specify a recommended or mandatory print style. The concurrent manager uses the values of user profile options to send copies of report output to a specific printer. Reports submitted through Standard Request Submission have printing and submission options specified at submission time.
A user can change the printer, number of report copies, and the print style when requesting a reprint of report output in the Detail zone of the Submit Requests form.
See: Implementing User Profiles
If you want users of another application to be able to run your program, your application must be included in the Standard data group. Please read the Cross-application Reporting section in the Standard Request Submission chapter for more details.
If you add special WHO columns to your tables, your application users can track changes made to their data. Oracle Application Object Library lets users differentiate between changes they make using forms and changes they make using concurrent programs. Columns that tell you information about the creation and the last update of a row are:
LAST_UPDATED_BY
LAST_UPDATE_DATE
LAST_UPDATE_LOGIN
CREATED_BY
CREATION_DATE
Add the following columns to tell you information about the concurrent program that updated a row:
REQUEST_ID, type NUMBER(15)
PROGRAM_APPLICATION_ID, type NUMBER(15)
PROGRAM_ID, type NUMBER(15)
PROGRAM_UPDATE_DATE, type DATE
You should allow NULLs in these columns because they do not have values when a user inserts a new row using a form.
If you include WHO columns in a table, your concurrent program should update some of them during every insert and update operation. Oracle Application Object Library loads user profile options with the values you use to update these columns. Call the function afpoget at the beginning of your concurrent program to get the current values of these user profile options. Use the values of the user profile options listed in the following table to update the corresponding WHO columns. Update the CREATED_BY column only if you insert a row.
| WHO Column Name | Profile Option Name |
|---|---|
| REQUEST_ID | CONC_REQUEST_ID |
| PROGRAM_ APPLICATION_ID | CONC_PROGRAM_APPLICATION_ID |
| PROGRAM_ID | CONC_PROGRAM_ID |
| LAST_UPDATE_LOGIN | CONC_LOGIN_ID |
| CREATED_BY | USER_ID |
Use your operating system's current date or SQL's SYSDATE to update the following WHO columns. Update the CREATION_DATE column only if you insert a row.
PROGRAM_UPDATE_DATE
CREATION_DATE
See: Implementing User Profiles and PL/SQL APIs for Concurrent Processing.