AIM
MD. 70 APPLICATION EXTENSION
TECHNICAL DESIGN
University of Virginia-ISP
Coding Standards
Author:
Bob Shiflett, Vipul Gupta, UVA Developers
Creation Date:
March 15, 2002
Update:
April 18, 2002
E-file name:
S:\Phase 2 - Tech\Standards and Templates\MD070 Coding
Standards
Document Ref:
MD.070
Approvals:
Bill Randolph
Date
MD. 70 Application Extension Technical Design
Document Control
Reviewers
Documents: MD.020, MD.070, CV.060
Team Lead
Date:
Tech Track Lead
Date:
Tech Lead (U.Va./KPMG)
Date:
Documents: MD.050, CV.040
Team Lead
Date:
Tech Track Lead
Date:
Tech Lead (U.Va./KPMG)
Date:
Functional Lead (U.Va./KPMG)
Date:
All Other Documents (as appropriate)
Team Lead
Date:
Functional Lead (U.Va./KPMG)
Date:
Tech Lead (U.Va./KPMG)
Date:
Distribution
Copy No.
Name
Location
Library
Change Record
Document Control
Date
Author
Version
Change Reference
03/15/02
04/04/02
Vipul Gupta
Bob Shiflett
1
1.5
Original Version
Changed to meet UVA developers Preferences
2 of 13
MD. 70 Application Extension Technical Design
Contents
Document Control .................................................................................................................. 2
Coding Standards ................................................................................................................... 4
Unix Shell Script............................................................................................................... 4
PL/SQL Program ............................................................................................................. 6
References ....................................................................................................................... 13
Addendum...................................................................................................................... 13
Document Control
3 of 13
MD. 70 Application Extension Technical Design
Coding Standards
Unix Shell Script
File Naming Convention :
The file name must be in lower case.
The file name must begin with ‘uva_’ and have an extension of ‘.sh’.
Example:
uva_cash_balance_report.sh
uva_inv_min_max_v.sh
uva_project_contacts_v.sh
Script Coding Standards:
Unix is case sensitive. The coding must be done in lower case, unless otherwise necessary. For example, environment variables
like UVA_TOP are in upper case.
Example:
################################################################
# SET ENV VARIABLES
################################################################
SQL_DIR=$UVA_CUSTOM/sql
export SQL_DIR
LOG_DIR=$UVA_CUSTOM/log
export LOG_DIR
FORMS_DIR=$UVA_TOP/forms/US
export FORMS_DIR
The first line of a Shell Script must begin with the required command to invoke the necessary Unix shell. The default standard
of UVA is the KORN shell; use others only if relevant to your particular process.
Example:
#!/bin/ksh #korn shell
#!/bin/sh #sh shell
#!/bin/csh #c shell
Comments:
Comments should follow the shell statement and must include at least:
Program Name
Description
Created By
Creation Date
Arguments passed to this script
Example:
Coding Standards
4 of 13
MD. 70 Application Extension Technical Design
#!/bin/ksh
########################################################################
# PROGRAM
: uva_bank_load.sh
# DESCRIPTION : This shell script is for loading Legacy ABA Banks into Oracle Applications
#
# CREATED BY
: Brenneman
# CREATION DATE: 04-24-2001
#
# ARGUMENTS : NO Argument
# EXIT STATUS : 0-SUCCESS
#
1-FAILURE
########################################################################
NOTE:
If modifications are made to the shell script the following comments must be included after the original comments :
# MODIFIED BY
: Brenneman
# MODIFIED DATE : 04-24-2001
# Added additional error checking
########################################################################
Every section of the script must be preceded with the comments about that section.
################################################################################
# CHECK FOR DATA FILES. SET EXIT_STATUS TO 1 (ERROR) IF NOT FOUND
################################################################################
if [ ! -f $IN_DATA_DIR/datafile/*${interface_name}*.dat ] # if file does NOT exist
then
echo
echo
echo
echo $dash20 "Error report :" $dash20
echo "Budget Data File Not Found"
echo "Please FTP your Data files to the UNIX directory =>"${IN_DATA_DIR}/datafile
echo "Budget Data Loading Process exiting .."
echo $dash80
echo
echo
echo
exit_status=1 #set to exit (error)
fi
Return Status :
All Unix Scripts must check and handle appropriately the return status of each separate process within the script. The script
should ultimately return 0 (zero) for success or 1 (one) for failure to the calling process of the script.
#######################################################################
# RUN SQL*LOADER
# NOTE--expecting 1st record to be column headings which will be skipped
# IF SQLLDR RETURN CODE IS NOT EQUAL to 0 [ $? -ne 0 ] SET EXIT_STATUS TO 1 (ERROR)
#######################################################################
echo "==>Loading File " $data_file_name " ...into UVA_BUDGET_DEV_STAGING table"
sqlldr parfile=$par_file errors=100000 skip=1 control=$control_file data=$dat_file log=$log_file bad=$bad_file
if [ $? -ne 0 ] #
Coding Standards
5 of 13
MD. 70 Application Extension Technical Design
then # sqlloader error
echo
echo $dash80
echo "==> SQLLOADER ERROR"
echo $dash80
exit_status=1 # status of 1 (failure)
err_status=1
fi
#################################################################################
#
FINAL RETURN STATUS
#################################################################################
exit $exit_status
#################################################################################
#
END OF PROGRAM
#################################################################################
PL/SQL Program
Comments:
A PL/SQL Package must contain comments related to the concerned package. It must include File Name, Purpose, Notes, and
History for this package. The File Name section includes the name of the file and the name of package. The Purpose section
includes a description of this package. Notes should include the details of this package, important tips and information on
how to execute this package. History should include the date of creation/update, name of who created or updated the
package.
After the package is implemented in production, every change in the code MUST have a comment specifying the date, the
nature of the change and the name of the developer changing it. These comments must be included in the main comments
section of the program and just before the section in the code where these changes are made.
The guidelines on comments also apply to the PL/SQL scripts that are use to create database objects like Table, views,
synonyms, sequences, indexes, grants.
Sample of Comments Section are given below:
Create or replace package Uva_Leave_Reversion_Pkg
as
------------------------------------------------------------------------- name...: uva_leave_reversion_pkg.pls
-- desc...: this package
----- notes..: must be connected as apps to run this script. assumes
-- that all objects which the package is based on exist and
-- that apps select privileges and synonyms.
-- plsql programs that are to run through oracle applications are
-- required to have two varchar2 out variables defined as the first
-- two (errbuf retcode)
--- files..:
--- history:
Coding Standards
6 of 13
MD. 70 Application Extension Technical Design
--- who
what
when
-- ----------------------------------------------------------------- Gopal/Bob/Debbie/Biju
original version.
3/21/02
-- Gopal
Modified the base cursor to join Net
-Calculation rules
3/28/02
--- ADDITIONAL NOTES
-- ================
------------------------------------------------------------------------Every module (procedures, functions, calculations, etc.) of a PL/SQL program must start with comments that describe the
specific function of the module and any other relevant information that may not be inherently apparent.
/*
************************************************************************
this procedure uses the variable v_log_trace to write data to:
oracle apps log (log)
unix file
(file)
dbms_output
(all others)
************************************************************************
*/
procedure display_data(p_description varchar2,
p_data
varchar2 default null)
is
Case Standards :
This Case Standards are at the programmer’s discretion but must be consistent throughout the code.
Parameters Definition :
The parameters defined in the program must begin with ‘p_’ and be descriptive.
Example:
function get_award_number(p_award_id in number)
return varchar2;
Variable definition:
Variables must have meaningful names.
Example:
g_entity_name
-l_person_id
-c_creation_date
ap_reporting_entities.entity_name%type;
per_all_people_f.person_id%type;
date := sysdate;
It is highly recommended that variables have the following prefixes. This is at the programmer’s discretion, but must be
consistent throughout code.
Coding Standards
7 of 13
MD. 70 Application Extension Technical Design
Global variables begin with ‘g_’
Local variables begin with ‘l_’
Constants
begin with ‘c_’
If a variable is used to store a value from a table the ‘%type’ attribute must be used to define the data type and it should
preferably have the name of the table column with the appropriate prefix.
Example :
l_gl_application_id fnd_application.application_id%TYPE;
A value should never be hard-coded in the program. It must always be declared as a global variable and assigned a constant
value.
Cursor names end with ‘_cur’ and cursor records with ‘_rec’
Example:
cursor employee_info_cur is
select employee_name,
national_identifier
from per_all_people_f;
employee_info_rec
employee_info_cur%rowtype;
Table Aliases:
If you use a table alias, the alias must be descriptive of the table it is aliasing. Do not use A, B, C for a table alias.
Example:
from per_all_people_f papf,
per_person_types ppt
-from pa_projects_all
pa_pa,
gms_project_fundings_v gms_pf,
gms_installments
gms_i
Block Structure :
PL/SQL Program is block-structured program. Each PL/SQL block corresponds to a problem or sub-problem to be solved. A
PL/SQL block has three parts : a declarative part, an executable part, and an exception-handling part.
Example of a block structure :
[DECLARE
-- declaration]
BEGIN
-- statements
Coding Standards
8 of 13
MD. 70 Application Extension Technical Design
[EXCEPTION
-- handlers]
END;
Modularity :
Modularity lets us break an application down into manageable, well-defined logic modules. A complex program can be
reduced to a set of simple programs that have easy-to-implement solutions. PL/SQL meets this need with program unit
constructs. Avoid drop thru logic, instead create separate modules that perform a specific task. The “called” module should
be just above the “calling” module.
Package constructs should be used to group related program objects into larger units. The two types of subprograms that can
be used are procedures and functions. These subprograms should only be in the package specification if they are to be used
by other processes outside of the package. This eliminates the problem of developers having to research whether code
changes of subprograms in the specification could possibly affect other processes. Subprograms that are placed solely in a
package body eliminates the possibility of it being executed outside of the process for which it was designed.
Example of modularity security:
package uva_example_pkg
is
process_uva_data;
end uva_example_pkg;
package body uva_example_pkg
is
g_
process_uva_data
procedure insert_data
is
begin
…..
exception
when others then
…….
end;
procedure get_info
is
begin
…..
exception
when others then
…….
end;
end;
------------------------- PROCESSING STARTS HERE------------------------begin
get_info;
Insert_data;
Coding Standards
9 of 13
MD. 70 Application Extension Technical Design
end;
Code Format :
Every DML statement must be enclosed within BEGIN, END, EXCEPTION.
Unless additional processing is required when a handled exception occurs, each EXCEPTION must include:
Module name
Sqlerrm
Input parameters or relevant required data
Example of a handled exception:
exception
when others then
v_valid_data := false;
display_data('*');
display_data('ERROR');
display_data('===== ');
display_data(sqlerrm||' '||v_module|| ' task_number ' ||bud_stg_rec.task_number||
' project_number '||bud_stg_rec.project_number);
raise;
end;
NOTE: display_data is a custom written procedure that some programmers use to output data. The use of the display_data
procedure eliminates the need to change code to display the data.
Every section in the code must have the comments describing the details of that section.
A PL/SQL Block should be structured and properly indented for better reading. Try to keep code within 80 columns if
possible to keep wrapping at a minimun when printed.
Example PL/SQL Block:
/*********************************************************************************************************************
This following code is used to select data from uva_conv_work_title table
*********************************************************************************************************************/
begin
select distinct
p_work_super_ssn,
p_work_faculty_title,
p_work_title
into g_super_ssn,
g_work_faculty_title,
g_work_title
from uva_conv_work_title
where p_work_ss_number = assignments_rec.p_hrs_ss_nbr
and p_work_role_code = assignments_rec.p_hrs_role_code
and p_work_comp_nbr = assignments_rec.p_hrs_comp_nbr
Coding Standards
10 of 13
MD. 70 Application Extension Technical Design
and p_work_org||' '||p_work_org_name = g_org;
exception
when no_data_found then
g_record_status := 'i';
g_error_message := g_error_message||'|work title record does not exist';
return;
when too_many_rows then
g_record_status := 'i';
g_error_message := g_error_message||'|multiple rows pulled for work title ';
return;
when others then
g_record_status := 'i';
g_error_message := g_error_message||'|oracle error pulling work title';
return;
end;
IF g_super_ssn is null AND
assignments_rec.p_hrs_supervisor_ssn != '000-00-0000'
THEN
g_super_ssn := assignments_rec.p_hrs_supervisor_ssn;
ELSIF g_super_ssn is null AND
assignments_rec.p_hrs_supervisor_ssn = '000-00-0000' AND
assignments_rec.p_hrs_role_code
!= '00207'
THEN
g_record_status := 'I';
g_error_message := g_error_message||'|Assignment Does Not have Supervisor';
RETURN;
END IF;
NOTE:
Eliminate redundant code when possible:
Example:
when no_data_found then
g_record_status := 'i';
g_error_message := g_error_message||'|work title record does not exist';
return;
when too_many_rows then
g_record_status := 'i';
g_error_message := g_error_message||'|multiple rows pulled for work title ';
return;
when others then
g_record_status := 'i';
g_error_message := g_error_message||'|oracle error pulling work title';
return;
Replace with:
when others then
g_record_status := 'i';
g_error_message := g_error_message||’ ‘||sqlerrm||’ oracle error pulling work title';
return;
Program / File naming convention :
A pl/sql package name must begin with ‘UVA_XX’ and end with ‘_PKG’. XX is the module abbreviation.
Coding Standards
11 of 13
MD. 70 Application Extension Technical Design
Example:
create or replace package uva_po_req_wf_pkg
is
create or replace package uva_hr_positions_pkg
as
A package file name must begin with the name of the package and have an extension of ‘.pls’. It must be all in lower case.
Example:
uva_hr_positions_pkg.pls
uva_gl_state_acct_mapping_pkg.pls
uva_po_req_wf_pkg.pls
Note : Please refer to MD.040 Build Standards for the naming convention of other database objects such as table, views,
synonyms, sequences etc.
A Database trigger must have the format “UVA_<table name>_<timeframe><action><level>”. Where:
<table name> is the name of the table. Do not repeat the UVA prefix if already included in the table name.
<timeframe> is ‘A’ for ‘After’ and ‘B’ for ‘Before’.
<action> is ‘U’ for ‘Update’,’D’ for ‘Delete’ and ‘I’ for ‘Insert’
<level> is ‘R’ for ‘Row’ and ‘S’ for ‘Statement’
Example:
The after insert,delete row level trigger created on the RA_CUSTOMERS table would be named
“UVA_RA_CUSTOMERS_AIDR”
General guidelines :
Third party tools like SQL Navigator or Toad:
NOTE: When using third party tools it is the responsibility of the developer to ensure that the proper precautions are taken to
reduce the chance of code loss (ie. saving to a flat file regularly on a disk that is recoverable.)
If a PL/SQL program is created using such tools, the program source must be saved on the appropriate network drive and
the relevant UNIX directory in text format, and then is compiled from sqlplus within Unix.
If a PL/SQL program is to be modified by such tools, the program source must first be opened from the appropriate network
drive or copied from the relevant UNIX directory, and then saved on the appropriate network drive and the relevant UNIX
directory in text format when completed.
PL/SQL programs must be complied/executed from the file that stores the source code. It must be compiled at the SQL
prompt and not using any third party tools.
The code should not exceed 80 characters per line when possible. The use of the pipe feature || allows for concatenation. This
helps in avoiding the wrapping problems that occur when the files are opened using different editors and printing.
Use spaces instead of tabs when indenting code.
When creating a table, always use storage parameters so that optimum space is allocated for data that would reside in that
table.
Coding Standards
12 of 13
MD. 70 Application Extension Technical Design
References
The following Oracle documents provide additional information about application code development standards:
Oracle Application Object Library Reference Manual
Oracle PL/SQL Programming
Oracle Applications Developers Guide
Oracle SQL Reference Guide
MD.040 Build Standards
Addendum
Overview of Coding Standards – Oracle Applications 11i
Coding Standards
13 of 13