How To Create Custom Concurrent Requests for Oracle

Applications Release 11.X

Author: Roland Daane
Last updated: 20-NOV-2003

Table Of Contents
How To Create Custom Concurrent Requests for Oracle ................................................ 1
Applications Release 11.X .............................................................................................. 1
PURPOSE ...................................................................................................................... 2
Registering Your Concurrent Request............................................................................. 2
Defining the Executable............................................................................................... 2
Defining the Concurrent Program ................................................................................ 3
Assigning the Concurrent Program to a Request Group .............................................. 5
Implementing a SQL*PLUS Concurrent Request ............................................................ 5
Implementing a PL/SQL Concurrent Request.................................................................. 6
Implementing a Host Concurrent Request....................................................................... 8
APPENDIX 1: Sample SQL*PLUS Script ........................................................................ 9
APPENDIX 2: Sample Stored Procedure ......................................................................10
APPENDIX 3: Sample Host Program (UNIX) ................................................................12
PURPOSE
This document discusses steps to set up custom concurrent request that are integrated
into Oracle Applications Release 11.0.X. The following discussion is pertinent for all
releases of Oracle Applications Release 11 on UNIX. This paper specifically addresses
SQL*PLUS, PL/SQL Stored Procedure, and HOST program concurrent request types
and generically addresses the steps to register any concurrent request.

Registering Your Concurrent Request

There are three primary steps that have to be performed to be able to register a
concurrent program and make it available to be submitted via Oracle Applications: 1)
define the executable, 2) define the concurrent program and 3) assign the concurrent
program to a request group.

Defining the Executable

The executable has to be defined first, navigation to the form is accomplished from
SYSADMIN responsibility Concurrent:Program:Executable. After double clicking the
Executable menu item from the navigator window you will be routed to the Concurrent
Program Executable form (FNDCPMPE). On the Concurrent Program Executable form
you must supply the following information: Executable Name, Short Name, Application,
Description, Execution Method, Execution File Name and Subroutine Name.

Executable Name - is the logical name for the executable, it is informational only. The
executable name can be changed after the executable has already been assigned to a
concurrent program.
Short Name - is the Name that is queried from the executable zone on the Define
Concurrent Program form. The Short Name cannot be changed after the record has
been saved in the database.
Application - is the application that the executable should be registered under. The
Application field cannot be changed after the record has been saved in the database, the
Application determines the product_top that will be searched when Oracle Applications
attempts to locate the executable i.e. if you specify Application Object Library the
$FND_TOP will be searched.
Description - field is informational only and can be changed anytime.
The Execution Method - determines how Oracle Applications will invoke your concurrent
program and also determines which directory under the product top that will be
interrogated to find your executable i.e. if the Execution Method is SQL*PLUS then the
executable should be located under $PRODUCT_TOP/sql.
Execution File Name - is the name of the program unit that will be executed, this is a
physical entity and must be located in the correct directory in the file system or
database. The Execution File Name can be changed and does not permit the standard
extension to be specified, the standard extension should be used when the executable is
created in the file system i.e. specify TEST_SQL for the Execution File Name in the form
but create a script named TEST_SQL.sql on the file system.
Subroutine Name - is only applicable for the spawned and immediate execution
methods.
After an executable has been defined an executable cannot be deleted once it has been
assigned to a concurrent program. If you must delete the executable you would have to
delete the concurrent program first. (SEE 6-48 Oracle Applications Systems
Administration Guide)

Defining the Concurrent Program

The second step is to define the concurrent program, navigation to the form is
accomplished from SYSADMIN responsibility Concurrent:Program:Define After double
clicking the Define menu from the navigator window item you will be routed to the
Concurrent Programs form (FNDCPMPP). On the Concurrent Program form you must
supply the following information:
Program, Short Name, Application and Description.
Program - is the logical name for the concurrent request, it is informational only and can
be changed at any time.
Short Name - is the name that can be used to query the
FND_CONCURRENT_PROGRAMS table by CONCURRENT_PROGRAM_NAME
column. You can use the information in this table to join other tables by
CONCURRENT_PROGRAM_ID (primary key). The short name cannot be changed after
the record has been saved in the database.
Application - is used to determine what ORALCE user name your program runs in and
where to place log and output files. The Application assigned to the concurrent program
can be different than the Application assigned to the executable that is assigned to the
concurrent program i.e. you can assign executable A (registered under the Application
Object Library application) to concurrent program B (registered under General Ledger
application).
Enabled Check Box - must be checked to be able to submit the concurrent request after
it has been defined. If this box is not checked the request will not show up in users’lists
and does not appear in any concurrent manager queues.
Executable Zone - of this form contains the information for the executable that will be
invoked by this concurrent program. The executable must have been defined prior to
setting up the concurrent program and can be selected from a list of values.

Priority - is used to indicate the priority that the concurrent request will be assigned when
it is submitted. If you do not assign a priority, the user’s profile option Concurrent:Priority
sets the request’s priority at submission. For detail explanations of the Request zone,
Output zone and how to define incompatibilities from this form see (6-53 of the Oracle
Applications System Administration Guide).
Assigning the Concurrent Program to a Request Group
The last step to ready your custom concurrent request - so that it can be submitted from
applications - is to assign the concurrent program to a Request Group. Navigation to the
form is accomplished from SYSADMIN responsibility Security:Responsibility:Request.

Use Query from the toolbar, select Find and select the Report Group that you would like
to add
your concurrent request to. Then place your cursor in the TYPE column and use Edit
from the
toolbar to create a new record. Specify type as “program”and then select the concurrent
program from the LOV. After you have completed this step you are able to submit the
concurrent request from a responsibility that has the request group assigned.

Implementing a SQL*PLUS Concurrent Request

This section details special considerations that should be taken when implementing a
SQL*PLUS type concurrent request. A SQL*PLUS type concurrent request is best used
for implementing simple reports (character format) or creating utility programs to purge
data from tables or update information in tables.
The SQL script must be stored on the file system under the product_top for the
application the executable was registered. For example if you register the executable
under Application Object Library you will need to store the SQL script in the
$FND_TOP/sql directory. The name of the script should be suffixed with .sql. For
example if you registered the executable with an Execution File Name of TEST_SQL the
name of the executable on the file system should be “TEST_SQL.sql”.
If you want to use parameters with your script first, you must define the parameters for
the concurrent request by navigating to the Concurrent:Program:Define form via
depressing the parameters button which will display the Concurrent Program
Parameters form (see below).
For detailed explanation on how to define parameters see page 6-57 of the Oracle
Applications Systems Administration Guide.

The key item to remember when defining parameters for SQL*PLUS concurrent
programs is that the reference to the parameter being passed to the script is based on
the order of the parameters specified in the above form. For example in the above form
the parameter for the User ID should be named &1 and Signon Date should be named
&2 in the script (See Appendix 1 for example script). The sequence specified in the form
does not correlate to the value that should be specified in the script. For example if the
sequence for User Id remains 1 and the Signon Date is changed to sequence 5 the
names of the parameters in the script should still be called &1 and &2 respectively. If you
change the order of the parameters on the form you will have to change the script to
reflect the correct names based on the order of the parameters on the form. Lastly, the
name of the parameter must be a &number where number is the order of the parameter
specified on the form, i.e. the form has 5 parameters the names in the script would be
&1, &2, &3, &4 and &5 respectively. If your custom script contains a date format
parameter and you want to schedule the request and have the request increment that
date parameter the value set used for the parameter must be FND_DATE. Otherwise
when you submit the request to be rescheduled and check the box to increment date
parameters the date will not change from each execution to the next. The output from
any SQL select statements in your script will be written to the output file for the request
automatically. It is not necessary to specify an alternate spool file for output unless the
client wants the output to be written to a different directory or file name.

Implementing a PL/SQL Concurrent Request

The PL/SQL Stored Procedure type concurrent request is best used to submit other
concurrent request (custom request set) or update tables in the database. The PL/SQL
Stored Procedure type is not effective for running reports because file I/O is tedious.
The first step in creating the PL/SQL Stored Procedure concurrent request would be to
write the procedure. Generally procedures are part of another object called a package,
for the discussion of this paper it will be assumed that you already have a debugged
procedure that has been created within SQL*PLUS under the APPS schema. It is a good
practice to store the package specification and body under the
$PRODUCT_TOP/admin/sql directory for the application that the executable was
registered under. If the executable was registered under Application Object Library then
the package specification and body should be stored under $FND_TOP/admin/sql.
Any PL/SQL Stored Procedure that is going to be run under Oracle Applications must
specify at least two parameters which are errbuf OUT VARCHAR2 and retcode OUT
NUMBER. If these parameters are not passed in the correct order and format the
request will fail with a PLS-201 error.
The rules for passing parameters to the PL/SQL stored procedure are essentially the
same as for SQL*PLUS type concurrent requests. The order that the parameters are
defined on the Concurrent Program Parameters form is the order that the parameters
should be passed to the procedure. The exception is that the user defined parameters
will be the 3 rd thru N parameter passed because the first two parameters are reserved
for errbuf and retcode. The errbuf and retcode parameters are not defined on the form
(SEE Appendix 2 for example Stored Procedure). For example if you have defined two
parameters for your concurrent request called user_id (character) and cutoff_date (date)
then your procedure specification should look like this:
test_procedure ( errbuf OUT VARCHAR2, retcode OUT NUMBER, uid IN
VARCHAR2, cutoffdate IN DATE);
The names of the parameters in the form and the names on the procedure are
inconsequential, the important thing is that the order and format are correct.
If you would like to write messages to the log and output files of your PL/SQL Stored
Procedure concurrent request you should use the FND_FILE package to accomplish
these tasks. The FND_FILE package is documented in the Oracle Applications
Developer’s Guide (20-15). The FND_FILE package will only work if the APPLPTMP
environment variable is set to a directory value specified for the UTL_FILE_DIR
parameter in the INIT.ora file.
Implementing a Host Concurrent Request
Host concurrent programs are best for performing operating system tasks such as
copying files.
Setting up a Host Concurrent program in the UNIX operating system is relatively
painless. First you must write your shell script and save the script under the
$PRODUCT_TOP/bin directory corresponding to the application that the executable is
registered under. When the host concurrent program is invoked five standard
parameters are passed in $0 thru $4. The five standard parameters do not need to be
defined on the Concurrent Program Parameters Form.
Variable Contents
$0 Name of the Concurrent Program
$1 Oracle User ID/PASSWORD
$2 User ID (numeric representation)
$3 User Name that submitted the request (character representation)
$4 Request ID for the request

The parameters in $5 thru $9 are user defined and are passed in the order defined on
the Concurrent Program Parameters form. The total number of parameters passed is
shell (ksh, csh, bourne, etc) dependent. To be able to reference parameters 6 thru N
where parameter 6 would be the equivalent of $10 you must use the shift command to
place the value of the 10 th argument into $9 variable (see example script APPENDIX
3).
If you specify “encrypt”in the Execution Options filed of the Concurrent Programs
window.
This signals the concurrent manager to pass orauser\pwd in the environment variable
fcp_login. The password of the argument $1 will be populated with asterisks (SEE UNIX
Installation Guide B-12).After you have created your host concurrent program make sure
that you save the program with an extension of “YOUR_HOST.prog”. The execution file
specified when the executable is defined should be equal to “YOUR_HOST” excluding
the .prog extension. After you have saved your executable it is important to create a
symbolic link from “YOUR_HOST”to fndcpesr in the same directory that your host
concurrent program is saved. The command to create the symbolic link is:
“ln -s fndcpesr YOUR_HOST”
If you fail to create the symbolic link the parameters passed to your program will not be
passed in separate variables rather they will be passed as one long string in the $1
parameter. It is important to remember to grant executable permissions on the script file
that is your host concurrent program. The command to do this is:
chmod 755 YOUR_HOST.prog
if you fail to do this your concurrent program will fail and exit with status 1.
If you wish to direct output to the request log or output log for your host concurrent
program it is the responsibility of the programmer to construct the correct file name
based on the user name ($3) and request id ($4) parameters. The request log is of the
format “l######.req”where ###### = request id ($4). The output files fomat is
dependent upon the environment variable $APPCPNAM. If $APPCPNAM is set to
USER.REQUID then the naming convention for output files will be USERNAME.######
where ###### = request id ($4) and USERNAME is the user that submitted the request
($3). If APPCPNAM is not set the default 8.3 naming convention will be used which is
o######.out where ###### = request id ($4).
APPENDIX 1: Sample SQL*PLUS Script
SET PAGESIZE 40
SET LINESIZE 80
SET FEEDBACK OFF
SET VERIFY OFF
SET HEADING ON
TTITLE 'Userid|Activity Report'
BTITLE 'Confidential'
COLUMN c1 HEADING 'User Name'
COLUMN c2 HEADING 'Session Start Time'
COLUMN c3 HEADING 'Session End Time'

SELECT SUBSTR(fu.user_name, 1,30) "c1"

, TO_CHAR(fl.start_time, 'fmYYYY/MM/DD fmHH:MI:SS AM') "c2"
, NVL(TO_CHAR(fl.end_time, 'fmYYYY/MM/DD fmHH:MI:SS AM'),
'Session In Doubt') "c3"
FROM fnd_user fu,
fnd_logins fl
WHERE fu.user_id = fl.user_id
AND fu.user_name = UPPER('&1')
AND fl.start_time >= '&2'
ORDER BY fl.start_time
/
SET FEEDBACK ON
SET VERIFY ON
APPENDIX 2: Sample Stored Procedure
Package Specification
/*
|| PACKAGE SPECIFICATION
*/
CREATE or REPLACE PACKAGE test_package
IS
/*
|| PROCEDURE: purge_signon_data
|| PURPOSE: delete rows from fnd_logins.
*/
PROCEDURE purge_signon_data
( errbuf OUT VARCHAR2
, retcode OUT NUMBER
, v_user_name IN VARCHAR2
, v_cutoff_date IN DATE );
END test_package;
/

Package Body
/*
|| PACKAGE BODY
*/
CREATE or REPLACE PACKAGE BODY test_package AS
/*
|| Implementation of purge_signon_data
*/
PROCEDURE purge_signon_data ( errbuf OUT VARCHAR2
, retcode OUT NUMBER
, v_user_name IN VARCHAR2
, v_cutoff_date IN DATE )
IS
v_num_recs_deleted NUMBER := 0; -- records deleted
v_username VARCHAR2(100); -- user name
v_login_id NUMBER := 0; -- login id
v_text_msg VARCHAR2(100); -- text message
v_error_code NUMBER; -- error code
v_error_message VARCHAR2(255); -- error message
CURSOR purge_signon_cursor ( v_user_name VARCHAR2,
v_cutoff_date DATE )
IS
SELECT fu.user_name
, fl.login_id
FROM fnd_user fu
, fnd_logins fl
WHERE fu.user_id = fl.user_id
AND fu.user_name = UPPER(v_user_name)
AND fl.start_time < v_cutoff_date;
BEGIN
errbuf := NULL;
retcode := 0;
/*
|| Open cursor, fetch each record that meets selection criteria,
|| delete each record that meets selection criteria and commit
|| changes.
*/
fnd_file.put_line (fnd_file.log
, 'Beginning Procedure purge_signon_data');
fnd_file.put_line (fnd_file.log, '');
fnd_file.put_line (fnd_file.log
, 'User Name: ' || v_user_name);
fnd_file.put_line (fnd_file.log
, 'Cutoff Date: ' || v_cutoff_date);
fnd_file.put_line (fnd_file.log, '');
OPEN purge_signon_cursor ( v_user_name, v_cutoff_date );
LOOP
FETCH purge_signon_cursor
INTO v_username, v_login_id;

EXIT WHEN purge_signon_cursor%NOTFOUND;

DELETE FROM fnd_logins

WHERE login_id = v_login_id;

v_num_recs_deleted := v_num_recs_deleted + 1;
END LOOP;
CLOSE purge_signon_cursor;

IF v_num_recs_deleted > 0 THEN

COMMIT;
v_text_msg := 'Total Records Deleted: '
|| TO_CHAR
(v_num_recs_deleted, '999,999');
ELSE
v_text_msg := 'No Records Matched Selection Criteria';
END IF;
fnd_file.put_line (fnd_file.log, v_text_msg);
fnd_file.put_line (fnd_file.log, '');
fnd_file.put_line (fnd_file.log
, 'Ending Procedure purge_signon_data');
EXCEPTION
/*
|| Catch all error.
*/
WHEN OTHERS THEN
ROLLBACK;
v_error_code := SQLCODE;
v_text_msg := 'Fatal Error, Oracle Error is: '
|| TO_CHAR (v_error_code, '99999');
fnd_file.put_line (fnd_file.log, v_text_msg);
v_error_message := SQLERRM;
fnd_file.put_line (fnd_file.log, v_error_message);
END purge_signon_data; -- end purge_signon_data
END test_package; -- end test_package
APPENDIX 3: Sample Host Program (UNIX)
#!/usr/bin/ksh
# test shell script to verify what parms are passed
OUTDIR=$APPLCSF/$APPLOUT/$3.$4

echo "BEGIN: `date`" >> $OUTDIR

if [ $# = 0 ]
then
echo "No parms were passed to the Shell Program" >> $OUTDIR
exit
fi
counter=0
while [ "$counter" -le $# ]
do
echo "Passed Parm $counter : \c" >> $OUTDIR
case "$counter" in
0) echo "$0" >> $OUTDIR
;;
1) echo "$1" >> $OUTDIR
;;
2) echo "$2" >> $OUTDIR
;;
3) echo "$3" >> $OUTDIR
;;
4) echo "$4" >> $OUTDIR
;;
5) echo "$5" >> $OUTDIR
;;
6) echo "$6" >> $OUTDIR
;;
7) echo "$7" >> $OUTDIR
;;
8) echo "$8" >> $OUTDIR
;;
9) echo "$9" >> $OUTDIR
;;
10) shift
echo "$9" >> $OUTDIR
;;
*) echo "Not parm 0 thru 10" >> $OUTDIR
;;
esac
counter=`expr $counter + 1`
done
echo "END: `date`" >> $OUTDIR
exit