Message Dictionary

Overview of Message Dictionary

Message Dictionary lets you catalog messages for display from your application without hardcoding them into your forms and programs. Using Message Dictionary, you can:

Major Features

Modifiable Message Text

Message Dictionary makes it easy for you to modify your messages. All your message text is available from one simple form, and you do not need to regenerate your forms or recompile your programs if you change your message text.

Message Dictionary displays your application messages in a format you choose. For example, you can display your messages in a dialog box or on the message line. You can also display messages without codes, such as warnings that have an intuitive remedy or do not need one.

Easy Translation

Message Dictionary facilitates translation of your messages by allowing you to easily modify your messages and by allowing you to define message notes for each message. Message Dictionary saves you time because you do not need to regenerate your forms or recompile your programs after translation of message text.

Standardized Messages

Message Dictionary lets you create standardized messages you can use in your application. Message Dictionary reduces redundant programming of standard messages by storing all of your messages as entries in Message Dictionary. Once you define your messages in the Message Dictionary, you can refer to them in your forms, concurrent programs, and other application modules using a simple message name you define. You can call the same message many times, from anywhere in your application. If you need to change your message, you only need to change it in one place.

Dynamic Message Text

Message Dictionary lets you include information in your message that Oracle Application Object Library derives at runtime. You can define your messages to accept variable text such as field values or module names. You specify the values of the variable message parts when you call Message Dictionary from a form or other application module. Message Dictionary inserts these values in the message before it returns the message to you. You can also include a field reference in your message call from a form, displaying the field's value in the message your user sees.

Definitions

Message Name

A non-updatable internal identifier for a message in your application. A message name can be up to 30 characters of text. A message name, together with your application name and language name, uniquely identifies your message text. You specify the message name when you call Message Dictionary from a form or program module.

Message

Text your application displays or prints to an output file. You can define your message to be up to about 1800 characters long (about 1260 in English to allow for translation into longer languages such as German).

Message Number

A number that appears with your message. If you define a non-zero message number for your message, Message Dictionary automatically prepends your message with the prefix APP- (or its translated equivalent).

Variable Token

A keyword you create to represent a value when you define a message. You specify the same variable token, along with its current value, when you call Message Dictionary from your form or program module. Message Dictionary replaces each variable token in your message with the current value you specify and then displays the message.

Implementing Message Dictionary

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

Create Your Message Directories

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

Define Your Messages

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.

Create Your Message Files

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 Oracle E-Business Suite Setup 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.

Code Logic to Set Up Messages

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.

Variable Description
SET_NAME Retrieves your message from Message Dictionary and sets it on the message stack.
SET_STRING Takes an input string and sets it on the message stack.
SET_TOKEN Substitutes a message token with a value you specify.
RETRIEVE Retrieves a message from the server-side message buffer, translates and substitutes tokens, and sets the message on the message stack.
GET (function) Retrieves a message from the message stack and returns a VARCHAR2.
CLEAR Clears the message stack.

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.

Variable Description
SET_NAME Sets a message name in the global area without actually retrieving the message from Message Dictionary.
SET_TOKEN Adds a token/value pair to the global area without actually doing the substitution.
CLEAR Clears the message stack.

Code Logic to Display Messages

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.

Variable Description
ERROR Displays an error message in a forms modal window or a concurrent program log file. (Example: “Invalid value entered.")
SHOW Displays an informational message in a forms modal window or a concurrent program log file. (Example: “To complete this function, please enter the following... ")
WARN Displays a warning message in a forms modal window and allows the user to either accept or cancel the current operation. (Example: “Do you wish to proceed with the current operation?")
QUESTION Displays a message and up to three buttons in a forms modal window. (Example: “Please choose one of the following actions.")
HINT Displays a message in the forms status line.
ERASE Clears the forms status line.

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.

Important: All forms built to integrate with Oracle E-Business Suite should have a form-level ON-ERROR trigger that calls APP_STANDARD.EVENT('ON-ERROR'). APP_STANDARD.EVENT('ON-ERROR') in the ON-ERROR trigger automatically detects application errors raised on the server and retrieves and displays those error messages in a forms alert box.

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:

Message Handling By Routine
Routine Output Destination Message Numbers Messages Displayed
SHOW out file Not printed One; top of stack
ERROR log file Printed if nonzero One; top of stack

Message Dictionary APIs for PL/SQL Procedures

This section describes Message Dictionary APIs you can use in your PL/SQL procedures. This section also includes examples of PL/SQL procedure code using these Message Dictionary APIs.

Some of these PL/SQL procedures have C code analogs that you can use for concurrent programs written in C. The syntax for the C code API is included at the end of the PL/SQL API routine description. All of the Message Dictionary C routines require the use of the fddutl.h header file.

FND_MESSAGE.CLEAR

Variable Description
Summary procedure FND_MESSAGE.CLEAR;
Location FNDSQF library and database (stored procedure)
Description Clears the message stack of all messages.

FND_MESSAGE.DEBUG

Variable Description
Summary 
 procedure FND_MESSAGE.DEBUG      
 (value    IN varchar2);
Location FNDSQF library
Description Immediately show a string. This procedure is normally used to show debugging messages only, not messages seen by an end user. The string does not need to be defined in the Messages window. These strings may be hardcoded into the form and are not translated like messages defined in Message Dictionary.
value The string to display.

Here is an example:

 /* as the last part of an item handler */
       ELSE 
          fnd_message.debug('Invalid event passed to
              ORDER.ITEM_NAME: ' || EVENT); 
       END IF;

FND_MESSAGE.ERASE

Variable Description
Summary procedure FND_MESSAGE.ERASE;
Location FNDSQF library
Description Clears the Oracle Forms status line.

Tip: Due to the way that Oracle Forms handles I/O to the status line, changes made to the status line with HINT or ERASE may not appear immediately if the call is made in the middle of some PL/SQL routine that does not involve user input. In such cases it may be necessary to use the forms Synchronize built-in to force the message to get displayed on the status line.

FND_MESSAGE.ERROR

Variable Description
Summary procedure FND_MESSAGE.ERROR;
Location FNDSQF library
Description Displays an error message in an Oracle Forms modal window or a concurrent program log file. (Example: “Invalid value entered.")
FND_MESSAGE.ERROR takes its message from the stack, displays the message, and then clears all the messages from the message stack.

Here is an example:

/* Display an error message with a translated token */
FND_MESSAGE.SET_NAME ('FND', 'FLEX_COMPILE_ERROR');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', 'TRANS_PROC_NAME', TRUE);
FND_MESSAGE.ERROR;
  /* Then either raise FORM_TRIGGER_FAILURE, or exit  
     routine*/
Variable Description
C Code API 
boolean afderror(/*_ void _*/);
Requires the fddutl.h header file.

FND_MESSAGE.GET

Variable Description
Summary 
function FND_MESSAGE.GET 
        return varchar2;
Location FNDSQF library and database (stored function)
Description Retrieves a translated and token-substituted message from the message stack and then clears that message from the message stack. This could be used for getting a translated message for a forms built-in or other function. Assumes you have already called FND_MESSAGE.SET_NAME and, if necessary, FND_MESSAGE.SET_TOKEN. GET returns up to 2000 bytes of message.
If this function is called from a stored procedure on the database server side, the message is retrieved from the Message Dictionary table. If the function is called from a form or forms library, the message is retrieved from the messages file on the forms server.
If you are trying to get a message from a stored procedure on the database server side to a form, you should use FND_MESSAGE.SET_NAME and, if necessary, FND_MESSAGE.SET_TOKEN in the stored procedure. The form should use Method 1 or Method 2 described earlier to obtain the message from the stored procedure. You should not use FND_MESSAGE.GET in the stored procedure for this case.

Example

/* Get translated string from message file */
declare 
   msg varchar2(2000);
begin
   FND_MESSAGE.SET_NAME ('FND', 'A_2000_BYTE_MSG');
   msg := FND_MESSAGE.GET;
end; 
  /*  We now have a translated value in the msg variable
      for forms built-in or other function */
Variable Description
C Code API Pass this function a buffer and tell it the size, up to 2001 bytes (including the null terminator), of the buffer in bytes. 
boolean afdget(/*_text *msg_buf, size_t buf_size _*/);

Requires the fddutl.h header file.

FND_MESSAGE.HINT

Variable Description
Summary 
procedure FND_MESSAGE.HINT;
Location FNDSQF library
Description Displays a message in the Oracle Forms status line. FND_MESSAGE.HINT takes its message from the stack, displays the message, and then clears that message from the message stack.
The user may still need to acknowledge the message if another message immediately comes onto the message line.

FND_MESSAGE.QUESTION

Variable Description
Summary 
 (button1    IN varchar2 default 'YES',
  button2 IN varchar2 default 'NO', 
  button3 IN varchar2 default 'CANCEL',
  default_btn IN number   default  1,
  cancel_btn  IN number   default  3, 
  icon        IN varchar2 default 'question'
 ) return number;
Location FNDSQF library
Description Displays a message and up to three buttons in an Oracle Forms modal window. (Example: “Please choose one of the following actions: ")
FND_MESSAGE.QUESTION takes its message from the stack, and clears that message. After the user selects a button, FND_MESSAGE.QUESTION returns the number of the button selected.
For each button, you must define or use an existing message in Message Dictionary (under the Oracle Application Object Library application) that contains the text of the button. This routine looks for your button name message in the Oracle Application Object Library messages, so when you define your message, you must associate it with Oracle Application Object Library (the “FND" application) instead of your application.
If there is no message defined for the button, the button text defaults to the message name. You must specify the message name in all uppercase so it will be easier to identify missing messages (if the message is missing, the button text will not be translated).
Arguments (input) button1 - Specify the message name that identifies the text for the button to the right of the default button. According to standard, this button serves as the "cancel" button. This name is identical to the message name you use when you define your button text using the Messages form.
button2 - Specify the message name that identifies the text for an additional button (that is, not the default button or cancel button). This name is identical to the message name you use when you define your button text using the Messages form.
button3 - Specify the message name that identifies the text for your default button, or leftmost button. This name is identical to the message name you use when you define your button text using the Messages form.
default_btn - Specify the number of the button that will be pressed when the user presses the "default" keyboard accelerator (usually the return or enter key). Passing NULL makes button 1 be the default.
cancel_btn - Specify the number of the button that will be pressed when the user presses the "cancel" keyboard accelerator (usually the escape key). Passing NULL makes no buttons get pressed by the "cancel" keyboard button.
icon - Specify the icon to display in the decision point box. If you do not specify an icon, a standard FND_MESSAGE.QUESTION icon is displayed. Standard icons you can use include STOP, CAUTION, QUESTION, NOTE, and FILE. In addition, you can use any icon in the AU_TOP/resource directory on your platform.

For more information on button placement and rendering, see: Buttons, Oracle E-Business Suite User Interface Standards for Forms-Based Products.

Important: Specifying no buttons produces a “Yes/No/Cancel" three-button display. Specifying one button displays that button as the first button, and defaults the second button to “Cancel". Button 1 appears on the lower right of the window, Button 2 to the left of Button 1, and Button 3 to the left of Button 2.

button3              button2         button1

To specify two buttons without a cancel button, pass in arguments of '<FIRST_OPTION>', '<SECOND_OPTION>', and NULL.

Example 1

/* Display a message with two buttons in a modal window */
FND_MESSAGE.SET_NAME('INV', 'MY_PRINT_MESSAGE');
FND_MESSAGE.SET_TOKEN('PRINTER', 'hqunx138');
FND_MESSAGE.QUESTION('PRINT-BUTTON');
  /* If 'PRINT-BUTTON' is defined with the value “Print",
     the user sees two buttons: “Print", and “Cancel".  */

Example 2

/* Display a message with three buttons in a modal window.
   Use the Caution icon for the window. */

FND_MESSAGE.SET_NAME('FND', 'DELETE_EVERYTHING');
FND_MESSAGE.QUESTION('DELETE', NULL, 'CANCEL', 1, 3, 'caution');

Example 3

/* Display a message with two buttons in a modal window.
   "Yes" and "No" */

FND_MESSAGE.SET_NAME('FND', 'REALLY');
FND_MESSAGE.QUESTION('YES', 'NO', NULL);

FND_MESSAGE.RETRIEVE

Variable Description
Summary procedure FND_MESSAGE.RETRIEVE;
Location FNDSQF library
Description Retrieves a message from the database server, translates and substitutes tokens, and sets the message on the message stack.

Example

/* Retrieve an expected message from the server side,
   then show it to the user */
FND_MESSAGE.RETRIEVE;
FND_MESSAGE.ERROR;
  /* Then either raise FORM_TRIGGER_FAILURE, or exit  
     routine*/

FND_MESSAGE.SET_NAME

Variable Description
Summary 
 (application    IN varchar2,
          name           IN varchar2);
Location FNDSQF library and database (stored procedure)
Description (Forms) Retrieves your message from Message Dictionary and sets it on the message stack. You call FND_MESSAGE.SET_NAME once for each message you use in your client-side PL/SQL procedure. You must call FND_MESSAGE.SET_NAME before you call FND_MESSAGE.SET_TOKEN.
Description (Database Server) Sets a message name in the global area without actually retrieving the message from Message Dictionary.
Arguments (input) application - The short name of the application this message is associated with. This short name references the application you associate with your message when you define it using the Messages form.
name - The message name that identifies your message. This name is identical to the name you use when you define your message using the Messages form. Message Dictionary names are not case sensitive (for example, MESSAGE_NAME is the same name as message_name).

Example 1

/* Display a warning, asking OK/Cancel question */
FND_MESSAGE.SET_NAME ('FND', 'WANT_TO_CONTINUE');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', 'Compiling this flexfield');
if (FND_MESSAGE.WARN) then
  /* User selected OK, so add appropriate logic ... */

Example 2

/* Display a warning, asking OK/Cancel question */
FND_MESSAGE.SET_NAME ('FND', 'WANT_TO_CONTINUE');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', translated_text_vbl);
if (FND_MESSAGE.WARN) then
  /* User selected OK, so add appropriate logic ... */

Example 3

/* Show an informational message */
FND_MESSAGE.SET_NAME ('FND', 'COMPILE_CANCELLED');
FND_MESSAGE.SHOW;

Example 4

/* This code is on the server.  It sets up a message and
   then raises an error so the client will retrieve the
   message and display it to the user */
FND_MESSAGE.SET_NAME ('FND', 'FLEX_COMPILE_ERROR');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', 'My Procedure');
APP_EXCEPTION.RAISE_EXCEPTION;

FND_MESSAGE.SET_STRING

Variable Description
Summary 
 procedure FND_MESSAGE.SET_STRING
(value    IN varchar2);
Location FNDSQF library
Description Takes an input string and sets it directly on the message stack. The string does not need to be defined in the Messages window. These strings may be hardcoded into the form and are not translated like messages defined in Message Dictionary.
Arguments (input) value - Indicate the text you wish to place on the message stack.

Example 1

/* Set up a specific string (from a variable) and show it */
FND_MESSAGE.SET_STRING (sql_error_message);
FND_MESSAGE.ERROR;

Example 2

/* Set up a specific string and show it */
FND_MESSAGE.SET_STRING ('Hello World');
FND_MESSAGE.SHOW;

FND_MESSAGE.SET_TOKEN

Variable Description
Summary 
procedure FND_MESSAGE.SET_TOKEN
         (token          IN varchar2,
          value          IN varchar2,
          translate      IN boolean default FALSE);
Location FNDSQF library and database (stored function)
Description (Forms) Substitutes a message token with a value you specify. You call FND_MESSAGE.SET_TOKEN once for each token/value pair in a message. The optional translate parameter can be set to TRUE to indicate that the value should be translated before substitution. (The value should be translated if it is, itself, a Message Dictionary message name.)
Description (Database Server) Same behavior as for client-side FND_MESSAGE.SET_TOKEN, except that adds a token/value pair to the global area without actually doing the substitution.
Arguments (input) token - Specify the name of the token you want to substitute. This token name is identical to the token name you use when you define your message using the Messages form. Though you specify & before each of your variable tokens when you define messages, you should not include the & in your Message Dictionary calls.
value - Indicate your substitute text. You can include as much substitute text as necessary for the message you call. You can specify a message name instead of actual substitute text. You must also specify TRUE for the translate argument in this case. If you are passing a Message Dictionary message this way, Message Dictionary looks for the message under the application specified in the preceding call to FND_MESSAGE.SET_NAME.
translate - Indicates whether the value is itself a Message Dictionary message. If TRUE, the value is "translated" before substitution; that is, the value is replaced with the actual Message Dictionary message text. Note that if the "token message" in turn contains a token, that token will not be substituted (that is, you cannot have "cascading substitution").

Example 1

/* Display a warning, asking OK/Cancel question */
FND_MESSAGE.SET_NAME ('FND', 'WANT_TO_CONTINUE');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', 'Compiling this flexfield');
if (FND_MESSAGE.WARN) then
  /* User selected OK ... */

Example 2

/* Display a warning, asking OK/Cancel question */
FND_MESSAGE.SET_NAME ('FND', 'WANT_TO_CONTINUE');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', translated_text_vbl);
if (FND_MESSAGE.WARN) then
  /* User selected OK ... */

Example 3

/* Display an error message with a translated token */
FND_MESSAGE.SET_NAME ('FND', 'FLEX_COMPILE_ERROR');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', 'TRANS_PROC_NAME', TRUE);
FND_MESSAGE.ERROR;
  /* Then either raise FORM_TRIGGER_FAILURE, or exit  
     routine*/

C Code API

The C code equivalent to SET_TOKEN(token_name, token_value, FALSE) is:

boolean afdtoken(/*_ text *token_name,
                  text *token_value _*/);

The C code equivalent to SET_TOKEN(token_name, token_value, TRUE) is:

boolean afdtrans(/*_ text *token_name,
                 text *token_value _*/);

The C code equivalent to SET_TOKEN(token_name, token_value, FALSE for number val* is:

boolean afdtkint(/*_ text *token_name, sb4 token_value _*/);

Requires the fddutl.h header file.

FND_MESSAGE.SHOW

Variable Description
Summary 
procedure FND_MESSAGE.SHOW;
Location FNDSQF library
Description Displays an informational message in an Oracle Forms modal window or a concurrent program log file. (Example: “To complete this function, please enter the following... ")
FND_MESSAGE.SHOW takes its message from the stack, displays the message, and then clears only that message from the message stack.

Example

/* Show an informational message */
FND_MESSAGE.SET_NAME ('FND', 'COMPILE_CANCELLED');
FND_MESSAGE.SHOW;
Variable Description
C Code API boolean afdshow(/*_ void _*/);
Requires the fddutl.h header file.

FND_MESSAGE.WARN

Variable Description
Summary 
function FND_MESSAGE.WARN          return boolean;
Location FNDSQF library
Description Displays a warning message in an Oracle Forms modal window and allows the user to either accept or cancel the current operation. (Example: “Do you wish to proceed with the current operation?")
FND_MESSAGE.WARN returns TRUE if the user accepts the message (that is, clicks OK), or FALSE if the user cancels.
FND_MESSAGE.WARN takes its message from the stack, displays the message, and clears that message from the message stack.

Example

/* Display a warning, asking OK/Cancel question */
FND_MESSAGE.SET_NAME ('FND', 'WANT TO CONTINUE');
FND_MESSAGE.SET_TOKEN ('PROCEDURE', 'Compiling this flexfield');
IF (FND_MESSAGE.WARN) THEN
  /* User selected OK, so add appropriate logic ... */ 
ELSE
  /* User selected Cancel, so add appropriate logic ... */ 
END IF;
Variable Description
C Code API boolean afdwarn(/*_ void _*/ );
Requires the fddutl.h header file.

Application Message Standards

Oracle E-Business Suite use messages to communicate with users. Typical messages include warnings and error messages, brief instructions, and informative messages that advise your user about the progress of concurrent requests, work done, and anything else of interest or helpful to users. Forms-based applications display messages on the user's screen; applications also print messages to output and log files.

Messages are part of the product, and should be treated with the same amount of care and attention to the user interface as a form. These message standards help you write messages that are brief, clear, and informative. When you follow these standards and use Message Dictionary, your application provides messages that are easy to understand, document, edit, and translate into other languages, resulting in an application that is easy to support and enhance.

Definitions

Message Type

A message type classifies your message as an Error, Prompt, and so on. Generally speaking, error messages display information about problems, while hint messages display helpful information that appears during the normal use of your form.

Error Message

An error message contains substantive information about your application that a user should consider and acknowledge. An error message does not always indicate a malfunction or user mistake. It may simply be a warning.

Most commonly, an error message informs your user of an invalid entry or action, or it reports a function that is not operating correctly.

Message Name

A message name is an internal identifier for a message in your application. A message name can be up to 30 characters long.

A message name, together with your application name and language name, uniquely identifies your message. You specify the message name when you call Message Dictionary from a form or program module.

Message Prefix

A message prefix is a short code that automatically precedes your message number and text for those messages that have numbers. The standard message prefix is APP:<application short name>.

Message Number

A message number is a number that precedes your message when your message is displayed to users. A message number is not changed by translators. The message number also helps your user determine which application generates a message, and helps your user to locate a message in the documentation.

If you define a message number for your message, Message Dictionary automatically precedes your message with the Oracle message standard "APP:<application short name>-nnnnn", where APP is a standard message prefix for Oracle E-Business Suite and nnnnn is your message number. Your message number may be up to 5 digits long. For example, your user might see "APP:SQLGL-0032 Please enter ..." for an Oracle General Ledger message.

Message Description

The Description field in the Messages form describes your message for other developers and translators. You can enter up to 230 characters of text in your message description. Typically this field contains information for translators about the context of your message.

Variable Token

A variable token, also called a substitute token, acts as a placeholder when you define message text. When Message Dictionary displays a message, it substitutes a developer-specified value for each variable token, allowing you to create dynamic messages.

Boilerplate

Boilerplate is any fixed text contained in a form. Boilerplate includes form titles, zone titles, region titles, and field prompts.

Message Naming Standards

The following suggested standards provide a consistent naming convention for message names.

Use a group identifier as the second word in each message name

Include a group identifier that indicates the functional area or organizational function that your message addresses. Your group identifier should correspond to the group identifier you use in your form names, which helps break your set of messages into smaller, manageable chunks.

Examples
Correct Incorrect
FND_FLEX_SEGMENT_NOT_REGISTERED [group identifier is FLEX, for Flexfields]
FND_MD_MESSAGE_NOT_FOUND [group identifier is MD, for Message Dictionary]		 FND_MESSAGE_NOT_FOUND

Some examples of message names are:

Message Numbering Standards

Oracle E-Business Suite products all have assigned message number ranges. These ranges, and messages that have non-zero numbers appear in the Oracle E-Business Suite Messages Manual. Messages without numbers are not included.

Here are some guidelines to help you decide whether to use a number.

Messages That Require Numbers

If the answers to any of the following questions are yes, the message probably needs a number:

Messages That Should Not Have Numbers

If the answers to any of the following questions are yes, the message probably does not need a number:

Custom Applications and Other Products

For custom applications and third-party products not included in the published message number ranges, we recommend that you avoid using message numbers 0-2999. Those are Oracle Application Object Library messages that appear in cross-product features such as flexfields and concurrent processing, and they may appear in your own applications.

In general, it may be useful to avoid duplicating any numbers that appear in Oracle E-Business Suite products even though there is no technical requirement to avoid duplication. Keeping your custom messages numerically separate from Oracle E-Business Suite messages may help users distinguish whether a problem stems from an Oracle E-Business Suite product or a custom application, and help them decide where they should seek assistance for problems.

If you want to avoid clashing with numbers that Oracle E-Business Suite products use or may use in the foreseeable future, we recommend that you number messages using 400000 (400,000) and up (the largest possible message number is about 2 billion).

Message Type Standards

Message type is used primarily for translation purposes. The correct message type (Error, Title, and so on) allows translators to distinguish between text that can be translated without worrying about length expansion, such as error messages, and text that has strict expansion limits, such as field prompts for a form. Note that for Oracle E-Business Suite Release 12 messages in English, one character is equivalent to one byte, but in other languages one character may require more than one byte.

Variable Description
Error Type is ERROR in script file. Use for error and warning messages. Messages with the Error type can be up to 1260 characters long in English and allow a translation length expansion up to a maximum length of 1800 bytes (at least 30% allowed expansion). Messages with the Error type should have a message number.
Note Type is NOTE in script file. Use for informational or instructional messages (typically messages displayed using FND_MESSAGE.SHOW). Messages with the Note type can be up to 1260 characters long in English and allow a translation length expansion up to a maximum length of 1800 bytes (at least 30% allowed expansion). Messages with the Note type should usually not have a message number.
Hint Type is HINT in script file. Use for informational or instructional messages (typically messages displayed using FND_MESSAGE.HINT). Messages with the Hint type can be up to 190 characters long in English and allow a translation length expansion up to a maximum length of 250 bytes (at least 30% allowed expansion).
Title Type is TITLE in script file. Use for window titles, report titles, report group titles, graph titles, and so on. Messages with the Title type can be up to 61 characters long in English and allow a translation length expansion up to a maximum length of 80 bytes (at least 30% allowed expansion).
30% Expansion Prompt Type is 30_PCT_EXPANSION_PROMPT in script file. Use for field prompts, report column labels, graph labels, and so on, where space has been allowed for up to 30% expansion during translation (allowing for a mimimum of 10 bytes after translation, except for approved phrases and abbreviations). For example, a 23-character field prompt in English would be allowed to expand to 30 bytes when translated. Most prompts and boilerplate should use this type. However, if you have more expansion space available on your form or layout, use the appropriate type (50% or 100% Expansion Prompt), especially for short prompts.
50% Expansion Prompt Type is 50_PCT_EXPANSION_PROMPT in script file. Use for field prompts, report column labels, graph labels, and so on, where space has been allowed for up to 50% expansion during translation (allowing for a mimimum of 10 bytes after translation). For example, a 10-character field prompt in English would be allowed to expand to 15 bytes when translated.
100% Expansion Prompt Type is 100_PCT_EXPANSION_PROMPT in script file. Use for field prompts, report column labels, graph labels, and so on, where space has been allowed for up to 100% expansion during translation (allowing for a mimimum of 10 bytes after translation). For example, a 6-character field prompt in English would be allowed to expand to 12 bytes when translated.
Menu Entry Type is MENU in script file. Use for menu entries, such as choices on the Special menu, especially where such entries have accelerator keys (keyboard equivalents) denoted by a double ampersand (&&). Ideally, menu entries should be less than about 25 characters long in English (for aesthetic reasons). The maximum length for a menu entry message is 46 bytes in English (60 bytes after translation).
Token Type is TOKEN in script file. Use for messages that are used as token values in other messages. This type is for backwards compatibility only, and should not be used for new messages (new messages should not use tokens that require translation). You must include a message description that contains the name of the message that uses the token and any translation length restrictions.
Other Type is OTHER in script file. Use for text not covered by any other type. You must include a message description explaining the message and its translation requirements (for example, if the message should not be translated or has a specific maximum length).

Message Description Standards

Use the description field to tell translators and other developers the purpose of the message, where it is used, and how it is used. For example, if you define a message to use as a label for a Special menu entry, you should mention that in the description field for your message. The message description is especially important for short pieces of text that will be translated, so that translators have some idea of how the text would appear.

Even if your message is unambiguous, translators may need to know where it occurs so that they can match their translations of your message to their translations of other text in related areas of your application.

Include a message description for any of the following cases:

where context is when and where your message appears. (You can use any format to explain token names, as long as your notes are clear and well-written).

Examples:

This message appears only when making new entries in the Enter Journals form. 
This message appears in the Invoice Register report to indicate division by zero.

Message Content Standards

Follow these standards to make your messages consistent, translatable, and user-friendly. These standards apply to both Oracle Forms windows and Oracle Application Framework pages.

For more information about building applications using Oracle Application Framework, refer to the Oracle Application Framework Developer's Guide, available from My Oracle Support Knowledge Document 1315485.1.

Writing for the User

Always write a message for the person most likely to encounter it. In most cases, the person seeing the message is the end user of the application—not the developer, system administrator, or support representative.

Address the user as “you”

Talk to the user, not about the user. Users prefer friendly messages that address them directly and make them feel that they control the application. "You" is also more concise and more forceful than "the user."

Use formal, user-friendly language

Avoid technical language and industry jargon, which may be unfamiliar to end users. Likewise, avoid colloquialisms and idioms, which can be difficult for non-native English speakers to understand, and are difficult or impossible to translate. Use common, everyday vocabulary and the simplest words that communicate your meaning. Consider the examples in the table below.

Examples
Correct Incorrect
APP-0127 No records match your search. Try altering your search criteria. APP-0127 Application located no rows matching specified relationship.

Be concise

So that translators and users can understand your message, use clear but concise language. Refer to the examples in the table below.

Examples
Correct Incorrect
APP:SQLAP-14039 You cannot add lines to a completed requisition. APP:SQLAP-14039 You cannot affix any more new lines to a requisition that has already been completed.

Be clear

Avoid words that could be ambiguous. Be as specific as possible. Some words have more than one meaning – try to find a word with only one definition to say what you mean. For example, since can indicate passage of time or causality. If you want to indicate causality, use because instead.

Distinguish between user errors and program errors

If the problem is not caused by a user action or is not something that the user can resolve, then include the phrase "Program error:" at the beginning of a message. This is especially important when an error traps for something that the developer or installer should have caught during system testing.

The following is an example message:

APP:FND-1591 Program error: Invalid arguments to the flexfield routines. Inform your support representative that: The argument &ARGUMENT_NAME was spelled incorrectly.

Differentiate between similar errors

If your application has two or more closely related error conditions, use messages that clearly distinguish between them. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-17403 This vendor cannot accept new purchase orders. Choose another vendor. APP-17403 This vendor cannot accept this purchase order. Choose another vendor.
APP-17408 This vendor cannot ship the requested quantity. Choose another vendor. APP-17408 This vendor cannot accept this purchase order. Choose another vendor.

Avoid accusatory messages

Even when a message addresses a user error, do not imply that the user is at fault. Consider the examples in the table below.

Examples
Correct Incorrect
APP-11394 That check number does not exist for this account. Enter a different check number. APP-11394 You entered an invalid check number.
APP-11394 You made a mistake. Enter the right check number.
APP-17503 Enter a deliver-to person. APP-17503 You did not enter a deliver-to person. Enter a deliver-to person.

Explain why the user cannot perform a function

When a user tries to do something that does not make sense in the current context, explain why it cannot be done. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-14420 You cannot update this invoice because it is selected for payment. APP-14420 Invalid action
APP-12483 You have already cleared this exception. APP-12483 You cannot clear this exception.

Tell the user how to solve the problem

Provide ways to solve the problem.

Be direct

When the user can easily correct a problem, (for example, a field without a value in it or a field containing an invalid value), do not describe the problem; just tell the user how to correct it. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-17403 Enter a shipper. APP-17403 The shipper is missing.

Give the user a realistic solution

Before you write a message, think about what access the user is likely to have to application functions. For example, a clerk probably cannot modify problematic code or go into application setup forms to change the default value for a flexfield segment Even if the ultimate target of the information in a message is a support person, system administrator or developer, write the message as if an end user will read it first. Identify technical information that is intended for support, system administrators, or development.

Tell the user how to get help

If the user needs to communicate specific details, such as token values, to the person who will help solve the problem, then use one of the first three phrases. If a support person or administrator could look up the entire message by the message number, then use one of the last three phrases.

The following is an example message:

APP:FND-1591 Program error: Invalid arguments to the flexfield routines. Inform your support representative that: The argument &ARGUMENT_NAME was spelled incorrectly.

If the problem could be resolved by most system administrators (or if what you really want to say is "call support and log a bug"), use one of the standard phrases above that includes the phrase "support representative." The support representative can then determine whether a bug should be reported.

Do not ask the user to contact Oracle, Oracle Support, or Worldwide Support (or anything similar), or Oracle Consulting. End users at most customer sites must contact someone at their site who in turn might contact someone at Oracle or elsewhere (or visit a website), so the term "your support representative" is appropriate for those cases.

You can also use the following optional phrases where appropriate. Using standard phrases helps contain translation costs because a standard translation can be reused cheaply.

Program error: [Insert 1 space, then a complete sentence.] 

Possible causes: [Insert a blank line, followed by a numbered list of possible causes.] 

Additional information for the support representative: [Insert a blank line, followed by the additional information in a complete, grammatical sentence.]

For example,

APP:FND-01234 Unable to execute &TRIGGER trigger.

Contact your support representative. 

Additional information for support representative: 

Check that the trigger exists in the form.

Note: Omit the sentence "Additional information..." if you do not include further technical information.

Include only the necessary information

In general, users want the minimum information necessary to correct a problem. End users do not want technical information, like the name of the routine that generated an error, unless it helps them solve the problem. If you provide technical information for use by a support representative or system administrator, tell the user what to do with that information.

Refer to screen navigation, not to keys on the keyboard

Do not force the user to remember which key performs a function. Also remember that the user might not have the same kind of device as you do. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-0457 Use the list of values to see values for this segment. APP-0457 Press [Ctrl+Shift+F9] to see values for this segment.

When you must refer to keys, use the standard key names listed below:

If you use a key name in a message, you must include a note in the message description indicating that it is a key name. Key names are translated for most languages other than Arabic (key names are in English on the English/Arabic keyboard), so translators specifically need to know if the message contains key names.

Organize complex messages effectively

Many messages require more explanation than will fit in a single short paragraph. Provide all the necessary information while keeping the message well organized and as brief as possible.

First, provide a short version of the message so the user can get the sense of the problem quickly. Add a blank line, then provide further information to help the user resolve the problem.

If the problem has several possible causes, list them by number and include the remedy for each cause.

Example:

APP:FND-1518  Program error: Invalid arguments were specified for the flexfield user exits.

The flexfield cannot find the segment qualifier name for your value validation rule.  
Possible causes:

1.  The flexfield user exits #FND LOADID, #FND POPID, or #FND VALID are specified incorrectly. Check the syntax and spelling of the user exit arguments.

2.  The VRULE= parameter is incorrect. Make sure that the value is in quotes, that the \n's are in lower case, that there are no spaces around the \n's, and that all of the information is provided.

Grammar, Style, and Conventions

Write complete, grammatically correct sentences

Write messages in formal prose, using complete sentences and appropriate punctuation. Do not omit definite and indefinite articles (a, an, the), pronouns (such as this and that) or other words that seem unimportant. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-8402 The account number you entered does not exist. Verify that you have entered the correct account number. APP-8402 Account ID nonexistent. Enter correct account ID.

Choose words carefully

This section includes some guidelines for choosing words to use.

Preferred word choices

Using preferred word choices and spellings helps messages stay consistent across applications. In general, prefer the American English spelling of words. The following tables contain words to avoid and their preferred alternatives.

For general situations, refer to the guidelines in the following table:

Word Choice Guidelines
Prefer Avoid
file name filename
for example e. g.
number ID (unless part of a column or filed name); Id (never use this)
save commit
that is i. e.
time zone timezone
user name username

When using dates, refer to the following table for guidelines:

Word Choice Guidelines for Dates
Prefer Avoid
before less than
after greater than

Use the language of the user interface

The vocabulary you use in messages should match the UI. For example, if a field is labeled Sales Representative, do not use the message "Enter a different salesperson."

Avoid ambiguous words

Try to use words that have only one meaning. For example, the word since can refer to causality or to time passed. If by since you mean because, then use because.

Limit abbreviations

Keep abbreviations to a minimum, because they often make messages harder to read and translate. Use only abbreviations that match those used in the application user interface. Follow these guidelines:

Refer to the examples in the table below.

Examples
Correct Incorrect
APP-24943 You are not authorized to complete this transaction. APP-24943 You are not authorized to complete this TRXN.
APP-24943 Close your MRP cycle. APP-8402 Acct ID nonexistent. Enter correct acct ID.

In the second correct example, "MRP" is a commonly-accepted industry abbreviation for Material Requirements Planning.

Do not use feature names as verbs

Do not create a new verb by using a feature name, which is a noun, as a verb. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-8402 You cannot use DateTrack to change this record. APP-8402 You cannot DateTrack this record.
APP-9341 You cannot use AutoCreate to create a purchase order from this requisition. APP-9341 You cannot AutoCreate a purchase order from this requisition.

Check your spelling

To prevent embarrassing errors from appearing in your messages, use a spellchecker. Spellcheckers can flag some terms erroneously and they do not catch misspellings that yield real words, so read your messages carefully.

Prefer the present tense

Use future tense only when a message refers to a specific time or event in the future. In other cases, "will" is usually ambiguous. Refer to the examples in the table below.

Examples
Correct Incorrect
Checks will print on Tuesday. Checks will print.
APP-10491 Select an invoice to cancel. APP-10491 Select an invoice that you will cancel.

Use the active voice

Avoid the passive voice. If a message refers to a specific person (such as the user, the system administrator, another user), the message should mention that person. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-4194 You have canceled this process. APP-4194 This process has been canceled by you.
APP-0513 You cannot delete a row in this zone. APP-0513 Rows in this zone cannot be deleted.
APP-4882 Your password is expired. Contact your system administrator. APP-4882 Your password has expired. It must be changed.

Use the imperative mood to give instructions

The imperative mood is a verb form used for giving a command or instruction. Use the imperative mood to tell the user what to do next. Avoid stating what the user can do next.

Sentences that contain auxiliary verbs can imply uncertainty.

In many cases, you can transform sentences that are indicative (descriptive) into an imperative (instructional) form.

Consider the examples in the table below.

Examples
Correct Incorrect
APP-17493 Enter a commission plan. APP-17493 You can enter a commission plan.

Imperative statements are also usually clearer than statements that are merely descriptive.

Correct Incorrect
APP-14583 Save your screen to submit this requisition for approval. APP-14583 If you save your screen, the requisition will be submitted for approval.

Use auxiliary verbs carefully

If you want to indicate either capability or permission, use the word can, not may. Auxiliaries such as could, may, and might are ambiguous and imply uncertainty. Instead, use can, which always implies capability or permission, but does not imply chance or luck.

Consider the examples in the table below.

Examples
Correct Incorrect
The person you named cannot approve requisitions online. The person you named may not approve requisitions online.
You cannot delete a printed release. You may not delete a printed release.

Follow capitalization rules

This section describes some rules for capitalization.

Sentences and Bullet Points

Capitalize the first character of each sentence in a message and of each bullet point, even if the bulleted information is not a complete sentence.

Proper and Common Nouns

After capitalizing the first character of each sentence or bullet point, use initial capital letters only in the following cases:

Refer to the examples in the table below.

Examples
Correct Incorrect
Enter a name for the concurrent program. Enter a Name for the Concurrent Program.
You must run the Archive Fiscal Year concurrent program. You must run the Archive Fiscal Year Concurrent Program.
Enter a value in the Monetary Compensation field. Enter a Value in the Monetary Compensation Field.
You are at the last zone. You are at the Last Zone.

Examples of Common Nouns

The following nouns are often capitalized erroneously.

Use punctuation properly

This section describes guidelines for punctuation.

Terminal Punctuation

Write in complete sentences and use terminal punctuation (a period or question mark). Missing punctuation looks unprofessional, and users and translators might wonder if the message was accidentally truncated. Refer to the examples in the table below.

Examples
Correct Incorrect Error
Enter a value. Enter a value The user might wonder if this message was truncated. Was it supposed to say “Enter a value between…”?
Enter a value between 1 and 9. Enter a value between 1 and 9 The user might wonder if this message was truncated. Was it supposed to say “Enter a value between 1 and 999”?
Do you want to quit? Do you want to quit This is unprofessional and has an unfriendly tone.

Contractions

Avoid using contractions such as it's, don't, can't, and you've. Contractions are informal and are not always translated correctly. Instead, use it is, do not, cannot, you have, and so on.

Quotation Marks

Limit the use of quotation marks. They make messages choppy and difficult to read, and the appropriate use of capitalization is usually enough to set off a value or field name. However, quotation marks can be useful for setting off complex values from the rest of the message (such as when the structure or length of the value makes the sentences confusing). Refer to the examples in the table below.

Examples
Correct Incorrect
Enter a positive numeric value in the Interest Amount field. Enter a positive "Interest Amount".
Enter a positive numeric value in the "Interest Amount" field.
Assign a value to the "JLBR Interest Debit Memo Batch Source" profile option. Assign a value to the JLBR Interest Debit Memo Batch Source profile option.

When you do use quotations marks to set off a value or phrase, always use double quotation marks (“). In American English, single quotation marks are used to nest a quote or value inside another quote or value.

Use special characters only in specific cases

Follow the guidelines below for these special characters.

Underscore

Except for tokens, avoid using the underscore (_) in your messages. Translators assume that underscores are part of code or object names that should not be translated. If you must use an underscore that is not part of a token, include a description that tells translators what to do with them.

Ampersand

Avoid using the ampersand (&) except with tokens and for accelerator keys. This symbol can confuse translators, so always include an explanatory note in the message description. Use the word and if that is what you mean.

At (@) Sign

Avoid using at-signs (@) in your messages. In early versions of Message Dictionary, the @ sign indicated formatting information (such as @PARAGRAPHEND). Such formatting information should no longer be present in any message.

Format messages clearly

Follow the guidelines below for formatting your messages.

Formatting Messages (Multiple Paragraphs, etc.)

Keep message formatting simple. Where you need to have multiple sections or paragraphs in the message, use a blank line to separate them.

For example:

APP:FND-01234 Unable to execute [Trigger] trigger. Contact your support representative. 

Additional information for support representative: 
Check that the trigger exists in the form.

Avoid using tab characters or spaces for formatting, because these are difficult to see and are hard to maintain or translate. Avoid complex formatting in Message Dictionary.

Emphasis

Do not try to add emphasis to a message through typography (uppercase, bold, or italics, for example) or punctuation marks (such as exclamation marks or multiple question marks). Emphasis is not translatable and might seem to the user like shouting. The message itself is sufficient. Do ensure that the message is called using the correct routine for the situation (information, error, warning, and so on).

Additional Considerations

Use variable tokens carefully

You can use variable tokens to make a message more flexible by inserting a value at runtime. Use tokens sparingly and follow the guidelines in this section.

In general, tokens can represent the following types of values, which are usually not translated:

User names (such as from a profile option)

Tokens must be in uppercase to identify them to translators. Tokens are never translated, because translation would cause the substitution to fail at runtime.

Do not use a token if it affects surrounding text

Do not use a token for text values where the value of the token must be translated, and use a token only if different values substituted for the token do not affect the translation of the surrounding text. For example, avoid using a token to substitute for a word or phrase in a sentence, because different token values may require different translations for the surrounding text. The following example is impossible to translate:

This &ENTITY must be &ACTION to continue.  &ACTION this &ENTITY.

In this example, the noun represented by ENTITY could be either masculine or feminine, and either singular or plural. The verb represented by ACTION appears to be used in the passive voice and past tense in its first use in the message, but in the active voice and present tense in its second use in the message. These factors can affect the translation of the noun, the pronoun (this), the helping verb (must) and the main verb. To make the message clear and translatable, write it without tokens.

You must approve this purchase order in order to continue.

Some words and phrases that appear as a single unit or contiguously in an English sentence might be dispersed across the sentence when it is translated. For example, the expression "not" occupies one location in English sentences, but it may appear in a French phrase as two separated words, "ne" and "pas." The sentence "Terminal is not operational" translates to French as "Terminal n'est pas operationnel." Notice that the phrase "is not", while contiguous in the English sentence, is distributed across the French sentence as "ne…pas". If you must use substitutable text, make sure that it does not include phrases that may depend on word order, because word order and sentence structure may change in translation. To be safe, use tokens only for values that are not translated, like dates, numeric values, user names, proper names, and file names.

Use descriptive variable token names

Make token names clear and readable so that the message makes sense even before substitution takes place. Messages with descriptive token names are easier to use and debug. You can use underscores to separate words in token names. Consider the examples in the table below.

Examples
Correct Incorrect
&PURCHASE_ORDER_NUMBER &ENTITY1
&USER_NAME &NAME
&ROUTINE_NAME &NUMBER

The &ROUTINE_NAME token, for instance, might be used in a message as follows:

APP-0123  The routine &ROUTINE_NAME could not be run.

Even a descriptive token name can be ambiguous, so use the Description field to clarify the purpose of your token. This information is important to translators, because tokens often provide critical information about the purpose and context of a message.

Avoid using tokens in the same message in which one token is the beginning substring of another token; for example, avoid using &TOKEN_NAME and &TOKEN_NAME_INFO in the same message.

Important: Do not change or remove an existing token name without also changing the code that calls the message.

Use separate messages when a token value could be either singular or plural

Do not use the same message for both singular and plural token values. Placing an "(s)" after your token is not acceptable, since a message might be translated into a language that does not specify plural forms with a trailing "s" or any other trailing letters. For examples, refer to the table below.

Examples
Correct Incorrect
One row updated.
&NUMBER_OF_ROWS rows updated.
[Two distinct messages]		 &NUMBER_OF_ROWS row(s) updated.
&NUMBER_OF_ROWS rows updated.
[No singular message defined]

Avoid hardcoding text into your code

Avoid hardcoding substitute text into your forms, because this would prevent you from updating or translating your message text later using the Messages window (and you would have to regenerate your form if you needed to change your message). If you must have text fragments in a message, use the TRANSLATE token with Message Dictionary routines for substitute text that might require translation.

Convert date and date-time values

If you pass a date in a token, use a conversion routine to make the date appear in the correct format. Otherwise, it will be displayed in the DD-MON-YY format no matter what the NLS_DATE_FORMAT is set to.

FND_MESSAGE.SET_TOKEN('ORDER_DATE',    
  app_date.date_to_chardate(:ORDERS.DATE_ORDERED),   
  FALSE);  
FND_MESSAGE.SET_TOKEN('ORDER_DT_TIME',    
  app_date.date_to_chardt(:ORDERS.DATE_ORDERED),   
  FALSE);

Use capitalization deliberately

Translators use case as an indicator of what to translate. Mixed-case and lowercase words are translated. In general, uppercase words are not translated because they are assumed to be variable tokens, objects such as table or column names, or literal values. Tokens are never translated, because translation would cause the substitution to fail at runtime. Therefore, tokens must be all uppercase, as in &REQUEST_ID.

A complete message should never be written in lowercase only. Lowercase strings can confuse translators because they might be fragments of other messages. For example, "enter a value" could be a complete (but incorrect) message, or it could be substitute text for a variable token in a message like "&ACTION in the &FIELD field" where the action is enter a value. If you must define a lowercase fragment as a message in Message Dictionary, explain its purpose in the message description.

Avoid table and column names

Avoid including table or column names in messages. If you must have a table or column name in a message, use all uppercase. If appropriate, include table or column in the message for clarity. For example, "The table FND_CONCURRENT_REQUESTS has been updated." In the message description, tell the translator not to translate the text in uppercase. Include the table or column name in the description for clarity. For example, “Do not translate 'FND_CONCURRENT_REQUESTS' because it is a table name.”

Avoid navigation paths and menu items

Never use a navigation path (what a user chooses from the Navigator window) to a form or function in a message, because the navigation path is very likely to change at a customer site (customers can redefine menus), so your message would then be incorrect.

Avoid using menu paths (the default or pulldown menu) in messages if possible. Translators would need to know the entire corresponding menu path in the target language to translate the path correctly. Try to write out the navigation path in words; for example, "Click Help, then Tools, then Custom Code, and then Off." If you must use a menu path for a choice on the default menu, use -> as the delimiter between menu entries. For example, Help->Tools- >Custom Code->Off. Indicate that this is a default menu path in your message description so translators can figure out the corresponding translated menu path.

Avoid field names

Avoid using a field name in a message, because the field name in the message may not match the field name in the UI once both the UI and the message are translated. Field names may change over time, rendering messages obsolete or requiring extra maintenance. If you must include a field name in a message, the preferred method is to:

Avoid listing valid values

Avoid listing values in messages. For example, a message like "Enter one of the following values: Blanket, Standard," is problematic because the set of valid values may change over time, rendering the message obsolete or requiring extra maintenance. Instead, make the valid values available in an LOV or a poplist.

If you must list values, list them exactly as the user should type them, paying attention to capitalization. Separate the values with commas. Most values should be in mixed case, depending on the field requirements. Do not put quotation marks around the values unless at least one value contains a space. In that case, enclose each value in double quotation marks and separate the values with commas. For example, "First Value", "Second Value", "Third".

If you include values in a message, use the message description to tell the translator whether and how to translate the values. For example, in a message like "Choose A for Amount or R for Rate.", the translator would not know whether "A" and "R" should be replaced with the first letters of the translations of "Amount" and "Rate", or should be retained as A and R while Amount and Rate are translated.

Limit the length of the message

Messages should never exceed about 1260 characters in English. This allows space for the messages to be translated to "longer" languages such as German.

Never write temporary messages

Always assume that the message you define is final, even if you expect someone else to check it before it is released. Similarly, give your error and warning messages real message numbers when you create them, not later. Refer to the examples in the table below.

Examples
Correct Incorrect
APP-8402 This account number does not exist. APP-9999 John, we need a message here.

Do not change existing message text unnecessarily

Each change usually requires the combined efforts of a number of people. When you change the text of a message, translators must also revise existing translations of the message to prevent mismatches between versions of your application in different languages.

Special Purpose Messages

Messages to Be Used as Boilerplate, Titles, Button Text, Labels

Avoid storing text to be used as boilerplate, prompts, titles, button text, labels, report titles, or HTML in Message Dictionary. Such pieces of text are extremely difficult to translate out of context. In particular, text with HTML markup requires translators to use a separate toolset for translation and should not be stored in Message Dictionary.

The preferred method for storing such text is to put the text in the form using a parameter default value or static record group cell, where it will be translated with the rest of the form.

If you must store such text in Message Dictionary, provide a complete message description indicating exactly how and where the text is to be used, and the maximum length to which it can be allowed to expand. Do not give these messages message numbers.

Messages to Be Used as Menu Choices

Indicate that this is a menu entry in your message description. If there is an ampersand (&) in the menu entry to enable an accelerator key, indicate that in your message description so the translator does not assume that you have simply misplaced the ampersand for a token.

Typically, the translator would eliminate ampersands in the translated menu entry, but the translator must be careful not to eliminate ampersands that are used for tokens. You may also use a double ampersand (&&) in your menu entry, but you must still have an appropriate message description.

Usage Messages

Provide usage information when a developer or user incorrectly specifies arguments for a routine. You make it easier for support personnel to resolve customer problems with your concurrent programs if you include an action containing usage information for your routine. You also help developers to implement your routines more easily. Include the following information in your usage action:

Follow the example below when providing usage information:

Example

APP:FND-0490  Please enter the correct arguments for FNDMDCTM as follows. 
Syntax:  FNDMDCTM <ORACLE ID> <Request ID> <OS Flag> <Source Language Short Name> <Destination Language Short Name> [<Application Name>] 
Example:  FNDMDCTM APPLSYS/FND 0 Y usaeng gerger 'Oracle General Ledger' 
ORACLE ID:  Enter the username and password of the applsys ORACLE ID.  Enter the username and password without any spaces and separated by a slash ("/"). 
Request ID:  This argument is no longer used and is present for backward compatibility only.  Enter 0. 
OS Flag:  This argument is no longer used and is present for backward compatibility only.  Enter Y. 
Source Language Short Name:  Enter the short name of the language from which you wish to copy messages. 
Destination Language Short Name:  Enter the short name of the language to which you wish to copy messages. 
Application Name:  Enter the name of the application for the messages you wish to copy.  This argument is optional.

Be sure to include a message description that tells translators what parts, if any, of your message to translate (or not).

Debugging Messages

Many debugging messages are hardcoded directly into forms in English and are never translated or defined in Message Dictionary. These are typically messages embedded in PL/SQL code that act as the last branch in a handler. For example:

 ELSE 
           fnd_message.debug('Invalid event passed to
                   control.orders_lines: ' || EVENT); 
       END IF;

These messages should never be seen by an end user.

Another type of debugging message can appear to a user (typically support personnel) when an application is being run in "debug mode" (supported by some applications, such as Oracle Receivables). These messages typically appear in a log file, and they are defined in Message Dictionary. These messages should be translated, and should follow all appropriate message standards.

Messages Window

Define your application messages before your routines can call them from a form and before your users can request detailed messages from a form. You should define your messages according to the Oracle E-Business Suite message standards.

Once you leave the Messages window, after you make and save your changes, you should submit a concurrent request for the Generate Messages program to build your message file. Your new messages take effect as soon as your concurrent request finishes successfully and you have placed the new file in the appropriate directories.

When you upgrade, any customizations you make to Oracle E-Business Suite messages will be overwritten. However, an upgrade does not overwrite messages you define using your own application.

Before defining your messages, do the following:

Messages Block

Application name, message name, and language uniquely identify your message.

Name

Your message name can be any combination of letters, numbers, hyphens (-), underscores (_) and spaces, up to 30 characters in length. Message Dictionary names are not case sensitive (for example, MESSAGENAME is the same name as messagename).

You use this message name in your forms or concurrent programs when you invoke the Message Dictionary.

Language

Enter the language code for this message. Oracle E-Business Suite displays the message in the correct language based on the user's current language.

Application

Enter the name of the application for which you wish to define message text.

When you upgrade, any customizations to Oracle E-Business Suite messages will be overwritten. However, an upgrade does not overwrite messages you define using your own application name.

Number

Enter a message number, if appropriate. If you define a non-zero message number for your message, Message Dictionary automatically prepends your message with the prefix APP:<application short name>- (or its translated equivalent). Message Dictionary treats 0 and null as the same (and does not display the APP:<application short name>- or the message number).

Type

Use the message type to classify your messages. The message type does not affect how your messages can be called in your code.

In Oracle E-Business Suite, the message type is used to help translators translate messages within length expansion constraints that vary by message type. For certain message types, this form enforces message byte length limits smaller than 1800. The message length limits (in bytes) are 60 for Menu Entry, 250 for Hint, and 80 for Title (note that these limits are for translated messages, so messages in English should be 30% shorter if they will be translated).

Maximum Length

In Oracle E-Business Suite, the maximum length (in bytes) is used to help translators translate messages within length expansion constraints imposed by the form or program that uses the message. Specifying a maximum length is particularly important where the expansion constraint is tighter than would otherwise be expected for a particular type of message. If your message is in English, the maximum length you specify should be at least 30% longer than your actual English message to allow for expansion during translation.

You may optionally specify a maximum length for messages of type Error, Note, Token, Other, or for messages with no message type. If you do specify a maximum length, it must be between 10 and 1800 (inclusive), and it must be equal to or greater than the actual (byte) length of the message text you specify.

Description

You should enter information in this field that would help explain the context of this message to translators. This field is required if the message is of type Token or Other.

Alert Category, Alert Severity, and Log Severity

Oracle E-Business Suite Message Dictionary messages can appear as alerts in Oracle Applications Manager or written to log files. For more information on using these features and setting these fields, see the Oracle E-Business Suite Maintenance Guide.

Current Message Text

Enter a message that describes the problem and its resolution. You can include variable tokens (in uppercase) preceded by an ampersand (&) to indicate the location of substitute text. You supply the substitute text or field references in your form's message calls. For example, you could define an explanation for a message you call "Value Less Than Or Equal" like this:

Please enter a value that is less than or equal to &VALUE.

Your user sees the message explanation as:

Please enter a value that is less than or equal to $30.00.

You can specify your own variable tokens using numbers, uppercase letters, and underscores (_). Your variable tokens can be up to 30 characters long. You can use the same token more than once in your defined messages to repeat your substitute text.

Some uses of messages (such as entries for the Special menu) use an ampersand character to indicate an access, power, or accelerator key. In these cases, you should use a double ampersand (&&) to indicate the letter for the key. Message Dictionary returns only a single ampersand to the calling routine. Words with embedded double ampersands should be mixed case or lowercase (to distinguish them further from tokens).

Messages Page

The HTML-based Messages page is available using the seeded Functional Administrator responsibility, Core Services tab.

Refer to the section on the Forms-based Messages Window for more information on defining messages: Messages Window.

Code

Code corresponds to the Name field in the Messages window.

Your message name can be any combination of letters, numbers, hyphens (-), underscores (_) and spaces, up to 30 characters in length. Message Dictionary names are not case sensitive (for example, MESSAGENAME is the same name as messagename).

You use this message name in your forms or concurrent programs when you invoke the Message Dictionary.

Click on the code to navigate to the View Message page. From the View Message page, you can update the message.

Description

You should enter information in this field that would help explain the context of this message to translators. This field is required if the message is of type Token or Other.

Application

Enter the name of the application for which you wish to define message text.

When you upgrade, any customizations to Oracle E-Business Suite messages will be overwritten. However, an upgrade does not overwrite messages you define using your own application name.

Language

Enter the language code for this message. Oracle E-Business Suite displays the message in the correct language based on the user's current language.

Type

Use the message type to classify your messages. The message type does not affect how your messages can be called in your code.

In Oracle E-Business Suite, the message type is used to help translators translate messages within length expansion constraints that vary by message type. For certain message types, this form enforces message byte length limits smaller than 1800. The message length limits (in bytes) are 60 for Menu Entry, 250 for Hint, and 80 for Title (note that these limits are for translated messages, so messages in English should be 30% shorter if they will be translated).

Text

Enter a message that describes the problem and its resolution. You can include variable tokens (in uppercase) preceded by an ampersand (&) to indicate the location of substitute text. You supply the substitute text or field references in your form's message calls. For example, you could define an explanation for a message you call "Value Less Than Or Equal" like this:

Please enter a value that is less than or equal to &VALUE.

Your user sees the message explanation as:

Please enter a value that is less than or equal to $30.00.

You can specify your own variable tokens using numbers, uppercase letters, and underscores (_). Your variable tokens can be up to 30 characters long. You can use the same token more than once in your defined messages to repeat your substitute text.

Some uses of messages (such as entries for the Special menu) use an ampersand character to indicate an access, power, or accelerator key. In these cases, you should use a double ampersand (&&) to indicate the letter for the key. Message Dictionary returns only a single ampersand to the calling routine. Words with embedded double ampersands should be mixed case or lowercase (to distinguish them further from tokens).