Skip Headers

Oracle E-Business Suite Developer's Guide
Release 12.1
Part Number E12897-04
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

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 System Administrator's Guide - Configuration.

  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:

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 your rightmost 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 your middle 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 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.

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

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.

Variable Description
Right: FND_FLEX_SEGMENT_NOT_REGISTERED [group identifier is FLEX, for Flexfields]
Right: FND_MD_MESSAGE_NOT_FOUND [group identifier is MD, for Message Dictionary]
Wrong: 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).

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

Message Content Standards

Following content standards makes your application more pleasant to use and easier to translate.

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

Message Token Standards

Using tokens to include values at runtime can make the message more flexible, but use them sparingly.

Always make tokens in your message uppercase so they are easy to identify in a messages manual or in a message file being translated.

Use tokens only if different values for a token do not require different translations for surrounding text. Avoid using tokens for text where the value of the token must be translated. In general, you can use tokens to represent the following types of values:

Avoid using tokens to substitute for words or phrases in a sentence. These are nearly impossible to translate, because different token values may require different translations for the surrounding text. For example:

Variable Description
Wrong: This &ENTITY must be &ACTION.

This bad example is impossible to translate because the noun, ENTITY, could be either masculine or feminine, and singular or plural, all of which may affect translation of both the pronoun "This" and the verb "must" (for example, singular or plural, or masculine or feminine). The message would be better written as one or more messages without tokens at all (assuming the user seeing the message can approve the purchase order):

Variable Description
Right: Please approve this purchase order.

Some phrases that appear contiguously in an English sentence may be dispersed across the sentence when it is translated into another language. Dispersion can even be a problem for single words if they translate into multiple words. For example, the expression "not" occupies one location in English sentences, but it may appear in a French sentence as two separated words, "ne" and "pas."

The sentence "Terminal is operational", for instance, translates into "Terminal est operationnel." The negative form of this sentence, however, translates from "Terminal is not operational" to "Terminal n'est pas operationnel." Therefore, while you could represent the expression "not" with a single token in English, you would need two tokens placed in different locations to make a French translation.

You should make sure that any substitutable text does not include phrases that depend on word order, as word order and sentence structure may change when translators translate a message.

Avoid hardcoding text into your code

You should also avoid hardcoding substitute text into your forms, since 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 your message, you should use the TRANSLATE token with Message Dictionary routines for substitute text that may require translation.

Use descriptive variable token names

Avoid cryptic variable tokens. Make token names clear and readable so that the message makes sense to a reader even before substitution takes place. Messages containing descriptive variable tokens are easier to use and debug. You can use underscores in your token names to separate words.

Variable Description
Right: &PURCHASE_ORDER_NUMBER
Right: &USER_NAME
Right: &ROUTINE_NAME
Wrong: &ENTITY1
Wrong: &TOKEN
Wrong: &NUMBER
Wrong: &NAME
Wrong: &TYPE

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

APP-0123  Could not run routine &ROUTINE_NAME. 

Even a descriptive token name can contain ambiguities, so use the notes field to clarify the purpose of your token if translators might not know exactly what your token represents. This information is important to translators, since your token often provides critical information about the purpose and context of your message.

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

Use two messages to distinguish singular and plural token values

Do not use the same message for both singular and plural token values. Simply placing an "(s)" after your token is not acceptable, since your message may be translated into a language that does not specify plural forms with a trailing "s", or any other trailing letter or letters. For example:

Variable Description
Right: One row updated. &NUMBER_OF_ROWS rows updated. [Two distinct messages]
Wrong: &NUMBER_OF_ROWS row(s) updated.
Wrong: &NUMBER_OF_ROWS rows updated. [No singular message defined]

Converting a Date or Date-Time Value

If you pass dates in tokens, use a conversion routine to make the date appear in the correct format. Otherwise, they will show up as 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_DATE_TIME', app_date.date_to_chardt(:ORDERS.DATE_ORDERED), FALSE);

A Few General Guidelines for Writing Good Messages

Address the Correct Person (Do Not Accuse the Innocent Bystander)

Always keep in mind who is the person most likely to encounter your message, and write your message for that audience. In most cases, the person seeing the message is the end user of the application, not the developer, system administrator, or support representative.

Just the Important Information

In general, end users (and other users) want to know the minimum information necessary to correct a problem and get on with their work. End users do not necessarily want to know information such as the routine name of the routine that generated the error, or other technical information, unless it helps them solve the problem.

Give Users Actions They Can Accomplish

Think about what access the user is likely to have to application functions. A clerk is unlikely to have sufficient authority to go into application setup forms to change the default value for a flexfield segment, for example. Similarly, the clerk probably does not have the access or ability to go and modify the code of a form that a developer coded improperly.

Write your explanation with the expectation that your end user will encounter it, even if your message is intended only for developers and debugging. Label technical actions that are intended for system administration, development, or support personnel so that your end user knows what to do.

If the Problem Is Not the User's Fault, Say So Immediately

Optionally use the convention "Program error: " at the start of a message if the problem is not something the user did or can do something about. This is especially important for "developer-error" problems where an error traps for something that the developer or installer should have caught during system testing.

Variable Description
Example APP:FND-1514 Program error: Invalid arguments specified for the flexfield user exits.

Avoid including the routine name in the message unnecessarily

In many cases, a routine name (especially delivered by a token) is both unnecessary and unduly intimidating.

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 your message to prevent mismatches between versions of your application in different languages.

Never write "temporary" messages

Prevent embarrassing errors from appearing in your messages; always assume that the message you define is "the real thing", even if you expect someone else to check it. Similarly, give your error and warning messages a "real" message number immediately.

Variable Description
Right: APP-8402 Account number does not exist.
Wrong: APP-9999 John, we need a message here.

Spell-check your messages

Prevent embarrassing errors from appearing in your messages; pass them through a spell-checking program.

When the User Needs to Get Help

When a user needs to get someone else to help solve the problem, use one of the following phrases. If the content of the message includes tokens whose values are important to know to solve the problem, use the version of the phrase containing "that:", implying to the user that writing down the entire message is important for getting help. If there are no tokens, and a support representative or other person could look up the entire message given only the message number, then use the "Please contact your..." version.

Please inform your support representative that:  (then blank line)
Please inform your system administrator or support representative that:  (then blank line)
Please inform your system administrator that:  (then blank line)
Please contact your support representative.
Please contact your system administrator.
Please contact your system administrator or support representative.
Variable Description
Example: APP:FND-1591 Program error: Invalid arguments to the flexfield routines. Please inform your support representative that: The argument &ARGUMENT_NAME was spelled incorrectly.

If a problem can be resolved by a system administrator, use the same heading, but substitute "system administrator" for "support representative".

Variable Description
Example: APP:FND-1591 Flexfield validation table &TABLE_NAME was not found.
The flexfield validation table associated with a value set was not found, so the default value for the segment using that value set could not be validated.
Please contact your system administrator.

If a problem cannot 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 should be able to determine whether a bug should in fact be reported.

You should never specifically ask users to contact Oracle, Oracle Support or Worldwide Support (or anything similar), or Oracle Consulting in your message. End users at many customer sites usually must contact someone at their site who in turn may contact someone at Oracle or elsewhere (or visit a Web site) so the term "your support representative" is appropriate for those cases. In addition, the name of the support organization at Oracle has changed several times, and some customers may contact different parts of the support organization that have different names.

You can also use the following optional phrases (including punctuation and spacing) where appropriate in your messages. Using standard phrases helps contain translation costs because a standard translation can be reused cheaply.

Program error:  (1 space, then init cap)
Possible causes:  (then blank line)
Additional information for support representative:  (then blank line)
Variable Description
Example: APP:FND-01234 Unable to execute &TRIGGER trigger.
Please 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.

Complex Messages

Many messages require more explanation than will fit in a short simple message. In these cases, you need to provide all the necessary information while still keeping the message as brief as possible.

First, provide a short version of the message so the user can get the sense of the problem quickly without needing to read through the entire message. Add a blank line, then provide further information to help the user result the problem.

If the problem has several possible causes, list them by number and include the remedy with the description of the cause.

Example

APP:FND-1518  Program error: Invalid arguments specified for the flexfield user exits.
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 may be incorrect.  Make sure the value is in quotes, the \n's are in lower case, there are no spaces around the \n's, and all the information is provided.

Specific Types of Message Content

UPPERCASE, Mixed Case, and lowercase

Translators use case as an indicator of what should be translated. The general rule for messages is that all uppercase words are not translated (they are assumed to be objects such as table or column names, or to be literal values). Mixed-case words are translated.

Messages that are completely in lowercase usually cause confusion as to how they should be translated, because they may be fragments of other messages. For example, "enter a value" could be interpreted as a complete but incorrect message, or it could be interpreted as a fragment of another message (such as "Please &ACTION for the &FIELD field.") Message descriptions are required for clarification in these cases.

Substitute tokens must always be completely in uppercase, as in &REQUEST_ID. Tokens are never translated (translation would cause the substitution to fail at runtime because the token is embedded in the code).

Table and Column Names

Avoid having table or column names in messages because they are not generally considered user-friendly. For forms, typically the user will not have direct access to tables and columns anyhow and may not be able to carry out the instructions in the message, so table and column names in form messages are especially inappropriate.

If you must have table or column names in your message, they should be all uppercase, not lowercase or mixed case, to indicate that they should not be translated. If appropriate, include the words table or column in the message to make it clear to the user as well, for example, "... the table FND_CONCURRENT_REQUESTS has been...". You must also include a description for the message to tell the translator not to translate the table or column name (include the table or column name in the description just to be clear).

Navigation or Menu Paths in Messages

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. 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.

Field Names

Avoid using field names in messages. Field names written directly in the message may not match the actual field name once both the form and the message are translated. Field names may also change over time, rendering the message obsolete or requiring extra maintenance of the message to keep the message correct.

If you must have a field name in a message, the preferred method is to:

Avoid Listing Values in Messages

Avoid listing values in messages. A typical type of message where you might expect to list values in the message would be: "Please enter one of the following values: Blanket, Standard." However, in general, you should not list values in messages at all. Valid values are likely to change over time, rendering messages obsolete or requiring extra maintenance of the message to keep the message correct. Further, users can usually get a list of valid values using the LOV on the field (if available) or, if the field is a poplist, from the field itself. Duplicating the value list in the message is unnecessary.

Tip: If a field requires a message like "Choose A for Amount or R for Rate", because there is no list of values available, the field itself should probably be changed. The field could have a list of values added, or be reimplemented as a poplist or option group as appropriate. File an enhancement request for the affected form.

Where it is absolutely necessary to list values, list the values exactly as the user should type them. Typically that would be in mixed case instead of uppercase or lowercase, depending on the field requirements. You do not need to put quotes around your values unless the values contain spaces, in which case you should put double quotes around each of the values in the list (as in "My first value", "My second value", "Third").

If you must have values in your message, you must include a description for the message that tells translators whether they should translate the values. For example, in a message like "Choose A for Amount or R for Rate.", the translator would not know whether (or how) to translate "A", "R", "Amount", or "Rate".

Message Writing Style

Preferred Word Choices

Using preferred word choices and spellings help messages appear consistent across applications. In general, prefer American English spelling of words. The following tables contain words you should avoid using and their preferred alternatives.

For general situations:

Avoid Prefer
username user name
filename file name
commit save
ID (unless part of a column or field name) Id (never use this) number
e.g. such as, for example
i.e. that is

When using dates:

Avoid Prefer
less than before
greater than after

Colloquialisms and Informal Expressions

Avoid colloquial or informal expressions, because these often are difficult to translate.

Contractions

Avoid using contractions wherever possible. Contractions reflect informal speech and writing and are not always translated correctly. Spell out words that you might present as contractions in less formal writing, such as it's (it is), don't, can't (cannot is the accepted spelling), you've, and so on.

Special Characters: Quotes

Limit the use of quotation marks in messages. They make messages choppy and difficult to read. However, quotes are useful for setting off phrases such as complex values from the rest of the message (such as when the complex values contain spaces).

Variable Description
Right: Please assign a value to the "JLBR Interest Debit Memo Batch Source" profile option.
Wrong: Please assign a value to the JLBR Interest Debit Memo Batch Source profile option.

In many cases, the careful use of capitalization and descriptive words may be sufficient to set apart a value or field name.

Variable Description
Right: Please enter a positive numeric value in the Interest Amount field.
Wrong: Please enter a positive "Interest Amount".
Wrong: Please enter a positive numeric value in the "Amount" field.

Prefer to use double quotes ("double quotes") instead of single quotes ('single quotes'). In American English, single quotes are typically used as apostrophes indicating possession and contractions (as in "Don't forget Sara's lecture.").

Special Characters: Underscores

Avoid having words with underscores in your messages other than tokens. Translators assume that words containing underscores are code or table or column names that should not be translated. If you have words with underscores, include a description that tells translators what to do with them.

Special Characters: Ampersands, At-signs

Avoid using ampersands (&) other than for tokens (or accelerator keys if you also include a note in the description) in your messages. They will be confusing to translators, and your message may be translated incorrectly. Use the word "and" instead if that is what you mean.

You should also avoid using at-signs (@) in your messages. In early versions of Message Dictionary, at-signs were used to indicate formatting information (such as @PARAGRAPHEND). Such formatting information should no longer be present in any messages.

Industry Jargon

Keep extremely industry-specific jargon to a minimum. While users and support personnel may know many industry-specific terms, messages are likely to be easier to read and translate if they use simpler language.

Standard Capitalization

Use standard capitalization for feature names and terms. For example, use the following capitalizations for these phrases:

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.

Variable Description
Example: APP:FND-01234 Unable to execute [Trigger] trigger.
Please 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 using complex formatting in Message Dictionary.

Emphasis

Do not use uppercase, mixed case, exclamation marks ( ! ), multiple punctuation marks (such as "Do you want to quit???" or "Do you want to quit?!"), or anything else for emphasis. Emphasis is not translatable. The fact that the user has just gotten a message in a dialog box should be enough to make the user pay attention. Ensure that the message is called using the correct routine for the situation (error, warning, etc.).

Terminal Punctuation

Use terminal punctuation (period, question mark) at the end of your message if it is a complete sentence. If there is no terminal punctuation, users and translators may wonder if the message was accidentally truncated.

Variable Description
Right: Please enter a value.
Right: Please enter a value between 1 and 9.
Wrong: Please enter a value
Right: Do you want to quit?
Wrong: Do you want to quit

Do not use exclamation marks, because they seem to indicate that you are "shouting" at the user.

Be precise and concise

Treat message text as formal written prose. Use powerful and succinct language that can be easily translated. Omit unnecessary words.

Variable Description
Right: APP:SQLAP-14039 You cannot add lines to a completed requisition.
Wrong: APP:SQLAP-14039 You cannot affix any more new lines to a requisition that has already been completed.

Avoid ambiguous words

Try to use words that have only one meaning. Avoid words with data processing connotations unless you are referring to a specific application function.

Say please wherever possible

Be polite. When a message contains instructions, and the message is short enough to fit in the message field with room to spare, use please.

Variable Description
Right: APP-2201 Please enter an amount greater than 1.
Wrong: APP-2201 Enter an amount greater than 1.

Use vocabulary consistent with form boilerplate

Refer to a form field by its correct name. If a field is labelled Sales Representative, do not use the message "Please enter a different salesperson."

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 they control the application. "You" is also more concise and more forceful than "The user ..."

Variable Description
Right: APP-0842 You cannot delete this row.
Wrong: APP-0842 The user cannot delete this row.

Avoid nonspecific future tense

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

Variable Description
Right: Checks will print on Tuesday.
Right: APP-10491 Please select an invoice to cancel.
Wrong: APP-10491 Please select an invoice that you will cancel.

Use active voice

Avoid 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.

Variable Description
Right: APP-4194 You have cancelled this process.
Wrong: APP-4194 This process has been cancelled.
Wrong: APP-4194 This process has been cancelled by you.
Right: APP-0513 You cannot delete a row in this zone.
Wrong: APP-0513 Rows in this zone cannot be deleted. [Who cannot delete rows in this zone?]
Right: APP-4882 Your password has expired. Please contact your system administrator.
Wrong: APP-4882 Your password has expired. It must be changed.

Avoid accusatory messages

Do not insinuate that the user is at fault. Do not mention a user's mistake unless it pertains to the problem's solution.

Variable Description
Right: APP-11394 Check number does not exist for this account. Please enter another.
Wrong: APP-11394 You entered an illegal check number
Wrong: APP-11394 Please enter another check number
Wrong: APP-11394 You made a mistake. Enter the right check number.
Right: APP-17503 Please enter a deliver-to person.
Wrong: APP-17503 You did not enter a deliver-to person. Enter a deliver-to person.

Use imperative voice

Sentences containing auxiliary verbs imply uncertainty. Prefer imperative voice.

In many cases, you can transform sentences containing auxiliary verbs into imperatives.

Variable Description
Right: APP-17493 Please enter a commission plan.
Wrong: APP-17493 You can enter a commission plan. [or you can go to lunch, or ...]

Avoid conditionals

Prefer positive, imperative statements over statements containing conditionals.

Variable Description
Right: APP-14583 Save your screen to submit this requisition for approval.
Wrong: APP-14583 If you save your screen, the requisition will be submitted for approval.

Use "can" to indicate either capability or permission

Auxiliaries such as "could", "may", and "might" are ambiguous and imply more uncertainty than "can". Limit the range of uncertainty by using "can", which always implies capability or permission but does not imply chance or luck.

Variable Description
Right: The person you named cannot approve requisitions online.
Wrong: The person you named may not approve requisitions online. [The person may not approve a requisition because of a foul mood or capriciousness or ...]
Right: You cannot delete a printed release.
Wrong: You may not delete a printed release. [and it may not rain tomorrow, if you're lucky.]

Refer to menu paths, not power-user or terminal-specific keys

Do not force your user to remember which key performs a function. Also remember also that your user may not have the same kind of terminal as you do.

Variable Description
Right: APP-0457 Please use the list of values to see values for this segment.
Wrong: APP-0457 Please press [QuickPick] to see values for this segment.
Wrong: APP-0457 Please press [Do] to save your changes.

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

If you use a key name in your 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 in the English/Arabic keyboard), so translators specifically need to know if the message contains key names.

Use consistent vocabulary to describe application functions

When you write a message that advises your user to perform some other application function, use the same terminology as the application forms do.

Variable Description
Right: APP-16934 Please define a sales representative. [where the form is the Sales Representatives form]
Wrong: APP-16934 You have not entered any sales people. [where the form is the Sales Representatives form]

Use only abbreviations that match forms and reports

Keep abbreviations to a minimum, because they often make messages harder to read and translate. Use only abbreviations that match those used in your application forms. If the forms that use a message do not abbreviate a term, do not abbreviate that term in a message.

If your form or report abbreviates a word or phrase simply because of space constraints (that is, if there were room on the form, the full phrase would be used), your message should use the full word or phrase.

Variable Description
Right: APP-24943 Please close your MRP cycle.
Wrong: APP-24943 You are not authorized to complete this TRXN.

When a term is not used in any application forms, or when a term is abbreviated inconsistently, use the following criteria to decide whether to abbreviate a term:

Do not use feature names as verbs

Do not use feature names as verbs.

Variable Description
Right: APP-8402 You cannot use DateTrack to change this record.
Wrong: APP-8402 You cannot DateTrack this record.

Use friendly, simple, non-technical language in your message

Do not confront your user with technical or database jargon. Use your end user's vocabulary. Prefer to use the simplest words possible that will get your meaning across.

Variable Description
Right: APP-8402 Account number does not exist.
Wrong: APP-8402 Account ID does not exist.
Right: APP-0127 No records exist.
Wrong: APP-0127 Application located no rows matching specified relationship.

Begin messages with a capital letter

Capitalize the first character of a message. Do not capitalize every word.

Variable Description
Right: At last zone.
Wrong: at last zone
Wrong: At Last Zone

Prefer solution-oriented messages

When there is a simple error that your user can easily correct (for example, a field without a value in it or a field containing an illegal value), give directions for fixing the problem in your short message.

Do not describe the problem; tell how to fix it.

Variable Description
Right: APP-17403 Please enter a shipper.
Wrong: APP-17403 Shipper is missing.

Explain why your user cannot perform a function

When a user tries to do something that does not make sense in the current context, tell why it cannot be done.

Variable Description
Right: APP-14420 You cannot update this invoice because it is selected for payment.
Wrong: APP-14420 Invalid action
Right: APP-12483 You have already cleared this exception.
Wrong: APP-12483 You cannot clear this exception.

Differentiate between similar messages

If your form has several closely-related error conditions, use messages that distinguish between them.

Variable Description
Right: APP-17403 Vendor cannot accept new purchase orders. Choose another vendor.
APP-17408 Vendor cannot ship item in requested quantity. Choose another vendor.
Wrong: APP-17403 Vendor cannot accept this purchase order. Choose another vendor.
APP-17408 Vendor cannot accept this purchase order. Choose another vendor.

Use precise, descriptive, and unambiguous language

Make sure that a translator, as well as your user, can easily understand your message. Your message is easier to translate if you do not use abbreviated, obscure, ambiguous, or context-sensitive language.

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 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 Oracle E-Business Suite System Administrator's Guide - Configurationand Oracle E-Business Suite System Administrator's Guide - Maintenance.

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).