AIM

MD. 70 APPLICATION EXTENSION TECHNICAL DESIGN University of Virginia-ISP Coding Standards

Author: Creation Date: Update: E-file name: Document Ref: Approvals: Bob Shiflett, Vipul Gupta, UVA Developers March 15, 2002 April 18, 2002 S:\Phase 2 - Tech\Standards and Templates\MD070 Coding Standards MD.070

Bill Randolph

Date

MD. 70 Application Extension Technical Design

Document Control
Reviewers
Documents: MD.020, MD.070, CV.060 Team Lead Tech Track Lead Tech Lead (U.Va./KPMG) Documents: MD.050, CV.040 Team Lead Tech Track Lead Tech Lead (U.Va./KPMG) Functional Lead (U.Va./KPMG) All Other Documents (as appropriate) Team Lead Functional Lead (U.Va./KPMG) Tech Lead (U.Va./KPMG) Date: Date: Date: Date: Date: Date: Date: Date: Date: Date:

Distribution
Copy No. Name Library Location

Change Record
Date 03/15/02 04/04/02 Author Vipul Gupta Bob Shiflett Version 1 1.5 Change Reference Original Version Changed to meet UVA developers Preferences

Coding Standards

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

Coding Standards

3 of 13

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

#!/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
Coding Standards 5 of 13

# 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 ] # 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
Coding Standards 6 of 13

-- 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: --- 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 programmers 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:
Coding Standards 7 of 13

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 programmers discretion, but must be consistent throughout code. 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 :
Coding Standards 8 of 13

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 [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;
Coding Standards 9 of 13

procedure get_info is begin .. exception when others then . end; end; ------------------------- PROCESSING STARTS HERE------------------------begin get_info; Insert_data; 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: / ************************************************************************************************************** *******

Coding Standards 10 of 13

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 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 g_record_status g_error_message return; when too_many_rows
Coding Standards

then := 'i'; := g_error_message||'|work title record does not exist'; then

11 of 13

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. 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.)
Coding Standards 12 of 13

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.

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