Skip Headers
Oracle® Application Express API Reference
Release 4.1

Part Number E21676-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

6 APEX_DEBUG_MESSAGE

The APEX_DEBUG_MESSAGE package provides utility functions for managing the debug message log. Specifically, this package provides the necessary APIs to instrument and debug PL/SQL code contained within your APEX application as well as PL/SQL code in database stored procedures and functions. Instrumenting your PL/SQL code makes it much easier to track down bugs and isolate unexpected behavior more quickly.

The package also provides the means to enable and disable debugging at different debug levels and utility procedures to clean up the message log.

You can view the message log either as described in the "Accessing Debugging Mode" section of the Oracle Application Express Application Builder User's Guide or by querying the APEX_DEBUG_MESSAGES view.

Please see the individual API descriptions for further information.

Topics:


DISABLE_DEBUG_MESSAGES Procedure

This procedure is used to turn off debug messaging.

Syntax

APEX_DEBUG_MESSAGE.DISABLE_DEBUG_MESSAGES;

Parameters

None.

Example

This example shows how you can turn off debug messaging.

BEGIN
    APEX_DEBUG_MESSAGE.DISABLE_DEBUG_MESSAGES();
END;

ENABLE_DEBUG_MESSAGES Procedure

This procedure turns on debug messaging. You can specify, by level of importance, the types of debug messages that will be monitored.

Note:

ENABLE_DEBUG_MESSAGES procedure only needs to be called once per page view or page accept.

Syntax

APEX_DEBUG_MESSAGE.ENABLE_DEBUG_MESSAGES (
    p_level    IN  NUMBER DEFAULT 7);

Parameters

Table 6-1 describes the parameters available in the ENABLE_DEBUG_MESSAGES procedure.

Table 6-1 ENABLE_DEBUG_MESSAGES Parameters

Parameter Description

p_level

Level or levels of messages to log. Must be an integer from 1 to 7, where level 1 is the most important messages and level 7 (the default) is the least important. Setting to a specific level will log messages both at that level and below that level. For example, setting p_level to 3 will log any message at level 1, 2 or 3.


Example

This examples shows how to enable logging of messages for levels 1, 2 and 3. Messages at levels 4, 5, 6 and 7 are not logged.

BEGIN
    APEX_DEBUG_MESSAGE.ENABLE_DEBUG_MESSAGES(
        p_level => 3);
END;

LOG_MESSAGE Procedure

This procedure is used to emit debug messages from PLSQL components of Application Express, or PLSQL procedures and functions.

Syntax

APEX_DEBUG_MESSAGE.LOG_MESSAGE (
    p_message    IN VARCHAR2  DEFAULT NULL,
    p_enabled    IN BOOLEAN   DEFAULT FALSE,
    p_level      IN NUMBER    DEFAULT 7);

Parameters

Table 6-2 describes the parameters available in the LOG_MESSAGE procedure.

Table 6-2 LOG_MESSAGE Parameters

Parameter Description

p_message

Log message with maximum size of 4000 bytes.

p_enabled

Set to TRUE to always log messages, irrespective of whether debugging is enabled. Set to FALSE to only log messages if debugging is enabled.

p_level

Identifies the level of the log message. Must be an integer from 1 to 7, where level 1 is the most important and level 7 (the default) is the least important.


Example

This example shows how to enable debug message logging for 1, 2 and 3 level messages and display a level 1 message showing a variable value. Note, the p_enabled parameter need not be specified, as debugging has been explicitly enabled and the default of false for this parameter respects this enabling.

DECLARE
    l_value varchar2(100) := 'test value';
BEGIN
    APEX_DEBUG_MESSAGE.ENABLE_DEBUG_MESSAGES(p_level => 3);
 
APEX_DEBUG_MESSAGE.LOG_MESSAGE(
    p_message => 'l_value = ' || l_value,
    p_level => 1 );
 
END;

LOG_LONG_MESSAGE Procedure

This procedure is used to emit debug messages from PLSQL components of Application Express, or PLSQL procedures and functions. This procedure is the same as LOG_MESSAGE, except it allows logging of much longer messages, which are subsequently split into 4,000 character chunks in the debugging output (because a single debug message is constrained to 4,000 characters).

Syntax

APEX_DEBUG_MESSAGE.LOG_LONG_MESSAGE (
    p_message    IN VARCHAR2  DEFAULT NULL,
    p_enabled    IN BOOLEAN   DEFAULT FALSE,
    p_level      IN NUMBER    DEFAULT 7);

Parameters

Table 6-2 describes the parameters available in the LOG_LONG_MESSAGE procedure.

Table 6-3 LOG_LONG_MESSAGE Parameters

Parameter Description

p_message

Log long message with maximum size of 32767 bytes.

p_enabled

Set to TRUE to always log messages, irrespective of whether debugging is enabled. Set to FALSE to only log messages if debugging is enabled.

p_level

Identifies the level of the long log message. Must be an integer from 1 to 7, where level 1 is the most important and level 7 (the default) is the least important.


Example

This example shows how to enable debug message logging for 1, 2 and 3 level messages and display a level 1 message that could contain anything up to 32767 characters. Note, the p_enabled parameter need not be specified, as debugging has been explicitly enabled and the default of false for this parameter respects this enabling.

DECLARE
    l_msg VARCHAR2(32767) := 'Debug will output anything up to varchar2 limit';
BEGIN
    APEX_DEBUG_MESSAGE.ENABLE_DEBUG_MESSAGES(p_level => 3);
    
    APEX_DEBUG_MESSAGE.LOG_LONG_MESSAGE(
        p_message => l_msg,
        p_level => 1 );
        
END;

LOG_PAGE_SESSION_STATE Procedure

This procedure is used to log the session state of a page.

Syntax

APEX_DEBUG_MESSAGE.LOG_PAGE_SESSION_STATE (
    p_page_id    IN NUMBER    DEFAULT NULL,
    p_enabled    IN BOOLEAN   DEFAULT FALSE,
    p_level      IN NUMBER    DEFAULT 7);

Parameters

Table 6-4 describes the parameters available in the LOG_PAGE_SESSION_STATE procedure.

Table 6-4 LOG_PAGE_SESSION_STATE Parameters

Parameter Description

p_page_id

Identifies a page within the current application and workspace. If no value is passed for this parameter, the application's current page will be used.

p_enabled

Set to TRUE to always log messages, irrespective of whether debugging is enabled. Set to FALSE to only log messages if debugging is enabled.

p_level

Identifies the level of the long log message. Must be an integer from 1 to 7, where level 1 is the most important and level 7 (the default) is the least important.


Example

This example shows how to enable debug message logging for 1, 2 and 3 level messages and display a level 1 message containing all the session state for the application's current page. Note, the p_enabled parameter need not be specified, as debugging has been explicitly enabled and the default of false for this parameter respects this enabling. Also note the p_page_id has not been specified, as this example just shows session state information for the application's current page.

BEGIN
    APEX_DEBUG_MESSAGE.ENABLE_DEBUG_MESSAGES(p_level => 3);
    
    APEX_DEBUG_MESSAGE.LOG_PAGE_SESSION_STATE (p_level => 1);
    
END;

REMOVE_DEBUG_BY_AGE Procedure

This procedure is used to delete from the debug message log all data older than the specified number of days.

Syntax

APEX_DEBUG_MESSAGE.REMOVE_DEBUG_BY_AGE (
    p_application_id    IN NUMBER,
    p_older_than_days   IN NUMBER);

Parameters

Table 6-5 describes the parameters available in the REMOVE_DEBUG_BY_AGE procedure.

Table 6-5 REMOVE_DEBUG_BY_AGE Parameters

Parameter Description

p_application_id

The application ID of the application.

p_older_than_days

The number of days data can exist in the debug message log before it is deleted.


Example

This example demonstrates removing debug messages relating to the current application, that are older than 3 days old.

BEGIN
    APEX_DEBUG_MESSAGE.REMOVE_DEBUG_BY_AGE (
        p_application_id  => TO_NUMBER(:APP_ID),
        p_older_than_days => 3 );
END;

REMOVE_DEBUG_BY_APP Procedure

This procedure is used to delete from the debug message log all data belonging to a specified application.

Syntax

APEX_DEBUG_MESSAGE.REMOVE_DEBUG_BY_APP (
    p_application_id    IN NUMBER);

Parameters

Table 6-5 describes the parameters available in the REMOVE_DEBUG_BY_APP procedure.

Table 6-6 REMOVE_DEBUG_BY_APP Parameters

Parameter Description

p_application_id

The application ID of the application.


Example

This example demonstrates removing all debug messages logged for the current application.

BEGIN
    APEX_DEBUG_MESSAGE.REMOVE_DEBUG_BY_APP(
        p_application_id => TO_NUMBER(:APP_ID) );
END;

REMOVE_DEBUG_BY_VIEW Procedure

This procedure is used to delete all data for a specified view from the message log.

Syntax

APEX_DEBUG_MESSAGE.REMOVE_DEBUG_BY_VIEW (
    p_application_id    IN NUMBER,
    p_view_id           IN NUMBER);

Parameters

Table 6-7 describes the parameters available in the REMOVE_DEBUG_BY_VIEW procedure.

Table 6-7 REMOVE_DEBUG_BY_VIEW Parameters

Parameter Description

p_application_id

The application ID of the application.

p_view_id

The view ID of the view.


Example

This example demonstrates the removal of debug messages within the 'View Identifier' of 12345, belonging to the current application.

BEGIN
    APEX_DEBUG_MESSAGE.REMOVE_DEBUG_BY_VIEW (
        p_application_id => TO_NUMBER(:APP_ID),
        p_view_id        => 12345 );
END;

REMOVE_SESSION_MESSAGES Procedure

This procedure is used to delete all data from a given session within your workspace from the debug message log.

Syntax

APEX_DEBUG_MESSAGE.REMOVE_SESSION_MESSAGES (
    p_session    IN NUMBER  DEFAULT NULL);

Parameters

Table 6-8 describes the parameters available in the REMOVE_SESSION_MESSAGES procedure.

Table 6-8 REMOVE_SESSION_MESSAGES Parameters

Parameter Description

p_session

The session ID. Defaults to your current session.


Example

This example demonstrates the removal of all debug messages logged within the current session. Note: As no value is passed for the p_session parameter, the procedure defaults to the current session.

BEGIN
    APEX_DEBUG_MESSAGE.REMOVE_SESSION_MESSAGES();
END;