This document is available in two formats: this web page (for browsing content) and PDF (comparable to original document formatting). To view the PDF you will need Acrobat Reader, which may be downloaded from the Adobe site. For an official signed copy, please contact the Antitrust Documents Group.

GOVERNMENT EXHIBIT P2207

 

Oracle® Common Application Components
API Reference Guide
Release 11i
Part No. B10562-01

March 2003

ORACLE  

Oracle Common Application Components API Reference Guide, Release 11i

Part No. B10562-01

Copyright © 2000,2003 Oracle Corporation. All rights reserved.

Primary Authors: Charles Colt,. Melody Yang

Contributing Authors: Kellie Briesach, Carol Fager-Higgins, Robert Geiwitz

Contributors: Remi Aimsuphanimit, Sarvi Anandan, Huub Bouten, Kalyani Venkat Chervela, Kenny Ching, Sudarsana Choudhury, Rada Despotovic, Conrad Dias, Ravi Epuri, Killian Evers, Girish Mohan Jashnani, Inna Kitaina, Leela Krishna, Milan Marovic, Sharad Mathur, Chirag Mehta, Suma Neeruganti, John-Tae Park, Hari Radhakrishnan, Peter Pil Seo, Rajesh Singh, Nimit B. Thaker, Jane Wang, Ray Wang, Roger Wigenstam

The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent and other intellectual and industrial property laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.

If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on behalf of the U.S. Government, the following notice is applicable:

Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs.

Oracle is a registered trademark, and PL/SQL, OracleMetaLink, and SQL*Plus are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners.

Contents

Send Us Your Comments .............................................................................................. vii

Preface ........................................................................................................................... ix

Audience for This Guide ................................................................................................... ix
How To Use This Guide ................................................................................................... x
Typographic Conventions ................................................................................................. x
Documentation Accessibility ............................................................................................. xi
Other Information Sources ............................................................................................... xii
Do Not Use Database Tools to Modify Oracle Applications Data .................................... xvii
About Oracle .................................................................................................................. xvii

1 Introduction

1.1 Parameter Specifications ........................................................................................... 1-2
1.1.1 Standard IN Parameters ........................................................................................ 1-3
1.1.2 Standard OUT Parameters .................................................................................... 1-4
1.1.3 Parameter Size ...................................................................................................... 1-5
1.1.4 Missing Parameter Attributes ................................................................................. 1-5
1.1.5 Parameter Validations ............................................................................................ 1-5
1.1.6 Invalid Parameters ................................................................................................. 1-6
1.2 Version Information .................................................................................................. 1-6
1.3 Status Messages ....................................................................................................... 1-6

2 Resource Manager Public APIs

2.1 Resource Manager Public Packages ........................................................................... 2-1
2.1.1 Resource Manager Public APIs ............................................................................... 2-2
2.2 Package JTF_RS_RESOURCE_PUB. ....................................................................... 2-3
2.2.1 Create_Resource ..................................................................................................... 2-3
2.2.2 Update_Resource .................................................................................................... 2-11
2.3 Package JTF_RS_GROUPS_PUB ............................................................................. 2-19

iii

2.3.1 Create_Resource_Group ......................................................................................... 2-19
2.3.2 Update_Resource_Group ........................................................................................ 2-21
2.4 Package JTF_RS_SALESREPS_PUB ....................................................................... 2-24
2.4.1 Create_SalesRep ..................................................................................................... 2-24
2.4.1.1 Setting the org_context .......................................................................................... 2-25
2.4.2 Update_SalesRep .................................................................................................... 2-28
2.4.2.1 Setting the org_context .......................................................................................... 2-28
2.5 Messages and Notifications ......................................................................................... 2-32
2.5.1 JTF_RS_RESOURCE_PUB ................................................................................... 2-32
2.5.1.1 Create_Resource .................................................................................................. 2-32
2.5.1.2 Update_Resource ................................................................................................. 2-35
2.5.2 JTF_RS_GROUPS_PUB ........................................................................................ 2-37
2.5.2.1 Create_Resource_Group ...................................................................................... 2-37
2.5.2.2 Update_Resource_Group ..................................................................................... 2-38
2.5.3 JTF_RS_SALESREPS_PUB .................................................................................. 2-39
2.5.3.1 Create_SalesRep .................................................................................................. 2-39
2.5.3.2 Update_SalesRep ................................................................................................. 2-41
2.6 Sample Code .............................................................................................................. 2-42
2.6.1 JTF_RS_RESOURCE_PUB .................................................................................... 2-42
2.6.1.14 Create_Resource ................................................................................................. 2-42
2.6.1.15 Update_Resource ................................................................................................ 2-45
2.6.2 JTF_RS_GROUPS_PUB ......................................................................................... 2-49
2.6.2.1 Create_Resource_Group Sample Code .................................................................. 2-49
2.6.2.2 Update_Resource_Group Sample Code ................................................................. 2-51
2.6.3 JTF_RS_SALESREPS_PUB .................................................................................... 2-53
2.6.3.1 Create_SalesRep Simple Code ............................................................................... 2-53
2.6.3.2 Update_SalesRep Sample Code ............................................................................. 2-55

3 Task Manager Public APIs

3.1 Task Manager Public Packages ................................................................................... 3-2
3.2 Package JTF_TASKS_PUB ....................................................................................... 3-5
3.2.1 Data Structure Specifications ..................................................................................... 3-5
3.2.1.1 Task Assign Record Type ...................................................................................... 3-5
3.2.1.2 Task Dependency Record Type ............................................................................. 3-6
3.2.1.3 Task Reference Record Type ................................................................................. 3-6

iv

3.2.1.4 Task Recurrence Record Type ............................................................................... 3-7
3.2.1.5 Task Dates Record Type ........................................................................................ 3-7
3.2.1.6 Task Contact Record Type ..................................................................................... 3-7
3.2.1.7 Task Notes Record Type ........................................................................................ 3-8
3.2.1.8 Sort Record Type ................................................................................................... 3-8
3.2.2 Create_Task .............................................................................................................. 3-9
3.2.3 Update_Task ............................................................................................................. 3-19
3.2.4 Delete_Task ............................................................................................................... 3-27
3.3 Package JTF_TASKS_ASSIGNMENTS_PUB ............................................................ 3-29
3.3.1 Date Structure Specifications ....................................................................................... 3-29
3.3.1.1 Task Assignments Record Type ................................................................................ 3-29
3.3.2 Create_Task_ Assignment ........................................................................................... 3-30
3.3.3 Update_Task_Assignment ........................................................................................... 3-36
3.3.4 Delete_Task_Assignment ............................................................................................. 3-40
3.4 Package JTF_TASK_REFERENCES_PUB ................................................................... 3-42
3.4.1 Data Structure Specifications ........................................................................................ 3-42
3.4.1.1 References Record Type ........................................................................................... 3-42
3.4.2 Create_References ....................................................................................................... 3-43
3.4.3 Update_References ...................................................................................................... 3-46
3.4.4 Delete_References ........................................................................................................ 3-49
3.5 Messages and Notifications .............................................................................................. 3-50
3.5.1 Common Messages ....................................................................................................... 3-51
3.5.2 JTF_TASK_ASSIGNMENTS_PUB ............................................................................ 3-54
3.5.3 JTF_TASK_REFERENCES_PUB ............................................................................... 3-54
3.5.4 JTF_TASKS_PUB ....................................................................................................... 3-55
3.6 Sample Code ................................................................................................................... 3-56
3.6.1 Package JTF_TASKS_PUB ......................................................................................... 3-57
3.6.2 Package JTF_TASK_ASSIGNMENTS_PUB .............................................................. 3-61
3.6.3 Package JTF_TASK _REFERENCES_PUB ................................................................ 3-64

4 Notes Public APIs

4.1 Package JTF_NOTES_PUB ............................................................................................. 4-1
4.1.1 Data Structure Specifications ........................................................................................... 4-2
4.1.1.1 Record jtf_note_contexts_rec_type ............................................................................... 4-2
4.1.2 Notes Public APIs ........................................................................................................... 4-2

V

4.1.3 Note Source and Note Context ....................................................................................... 4-2
4.1.3.1 Note Source ................................................................................................................ 4-3
4.1.3.2 Note Context ............................................................................................................... 4-3
4.1.4 Party Relationships .......................................................................................................... 4-4
4.1.5 Create_Note ................................................................................................................... 4-5
4.1.6 Update_Note .................................................................................................................. 4-11
4.2 Messages and Notifications ................................................................................................. 4-13
4.2.1 JTF_NOTES_PUB ......................................................................................................... 4-14
4.3 Sample Code ...................................................................................................................... 4-14
4.3.1 Package JTF_NOTES_PUB ........................................................................................... 4-14
4.3.1.7 Create_Note ................................................................................................................ 4-15
4.3.1.8 Update_Note ............................................................................................................... 4-17

Index

vi

Send Us Your Comments

Oracle Common Application Components API Reference Guide, Release 11i
Part No. B10562-01

Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this publication. Your input is an important part of the information used for revision.

  • Did you find any errors?
  • Is the information clearly presented?
  • Do you need more information? If so, where?
  • Are the examples correct? Do you need more examples?
  • What features did you like most about this manual?
If you find any errors or have any other suggestions for improvement, please indicate the chapter, section, and page number (if available). You can send comments to us at:

Oracle Corporation
Oracle Common Application Components, Content Development Manager
500 Oracle Parkway
Redwood Shores, CA 94065
USA

If you would like a reply, please give your name, address, and telephone number below.
_________________________________________________________________
_________________________________________________________________
_________________________________________________________________


vii

viii

Preface

Audience for This Guide

Welcome to Release 11i of the Oracle Common Application Components API Reference Guide. This manual describes the Oracle Common Application Components' public APIs, and provides information to help you work effectively with these public APIs.

Note: This document provides API information for the following Oracle Common Application Components only:
  • Resource Manager
  • Task Manager
  • Notes

This guide assumes you have a working knowledge of the following:

  • The principles and customary practices of your business area

  • Oracle Common Application Components
    If you have never used the Oracle Common Application Components modules, Oracle suggest you attend one or more of the Oracle Common Application Components training classes available through Oracle University.

  • The Oracle Applications graphical user interface
    To learn more about the Oracle Applications graphical user interface, read the Oracle Applications User's Guide. See "Other Information Sources" for more information about Oracle Applications product information.

ix

This preface explains how the Reference Guide is organized and introduces other sources of information that can help you.

How To Use This Guide
This manual contains the following chapters:

Chapter Title Summary
Chapter 1 Introduction Discusses the following topics:
  • API and parameter specifications
  • Standard IN and OUT parameters
  • Status messages
Chapter 2 Resource Manager Public APIs Discusses the following Resource Manager public packages, and the associated public APIs:
  • JTF_RESOURCES_PUB
  • JTF_RS_GROUP_PUB
  • JTF_RS_SALESREPS_PUB
Chapter 3 Task Manager Public APIs Discusses the following Task Manager public packages, and the associated public APIs:
  • JTF_TASKS_PUB
  • JTF_TASK_ASSIGNMENT_PUB
  • JTF_TASK_REFERENCES_PUB
Chapter 4 Notes Public APIs Discusses the Notes public package (JTF_ NOTES_PUB), and the associated public APIs.

Typographic Conventions
This document uses the following typographic conventions:

Convention Description
Monospace text Monospace text represents code or SQL statements.

X
Convention Description
lowercase italics Lowercase italics in the text represent variables. Substitute an appropriate value for the variable.
UPPERCASE Uppercase characters within the text represent command names, SQL reserved words and keywords, and terms associated with the Oracle database.
Indentation Indentation helps to show structure within code examples, but is not required.
<text> Text inside angle brackets can mean either of the following:
  • It denotes a variable that is replaced with an actual value at runtime.
  • In indicates XML elements in discussions about XML code.

Documentation Accessibility

Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle Corporation is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/

Accessibility of Code Examples in Documentation
JAWS, a Windows screen reader, may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.

xi

Accessibility of Links to External Web Sites in Documentation
This documentation may contain links to Web sites of other companies or organizations that Oracle Corporation does not own or control. Oracle Corporation neither evaluates nor makes any representations regarding the accessibility of these Web sites.

Other Information Sources
You can choose from many sources of information, including online documentation, training, and support services, to increase your knowledge and understanding of Oracle Common Application Components.

If this guide refers you to other Oracle Applications documentation, use only the Release 11i versions of those guides.

Online Documentation
All Oracle Applications documentation is available online (HTML or PDF). Online help patches are available on Metalink.

Related Documentation
Oracle Common Application Components shares business and setup information with other Oracle Applications products. Therefore, you may want to refer to other product documentation when you set up and use Oracle Common Application Components

You can read the documents online by reading from the Oracle Applications Document Library CD included in your media pack, or by using a Web browser with a URL that your system administrator provides.

If you require printed guides, you can purchase them from the Oracle Store at
http://oraclestore.oracle.com.

Documents Related to All Products

Oracle Applications User's Guide
This guide explains how to enter data, query, run reports, and navigate using the graphical user interface: (GUI) available with this release of Oracle Common Application Components (and any other Oracle Applications products). This guide also includes information on setting user profiles, as well as running and reviewing reports and concurrent processes.

xii

You can access this user's guide online by choosing"Getting Started with Oracle Applications" from any Oracle Applications help file.

Documents Related to This Product

Oracle Common Application Components Implementation Guide
Use this manual to understand the necessary configuration and setup steps that need to be performed after the Oracle Common Application Components modules are installed.

Oracle Common Application Components User's Guide
This manual provides basic conceptual and reference information needed to understand the Oracle Common Application Components modules. In addition, it details the procedures performed by a typical end-user of the Oracle Common Application Components modules.

Installation and System Administration

Oracle Applications Concepts
This guide provides an introduction to the concepts, features, technology stack, architecture, and terminology for Oracle Applications Release 11i. It provides a useful first book to read before an installation of Oracle Applications. This guide also introduces the concepts behind Applications-wide features such as Business Intelligence (BIS), languages and character sets, and Self-Service Web Applications.

Installing Oracle Applications
This guide provides instructions for managing the installation of Oracle Applications products. In Release 11i, much of the installation process is handled using Oracle Rapid Install, which minimizes the time to install Oracle Applications, the Oracle8 technology stack, and the Oracle8i Server technology stack by automating many of the required steps. This guide contains instructions for using Oracle Rapid Install and lists the tasks you need to perform to finish your installation. You should use this guide in conjunction with individual product user's guides and implementation guides.

xiii

Oracle Applications Supplemental Common Application Components Installation Steps
This guide contains specific steps needed to complete installation of a few of the Common Application Components products. The steps should be done immediately following the tasks given in the Installing Oracle Applications guide.

Upgrading Oracle Applications
Refer to this guide if you are upgrading your Oracle Applications Release 10.7 or Release 11.0 products to Release 11i. This guide describes the upgrade process and lists database and product-specific upgrade tasks. You must be either at Release 10.7 (NCA, SmartClient, or character mode) or Release 11.0, to upgrade to Release 11i. You cannot upgrade to Release 11i directly from releases prior to 10.7.

Maintaining Oracle Applications
Use this guide to help you run the various AD utilities, such as AutoUpgrade, AutoPatch, AD Administration, AD Controller, AD Relink, License Manager, and others. It contains how-to steps, screenshots, and other information that you need to run the AD utilities. This guide also provides information on maintaining the Oracle applications file system and database.

Oracle Applications System Administrator's Guide
This guide provides planning and reference information for the Oracle Applications System Administrator. It contains information on how to define security, customize menus and online help, and manage concurrent processing.

Oracle Alert User's Guide
This guide explains how to define periodic and event alerts to monitor the status of your Oracle Applications data.

Oracle Applications Developer's Guide
This guide contains the coding standards followed by the Oracle Applications development staff. It describes the Oracle Application Object Library components needed to implement the Oracle Applications user interface described in the Oracle Applications User Interface Standards for Forms-Based Products. It also provides information to help you build your custom Oracle Forms Developer 6i forms so that they integrate with Oracle Applications.

xiv

Oracle Applications User Interface Standards for Forms-Based Products
This guide contains the user interface (UI) standards followed by the Oracle Applications development staff. It describes the UI for the Oracle Applications products and how to apply this UI to the design of an application built by using Oracle Forms.

Other Implementation Documentation

Oracle Workflow Administrator's Guide
This guide explains how to complete the setup steps necessary for any Oracle Applications product that includes workflow-enabled processes, as well as how to monitor the progress of runtime workflow processes.

Oracle Workflow Developer's Guide
This guide explains how to define new workflow business processes and customize existing Oracle Applications-embedded workflow processes. It also describes how to define and customize business events and event subscriptions.

Oracle Workflow User's Guide
This guide describes how Oracle Applications users can view and respond to workflow notifications and monitor the progress of their workflow processes.

Oracle Workflow API Reference
This guide describes the APIs provided for developers and administrators to access Oracle Workflow.

Oracle eTechnical Reference Manuals
Each eTechnical Reference Manual (eTRM) contains database diagrams and a detailed description of database tables, forms, reports, and programs for a specific Oracle Applications product. This information helps you convert data from your existing applications integrate Oracle Applications data with non-Oracle applications, and write custom reports for Oracle Applications products. Oracle eTRM is available on Metalink

Oracle Manufacturing APIs and Open Interfaces Manual
This manual contains up-to-date information about integrating with other Oracle Manufacturing applications and with your other systems. This documentation includes APIs and open interfaces found in Oracle Manufacturing.

xv

Oracle Order Management Suite APIs and Open Interfaces Manual
This manual contains up-to-date information about integrating with other Oracle Manufacturing applications and with your other systems. This documentation includes APIs and open interfaces found in Oracle Order Management Suite.

Oracle Applications Message Reference Manual
This manual describes Oracle Applications messages. This manual is available in HTML format on the documentation CD-ROM for Release 11i.

Training and Support

Training
Oracle offers training courses to help you and your staff master the Oracle Common Application Components modules and reach full productivity quickly. You have a choice of educational environments:

  • You can attend courses offered by Oracle University at any one of our many Education Centers.
  • You can arrange for our trainers to teach at your facility.
  • You can use Oracle Learning Network (OLN), Oracle University's online education utility.

In addition, Oracle training professionals can tailor standard courses or develop custom courses to meet your needs. For example, you may want to use your organization's structure, terminology, and data as examples in a customized training session delivered at your own facility.

Support
From on-site support to central support, our team of experienced professionals provides the help and information you need to keep the Oracle Common Application Components modules working for you. This team includes your Technical Representative, Account Manager, and Oracle's large staff of consultants and support specialists with expertise in your business area, managing an Oracle8i server, and your hardware and software environment.

OracleMetaLink
OracleMetaLink is your self-service support connection with Web, telephone menu, and e-mail alternatives. Oracle supplies these technologies for your convenience, available 24 hours a day, 7 days a week. With OracleMetaLink, you can obtain

xvi

information and advice from technical libraries and forums, download patches, download the latest documentation, look at bug details, and create or update TARs. To use MetaLink, register at (http://rnetalink.oracle.com).

Alerts: You should check OracleMetaLink alerts before you begin to install or upgrade any of your Oracle Applications. Navigate to the Alerts page as follows: Technical Libraries/ERP Applications/Applications Installation and Upgrade/Alerts.

Self-Service Toolkit: You may also find information by navigating to the Self-Service Toolkit page as follows: Technical Libraries/ERP Applications/Applications Installation and Upgrade.

Do Not Use Database Tools to Modify Oracle Applications Data
Oracle STRONGLY RECOMMENDS that you never use SQL*Plus, Oracle Data Browser, database triggers, or any other tool to modify Oracle Applications data unless otherwise instructed.

Oracle provides powerful tools you can use to create, store, change, retrieve, and maintain information in an Oracle database. But if you use Oracle tools such as SQL*Plus to modify Oracle Applications data, you risk destroying the integrity of your data and you lose the ability to audit changes to your data.

Because Oracle Applications tables are interrelated, any change you make using Oracle Applications can update many tables at once. But when you modify Oracle Applications data using anything other than Oracle Applications, you may change a row in one table without making corresponding changes in related tables. If your tables get out of synchronization with each other, you risk retrieving erroneous information and you risk unpredictable results throughout Oracle Applications.

When you use Oracle Applications to modify your data, Oracle Applications automatically checks that your changes are valid. Oracle Applications also keeps track of who changes information. If you enter information into database tables using database tools, you may store invalid information. You also lose the ability to track who has changed your information because SQL*PIus and other database tools do not keep a record of changes.

About Oracle
Oracle Corporation develops and markets an integrated line of software products for database management, applications development, decision support, and office automation, as well as Oracle Applications, an integrated suite of more than 160

xvii

software modules for financial management, supply chain management, manufacturing, project systems, human resources and customer relationship management

Oracle products are available for mainframes, minicomputers, personal computers, network computers and personal digital assistants, allowing organizations to integrate different computers, different operating systems, different networks, and even different database management systems, into a single, unified computing and information resource.

Oracle is the world's leading supplier of software for information management, and the world's second largest software company. Oracle offers its database, tools, and applications products, along with related consulting, education, and support services, in over 145 countries around the world.

xviii

1

Introduction

The Oracle e-Business Suite contains the following types of APIs:

  • Private APIs are for internal, development use only. Details are not provided to anyone outside of the immediate development environment, nor are they intended for use by anyone outside of the e-Business Suite development environment.

  • Public APIs are designed for customers and Oracle consultants to integrate non-Oracle systems into Oracle e-Business Suite or to extend the functionality of the base products. Oracle does not support public APIs unless they are published in a reference manual such as this one. The user accepts all risk and responsibility for working with non-published public APIs.

  • Public, published APIs are guaranteed by Oracle to remain valid from release to release and that patches will not alter the API behavior. Public, published APIs are supported by Oracle to the same extent as released software.

For non-published APIs, Oracle expressly does not provide any guarantees regarding consistency of naming, usage, or behavior of any API (public or private) between releases. It is also possible that a patch could alter any characteristic of any non-published e-Business Suite API. As such, those who choose to use these APIs do so at their own risk. However, Oracle does attempt to minimize all changes to public APIs, even if not published.

Introduction 1-1

Parameter Specifications

Note: In Applications release 11.5.9, many of the Applications' PL/SQL server side APIs have been enhanced to utilize the pass by reference semantics of PL/SQL. This improves performance considerably and reduces memory consumption. In the normal processing case (i.e. success), there is no change of behavior, and callers of these APIs are not impacted. However, in the case of exceptions, there is a behavior change which results in assignments being exposed to the caller, which are made in the API prior to any exceptions being raised. The previous behavior would rollback these assignments made by the API if an exception occurred in this API. Developers writing custom extensions to Oracle Applications, or third party integrators which use the standard Applications' APIs should be aware of this change in semantics.

The Common Application Components APIs
The public APIs provided by the Oracle Common Application Components and described in this document are divided into groups of public packages. There are one or more packages for each of the following Oracle Common Application Components modules covered here:

  • Resource Manager
  • Task Manager
  • Notes

Each published API provides an API specification, and definitions as for its parameters, data structures, and status messages. Sample scripts and documented process flow diagrams are included where applicable.

Note: The words procedure and API are used interchangeably in this document

1.1 Parameter Specifications

The specifications for the public APIs provided by the Oracle Common Application Components define four categories of parameters:

  • Standard IN
  • Standard OUT

1-2 Oracle Common Application Components API Reference Guide

Parameter Specifications

  • Procedure specific IN
  • Procedure specific OUT

Standard IN and OUT parameters are specified by the Oracle Applications business object API Coding Standards, and are discussed in the following sections.

Procedure specific IN and OUT parameter are related to the API being specified, and are discussed with that individual API.

1.1.1 Standard IN Parameters

The following table describes standard IN parameters, which are common to all public APIs provided by Oracle Common Application Components.

Table 1-1 Standard IN Parameters
Parameter Data Type Required Description
p_api_version NUMBER Yes This must match the version number of the API. An unexpected error is returned if the calling program version number is incompatible with the current API version number (provided in the documentation).
p_init_msg_list VARCHAR2 Yes The valid values for this parameter are:
  • True = FND_API.G_TRUE
  • False = FND_API.G_FALSE
  • Default = FND_API.G_FALSE
If set to true, then the API makes a call to fnd_msg_pub.initialize to initialize the message stack. To set to true, use the value, "T".

If set to false then the calling program must initialize the message stack. This action is required to be performed only once, even in the case where more than one API is called. To set to false, use the value, "F".

Introduction 1-3

Parameter Specifications

Table 1-1 Standard IN Parameters
Parameter Data Type Required Description
p_commit VARCHAR2(1) No The valid values for this parameter are:
  • True = FND_API.G_TRUE
  • False = FND_API.G_FALSE
  • Default = FND_API.G_FALSE

If set to true, then the API commits before returning to the calling program. To set to true, use the value, "T".

If set to false, then it is the calling program's responsibility to commit the transaction. To set to false, use the value, "F".

1.1.2 Standard OUT Parameters

The following table describes standard OUT parameters, which are common to all public APIs provided by Oracle Common Application Components.

Note: All standard OUT parameters are required.

Table 1-2 Standard OUT Parameters
Parameter Data Type Description
x_return_status VARCHAR2(l) Indicates the return status of the API. The values returned are one of the following:
  • FND_API.G_RET_STS_SUCCESS
    Success: Indicates the API call was successful

  • FND_API.G_RET_STS_ERROR
    Expected Error: There is a validation error, or missing data error.

  • FND_API.G_RET_STS_UNEXP_ERROR
    Unexpected Error: The calling program can not correct the error.
x_msg_count NUMBER Holds the number of messages in the message list.

1-4 Oracle Common Application Components API Reference Guide

Parameter Specifications

Table 1-2 Standard OUT Parameters
Parameter Data Type Description
x_msg_data VARCHAR2(2000) Holds the encoded message if x_msg_count is equal to one.

1.1.3 Parameter Size
Verify the size of the column from the base table for that column when passing a parameter of a specific length. For example, if you pass a NUMBER value, first query to find the exact value to pass. An incorrect value can cause the API call to fail.

1.1.4 Missing Parameter Attributes
The following table describes optional IN parameters which are initialized to pre-defined values representing missing constants. These constants are defined for the common PL/SQL data types and should be used in the initialization of the API formal parameters.

Table 1-3 Initialized IN Parameters
Parameter Type Initialized Value
G_MISS_NUM CONSTANT NUMBER= 9.99E125
G_MISS_CHAR CONSTANT VARCHAR2(l):=chr(0)
G_MISS_DATE CONSTANT DATE:= TO_DATE('l','j');

These constants are defined in the package FND_API in the file fndpapis.pls. All columns in a record definition are set to the G_MISS_X constant as defined for the data type.

1.1.5 Parameter Validations
The following types of parameters are always validated during the API call:

  • Standard IN
  • Standard OUT
  • Mandatory procedure specific IN
  • Procedure specific OUT

Introduction 1-5

Version Information

1.1.6 Invalid Parameters
If the API encounters any invalid parameters during the API call, then one of the following actions will occur:

  • An exception is raised.
  • An error message identifying the invalid parameter is generated.
  • All API actions are cancelled.

1.2 Version Information
It is mandatory that every API call pass a version number for that API as its first parameter (p_api_version).

This version number must match the internal version number of that API. An unexpected error is returned if the calling program version number is incompatible with the current API version number.

Warning: The currently supported version at this time is 1.0. Use only this for the API version number.

In addition, the object version number must be input for all update and delete APIs.

  • If the object_version_ number passed by the API matches that of the object in the database, then the update is completed.

  • If the object_version_number passed by the API does not match that of the object in the database, then an error condition is generated.

1.3 Status Messages

Note: It is not required that all status notifications provide a number identifier along with the message, although, in many cases, it is provided.

Every API must return one of the following states as parameter x_return_status after the API is called:

  • S (Success)

1-6 Oracle Common Application Components API Reference Guide

Status Messages

  • E (Error)
  • U (Unexpected error)

Each state can be associated with a status message. The following table describes each state.

Table 1-4 Status Messsage and Description
Status Description
S Indicates that the API performed all the operations requested by its caller.
  • A success return status may or may not be accompanied by messages in the API message list.
  • Currently, the Oracle Common Application Components APIs do not provide a message for a return status of success.
E Indicates that the API failed to perform one or more of the operations requested by its caller.

An error return status is accompanied by one or more messages describing the error.

U Indicates that the API encountered an error condition it did not expect, or could not handle, and that it is unable to continue with its regular processing.
  • For example, certain programming errors such as attempting to divide by zero causes this error.
  • These types of errors usually cannot be corrected by the user and requires a system administrator or application developer to correct.

Warning and Information Messages
In addition to these three types of possible status messages, you can also code the following additional message types:

  • Warnings
  • Information

To create a warning message, perform the following steps:

  1. Create a global variable to be used to signal a warning condition. For example, this could be similar to the following:

    G_RET_STS_WARNING := 'W'

    This global variable is not part of the FND_API package.

Introduction 1-7

Status Messages

  1. Return this value if the warning condition is encountered. For example, using the same example as in step one, set up the following code in the API to process the warning condition:

    x_return_status := G_RET_STS_WARNING

    This code replaces the more usual:

    x_return_status := fnd_api.g_ret_sts_unexp_error for "U"

  2. If desired, perform, a similar procedure to create Information messages.

1-8 Oracle Common Application Components API Reference Guide