This chapter covers the following topics:
The Resource Manager 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 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). 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.
Note: Earlier, many of the Oracle E-Business Suite's' 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 E-Business Suite, or third party integrators which use the standard Oracle E-Business Suite's APIs should be aware of this change in semantics.
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.
The specifications for the public APIs provided by the Resource Manager define four categories of parameters:
Standard IN
Standard OUT
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.
The following table describes standard IN parameters, which are common to all public APIs provided by Resource Manager.
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:
|
p_commit | VARCHAR2(1) | No | The valid values for this parameter are:
|
The following table describes standard OUT parameters, which are common to all public APIs provided by Resource Manager.
Note: All standard OUT parameters are required.
Parameter | Data Type | Description |
---|---|---|
x_return_status | VARCHAR2(1) | Indicates the return status of the API. The values returned are one of the following:
|
x_msg_count | NUMBER | Holds the number of messages in the message list. |
x_msg_data | VARCHAR2(2000) | Holds the encoded message if x_msg_count is equal to one. |
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.
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.
Parameter | Type | Initialized Value |
---|---|---|
g_miss_num | CONSTANT | NUMBER:= 9.99E125 |
g_miss_char | CONSTANT | VARCHAR2(1):= chr(0) |
g_miss_date | CONSTANT | DATE:= TO_DATE('1','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.
The following types of parameters are always validated during the API call:
Standard IN
Standard OUT
Mandatory procedure specific IN
Procedure specific OUT
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.
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.
Every API must return one of the following states as parameter x_return_status after the API is called:
S (Success)
E (Error)
U (Unexpected error)
Note: It is not required that all status notifications provide a number identifier along with the message, although, in many cases, it is provided.
Each state can be associated with a status message. The following table describes each state.
Status | Description |
---|---|
S | Indicates that the API performed all the operations requested by its caller.
|
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.
|
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:
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.
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"
If desired, perform a similar procedure to create Information messages.