There are several steps to implementing Message Dictionary in your application:

1. Create your message directories

2. Define your messages

3. Create your message files

4. Code logic to set up messages

5. Code logic to display messages

On most operating systems, you should create a special subdirectory to hold your Message Dictionary files for your application. You must create your message directory (or some other location for your messages if your operating system does not support directories) before you define your messages so Oracle Application Object Library can store your message files. In general, name your subdirectory mesg, and create it directly under your application's base directory (exactly how you create a location for your Message Dictionary files depends on your operating system). You should have a mesg directory for your application on each machine where you have a directory structure for your application (concurrent processing servers, forms server machines).

See: Setting Up Your Application Framework

Use the Messages window to define your message information. You can include variable tokens in your message text when you define your messages. Message Dictionary inserts your values in the message automatically when it displays your message.

You can modify your messages at any time using the Messages window. If you want to change your message text, you need only change it once, instead of the many times your application may call it. You do not need to regenerate your forms or recompile your programs when you change your messages.

See: Message Standards and Messages Window.

Use the Generate Messages concurrent program to generate your runtime message files, such as US.msb.

To use the program to generate your message files:

1. Using the Application Developer responsibility, navigate to the Submit Requests window.

2. Select the Generate Messages concurrent program in the Name field.

3. In the Parameters window, select the language code for the language file you want to generate (for example, US for American English).

4. Provide the appropriate application name for the message file you wish to create. Each application must have its own message file.

5. Select the mode for the program. To generate your runtime message file, choose DB_TO_RUNTIME.

   To generate human-readable text files that can be edited and loaded back into the database (or into different databases), you must use the FNDLOAD utility with the configuration file FNDMDMSG.lct.

   For more information, see the Oracle Applications System Administrator's Guide.

6. Leave the Filename parameter blank, as the message generator will create a file with a standard name (such as US.msb) in the mesg directory for your application on the server side (or an equivalent location for your platform).

7. Make a copy of the resulting file (which is on the server side), and transfer the copy to the appropriate mesg directory for your application on other machines as needed (concurrent processing servers, forms server machines). The file should have the same name (such as US.msb) in each location.

Command Line Interface

On UNIX systems, you can also use a command line interface to generate your message files (such as US.msb):

FNDMDGEN <Oracle ID> 0 Y <language codename> <application shortname> DB_TO_RUNTIME

where Oracle ID is the username and password of the APPS schema and language codename is a language code such as US.

To generate human-readable text files that can be edited and loaded back into the database (or into different databases), you must use the FNDLOAD utility with the configuration file FNDMDMSG.lct.

Generating a message and showing it to a user is a two-step process: first you must set up the message (on the client side) or retrieve it from the server side, and then you must display it to the user (or write it to a file for a concurrent program). This section covers the setup part of the process.

When your application calls Message Dictionary, Message Dictionary finds the message associated with your application and the message name you specify, and replaces any variable tokens with your substitute text. If a concurrent process generates the message, depending on which routine it calls, Message Dictionary either writes the message to the concurrent program log or out file, or returns your message to your concurrent program so your program can write it to the log or out file. You can call Message Dictionary from any form or C concurrent program.

Client-side APIs for Retrieving and Setting up Messages

The following routines in the FND_MESSAGE package are used in client-side (that is, Oracle Forms) PL/SQL procedures to retrieve and set up messages for subsequent display.

Server-side APIs for Messaging

The following server-side routines are used to buffer a message (and if necessary, token/value pairs) so that a client-side PL/SQL Procedure (that is, one called from Oracle Forms) can retrieve and display it. Only one message can be buffered on the server.

Once you have set up or retrieved the message and substituted any tokens, you can then display it to a user (on the forms server side; that is, in forms) or write it to a file (on the database server side for a concurrent program).

Forms Server-side APIs for Displaying Messages

The following routines are used in PL/SQL procedures in forms and libraries to display messages. Each of these routines displays the message placed on the message stack by the most recent FND_MESSAGE.SET_NAME or FND_MESSAGE.RETRIEVE call in your program.

The FND_MESSAGE.ERROR, FND_MESSAGE.SHOW, FND_MESSAGE.WARN, and FND_MESSAGE.QUESTION routines each display a message in a forms modal window (on the client side). The primary difference between these routines is the icon they display next to the message in a forms modal window. For each routine, the icon is designed to convey a particular meaning. You should choose which routine to use based on the type of message you wish to display. For example, you should use the FND_MESSAGE.ERROR routine to display error messages, the FND_MESSAGE.SHOW routine to display informational messages, and so on.

Note that the look of the icons that the FND_MESSAGE.ERROR, FND_MESSAGE.SHOW, FND_MESSAGE.WARN, and FND_MESSAGE.QUESTION routines display is platform-dependent.

Methods for Database Server-side Messaging

Database server-side PL/SQL currently has no I/O abilities by itself. Therefore, it relies on the environment that called the server-side routine to output the message.

There are three distinct, non-interchangeable methods for displaying messages that were set on the server:

Method 1: Set an error message on the server, to be displayed by the forms client that called the server procedure.

On the server, use FND_MESSAGE.SET_NAME and FND_MESSAGE.SET_TOKEN to set the message. Then call APP_EXCEPTION.RAISE_EXCEPTION (an APPCORE routine) to raise the application error PL/SQL exception. This exception is trapped when the server procedure is exited and control resumes on the client side in the standard Oracle Forms ON_ERROR trigger. The ON-ERROR trigger retrieves the message from the server and displays it.

Method 2: Set a message on the server, to be retrieved on the client side.

On the server, use FND_MESSAGE.SET_NAME and FND_MESSAGE.SET_TOKEN to set the message. Return a result code to the calling client code to indicate that a message is waiting. If there is a message waiting, the client calls FND_MESSAGE.RETRIEVE to pull the message from the server to the client, placing the message on the client's message stack. The client calls FND_MESSAGE.ERROR, FND_MESSAGE.SHOW, FND_MESSAGE.HINT, or FND_MESSAGE.WARN to display the message, or FND_MESSAGE.GET to retrieve the message to a buffer.

Method 3: Get a message into a buffer on the server

Use the FND_MESSAGE.SET_NAME, FND_MESSAGE.SET_TOKEN, and FND_MESSAGE.GET routines to get the message into a buffer. Or, use FND_MESSAGE.GET_STRING to get a single message into a string.

Calling Message Dictionary From Concurrent Programs

If you call Message Dictionary routines from your concurrent programs, the messages are treated differently according to the routine you use, as shown in the following table: