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.
| Summary | procedure FND_MESSAGE.CLEAR; |
| Location | FNDSQF library and database (stored procedure) |
| Description | Clears the message stack of all messages. |
| 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;
| Summary | procedure FND_MESSAGE.ERASE; |
| Location | FNDSQF library |
| Description | Clears the Oracle Forms status line. |
Suggestion: 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.
| 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*/
| C Code API | boolean afderror(/*_ void _*/);Requires the fddutl.h header file. |
| 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. |
/* 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 */
| 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. |
| 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. |
| 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. |
Attention: 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.
/* 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);
| 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. |
/* 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*/
| 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). |
/* 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;
| 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. |
/* 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;
| 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"). |
/* 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.
| 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. |
/* Show an informational message */
FND_MESSAGE.SET_NAME ('FND', 'COMPILE_CANCELLED');
FND_MESSAGE.SHOW;
| C Code API | boolean afdshow(/*_ void _*/); Requires the fddutl.h header file. |
| 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. |
/* 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;
| C Code API | boolean afdwarn(/*_ void _*/ ); Requires the fddutl.h header file. |