Skip Headers

Oracle E-Business Suite Developer's Guide
Release 12.1
Part Number E12897-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Building Database Objects

Overview of Building Your Database Objects

This section describes specifications for how to define your tables and the required columns to add. It also covers special data types such as LONG and LONG RAW, and declarative constraints.

Using Cost-Based Optimization

Oracle E-Business Suite uses Oracle Cost-Based Optimization (CBO) instead of the Rule-Based Optimization (RBO) used in previous versions. All new code should be written to take advantage of Cost-Based Optimization. Where your custom application code was tuned to take advantage of Rule-Based Optimization, you may need to retune that code for Cost-Based Optimization.

For additional information, refer to the Oracle database tuning documentation.

Tracking Data Changes with Record History (WHO)

The Record History (WHO) feature reports information about who created or updated rows in Oracle E-Business Suite tables. Oracle E-Business Suite upgrade technology relies on Record History (WHO) information to detect and preserve customizations.

If you add special WHO columns to your tables and WHO logic to your forms and stored procedures, your users can track changes made to their data. By looking at WHO columns, users can differentiate between changes made by forms and changes made by concurrent programs.

You represent each of the WHO columns as hidden fields in each block of your form (corresponding to the WHO columns in each underlying table). Call FND_STANDARD.SET_WHO in PRE-UPDATE and PRE-INSERT to populate these fields.

Adding Record History Columns

The following table lists the standard columns used for Record History (WHO), the column attributes and descriptions, and the sources for the values of those columns. Set the CREATED_BY and CREATION_DATE columns only when you insert a row (using FND_STANDARD.SET_WHO for a form).

Column Name Type Null? Foreign Key? Description Value
CREATED_BY NUMBER(15) NOT NULL FND_ USER Keeps track of which user created each row TO_NUMBER (FND_ PROFILE. VALUE ('USER_ID'))
CREATION_ DATE DATE NOT NULL   Stores the date on which each row was created SYSDATE
LAST_ UPDATED_BY NUMBER(15) NOT NULL FND_ USER Keeps track of who last updated each row TO_NUMBER (FND_ PROFILE. VALUE ('USER_ID'))
LAST_UPDATE_ DATE DATE NOT NULL   Stores the date on which each row was last updated SYSDATE
LAST_UPDATE_ LOGIN NUMBER(15)   FND_ LOGINS Provides access to information about the operating system login of the user who last updated each row TO_NUMBER (FND_ PROFILE. VALUE ('LOGIN_ ID'))

Any table that may be updated by a concurrent program also needs additional columns. The following table lists the concurrent processing columns used for Record History, the column attributes and descriptions, and the sources for the values of those columns.

Column Name Type Null? Foreign Key to Table? Description
REQUEST_ID NUMBER(15)   FND_ CONCURRENT_ REQUESTS Keeps track of the concurrent request during which this row was created or updated
PROGRAM_ APPLICATION_ ID NUMBER(15)   FND_ CONCURRENT_ PROGRAMS With PROGRAM_ID, keeps track of which concurrent program created or updated each row
PROGRAM_ID NUMBER(15)   FND_ CONCURRENT_ PROGRAMS With PROGRAM_ APPLICATION_ID, keeps track of which concurrent program created or updated each row
PROGRAM_ UPDATE_DATE DATE   PROGRAM_ UPDATE_ DATE Stores the date on which the concurrent program created or updated the row

Use Event Handlers to Code Record History in Your Forms

Some operations that must be done at commit time do not seem designed for a table handler. For example, event handlers are preferred to table handlers for setting Record History information for a record, or determining a sequential number. The logic for these operations may be stored in a PRE_INSERT and/or PRE_UPDATE event handler, which is called from PRE-INSERT and PRE-UPDATE block-level triggers during inserts or updates.

See: FND_STANDARD: Standard APIs

Property Classes For WHO Fields

Apply the CREATION_OR_LAST_UPDATE_DATE property class to the form fields CREATION_DATE and LAST_UPDATE_DATE. This property classes sets the correct attributes for these fields, including the data type and width.

Record History Column Misuse

Never use Record History columns to qualify rows for processing. Never depend on these columns containing correct information.

In general, you should not attempt to resolve Record History columns to HR_EMPLOYEES; if you must attempt such joins, they must be outer joins.

Tables Without Record History Information

For blocks that are based on a table, but do not have Record History information, disable the menu entry HELP->ABOUT_THIS_RECORD (all other cases are handled by the default menu control).

Code a block-level WHEN-NEW-BLOCK-INSTANCE trigger (style "Override") with these lines:

 app_standard.event('WHEN-NEW-BLOCK-INSTANCE');
 app_special.enable('ABOUT', PROPERTY_OFF);

See: APP_SPECIAL: Menu and Toolbar Control

Oracle Declarative Constraints

This section discusses the declarative constraints the Oracle database permits on tables, and when to use each feature with your Oracle E-Business Suite tables.

For the most part, any constraint that is associated with a table should be duplicated in a form so that the user receives immediate feedback if the constraint is violated.

Warning: You should not create additional constraints on Oracle E-Business Suite tables at your site, as you may adversely affect Oracle E-Business Suite upgrades. If you do create additional constraints, you may need to disable them before upgrading Oracle E-Business Suite.

NOT NULL

Use wherever appropriate. Declare the corresponding fields within Oracle Forms as "Required" = True.

DEFAULT

In general, do not use this feature due to potential locking problems with Oracle Forms. You may be able to use this feature with tables that are not used by forms (for example, those used by batch programs), or tables that contain columns that are not maintained by forms. For example, defaulting column values can make batch programs simpler. Possible default values are SYSDATE, USER, UID, USERENV(), or any constant value.

UNIQUE

Use wherever appropriate. A unique key may contain NULLs, but the key is still required to be unique. The one exception is that you may have any number of rows with NULLS in all of the key columns.

In addition, to implement a uniqueness check in a form, create a PL/SQL stored procedure which takes ROWID and the table unique key(s) as its arguments and raises an exception if the key is not unique. Only fields that the user can enter should have a uniqueness check within the form; system-generated unique values should be derived from sequences which are guaranteed to be unique.

See: Uniqueness Check

CHECK

Use this feature to check if a column value is valid only in simple cases when the list of valid values is static and short (i.e., 'Y' or 'N').

CHECK provides largely duplicate functionality to database triggers but without the flexibility to call PL/SQL procedures. By using triggers which call PL/SQL procedures instead, you can share constraints with forms and coordinate validation to avoid redundancy.

CHECK does provide the assurance that all rows in the table will pass the constraint successfully, whereas database triggers only validate rows that are inserted/updated/deleted while the trigger is enabled.

This is not usually a concern, since Oracle E-Business Suite database triggers should rarely be disabled. Some triggers (such as Alert events) are disabled before an upgrade and re-enabled at the end of the upgrade.

We strongly advise against the use of database triggers.

PRIMARY KEY

Define a Primary Key for all tables.

Cascade Delete and Foreign Key Constraint

Do not use the Declarative Cascade Delete or the Foreign Key Constraint when defining tables. Cascade Delete does not work across distributed databases, so you should program cascade delete logic everywhere it is needed.

To implement a referential integrity check, create a PL/SQL stored procedure which takes the table unique key(s) as its argument(s) and raises an exception if deleting the row would cause a referential integrity error.

See: Integrity Checking

LONG, LONG RAW and RAW Datatypes

Avoid creating tables with the LONG, LONG RAW, or RAW datatypes. Within Oracle Forms, you cannot search using wildcards on any column of these types. Use VARCHAR2(2000) columns instead.

Columns Using a Reserved Word

If a table contains a column named with a PL/SQL or an Oracle Forms reserved word, you must create a view over that table that aliases the offending column to a different name. Since this view does not join to other tables, you can still INSERT, UPDATE, and DELETE through it.

Views

In general, complex blocks are based on views while simple setup blocks are based on tables. The advantages to using views include:

You should also base your Lists of Values (LOVs) on views. This allows you to centralize and share LOV definitions. An LOV view is usually simpler than a block view, since it includes fewer denormalized columns, and contains only valid rows of data.

See: Example LOV

Define Views To Improve Performance

Whenever performance is an issue and your table has foreign keys, you should define a view to improve performance. Views allow a single SQL statement to process the foreign keys, reducing parses by the server, and reducing network traffic.

Define Views to Promote Modularity

Any object available in the database promotes modularity and reuse because all client or server side code can access it. Views are extremely desirable because:

When Not to Create A View

Avoid creating views that are used by only one SQL statement. Creating a view that is only used by a single procedure increases maintenance load because both the code containing the SQL statement and the view must be maintained.

ROW_ID Is the First Column

The first column your view should select is the ROWID pseudo-column for the root table, and the view should alias it to ROW_ID. Your view should then include all of the columns in the root table, including the WHO columns, and denormalized foreign key information.

Tip: You only need to include the ROWID column if an Oracle Forms block is based on this view. The Oracle Forms field corresponding to the ROW_ID pseudo-column should use the ROW_ID property class.

Change Block Key Mode

In Oracle Forms, you need to change the block Key Mode property to Non-Updatable to turn off Oracle Forms default ROWID references for blocks based on views. Specify the primary keys for your view by setting the item level property Primary Key to True.

For example, a view based on the EMP table has the columns ROW_ID, EMPNO, ENAME, DEPTNO, and DNAME. Set the Key Mode property of block EMP_V to Non-Updatable, and set the Primary Key property of EMPNO to True.

If your block is based on a table, the block Key Mode should be Unique.

Code Triggers for Inserting, Updating, Deleting and Locking

When basing a block on a view, you must code ON-INSERT, ON-UPDATE, ON-DELETE, and ON-LOCK triggers to insert, update, delete, and lock the root table instead of the view.

See: Coding Table Handlers

Single Table Views

Single table views do not require triggers for inserting, updating, deleting and locking. Set the block Key Mode to Unique. Single table views do not require a ROW_ID column.

Special Characters

Do not use the CHR() function (used to define a character by its ASCII number) on the server side. This causes problems with server-side platforms that use EBCDIC, such as MVS. You should not need to embed tabs or returns in view definitions.

Sequences

This section discusses standards for creating and using sequences.

Create Single Use Sequences

Use each sequence to supply unique ID values for one column of one table.

Do Not Limit the Range of Your Sequences

Do not create sequences that wrap using the CYCLE option or that have a specified MAXVALUE. The total range of sequences is so great that the upper limits realistically are never encountered.

In general, do not design sequences that wrap or have limited ranges.

Use Number Datatypes to Store Sequence Values

Use a NUMBER datatype to store sequence values within PL/SQL.

If you need to handle a sequence generate a sequence value in your C code, do not assume that a sequence-generated value will fit inside a C long variable. The maximum value for an ascending sequence is 10^27, whereas the maximum value for a C signed long integer is 10^9. If 10^9 is not a reasonable limit for your sequence, you may use a double instead of a long integer. Remember that by using a double for your sequence, you may lose some precision on fractional values. If you do not need to do arithmetic, and simply need to fetch your sequence either to print it or store it back, consider retrieving your sequence in a character string.

Do Not Use the FND_UNIQUE_IDENTIFIER_CONTROL Table

Do not rely on the FND_UNIQUE_IDENTIFIER_CONTROL table to supply sequential values. Use a sequence or the sequential numbering package instead. The FND_UNIQUE_IDENTIFIER_CONTROL table is obsolete and should not have any rows for objects in your product.

Additionally, do not create application-specific versions of the FND table to replace the FND_UNIQUE_IDENTIFIER_CONTROL table.

Table Registration API

You register your custom application tables using a PL/SQL routine in the AD_DD package.

Flexfields and Oracle Alert are the only features or products that depend on this information. Therefore you only need to register those tables (and all of their columns) that will be used with flexfields or Oracle Alert. You can also use the AD_DD API to delete the registrations of tables and columns from Oracle Application Object Library tables should you later modify your tables.

If you alter the table later, then you may need to include revised or new calls to the table registration routines. To alter a registration you should first delete the registration, then reregister the table or column. You should delete the column registration first, then the table registration.

You should include calls to the table registration routines in a PL/SQL script. Though you create your tables in your own application schema, you should run the AD_DD procedures against the APPS schema. You must commit your changes for them to take effect.

The AD_DD API does not check for the existence of the registered table or column in the database schema, but only updates the required AOL tables. You must ensure that the tables and columns registered actually exist and have the same format as that defined using the AD_DD API. You need not register views.

Procedures in the AD_DD Package

procedure register_table (p_appl_short_name in varchar2,
                       p_tab_name    in varchar2,
                       p_tab_type    in varchar2,
                       p_next_extent in number default 512,
                       p_pct_free    in number default 10,
                       p_pct_used    in number default 70);

procedure register_column (p_appl_short_name in varchar2,
                       p_tab_name   in varchar2,
                       p_col_name   in varchar2,
                       p_col_seq    in number,
                       p_col_type   in varchar2,
                       p_col_width  in number,
                       p_nullable   in varchar2,
                       p_translate  in varchar2,
                       p_precision  in number default null,
                       p_scale      in number default null);

procedure delete_table  (p_appl_short_name in varchar2,
                       p_tab_name    in varchar2);

procedure delete_column (p_appl_short_name in varchar2,
                       p_tab_name    in varchar2,
                       p_col_name    in varchar2);
Variable Description
p_appl_short_ name The application short name of the application that owns the table (usually your custom application).
p_tab_name The name of the table (in uppercase letters).
p_tab_type Use 'T' if it is a transaction table (almost all application tables), or 'S' for a "seed data" table (used only by Oracle E-Business Suite products).
p_pct_free The percentage of space in each of the table's blocks reserved for future updates to the table (1-99). The sum of p_pct_free and p_pct_used must be less than 100.
p_pct_used Minimum percentage of used space in each data block of the table (1-99). The sum of p_pct_free and p_pct_used must be less than 100.
p_col_name The name of the column (in uppercase letters).
p_col_seq The sequence number of the column in the table (the order in which the column appears in the table definition).
p_col_type The column type ('NUMBER', 'VARCHAR2', 'DATE', etc.).
p_col_width The column size (a number). Use 9 for DATE columns, 38 for NUMBER columns (unless it has a specific width).
p_nullable Use 'N' if the column is mandatory or 'Y' if the column allows null values.
p_translate Use 'Y' if the column values will be translated for an Oracle E-Business Suite product release (used only by Oracle E-Business Suite products) or 'N' if the values are not translated (most application columns).
p_next_extent The next extent size, in kilobytes. Do not include the 'K'.
p_precision The total number of digits in a number.
p_scale The number of digits to the right of the decimal point in a number.

Example of Using the AD_DD Package

Here is an example of using the AD_DD package to register a flexfield table and its columns:

EXECUTE ad_dd.register_table('FND', 'CUST_FLEX_TEST', 'T', 8, 10, 90);

EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'APPLICATION_ID', 1, 'NUMBER', 38, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'ID_FLEX_CODE', 2, 'VARCHAR2', 30, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'LAST_UPDATE_DATE', 3, 'DATE', 9, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'LAST_UPDATED_BY', 4, 'NUMBER', 38, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'UNIQUE_ID_COLUMN', 5, 'NUMBER', 38, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'UNIQUE_ID_COLUMN2', 6, 'NUMBER', 38, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'SET_DEFINING_COLUMN', 7, 'NUMBER', 38, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'SUMMARY_FLAG', 8, 'VARCHAR2', 1, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'ENABLED_FLAG', 9, 'VARCHAR2', 1, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'START_DATE_ACTIVE', 10, 'DATE', 9, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'END_DATE_ACTIVE', 11, 'DATE', 9, 'N', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'SEGMENT1', 12, 'VARCHAR2', 60, 'Y', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'SEGMENT2', 13, 'VARCHAR2', 60, 'Y', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'SEGMENT3', 14, 'VARCHAR2', 60, 'Y', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'SEGMENT4', 15, 'VARCHAR2', 60, 'Y', 'N');
EXECUTE ad_dd.register_column('FND', 'CUST_FLEX_TEST', 'SEGMENT5', 16, 'VARCHAR2', 60, 'Y', 'N');

XML Definition File Utility

The XDF (XML Definition File) is the next generation version of the current ODF (Object Definition File) utility which is used to propagate object definitions from Oracle to customer sites.

Note that XDF currently does not support "alters" for nested tables; Only "create" scenarios for nested tables is supported. In Release 12.1, XDF can capture the nested table information in the XDF file, read this information while propagating the table object, and alter the base table to include this nested table column.

Per Oracle E-Business Suite standards, there cannot be two primary keys on a table both with the primary key type as ’D’. In Release 12.1, the XDF application will, depending on a specified parameter value, overwrite the old primary key and create a new one in the XDF file.

Object Containment in XDF

The ADODFGEN utility relied on the concept of building blocks to generate ODF(s). XDF does not support the concept of building blocks and instead groups a primary object along with its dependent objects to allow for a blend of granularity, ease of maintenance, and efficient comparison. The following table provides details on object containment:

Primary Object Types Details Dependent Objects Containment in XDF
Tables These include Global Temporary tables, IOTs, Queue Tables, normal tables, Tables with types (eg. VARRAYS and nested tables types, object types, spatial data-types) Partitioned tables Indexes, triggers (optional), types, constraints, sequences, policies One Table & dependent object definitions per XDF
Materialized Views on Materialized Views   Indexes, triggers (optional), Materialized view logs. One MV & dependent object definitions per XDF
Materialized Views on Base Tables   Indexes, triggers (optional) One MV & dependent object definitions per XDF
Materialized View Logs on base Tables   Indexes, triggers (optional), constraints One MV Log & dependent object definitions per XDF
Views     One View definition per XDF
Advanced Queues     One queue definition per XDF
Triggers Triggers could be generated along with the Table definition or separately.   One or more Trigger definition(s) per XDF
ADT (Object or Abstract Datatypes)     One ADT definition per XDF