Which Data Can Be Collected? 

Use

The Application Log collects messages and puts them in logs. This section describes the data which the Application Log can collect.

Function module	Use
BAL_LOG_CREATE	Create log with header data
BAL_LOG_MSG_ADD	Put message in log
BAL_LOG_EXCEPTION_ADD	Put exception in log

 

Types	Use
BAL_S_LOG	Contains log header data
BAL_S_MSG	Contains message data
BAL_S_EXC	Contains exception data
BAL_S_CONT BAL_S_CONT	Message/log header context
BAL_S_PARM BAL_S_PARM	Message/log header parameter

 

The program SBAL_DEMO_02 simulates a flight check. The check result is logged.

Procedure

Log header

The Application Log opens a log with the function module BAL_LOG_CREATE. The header data is passed in the structure BAL_S_LOG.

The data in this structure is:

BAL_S_LOG structure data	Use
OBJECT, SUBOBJECT	The Application Log is used by various applications. Each log has the attributes OBJECT and SUBOBJECT in the log header so that an application can find its logs efficiently. These attributes (CHAR20) identify the application and subapplication. They can be set with the transaction SLG0. OBJECT = "FREIGHT_COSTS" (Freight costs), SUBOBJECT = "SETTLEMENT" (settlement) These entries are optional until you save (with the function module BAL_DB_SAVE), when OBJECT (and any SUBOBJECT) must be present.
EXTNUMBER	External ID in the log header (CHAR100), defined by the application. It identifies a log. It can be used to link an application object to a log. You put the application object document number in the external log ID. You can combine several logs into one logical log with an external ID (logs can be displayed log-independently). The database has an index on the fields OBJECT/SUBOBJECT/EXTNUMBER, so that a log can be read from the database efficiently when these fields are entered (that is, no Full Table Scan).
ALDATE, ALTIME, ALUSER , ALTCODE, ALPROG, ALMODE	Other log header data that specifies how the log was created. These are date, time and user (ALDATE, ALTIME, ALUSER) and the transaction or program that created the log (ALTCODE, ALPROG). The processing mode in which the log was created is in ALMODE (online, background, and so on).
ALCHDATE, ALCHTIME, ALCHUSER	If a log in the database is changed, the user, date and time are put in the fields ALCHDATE, ALCHTIME and ALCHUSER.
DATE_DEL, DEL_BEFORE	A log has an expiration date (DATE_DEL) after which it can be deleted, and a flag (DEL_BEFORE) that explicitly forbids deletion before this date. For more information, see the BAL_DB_DELETE function module documentation.
ALSTATE	A log has a status that states whether it is finished. It is for information only.
CONTEXT: CONTEXT-TABNAME, CONTEXT-VALUE	Log header context
PARAMS: PARAMS-T_PAR, PARAMS-ALTEXT, PARAMS-CALLBACK	Log header parameters

When you read a log header with the function module BAL_LOG_HDR_READ, you receive other information which is not in BAL_S_LOG because it cannot be specified externally. This is, for example, the internal LOGNUMBER, the number of A, E. W, I and S messages, and the highest problem class that occurred.

Message

A message that can be collected by the Application Log with the function module BAL_LOG_MSG_ADD is represented by the structure BAL_S_MSG. This can have various versions as described below:

BAL_S_ MSG structure data	Use
MSGTY, MSGID, MSGNO, MSGV1, MSGV2, MSGV3, MSGV4	T100 message data. The fields Message type (MSGTY), Work area (MSGID), Error number (MSGNO) must be filled, the fields for the four message variables MSGV1 to MSGV4 are optional.
PROBCLASS, DETLEVEL, ALSORT, TIME_STMP	T100 message attributes, such as problem class (PROBCLASS, for example, "very important"), level of detail (DETLEVEL, from 1 to 9), sort criterion (ALSORT, unrestricted) and timestamp (TIME_STMP). These fields can be displayed in the log (except TIME_STMP).
MSG_COUNT	If a message is cumulated, the cumulation value can be put in MSG_COUNT. The value is incremented when more of these messages occur with the function module BAL_LOG_MSG_CUMULATE.
CONTEXT: CONTEXT-TABNAME, CONTEXT-VALUE	Message context
PARAMS: PARAMS-T_PAR, PARAMS-ALTEXT, PARAMS-CALLBACK	Message parameters

Context

A message or a log header is often only meaningful together with certain additional information. This is the Application Log context.

The message 'Credit limit exceeded for customer ABC' is meaningful in dialog because you are processing a particular document. The log must show the document number. You could put this information in the Message variables, but this can be difficult for detailed environment information (for example, request number, item number, schedule number, and so on).

This context information can be passed with a message (or a log header) in the Application Log. You must define a DDIC structure to contain the context information (maximum length 256 bytes). Enter the DDIC structure name in the CONTEXT field CONTEXT-TABNAME, and the structure content in CONTEXT-VALUE. The context data can be displayed later.

DATA:
  l_s_msg          TYPE bal_s_msg,
  l_s_my_context   type my_ddic_structure.

* Message 123(XY): 'Credit limit exceeded for customer &1'.
  l_s_msg-msgty = 'E'.
  l_s_msg-msgid = 'XY'.
  l_s_msg-msgno = '123'.
  l_s_msg-msgv1 = 'ABC'.
* Put document number in the message as context:
  l_s_my_context-document = '3000012345'.
  l_s_msg-context-tabname = 'MY_DDIC_STRUCTURE'.
  l_s_msg-context-value   = l_s_my_context.
* Put message in log
  CALL FUNCTION 'BAL_LOG_MSG_ADD'
       EXPORTING
          i_s_msg   = l_s_msg
       EXCEPTIONS
          others    = 1.

The line

   l_s_msg-context-value = l_s_my_context.

causes a syntax error in unicode if the context contains fields that are non character-like (for example, INTEGER). It is therefore recommended that you only use character-like fields (subsequent conversion is also possible, old context information in the database is automatically converted when it is read).

If non character-like fields must be used, the above line can be replaced by:

  FIELD-SYMBOLS:                                

    <l_s_my_context>  TYPE c.                        

  ASSIGN l_s_my_context TO <l_s_my_context> CASTING.      

  l_s_msg-context-value   = <l_s_my_context>.

Parameters

Log headers and messages in the Application Log can have parameters. This information can be called in the Application Log display, in the log header or message details. You can use these parameters in two ways:

·        Extended long text
If the long text of a T100 message is not sufficient, because you need more information than the 4 message variables, you can enter a transaction SE61 'Text in dialog' in the PARAMS-ALTEXT field. This text can contain any number of placeholders, which you pass in the table PARAMS-T_PAR.
An example is in the Form routine MSG_ADD_WITH_EXTENDED_LONGTEXT in the program SBAL_DEMO_02.

·        Callback routine
If you specify a callback routine in PARAMS-CALLBACK, the specified routine, in which you can display your own detail information, is called in the detail display.
A callback routine can be used whether the Application Log is a FORM routine or a function module.
To set a callback routine, the following fields therefore have to be specified:
USEREXITT: Type of routine (' ' = FORM, 'F' = Function module)
USEREXITP: Program in which it is found (only for FORM)
USEREXITF: Name of routine (name of form routine or function module)

Exception

An exception that can be collected by the Application Log with the function module BAL_LOG_EXCEPTION_ADD is represented by the structure BAL_S_EXC. This can have various versions as described below:

Data of BAL_S_EXC Structure	Use
EXCEPTION	Exception class from which an exception text is added to the log. This field must be filled.
MSGTY	Message type (MSGTY) of a T100 message. This field must also be filled for exceptions.
PROBCLASS, DETLEVEL, ALSORT, TIME_STMP	Message or exception attributes, such as problem class (PROBCLASS, for example, "very important"), level of detail (DETLEVEL, from 1 to 9), sort criterion (ALSORT, unrestricted) and timestamp (TIME_STMP). These fields can be displayed in the log (except TIME_STMP).
MSG_COUNT	This attribute is not used for exceptions.