Skip Headers

Oracle Receivables Reference Guide
Release 12.1
Part Number E13512-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Using Oracle Receivables APIs

Major Features

Before you begin....

Initialization of ARP_STANDARD and ARP_GLOBAL

Custom code that uses AR or HZ APIs will set the ORG_ID via dbms_application_info.set_client_info() and then call the APIs. The APIs in turn might access either ARP_STANDARD and ARP_GLOBAL, which initialize the global variables that are used across Oracle Receivables when the package is first called. Most of these global variable values are organization dependent, and the first such call sets the global variables based on the current ORG_ID.

If additional custom code then changes the ORG_ID via another call to dbms_application_info.set_client_info(), then the ORG context changes, but the ARP_STANDARD and ARP_GLOBAL context does not.

In such cases, you should explicitly re-initialize the global variables by a call to these two public procedures:

  1. ARP_GLOBAL.INIT_GLOBAL: For setting public variables in ARP_GLOBAL.

  2. ARP_STANDARD.INIT_STANDARD: For setting public variables in ARP_STANDARD.

Flexibility

Per Oracle API coding standards, the various Oracle Receivables APIs let you specify an ID or its associated value for any attribute that is an INPUT parameter of the API.

If both an ID and value have been specified, then the ID takes precedence over the value. This provides a wide degree of flexibility when using the API, both as a base table of the form and as a server-side routine call from the PL/SQL code.

The extensive defaulting mechanism for the input parameters ensures that you will be able to achieve your basic business needs by calling the relevant APIs with a minimum number of parameters. This gives you many options to achieve your requirements when you call the relevant API.

Modular Approach

The API has been designed in a highly modular fashion, resulting in code that is:

Error Handling

Oracle Receivables APIs provide an extensive error-handling and error-reporting mechanism whereby all errors encountered in the Defaulting and Validation phases are reported and put on the message stack. The calling program can look up all error messages, or the first error message on the stack.

If only one error exists on the message stack, then you do not need to fetch the message from the stack because the message will return as one of the output parameters of the API routine.

Robust Validation

The validations that Oracle Receivables APIs perform are robust in nature. The APIs collect all encountered validation errors and put them on the message stack. The relevant entity handler is called only if no errors are reported during the Defaulting and Validation phases.

Debug Messages

Extensive debug messages have been incorporated to simplify the troubleshooting process when problems are encountered with any API.

Debug messages can be written to the log file by calling the appropriate routines described in Exception Handling and Result Messages.

Solution Outline

Modular Approach

To modularize an API, the basic structure of the API is divided into four parts:

  1. Defaulting the IDs from the values and cross validating, if you provide both the values and the IDs.

  2. Defaulting all the entity level information, which you have not entered or which the API needs internally.

  3. Validating the entity level information that you entered.

  4. Calling to the entity handlers to perform the relevant task.

This results in code that is easy to understand and easy to maintain. Any new functionality can be added by a simple code plug-in at each of the four parts.

Defaulting

In general, the various parameters in each API call get defaulted, if not entered, based on the following:

Depending on the above three factors and the exact business requirement, the minimum number of parameters required to perform certain business tasks may vary.

Null values are defaulted for the parameters that could not be defaulted by the API defaulting routines.

For various attributes of the business objects, you can pass either the ID or the value of the attribute.

If you specify only the value, then the value is used to derive the ID; otherwise, the ID (if specified) is taken directly. If you specify both the ID and the value, then the ID takes precedence over the value and a warning message informs you of this.

Exception Handling and Result Messages

Each Oracle Receivables API returns three types of information to its calling programs:

Return Status

The return status (x_return_status) of the API informs the caller about the result of the operation (or operations) performed by the API. The different possible values for an API return status are:

The following section describes the different values of return status and their meanings.

Success

A success return status means that the API was able to perform all the operations requested by its caller. A success return status may be accompanied by informative messages in the API message list.

Error

An error return status means that the API failed to perform some or all of the operations requested by its caller. An error return status is usually accompanied by messages describing the error (or errors) and how to fix it.

In most cases, you should be able to take corrective action to fix regular, expected errors such as missing attributes or invalid date ranges.

Unexpected error

An unexpected error status means that the API has encountered an error condition it did not expect or could not handle. In this case, the API is unable to continue with its regular processing. Examples of such errors are irrecoverable data inconsistency errors, memory errors, and programming errors (such as attempting a division by zero).

In most cases, only system administrators or application developers can fix these unexpected errors.

Messages

The APIs put result messages into a message list. Programs calling the APIs can then get the messages from the list and process them by issuing them, loading them into a database table, or writing them to a log file.

Messages are stored in an encoded format to let the API callers find message names using the standard functions provided by the message dictionary. It also allows the storing of these messages in database tables and reporting off these tables in different languages.

The API message list must be initialized every time a program calls an API. API callers can either call the message list utility function FND_MSG_PUB.Initialize or request that the API do the initialization on their behalf by setting the p_init_msg_list parameter to TRUE.

The program calling the API can retrieve messages from the message stack using the existing FND API functions FND_MSG_PUB.Count_Msg and FND_MSG_PUB.Get.

Message Level Threshold

The message level threshold is stored in a profile option named FND_API_MSG_LEVEL_THRESHOLD. This profile option can be updated at all levels (site, application, or user). The API checks against this threshold before writing a message to the API message list.

Debug Messages

You must enable debugging by calling the routine arp_standard.enable_file_debug. The routine requires 2 parameters: path_name and file_name.

arp_standard.enable_file_debug(<pathname>, <filename>)

The path name can be identified by using the following select statement:

select value from v$parameter where name = 'utl_file_dir',

The file name can be any name that you choose.

Example

arp_standard.enable_file_debug ('/sqlcom/log','txt.log')

This call would write the output debug file 'txt.log' in the path '/sqlcom/log'.

Calling Program Context

The program calling these APIs should have set up the application, responsibility, and user in the context of Oracle Application.

If the calling program does not set up this context, then it can be done programmatically by calling the following FND API.

fnd_global.apps_initialize (  user_id in number, 
                              resp_id in number, 
                              resp_appl_id in number, 
                              security_group_id in number default 0);