XAL External Interface for Alert Management

XAL External Interface for Alert Management

Including External System Management Programs in the CCMS Monitoring Architecture


Version 1.0

SAP AG

XAL External Interface for Alert Management Page 1 of 76

November 12, 2002


Contents 1

The Task of External Interfaces .................................................................................5

2

A Short Introduction to the CCMS Monitoring Architecture....................................6

2.1

Data Suppliers .............................................................................................................................. 7

2.2

Alerts ............................................................................................................................................ 8

2.3

Monitoring Objects and Attributes............................................................................................... 9

2.4

MTE Classes and Attribute Groups............................................................................................ 10

2.5

Methods ...................................................................................................................................... 10

2.6

Additional Information About the Alert Monitor....................................................................... 11

3

Concept of External Interfaces ................................................................................12

3.1

Existing Interfaces ...................................................................................................................... 12

3.2

Naming Conventions .................................................................................................................. 13

3.3

Technical Foundations ............................................................................................................... 13 3.3.1 External Access Through the XMI Interface ......................................................................... 13 3.3.2 Remote Function Call (RFC) ................................................................................................. 14 3.3.3 Framework of a C Program for an RFC Client...................................................................... 15

4

Conditions for SAP Certification..............................................................................17

4.1

Read Alerts ................................................................................................................................. 17

4.2

Read Performance Values .......................................................................................................... 17

4.3

Complete Alert ........................................................................................................................... 17

5

Function Modules......................................................................................................18

5.1

Log On to the XMI Interface (BAPI_XMI_LOGON) ............................................................... 18

5.2

Log Off from the XMI Interface (BAPI_XMI_LOGOFF) ........................................................ 20

5.3

Confirm One or More Alerts (BAPI_SYSTEM_ALERT_ACKNOWLEDGE)........................ 21

5.4

Read the Detail Data of an Alert (BAPI_SYSTEM_ALERT_GETDETAILS) ........................ 23

5.5

Read All Monitors of a Monitor Set (BAPI_SYSTEM_MON_GETLIST)............................... 25

5.6

Read the Template for a Monitor (BAPI_SYSTEM_MON_GETTEMPLATE)....................... 26

5.7

Return the Monitoring Tree of a Monitor (BAPI_SYSTEM_MON_GETTREE)..................... 27

5.8

Read the Properties of a Set (BAPI_SYSTEM_MS_GETDETAILS)....................................... 28

5.9

Read All Saved Monitor Sets (BAPI_SYSTEM_MS_GETLIST)............................................. 29

5.10

Deactivate Alert Generation for an MTE (BAPI_SYSTEM_MTE_DISABLEALGEN).......... 30

5.11

Activate Alert Generation for an MTE (BAPI_SYSTEM_MTE_ENABLEALGEN) ............. 31

5.12

Read the Alerts for an MTE (BAPI_SYSTEM_MTE_GETALERTS) ..................................... 32

SAP AG


November 12, 2002


5.13

Read General MTE Properties (BAPI_SYSTEM_MTE_GETGENPROP)............................... 33

5.14

Read Current Log Attribute Values (BAPI_SYSTEM_MTE_GETMLCURVAL) .................. 36

5.15

Read the History of a Log Attribute (BAPI_SYSTEM_MTE_GETMLHIS)............................ 37

5.16

Read Specific Properties of a Log Attribute (BAPI_SYSTEM_MTE_GETMLPROP)............ 39

5.17

Read Current Performance Values (BAPI_SYSTEM_MTE_GETPERFCURVAL) ................ 40

5.18

Read the Performance Data History (BAPI_SYSTEM_MTE_GETPERFHIS) ........................ 41

5.19

Read Specific Properties of a Performance Attribute (BAPI_SYSTEM_MTE_GETPERFPROP)............................................................................... 43

5.20

Read Specific Properties of a Status Attribute (BAPI_SYSTEM_MTE_GETSMPROP)......... 44

5.21

Read the Current Status Attribute Value (BAPI_SYSTEM_MTE_GETSMVALUE).............. 45

5.22

Read the TID for an MTE Defined by its Name (BAPI_SYSTEM_MTE_GETTIDBYNAME)46

5.23

Read a Subtree Below an MTE (BAPI_SYSTEM_MTE_GETTREE) ..................................... 48

5.24

Reset MTE and Delete Active Alerts (BAPI_SYSTEM_MTE_RESET).................................. 49

5.25

Set General MTE Properties (BAPI_SYSTEM_MTE_SETGENPROP) .................................. 50

5.26

Set Specific Properties of a Log Attribute (BAPI_SYSTEM_MTE_SETMLPROP) ............... 52

5.27

Set Specific Properties of a Performance Attribute (BAPI_SYSTEM_MTE_SETPERFPROP)54

5.28

Set Specific Properties of a Status Attribute (BAPI_SYSTEM_MTE_SETSMPROP) ............ 56

5.29

Create Monitoring Tree By Template (BAPI_SYSTEM_MT_CREATEBYTEMPL).............. 58

5.30

Read Alert Data for a Monitoring Tree (BAPI_SYSTEM_MT_GETALERTDATA).............. 59

5.31

Read Current Performance Values for All Specified Performance Attributes (BAPI_SYSTEM_MT_GETPERFDATA) ................................................................................ 61

6

Description of Selected Transfer Parameters.........................................................62

6.1

Alert ID: AID (Structure BAPIAID).......................................................................................... 62

6.2

Return Messages of the Method Calls: RETURN (Structure BAPIRET2)................................ 62

6.3

ID of an MTE: TID (Structure BAPITID) ................................................................................. 63

6.4

Importance of an Alert (Structure BAPIALDATA)................................................................... 63

6.5

General Properties of an Alert (Structure BAPIALERT)........................................................... 63

6.6

Current Values of a Log Attribute (Structure BAPIMLCVAL) ................................................ 64

6.7

Filter Settings (Structure BAPIMLFLT) .................................................................................... 65

6.8

Current Values of a Performance Attribute (Structure BAPIPACVAL) ................................... 65

6.9

Nodes of a Monitor Template (Structure BAPITMPLND)........................................................ 66

6.10

Complete Set of Node Data (Structure BAPITNDEXT) ........................................................... 67

6.11

Alert Data in a Flat Structure (Structure BAPIALEXT) ............................................................ 68

6.12

Validity Range of Properties: TID_SPECIFIC .......................................................................... 69

SAP AG


November 12, 2002


6.13

Name of a Properties Variant: VARIANT_NAME ................................................................... 69

6.14

Time Basis of Records of the Data History RECTYPE (Data Element ALPDBRTYP) ........... 69

7

Error Messages of the Function Modules ...............................................................71

8

Glossary.....................................................................................................................73

9

Additional Information ..............................................................................................76

SAP AG


November 12, 2002


1 The Task of External Interfaces External interfaces should allow you to monitor and administer SAP installations (especially extensive IT landscapes) using programs from other vendors.

SAP system External program for system administration

Open interfaces

Using external interfaces, you can integrate SAP systems simply and seamlessly both into local administration programs and into company-wide system management infrastructures. This integration cannot and should not fully replace the use of CCMS functions. Complex and security-critical system monitoring tasks must always be performed using the CCMS. Basic CCMS functions are also required and expected by SAP applications and the SAP Solution Manager. This means that SAP applications use internal functions for job management even if you are using an external program for job management and scheduling. The goal of the integration is to provide the user with a homogenous infrastructure for the display of the required information. The goal of the interfaces is to facilitate the information flow between SAP systems and external programs. In this way, external programs can provide additional flexibility when extending basic CCMS functions.

SAP AG


November 12, 2002


2 A Short Introduction to the CCMS Monitoring Architecture In the Alert Monitor, problem messages (Alerts [page 8]) are displayed in a tree structure and are assigned a severity and a color (yellow for a warning, red for a problem).You can identify the current status of your system and process alerts. The Alert Monitor is based on the monitoring architecture introduced with SAP Basis 4.0:

CCMS Monitoring Architecture API

Data Consumer

Data Consumer

Monitor

Alert Monitor

Monitoring Architecture

Monitoring Object

Monitoring Object

Monitoring Object

Monitoring Object

Data Supplier

Data Supplier

Data Supplier

Data Supplier

Operating System

Database

SAP R/3

Other Objects

Methods for Object

Database

• Create MO • Delete MO • Change MO • Report Value for MO

EMC, Workplace, BW, CRM...

The CCMS monitoring architecture is not a monolithic monitoring and administration program. Rather, it provides a flexible framework to which extensive monitoring and administration functions can easily be added. The elements of the monitoring architecture function largely independently of each other and can also be further developed and customized independently of each other: •

Data Supplier A Data Supplier [page 7] is a program that provides data about monitored objects to the monitoring architecture. The monitoring architecture provides an infrastructure for collecting and administering system information. The monitoring architecture constantly compares the values recorded by the data suppliers with the threshold values and triggers an alert if a value exceeds or falls below a threshold values.

•

Data Consumer A Data Consumer is a program that reads data from the monitoring architecture; it displays the information transferred to the monitoring architecture by the data suppliers. SAP delivers both the default data consumer with the Alert Monitor and other special monitors that use the monitoring architecture data.

•

Monitoring Objects and Attributes A monitoring object signifies an object that is to be monitored; a monitoring attribute signifies an information type that is to be reported for a monitoring object (see Monitoring Objects and Attributes [page 9]).

SAP AG


November 12, 2002


The Alert Monitor also provides the administration methods required to monitor the system. In this way, you can set the threshold values for alerts and add or customize auto-reaction and analysis methods: when an alert is triggered, auto-reaction methods react automatically; you can use an analysis method to investigate the cause of an alert without leaving the Alert Monitor. The monitoring architecture also contains tools for the administration and archiving of the alerts.

2.1

Data Suppliers

Data Suppliers provide all of the values that are displayed in the Alert Monitor. They are associated with the individual system components and create Monitoring Objects and Attributes [page 9] that report values to the monitoring architecture. These values are displayed in monitor sets. The monitoring architecture is delivered with data suppliers for the most important components of your SAP system and its environment and you can therefore use it immediately after configuration. When starting the Alert Monitor, you can see that the data suppliers are already active for reporting for the following components: •

The host systems on which your SAP R/3 System is running

•

The SAP R/3 database

•

SAP R/3 instances (application servers) and their services and components

•

Components outside the SAP R/3 System

The data suppliers in your system are started either automatically during the system startup or as they are required. There are two types of data suppliers: •

Passive data suppliers are started by the monitoring architecture, and must therefore be defined there. “Passive” describes the behavior of the data supplier in relation to the monitoring architecture: it does not start itself, but must rather be started by the monitoring architecture. Passive data suppliers are also called data collection methods.

•

Active data suppliers are started by the monitored application, not by the monitoring architecture. These data suppliers are active in their start behavior in relation to the monitoring architecture.

A data supplier writes the values for the monitored objects to a segment of the shared memory, the monitoring segment. This monitoring data can be transferred to the monitoring architecture in two ways: •

Using a defined ABAP interface, in the case of an SAP instance - a free work process is required to do this

•

Using a CCMS agent [Agents], in the case of any server; the transfer is performed using Remote Function Calls (RFC)

SAP AG


November 12, 2002


Monitored SAP System (SAP R/3 4.X) Dispatcher

Central Monitoring System

AP B A

t In

ce a f er

CCMS Agent

Alert Monitor

Alert Monitor

Data Supplier

Monitoring Segment (Shared Memory)

As the connection route using a CCMS agent no longer requires a free work process, the access route is independent of error states of the SAP instance and is therefore more robust. The CCMS agents also use push technology with which the agents automatically report alerts as of SAP Web Application Server 6.10, and as of SAP Web Application Server 6.20, even the data. This helps achieve good performance, as the central monitoring system no longer needs to query the agent periodically for alerts. We therefore recommend that you use CCMS agents when connecting remote systems to the central monitoring system.

2.2

Alerts

The Alert Monitor generates alerts in the monitored system using threshold values and rules, as soon as the status of the monitored system deviates from the norm. The alerts direct your attention to critical situations, meaning that you do not have to search for them yourself. Auto-reaction methods inform you about a problem or react to it in some other way, even if you are not working in the Alert Monitor. For the system administrator, an alert is a malfunction report or a service request. You should react to every alert. Investigate the alert using the analysis methods of the Alert Monitor. When you have solved the problem, or are sure that you can safely ignore it, set the alert to complete. The alert is deleted from the display and saved to the alert database. The Alert Monitor reports alerts in the monitoring tree upward. This means that the color for a node always displays the highest alert in all elements of its branch. If, for example, a host system is displayed as red, one or more components in this tree is displaying a red alert. SAP AG


November 12, 2002


An alert is uniquely assigned to one monitoring tree element (MTE) in the monitoring tree. The alert is generated when values from a data supplier are sent to an MTE. The Alert Monitor evaluates the incoming information in comparison with the alert threshold values. If the incoming data exceeds or falls below a threshold value, the Alert Monitor triggers an alert. The Alert Monitor generates an alert for every status that deviates from the norm, and traces it until you set the status to Complete. Alert Threshold Values and Assignment to Attribute Groups Threshold values and severities are predefined for all monitoring attributes. These settings are based on our extensive experience with SAP R/3 production systems. Monitoring attributes are combined into attribute groups. An attribute group contains the threshold values that the associated monitoring attributes have in common. In this way, all instance-specific copies of the Response Time attribute belong to one attribute group. This means that the same threshold values are set in all instances of an SAP R/3 System. To change threshold values, you only need to change the value for the corresponding attribute group. Alert Colors and their Meaning Color

Meaning

Red

Problem or error

Yellow

Warning

Green

Everything OK

Gray

No information available

2.3

Monitoring Objects and Attributes

A monitoring object represents a component of the IT environment that is to be monitored, such as the CPU of a server, the dialog system, or background processing. Monitoring attributes are values, statuses, or texts that are reported for this object, such as CPU utilization or the response time in the dialog system. An alert can be assigned to a monitoring attribute. The selection of the monitoring objects is made by data suppliers, which exist for all areas of system management. Monitoring objects and attributes are displayed in a hierarchical tree in the alert monitoring tree. If the data reported to the monitoring architecture exceeds or falls below the defined alert threshold values, an alert is triggered in the corresponding MTE. You can assign Method [page 10] to monitoring attributes.

SAP AG


November 12, 2002


Types of Monitoring Attributes Attribute Type

Description

Performance Attribute

Collects reported performance values and calculates the average

Status Attribute

Reports error message texts and alert status

Log Attribute

Checks log and trace files (these attributes can use an existing log mechanism, such as the SAP system log, or you can create a separate log from an application to be used for the implementation)

Text Attribute

Allows a data supplier to report information without alert values; the text can be updated as required

2.4

MTE Classes and Attribute Groups

The alert monitoring tree consists of individual MTEs. These are either components of your IT landscape that are to be monitored (monitoring objects), or values, statuses, or texts that are reported for an object. MTE classes and attribute groups are assigned to these MTEs in the monitoring architecture: •

An MTE class describes the general properties and method assignments that are common to a particular group of monitoring tree elements.

•

An attribute group describes the common threshold values for alerts for a particular attribute type.

MTE classes and attribute groups simplify the customizing of the Alert Monitor, as you do not need to change the threshold values, properties, or methods individually for each MTE, but rather only for the corresponding attribute group or MTE class. MTE classes also simplify the creation of your own rule-based monitors, as you do not need to specify each MTE individually when constructing the alert monitoring tree, but rather only the corresponding MTE classes. The classification of MTEs to MTE classes and attribute groups is already fully predefined. You do not need to make any changes to be able to use this classification.

2.5

Methods

You can assign methods to monitoring attributes and access the method definitions using transaction RZ21 of the Alert Monitor. A method can be a report, a function module, an SAP transaction, or a URL that is to be run as a reaction to an alert. The execution of these methods is possible within the Alert Monitor. If, for example, you double click the MTE for prematurely terminated jobs, the monitoring architecture automatically starts the job administration transaction, in which the job reported in the MTE is already selected. All methods required for standard monitoring functions are predefined. You only need to change the method assignments if you are adding a new method, or if you want to replace one of the SAP standard methods with your own method. You can transport method definitions to other SAP systems. This is, however, only necessary for your own method definitions; the methods delivered by SAP are already available in all systems with the same SAP Basis release.

SAP AG


November 12, 2002


The following methods exist: •

Data Collection Methods These methods allow the collection of information about the SAP system and its environment that is then reported to the monitoring architecture. The methods start automatically or are automatically started by the Alert Monitor at a specified interval.

•

Auto-Reaction Methods These methods automatically start when an alert is triggered. There are several predefined autoreaction methods in the monitoring architecture that you can assign to MTE classes:

•

o

Send an e-mail

o

Execute an operating system command

o

Execute an auto-reaction in the central monitoring system

Analysis Methods These methods allow you to analyze error situations without leaving the Alert Monitor. You start an analysis method manually. An analysis method is, for example, an ABAP program for displaying information about a node in the monitoring tree and for collecting information about the problem that triggered an alert in this node.

2.6

Additional Information About the Alert Monitor •

For a detailed introduction to the concepts and use of the monitoring architecture, and especially to the operation of the Alert Monitor, see [AlMon].

•

For a detailed description of the standard monitors delivered by SAP with their monitoring tree elements, see [StdMon]

SAP AG


November 12, 2002


3 Concept of External Interfaces The XAL interface described here is part of an interface package for external system management programs. On the SAP side, these interfaces consist of a collection of function modules. External programs can call these modules using Remote Function Calls (RFC) (For examples, see the documentation for the interface). For a short introduction to the use of RFC, see the end of this section.

In the following, it is a prerequisite that the external system management program is connected to the SAP system using an agent that performs the communication with the function modules.

3.1

Existing Interfaces

The XM interfaces (eXternal SAP Management) currently include the following interfaces: •

XBP

External interface for background processing

•

XBR

External interface for backup and recovery (current name: BRI or Backint)

•

XMI

External monitoring interface

•

XMB

External interface for basic monitoring

•

XOM

External interface for output management

•

XAL

External interface for alert management

The following table shows, in addition to the abbreviation and the description of the interfaces, the technology used, the SAP Basis release with which it is delivered, and information about whether certification of the interface is possible: Abbr./ Version

Technology

SAP R/3 Release

Description

Certification?

XBP 1.0

RFC

3.1G

Interface for scheduling, release, and monitoring of SAP jobs

Yes (BC-XBP)

XBR 2.0

CLI/Script

3.0G

Interface with functions for backing up and restoring database data

Yes (BC-BRI)

XBM 0.1

RFC

3.1G

Interface with basic functions for scheduling and releasing SAP jobs

No

XMI

RFC

3.1G

Interface that allows external access to the CCMS (including monitoring and log functions)

Yes (with BC-XBP)

XOM 0.1

RFC/CLI

4.0A

Interface with control functions and Output Management return messages

Yes (BC-XOM)

XAL 1.0

RFC

4.0A

Interface for system monitoring and alert management

Yes (BC-XAL)

SAP AG


November 12, 2002


All RFC interfaces use the same function groups as the corresponding internal SAP functions. This does not apply, of course, for the XMI interface, as in this case there are no functions for internal use: SAP Agent

External access

SAP-internal monitoring architecture

XAL Function groups for system monitoring and alert management

3.2

Naming Conventions

All names for the function modules of the XM interfaces consist of the following parts, which are separated from each other by an underscore (“_”): •

Prefix BAPI

•

ID for the actual interface, such as XBP for eXternal Background Processing; for function modules of the XAL interface, this ID is SYSTEM

•

Object to which the module refers

•

Action that the module performs in relation to the specified object

The module to read all saved monitor sets is BAPI_SYSTEM_MS_GETLIST.

3.3

Technical Foundations

The two most important foundations for the external interfaces are XMI and RFC: •

XMI is the interface through which the activities of users and agents during the call of function modules are logged. In particular, XMI logs the first access of an agent to the function group. During this, the name of the external program is stored, and the version number that the external program requires at the interface is checked.

•

Remote Function Calls (RFC) form the basis of communication for the calls of the function modules of which the interface consists on the SAP side.

3.3.1 External Access Through the XMI Interface Within SAP, all external CCMS interfaces use the same function modules. These modules can also be collected themselves in an interface. External accesses are logged in this interface; this is the reason for the name XMI (eXternal Monitoring Interface). SAP AG


November 12, 2002


XMI as a common layer for external interfaces External access

XAL General functions for system monitoring and alert management

interfacespecific layer

XBP XMI – Logging and more...

...

common layer

The XMI interface remains almost invisible to developers that want to integrate external programs into the CCMS; only at the beginning and at the end of a session are the following calls required: •

BAPI_XMI_LOGON (Logon of an external system management program)

•

BAPI_XMI_LOGOFF (Log off of an external system management program)

In addition, the following functions are available to your from the external program: •

BAPI_XMI_ENTER_LOGMSG (Writes a message to the XMI log)

•

BAPI_XMI_GET_VERSIONS (Determines the current version of the interface)

•

BAPI_XMI_SELECT_LOG (Reads the XMI log)

Use transaction RZ15 (XMI Log Administration) to view the XMI log. The following data is displayed, along with other information: •

Date and time of the action

•

Name of the external program, the external user, and the company that provides the program

•

Name of the SAP user

•

Attempted or performed changes (such as resetting an alert)

3.3.2 Remote Function Call (RFC) Functions within and outside SAP systems use RFC to communicate with each other. From a technical point of view, the RFC function is available as a program library (written in the C programming language) for all operating system platforms supported by SAP. Features: With external system management programs, in relation to the SAP system, the program is a client that provides a service to an application server. This service includes the delivery of internal system information and the execution of individual system management functions.

SAP AG


November 12, 2002


RFC works in individual sessions - the user opens a session, performs the relevant tasks, and closes the session again. Opening the session requires a normal logon to the SAP system with user and password, with which the user is identified by the SAP system. This user must therefore exist within the SAP system and have the required authorizations for the activities that you want to perform during the RFC session. RFC can be used synchronously, asynchronously, or transactionally. For a detailed introduction to the basics and functions of RFC, see the online documentation (see [RFC]). The following examples use synchronous RFC calls (with the exception of RfcCall): Overview of the most important RFC commands: Name

Short Description

RfcOpen()

Creation of an RFC connection with an application server; the connection details are either specified directly or read from a file

RfcCallReceive()

Synchronous call of an RFC client; a function module is called in the SAP system; the client regains program control after the function module has been processed

RfcCall()

Calls a function module without waiting for the result of the call

RfcLastError()

Call for analysis of RFC errors; the information is displayed using stout

RfcClose()

Close the RFC connection and end the session

ItCreate() ItDelete()

Reservation and release of memory for the exchange of table contents between the client and the SAP system

3.3.3 Framework of a C Program for an RFC Client The example below is a framework of a program that uses the RFC program library as an RFC client, logs on to the XMI interface as an external program, reads the XMI logs and then logs off again: #include "saprfc.h" main() { rfc_handle = RfcOpen(&rfc_opt); function = "BAPI_XMI_LOGON"; ..... rfc_rc = RfcCallReceive(rfc_handle, function, exporting, importing, tables, &exception); function = "BAPI_XMI_SELECT_LOG"; ...... rfc_rc = RfcCallReceive(rfc_handle, function, exporting, importing, tables, &exception); /* a lot more action */ function = "BAPI_XMI_LOGOFF"; ......... rfc_rc = RfcCallReceive(rfc_handle, function, exporting, importing, tables, &exception); RfcClose(rfc_handle); }

SAP AG


November 12, 2002


From this example, you can develop a model for a session between an SAP system and an external system management program. An RFC session contains one or more XMI sessions. Each XMI session contains a series of function calls from the function group of the relevant interface: Open RFC Session

Authorization from SAP

Open XMI Session for XAL Call XAL Functions Open XMI Session for XBP

Identification of the XM Identification of the Agents Identification of the XM

Call XBP Functions

Identification of the Agents

Call XAL Functions

Identification of the Agents

End XMI Session End RFC Session

SAP AG


November 12, 2002


4 Conditions for SAP Certification To obtain certification from SAP, the relevant external system management program must at least be able to read an confirm alerts, and to read performance values.

To collect desired data from CCMS monitors, you first require the name of the CCMS monitoring architecture monitors. You can use the following BAPIs to obtain these:

4.1

•

Read All Saved Monitor Sets (BAPI_SYSTEM_MS_GETLIST) [page 29]

•

Read All Monitors of a Monitor Set (BAPI_SYSTEM_MON_GETLIST) [page 25]

Read Alerts

To read the alert data for a specified monitoring tree, first collect the node data for the monitor to then query the current alert data. You require the following BAPIs to do this: •

Return the Monitoring Tree of a Monitor (BAPI_SYSTEM_MON_GETTREE) [page 27]

•

Read Alert Data for a Monitoring Tree (BAPI_SYSTEM_MT_GETALERTDATA) [page 59]

4.2

Read Performance Values

When reading performance values for any monitor, proceed in the same way as when collecting alerts. First collect the node data for the monitor, to then query the current performance values for these nodes. You require the following BAPIs to do this: •

Return the Monitoring Tree of a Monitor (BAPI_SYSTEM_MON_GETTREE) [page 27]

•

Read Current Performance Values (BAPI_SYSTEM_MTE_GETPERFCURVAL) [page 40]

4.3

Complete Alert

When you set an alert to complete status, it is removed from the active alerts. Set alerts to complete as soon as you have solved the underlying problem or have determined that the alert was triggered by a temporary problem and can be ignored. When you set an alert to complete, it is stored in the alert database. To complete alerts using the XAL interface, the alert IDs must be available to you for the corresponding alerts (see Alert ID: AID (Structure BAPIAID) [page 62]). You receive these as return parameters of the function module BAPI_SYSTEM_MT_GETALERTDATA , when you Read Alerts [page 17]. Then use the following BAPI: •

Confirm One or More Alerts (BAPI_SYSTEM_ALERT_ACKNOWLEDGE) [page 21]

SAP AG


November 12, 2002


5 Function Modules

5.1

•

The terms Import and Export in the classification of the transfer parameters should always be considered from the point of view of the corresponding function module; that is, the function module is called with the import parameters, and returns export parameters.

•

As the use of XAL function modules first requires a log on to the XMI interface, the following list also includes the function modules BAPI_XMI_LOGON and BAPI_XMI_LOGOFF.

Log On to the XMI Interface (BAPI_XMI_LOGON)

Function Name SXMI_LOGON

Name

BAPI_XMI_LOGON

Short Description

Logon of an agent to the external XMI interface

BAPI Object

SystemManagementSession

BAPI Method

Logon

Function

With this method, you can log on to one of the CCMS system management interfaces. This logon is a prerequisite for the use of the functions of the CCMS interfaces. The logon ensures that all accesses to system management functions are logged. It is also possible to load language-specific messages from external products using the CCMS XMI session interface.

Notes

Before the first call of this function module, the external system management program must first log on to the SAP R/3 System with an SAP R/3 user name and the associated password (C function RfcOpen).

Parameters (Import)

INTERFACE

ID of the interface with which you are to work (such as XAL); if you do not set this parameter, you can only use the methods of the object XMISESSION

VERSION

Version of the CCMS system management interface that the external product expects from the SAP system (such as 1.1); you can find this version in the SAP interface documentation

EXTPRODUCT

Name of the product that wants to log on to a CCMS system management interface. This specification is useful for documentation purposes; no authorization check or other program function is performed with this specification

EXTCOMPANY

Vendor of the product that wants to log on to a CCMS system management interface

RETURN

Structure BAPIRET2 with the return messages from the method call

SESSIONID

Unique ID for the new session with a CCMS system management interface

Parameters (Export)

SAP AG


November 12, 2002


Name

BAPI_XMI_LOGON

RFC-Interface

function BAPI_XMI_LOGON importing EXTCOMPANY like TXMILOGRAW_EXTCOMPANY

type RFC_CHAR length 16

EXTPRODUCT like TXMILOGRAW_EXTPRODUCT


INTERFACE like TXMILOGRAW_INTERFACE VERSION like TXMILOGRAW_VERSION



exporting RETURN structure BAPIRET2 length 548 number of fields 14 SESSIONID like TXMILOGRAW_SESSIONID type RFC_CHAR length 24 tables exceptions ALREADY_LOGGED_ON CANT_LOG_ACTION INVALID_PARAMETERS LOGON_DENIED PROBLEM_DETECTED UNKNOWN_INTERFACE UNKNOWN_VERSION

SAP AG


November 12, 2002


5.2

Log Off from the XMI Interface (BAPI_XMI_LOGOFF)

Function Name SXMI_LOGON

Name

BAPI_XMI_LOGOFF

Short Description

Log off of an agent from the external XMI interface

BAPI Object

SystemManagementSession

BAPI Method

Logoff

Function

Use this method to end a session with a CCMS system management interface or to log off from the XMI interface completely.

Parameters (Import)

INTERFACE

ID of the CCMS system management interface from which you want to log off; there are the following options:

Parameters (Export)

RETURN

RFC Interface

function BAPI_XMI_LOGOFF

•

A specific interface (such as XAL): the connection to this interface is closed. If it was the last connection, the XMISESSION methods are still available after the connection is closed

•

Wildcard characters (*): All interfaces are closed; in the same way as with the first variant, the XMISESSION methods are still available after the interfaces are closed

•

Parameter not set: complete log off, after which no XMI calls are possible any longer (you must then close the RFC connection with the call rfcClose; the call SXMI_LOGON after this is answered with a new SESSIONID)


importing INTERFACE like TXMILOGRAW_INTERFACE


exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions CANT_LOG_ACTION NOT_LOGGED_ON PROBLEM_DETECTED

SAP AG


November 12, 2002


5.3

Confirm One or More Alerts (BAPI_SYSTEM_ALERT_ACKNOWLEDGE)

Name

BAPI_SYSTEM_ALERT_ACKNOWLEDGE

Short Description

Confirms an alert

BAPI Object

SystemAlert

BAPI Method

Acknowledge

Function

This method allows the confirmation of an alert by an external management tool (input in parameter AID). If multiple alerts are to be confirmed, the optional table BAPIAID_TBL can be filled. In this case, the parameter AID is ignored.

Parameters (Import)

AID

Alert ID (Structure BAPIAID)

EXTERNAL_USER_NAME

Name of the user in the external system that initiated the method call

BAPIAID_TBL

Table whose elements have the structure of the alert ID (structure BAPIAID), extended by a return code (RC and RC_TEXT) (as of SAP Basis 4.6C). The columns RC (Return Code) and RC_TEXT return the success (RC = 0) or failure (RC > 0) of the action for each alert. All alerts are always processed, even if an error occurs when confirming an alert. You can determine the alert for which the confirmation failed from the columns RC and RC_TEXT. The BAPI return value RETURN returns internal error in this case. This means only that at least one confirmation failed, and not that all confirmations failed.

Parameters (Export)

RETURN

Exceptions

MSG_AID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_AID_INVALID MSG_TID_INVALID MSG_CALL_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_DB_PROBLEM MSG_UNKNOWN_PROBLEM

SAP AG



November 12, 2002


Name

BAPI_SYSTEM_ALERT_ACKNOWLEDGE

RFC Interface

function BAPI_SYSTEM_ALERT_ACKNOWLEDGE importing AID structure BAPIAID length 84 number of fields 7 EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables BAPIAID_TBL structure BAPIAID_RC length 120 number of fields 9 exceptions

SAP AG


November 12, 2002


5.4

Read the Detail Data of an Alert (BAPI_SYSTEM_ALERT_GETDETAILS)

Name

BAPI_SYSTEM_ALERT_GETDETAILS

Short Description

Reads the detail data of an alert

BAPI Object

SystemAlert

BAPI Method

GetDetails

Function

For an alert specified with an alert ID (AID), this function returns all relevant alert properties, such as the meaning of the alert or the MTE associated with the alert.

Parameters (Import)

AID

Alert ID (Structure BAPIAID)

GET_ACTIVE

Indicator that, when set to the value “X”, ensures that the system searches only the active alerts for the desired alert (optional)

GET_HISTORY

Indicator that, when set to the value “X”, ensures that the system searches only the completed alerts for the desired alert (optional)

EXTERNAL_USER_NAME


TID

ID of an MTE (Structure BAPITID)

VALUE

Color and severity and therefore the importance of an alert (Structure BAPIALDATA)

TIME

Timepoint at which an alert occurred, consisting of date and time

PROPERTIES

General properties of the alert, such as the timepoint of the last value change (Structure BAPIALERT)

XMI_RAW_MSG

Parameter of the XMI message associated with the alert

XMI_EXT_MSG

Triggered XMI message for the alert

RETURN


Parameters (Export)

Exceptions

SAP AG

MSG_AID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_AID_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_UNKNOWN_PROBLEM


November 12, 2002


Name

BAPI_SYSTEM_ALERT_GETDETAILS

RFC Interface

function BAPI_SYSTEM_ALERT_GETDETAILS importing AID structure BAPIAID length 84 number of fields 7 EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 GET_ACTIVE like BAPIPARAMS-BOOL_PARA default 'X' type RFC_CHAR length 1 GET_HISTORY like BAPIPARAMS-BOOL_PARA default ' ' type RFC_CHAR length 1 exporting PROPERTIES structure BAPIALERT length 212 number of fields 12 RETURN structure BAPIRET2 length 548 number of fields 14 TID structure BAPITID length 84 number of fields 7 TIME structure BAPIALDATE length 14 number of fields 2 VALUE structure BAPIALDATA length 8 number of fields 2 XMI_EXT_MSG structure BAPIXMIEXT length 255 number of fields 1 XMI_RAW_MSG structure BAPIXMIRAW length 690 number of fields 11 tables exceptions

SAP AG


November 12, 2002


5.5

Read All Monitors of a Monitor Set (BAPI_SYSTEM_MON_GETLIST)

Name

BAPI_SYSTEM_MON_GETLIST

Short Description

Reads all monitors of a monitor set

BAPI Object

SystemMonitor

BAPI Method

GetList

Function

This method returns all monitors of a monitor set specified by its name.

Parameters (Import)

MONI_SET_NAME

Name of the desired monitor set (optional; if no set is specified, the monitor names of all monitor sets are returned)

EXTERNAL_USER_NAME


Parameters (Export)

RETURN


MONITOR_NAMES

Table of entries of the structure BAPIMNNAME, in which the names of the monitors for the specified monitor set MONI_SET_NAME are output. This structure contains the components MONI_NAME (name of the monitor) and MS_NAME (name of the monitor set). The name of a monitor must be unique within a monitor set. The name of a monitor set is globally unique.

Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_NO_MONITOR_SETS_FOUND MSG_UNKNOWN_PROBLEM MSG_MONI_SET_NAME_MISSING MSG_INVALID_MONI_SET_NAME MSG_MONI_SET_IS_EMPTY

RFC Interface

function BAPI_SYSTEM_MON_GETLIST importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER


MONI_SET_NAME structure BAPIMSNAME length 60 number of fields 1 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables MONITOR_NAMES structure BAPIMNNAME length 120 number of fields 2 exceptions

SAP AG


November 12, 2002


5.6

Read the Template for a Monitor (BAPI_SYSTEM_MON_GETTEMPLATE)

Name

BAPI_SYSTEM_MON_GETTEMPLATE

Short Description

Reads the monitor template for a particular monitor

BAPI Object

SystemMonitor

BAPI Method

GetTemplate

Function

This method returns the monitor template associated with the monitor. You can create the complete monitoring tree using the monitor template (for example, with SystemMonitorTree.CreateByTemplate).

Notes

In addition to the virtual summary nodes, the monitor template contains the real top nodes of the (real) subtrees that belong to the monitoring tree.

Parameters (Import)

MONITOR_NAME

Complete name of the monitor (Structure BAPIMNNAME). The structure contains the components MONI_NAME (name of the monitor) and MS_NAME (name of the monitor set). The name of a monitor must be unique within a monitor set.

EXTERNAL_USER_NAME


Parameters (Export)

RETURN


TEMPLATE_NODES

Table with the nodes of the monitor template (structure BAPITMPLND)

Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_MONI_SET_NAME_MISSING MSG_INVALID_MONI_SET_NAME MSG_MONI_NAME_MISSING MSG_INVALID_MONI_NAME MSG_CANT_READ_MONISET_FROM_DB MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MON_GETTEMPLATE importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER


MONITOR_NAME structure BAPIMNNAME length 120 number of fields 2 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables TEMPLATE_NODES structure BAPITMPLND length 232 number of fields 13 exceptions

SAP AG


November 12, 2002


5.7

Return the Monitoring Tree of a Monitor (BAPI_SYSTEM_MON_GETTREE)

Name

BAPI_SYSTEM_MON_GETTREE

Short Description

Returns the monitoring tree for the monitor

BAPI Object

SystemMonitor

BAPI Method

GetTree

Function

This method returns the complete monitoring tree of a monitor specified by its name. This monitoring tree contains both the virtual node and all real nodes.

Parameters (Import)

MONITOR_NAME

Complete name of the monitor (structure BAPIMNNAME). The structure contains the components MONI_NAME (name of the monitor) and MS_NAME (name of the monitor set). The name of a monitor must be unique within a monitor set.

EXTERNAL_USER_NAME


MAX_TREE_DEPTH

Maximum depth to which the monitoring tree is to be output (optional; by default, the maximum depth has the value 0, meaning that the complete monitor is output)

VIS_ON_USR_LEVEL

Visibility level (optional, is ignored – see SAP Note 429254)

Parameters (Export)

RETURN


TREE_NODES

Table with all node data of the monitoring tree (structure BAPITNDEXT)

Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_MONI_SET_NAME_MISSING MSG_INVALID_MONI_SET_NAME MSG_MONI_NAME_MISSING MSG_INVALID_MONI_NAME MSG_CANT_READ_MONISET_FROM_DB MSG_CANT_GET_MONI_PRESENTATION MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MON_GETTREE importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 MAX_TREE_DEPTH like BAPIPARAMS-MAXLEVEL default 0 type RFC_INT length 4 MONITOR_NAME structure BAPIMNNAME length 120 number of fields 2 VIS_ON_USR_LEVEL like BAPIPARAMS-VISUSRLEV default 3 type RFC_INT length 4 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables TREE_NODES structure BAPITNDEXT length 440 number of fields 40 exceptions

SAP AG


November 12, 2002


5.8

Read the Properties of a Set (BAPI_SYSTEM_MS_GETDETAILS)

Name

BAPI_SYSTEM_MS_GETDETAILS

Short Description

Reads the (display) properties of a monitor set

BAPI Object

SystemMonitorSet

BAPI Method

GetDetails

Function

This method returns the currently defined display properties for the monitor set specified by its name. An external management tool can use these values to structure the display of a monitor set in the same way as the view in SAP R/3.

Parameters (Import)

MONI_SET_NAME

Name of the desired monitor set

EXTERNAL_USER_NAME


Parameters (Export)

PROPERTIES

Structure BAPIMSPROP with the various (display) properties of the monitor set

RETURN


Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_MONI_SET_NAME_MISSING MSG_INVALID_MONI_SET_NAME MSG_CANT_GET_DISPLAY_CONFIG MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MS_GETDETAILS importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 MONI_SET_NAME structure BAPIMSNAME length 60 number of fields 1 exporting PROPERTIES structure BAPIMSPROP length 136 number of fields 32 RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.9

Read All Saved Monitor Sets (BAPI_SYSTEM_MS_GETLIST)

Name

BAPI_SYSTEM_MS_GETLIST

Short Description

Reads all saved monitor sets

BAPI Object

SystemMonitorSet

BAPI Method

GetList

Function

You can determine the names of all existing monitor sets using this method. Using these names, you can then determine the names of the monitors that exist in each of the sets.

Parameters (Import)

EXTERNAL_USER_NAME


Parameters (Export)

RETURN

Structure BAPIRET2 with the return values from the method call

MONITOR_SETS

Table with the names of the existing monitor sets (Structure BAPIMSNAME, that consists of only the component NAME)

Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_NO_MONITOR_SETS_FOUND MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MS_GETLIST importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 exporting RETURN structure BAPIRET2 length 552 number of fields 14 tables MONITOR_SETS structure BAPIMSNAME length 60 number of fields 1 exceptions

SAP AG


November 12, 2002


5.10

Deactivate Alert Generation for an MTE (BAPI_SYSTEM_MTE_DISABLEALGEN)

Name

BAPI_SYSTEM_MTE_DISABLEALGEN

Short Description

Deactivates alert generation for a monitoring tree element

BAPI Object

MonitorTreeElement

BAPI Method

DisableAlertGeneration

Function

You can use this method to deactivate alert generation for the specified MTE. You can use MonitorTreeElement.EnableAlertGeneration to activate alert generation again.

Parameters (Import)

TID

ID of an MTE (structure BAPITID)

EXTERNAL_USER_NAME


Parameters (Export)

RETURN


Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_TID_INVALID MSG_CALL_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_DB_PROBLEM MSG_INTERNAL_ERROR MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_DISABLEALGEN importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.11

Activate Alert Generation for an MTE (BAPI_SYSTEM_MTE_ENABLEALGEN)

Name

BAPI_SYSTEM_MTE_ENABLEALGEN

Short Description

Activates alert generation for a monitoring tree element

BAPI Object

MonitorTreeElement

BAPI Method

EnableAlertGeneration

Function

You can use this method to activate alert generation for the specified MTE. You can use MonitorTreeElement.DisableAlertGeneration to deactivate alert generation again.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

RETURN


Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_TID_INVALID MSG_CALL_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_DB_PROBLEM MSG_INTERNAL_ERROR MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_ENABLEALGEN importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.12

Read the Alerts for an MTE (BAPI_SYSTEM_MTE_GETALERTS)

Name

BAPI_SYSTEM_MTE_GETALERTS

Short Description

Reads the alerts for a monitoring tree element

BAPI Object

MonitorTreeElement

BAPI Method

GetAlerts

Function

This method returns a table with the alert IDs for the monitoring tree element. You can then collect the alert properties for an alert ID using the method SystemAlert.GetDetails.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

ALERTS

Table with the found alert IDs (structure BAPIAID) of the specified MTE

RETURN


Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_TID_INVALID MSG_COMMUNICATION_PROBLEM MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_GETALERTS importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables ALERTS structure BAPIAID length 84 number of fields 7 exceptions

SAP AG


November 12, 2002


5.13

Read General MTE Properties (BAPI_SYSTEM_MTE_GETGENPROP)

Name

BAPI_SYSTEM_MTE_GETGENPROP

Short Description

Reads the general properties of a monitoring tree element

BAPI Object

MonitorTreeElement

BAPI Method

GetGeneralProperties

Function

This function returns the general properties of an MTE. These general properties apply for all possible types of MTE.

Notes

The type-specific properties of an MTE can be collected using special methods. For example, MonitorTreeElement.GetPerfProperties returns the specific properties of a performance attribute.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

GENERAL_INFO

General specifications for the MTE, such as the name or the assigned MTE class

GENERAL_PROPERTIES

General properties of an MTE; the fields of this structure correspond in their meaning to the input parameters TID_SPECIFIC – TEXT_ID of the function module Set General MTE Properties (BAPI_SYSTEM_MTE_SETGENPROP) [page 50]

GENERAL_VALUES

Structure with the current general values of an MTE. This structure consists of the following components:

SAP AG

•

Status of the data messages (DELIVERSTA); the statuses are defined in RSALBAPI in the constants MT_DVLSTAT_*

•

Number of active alerts for this MTE (COUNTOFACT)

•

Total number of alerts that were reported for this MTE (COUNTSUM)

LAST_VALUE_TIME

Timepoint (date and time) of the last value change of the MTE

HIGHEST_ALERT

Alert ID (structure BAPIAID) of the most important alert for the MTE in the Open Alerts view

HIGHEST_ALERT_DATA

Color and severity of the most important alert for the MTE in the Open Alerts view

ACTUAL_ALERT

Alert ID (structure BAPIAID) of the alert for the MTE in the Current Status view

ACTUAL_ALERT_DATA

Color and severity of the alert for the MTE in the Current Status view


November 12, 2002


Name

BAPI_SYSTEM_MTE_GETGENPROP COLLECTION_TOOL_DEF ONALERT_TOOL_DEF ANALYZE_TOOL_DEF

COLLECTION_TOOL_RUN ONALERT_TOOL_RUN

Exceptions

SAP AG

Information about the effectively assigned methods (data collection, analysis, and auto.-reaction methods) of the MTE (structure BAPITLDEF) with the following components: •

Name of the method (TOOLNAME)

•

Name of the dispatcher responsible (TOOLDISPAT)

•

Status of the method (TOOLDEFSTA); the possible statuses are defined in RSALBAPI in the constants AL_TD_DEF_*

•

Indicator of whether the assignment to the method was set using the MTE class or using the individual MTE (CLASSORSPC)

•

Indicator of whether the assignment to the method was inherited from the superordinate node (ASSBYPAR)

Runtime information about the data collection and auto-reaction methods of the MTE (structure BAPITLRUN) with the following components: •

Name of the method (TOOLNAME)

•

Runtime status of the method (TOOLRUNSTA); the possible statuses are defined in RSALBAPI in the constants AL_TD_RUN_*

•

Start date and time of the method (TOOLRUNDAT, TOOLRUNTIM)

•

Name of the dispatcher responsible (TOOLRUNDSP)

PARENT_TID

TID of the parent node of the MTE (structure BAPITID)

PARENT_DATA

Name of the MTE and the MTE class for the parent node

RETURN


MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_TID_INVALID MSG_COMMUNICATION_PROBLEM MSG_UNKNOWN_PROBLEM


November 12, 2002


Name

BAPI_SYSTEM_MTE_GETGENPROP

RFC Interface

function BAPI_SYSTEM_MTE_GETGENPROP importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting ACTUAL_ALERT structure BAPIAID length 84 number of fields 7 ACTUAL_ALERT_DATA structure BAPIALDATA length 8 number of fields 2 ANALYZE_TOOL_DEF structure BAPITLDEF length 92 number of fields 5 COLLECTION_TOOL_DEF structure BAPITLDEF length 92 number of fields 5 COLLECTION_TOOL_RUN structure BAPITLRUN length 100 number of fields 5 GENERAL_INFO structure BAPIMTEGEN length 128 number of fields 5 GENERAL_PROPERTIES structure BAPIMTEPRP length 80 number of fields 10 GENERAL_VALUES structure BAPIMTEVAL length 12 number of fields 3 HIGHEST_ALERT structure BAPIAID length 84 number of fields 7 HIGHEST_ALERT_DATA structure BAPIALDATA length 8 number of fields 2 LAST_VALUE_TIME structure BAPIALDATE length 14 number of fields 2 ONALERT_TOOL_DEF structure BAPITLDEF length 92 number of fields 5 ONALERT_TOOL_RUN structure BAPITLRUN length 100 number of fields 5 PARENT_DATA structure BAPIPARENT length 80 number of fields 2 PARENT_TID structure BAPITID length 84 number of fields 7 RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.14

Read Current Log Attribute Values (BAPI_SYSTEM_MTE_GETMLCURVAL)

Name

BAPI_SYSTEM_MTE_GETMLCURVAL

Short Description

Reads the current values of a log attribute

BAPI Object

MonitorTreeElement

BAPI Method

GetMessageLogCurrentValue

Function

This method returns the current values of the log attribute.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

CURRENT_VALUE

Current values of the log attribute

XMI_MSG_RAW

Parameter of the XMI messages associated with the alert

XMI_MSG_EXT

XMI message triggered for the alert

RETURN


Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_TID_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_DB_PROBLEM MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_GETMLCURVAL importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting CURRENT_VALUE structure BAPIMLCVAL length 96 number of fields 9 RETURN structure BAPIRET2 length 548 number of fields 14 XMI_MSG_EXT structure BAPIXMIEXT length 255 number of fields 1 XMI_MSG_RAW structure BAPIXMIRAW length 690 number of fields 11 tables exceptions

SAP AG


November 12, 2002


5.15

Read the History of a Log Attribute (BAPI_SYSTEM_MTE_GETMLHIS)

Name

BAPI_SYSTEM_MTE_GETMLHIS

Short Description

Reads the value history of a log attribute

BAPI Object

MonitorTreeElement

BAPI Method

GetMessageLogHistory

Function

Using this method, you can collect the value history of a log attribute for any time frame.

Notes

The value history of a log attribute essentially consists of a segment of the monitored log file. The values of a log attribute are therefore generally individual lines from a log file of this type.

Parameters (Import)

TID


START_TIMESTAMP END_TIMESTAMP

Time period for which the value history is to be collected

CLIENT

Client for which the value history is to be collected (this parameter is optional; if it is not specified, value histories are returned for all clients)

USERID

User for which the value history is to be collected (this parameter is optional; if it is not specified, value histories are returned for all users)

EXTERNAL_USER_NAME


RETURN


MSG_LINE_DATA

Table with the current values for the individual lines of the value history, such as the time of the occurrence of the messages, the important of the associated alert, and the ID of the messages in the external storage mechanism (structure BAPIMLCVAL)

XMI_MSG_RAW

Table with the parameters of the XMI messages for the log attribute (structure BAPIXMIRAW)

XMI_MSG_EXT

Table with the resolved XMI messages (structure BAPIXMIEXT; the structure contains only the component MSG) for the log attribute

Parameters (Export)

Exceptions

SAP AG

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_TID_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_DB_PROBLEM MSG_INVALID_TIME_RANGE MSG_UNKNOWN_PROBLEM


November 12, 2002


Name

BAPI_SYSTEM_MTE_GETMLHIS

RFC Interface

function BAPI_SYSTEM_MTE_GETMLHIS importing CLIENT like BAPIPARAMS-MANDANT type RFC_CHAR length 3 END_TIMESTAMP like BAPIPARAMS-TIMESTAMP type RFC_BCD length 8 decimals 0 EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 START_TIMESTAMP like BAPIPARAMS-TIMESTAMP type RFC_BCD length 8 decimals 0 TID structure BAPITID length 84 number of fields 7 USERID like BAPIPARAMS-USERID type RFC_CHAR length 12 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables MSG_LINE_DATA structure BAPIMLCVAL length 96 number of fields 9 XMI_MSG_EXT structure BAPIXMIEXT length 255 number of fields 1 XMI_MSG_RAW structure BAPIXMIRAW length 690 number of fields 11 exceptions

SAP AG


November 12, 2002


5.16

Read Specific Properties of a Log Attribute (BAPI_SYSTEM_MTE_GETMLPROP)

Name

BAPI_SYSTEM_MTE_GETMLPROP

Short Description

Reads the specific properties of a log attribute

BAPI Object

MonitorTreeElement

BAPI Method

GetMessageLogProperties

Function

You can use this method to collect the specific properties of a log attribute.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

PROPERTIES

Specific properties of a log attribute; the fields of this structure correspond in their meaning to the input parameters RAISE_VALUE – KEEP_LINE_MAX of the function module Set Specific Properties of a Log Attribute (BAPI_SYSTEM_MTE_SETMLPROP) [Page 52]; in addition, the structure contains the field ATTRGROUP, which specifies the assigned attribute group

RETURN

Structure with the return messages from the method call

FILTER

Table that describes the filter set for the log attribute (the individual entries of the table have the structure BAPIMLFLT

Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_TID_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_DB_PROBLEM MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_GETMLPROP importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting PROPERTIES structure BAPIMLPROP length 68 number of fields 8 RETURN structure BAPIRET2 length 548 number of fields 14 tables FILTER structure BAPIMLFLT length 104 number of fields 7 exceptions

SAP AG


November 12, 2002


5.17

Read Current Performance Values (BAPI_SYSTEM_MTE_GETPERFCURVAL)

Name

BAPI_SYSTEM_MTE_GETPERFCURVAL

Short Description

Reads the current performance values

BAPI Object

MonitorTreeElement

BAPI Method

GetPerformanceAttrCurrentValue

Function

This method returns the current values of the performance attribute.

Notes

You can collect the value history using the method MonitorTreeElement.GetPerformanceAttrHistory.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

CURRENT VALUE

Current values of the performance attribute (structure BAPIPACVAL)

RETURN


Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_GETPERFCURVAL importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting CURRENT_VALUE structure BAPIPACVAL length 104 number of fields 20 RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.18

Read the Performance Data History (BAPI_SYSTEM_MTE_GETPERFHIS)

Name

BAPI_SYSTEM_MTE_GETPERFHIS

Short Description

Reads the performance data history

BAPI Object

MonitorTreeElement

BAPI Method

GetPerformanceAttrHistory

Function

This method returns the value history of the specified performance attribute. In this context, value history means the performance values that are stored in the performance database, collected and averaged over a particular period of time.

Notes

You can collect the current performance values using the method MonitorTreeElement.GetPerformanceAttrCurrentValue.

Parameters (Import)

TID


EXTERNAL_USER_NAME


REQUESTS

Table of entries with the structure BAPIPAREQ; they contain information about exactly which data is requested:

Parameters (Export)

SAP AG

•

Time basis of the data (RECTYPE)

•

Date range from which the values are requested from the data history (FIRSTDAY, LASTDAY)

RETURN


HISTORY_VALUES

Table with entries with the structure BAPIPAHIS; they contains the following collected history data: •

Time basis of the data (RECTYPE)

•

Start and end date of the time period of the history data (START_DATE, END_DATE)

•

Start time of the time period of the history data (START_TIME)

•

Length of time period of the history data in seconds (PERIOD)

•

Total of the history data (DATA_SUM)

•

Number of measured values of the history data (DATA_CNT)

•

Average value of the history data (DATA_AVG)

•

AVG_TYPE: is not used


November 12, 2002


Name

BAPI_SYSTEM_MTE_GETPERFHIS

Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_REQUESTS_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_TID_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_DB_PROBLEM MSG_INVALID_REC_TYPE MSG_INVALID_DATA_RANGE MSG_EMPTY_INPUT_DATE MSG_NO_ACCESS_TO_ANOTHER_R3 MSG_REQUESTS_MISSING MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_GETPERFHIS importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables HISTORY_VALUES structure BAPIPAHIS length 60 number of fields 9 REQUESTS structure BAPIPAREQ length 22 number of fields 3 exceptions

SAP AG


November 12, 2002


5.19 Read Specific Properties of a Performance Attribute (BAPI_SYSTEM_MTE_GETPERFPROP) Name

BAPI_SYSTEM_MTE_GETPERFPROP

Short Description

Reads the specific properties of a performance attribute

BAPI Object

MonitorTreeElement

BAPI Method

GetPerformanceAttrProperties

Function

This method returns the specific properties of a performance attribute.

Parameters (Import)

TID


EXTERNAL_USER_NAME

Name of the user in the external system that initiated the external call

Parameters (Export)

PROPERTIES

Specific properties of a performance attribute (structure BAPIPAPROP); the fields of this structure correspond in their meaning to the input parameters RELEVANT_VALUE – DECIMALS of the function module Set Specific Properties of a Performance Attribute (BAPI_SYSTEM_MTE_SETPERFPROP) [page 54]; the structure also contains the field ATTRGROUP, which specifies the associated attribute group

RETURN


Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_GETPERFPROP importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting PROPERTIES structure BAPIPAPROP length 124 number of fields 12 RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.20 Read Specific Properties of a Status Attribute (BAPI_SYSTEM_MTE_GETSMPROP) Name

BAPI_SYSTEM_MTE_GETSMPROP

Short Description

Reads the specific properties of a status attribute

BAPI Object

MonitorTreeElement

BAPI Method

GetStatusMessageAttrProperties

Function

This method returns the specific Customizing properties of a status attribute.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

PROPERTIES

Specific properties of a status attribute (structure BAPISMPROP); the fields of this structure correspond in their meaning to the input parameters ALERT_MODE and ALERT_SHIFT of the function module Set Specific Properties of a Status Attribute (BAPI_SYSTEM_MTE_SETSMPROP) [page 56]; the structure also contains the field ATTRGROUP, which specifies the associated attribute group

RETURN


Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_GETSMPROP importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting PROPERTIES structure BAPISMPROP length 48 number of fields 3 RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.21

Read the Current Status Attribute Value (BAPI_SYSTEM_MTE_GETSMVALUE)

Name

BAPI_SYSTEM_MTE_GETSMVALUE

Short Description

Reads the current values of the status attribute

BAPI Object

MonitorTreeElement

BAPI Method

GetStatusMessageAttrValue

Function

This method returns the current value of the status attribute. This includes both the time of the message and the (resolved and converted) XMI message.

Notes

Unlike performance and log attributes, there is no value history for a status attribute, as a status attribute always contains only the current message.

Parameters (Import)

TID


EXTERNAL_USER_NAME


Parameters (Export)

VALUE

Current value of a status attribute (structure BAPISMCVAL), consisting of:

RETURN

•

Color of the current message (SMSGVALUE)

•

Date and time of the current message (SMSGDATE, SMSGTIME)

•

Current message (MSG)


Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_GETSMVALUE importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 exporting RETURN structure BAPIRET2 length 548 number of fields 14 VALUE structure BAPISMCVAL length 276 number of fields 4 tables exceptions

SAP AG


November 12, 2002


5.22 Read the TID for an MTE Defined by its Name (BAPI_SYSTEM_MTE_GETTIDBYNAME) Name

BAPI_SYSTEM_MTE_GETTIDBYNAME

Short Description

Reads the TID for an MTE defined by its name

BAPI Object

MonitorTreeElement

BAPI Method

GetTidByName

Function

This method returns the associated MTE ID (TID) for a specified complete name of a monitoring tree element.

Notes

The complete name of an MTE consists of the name of the system, the context, the monitoring object, and the monitoring attribute. These four names characterize uniquely an MTE globally. Any summary nodes and virtual nodes that exist are not displayed in the Alert Monitor in this complete name of an MTE, but are simply indicated by “…”. The short name of an MTE is the name of the MTE itself. You can determine this, for example by using the method SystemMonitorTreeElement.GetGeneralProperties. SYSTEM_ID

Name of the system to which the MTE for which you are searching belongs

CONTEXT_NAME

Name of the monitoring context to which the MTE for which you are searching belongs

OBJECT_NAME

Name of the monitoring object to which the MTE for which you are searching belongs (optional)

MTE_NAME

Name of the attribute to which the MTE for which you are searching belongs (optional)

EXTERNAL_USER_NAME


Parameters (Export)

TID


RETURN

Structure BAPIRET2 with the return values of the method call

Exceptions

MSG_SERVICE_ID_MISSING MSG_CONTEXT_NAME_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_SEGMENT_NOT_AVAILABLE MSG_NAME_UNABLE_TO_EXPAND MSG_NAME_NOT_FOUND MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_UNKNOWN_PROBLEM

Parameters (Import)

SAP AG


November 12, 2002


Name

BAPI_SYSTEM_MTE_GETTIDBYNAME

RFC Interface

function BAPI_SYSTEM_MTE_GETTIDBYNAME importing CONTEXT_NAME like BAPITID_MTMCNAME type RFC_CHAR length 40 EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 MTE_NAME like BAPIMTEGEN-SHORTNAME type RFC_CHAR length 40 optional OBJECT_NAME like BAPIMTEGEN-OBJECTNAME type RFC_CHAR length 40 optional SYSTEM_ID like BAPITID-MTSYSID type RFC_CHAR length 8 exporting RETURN structure BAPIRET2 length 548 number of fields 14 TID structure BAPITID length 84 number of fields 7 tables exceptions

SAP AG


November 12, 2002


5.23

Read a Subtree Below an MTE (BAPI_SYSTEM_MTE_GETTREE)

Name

BAPI_SYSTEM_MTE_GETTREE

Short Description

Reads the subtree spanned by a monitoring tree element

BAPI Object

MonitorTreeElement

BAPI Method

GetTree

Function

This method returns the subtree that is spanned by the specified MTE.

Notes

You can also define up to what maximum tree depth you want the subtree to be returned.

Parameters (Import)

TID


MAX_TREE_DEPTH

Desired tree depth. A tree depth of one, for example, returns only the nodes that are directly under the specified MTE. Their children are not returned. By default, the maximum depth has the value 0, meaning that the complete subtree is returned.

VISIBLE_LEVEL


EXTERNAL_USER_NAME


Parameters (Export)

RETURN


TREE_NODES

Table with node data of the monitoring tree (structure BAPITNDEXT)

Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_GETTREE importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 MAX_TREE_DEPTH like BAPIPARAMS-MAXLEVEL default 0 type RFC_INT length 4 TID structure BAPITID length 84 number of fields 7 VISIBLE_LEVEL like BAPIPARAMS-VISUSRLEV default 3 type RFC_INT length 4 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables TREE_NODES structure BAPITNDEXT length 440 number of fields 40 exceptions

SAP AG


November 12, 2002


5.24

Reset MTE and Delete Active Alerts (BAPI_SYSTEM_MTE_RESET)

Name

BAPI_SYSTEM_MTE_RESET

Short Description

Resets properties of the monitoring tree element

BAPI Object

MonitorTreeElement

BAPI Method

Reset

Function

This method resets an MTE to the status directly after creation. This means, for example, that all active alerts are lost (the alert history, on the other hand, is retained).

Parameters (Import)

TID


USER

SAP R/3 user name of the user that wants to execute this method

EXTERNAL_USER_NAME


Parameters (Export)

RETURN


Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_TID_INVALID MSG_C_CALL_FAILED MSG_COMMUNICATION_PROBLEM MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_RESET importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 USER like BAPIPARAMS-USERNAME type RFC_CHAR length 16 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.25

Set General MTE Properties (BAPI_SYSTEM_MTE_SETGENPROP)

Name

BAPI_SYSTEM_MTE_SETGENPROP

Short Description

Sets the general properties of an MTE

BAPI Object

MonitorTreeElement

BAPI Method

SetGeneralProperties

Function

You can use this method to set new values for the general properties of an MTE; with the exceptions of TID and EXTERNAL_USER_NAME, all parameters are optional

Parameters (Import)

TID


EXTERNAL_USER_NAME


VARIANT_NAME

Name of the utilized variant (see VARIANT_NAME)

TID_SPECIFIC

Indicator that ensure, if it is set to the value “X”, that changes are made only for the MTE itself. Otherwise, changes are made for the MTE class to which the MTE belongs. By default, changes are made for the MTE class. (See TID_SPECIFIC)

SEVERITY

Severity of the alerts that are generated for this MTE; possible values are between 0 (very low) and 255 (very high)

VISIBLE_LEVEL

Visibility level; is ignored (see SAP Note 429254)

KEEP_ALERT_TYPE

Method with which alerts are removed if the number of alerts exceeds the maximum specified for a particular MTE, such as the newest or oldest alerts. The possible methods are defined in RSALBAPI in the constants AL_KEEP_*.

KEEP_ALERT_MAX

Maximum number of alerts that is to be stored for this MTE

SEC_TILL_COLLECT

Time in seconds that the system should wait between two calls of the associated data collection method

SEC_TILL_INACTIVE

Time in seconds after which the MTE should be set to inactive if no new values are reported

SEC_TILL_WARMUP

Length of the warm up phase for the MTE after the start of the monitoring segment, during which no alerts are generated for this MTE

TEXT_CLASS

Message class that is used by this MTE

TEXT_ID

Message ID that is used by this MTE

RETURN


Parameters (Export)

SAP AG


November 12, 2002


Name

BAPI_SYSTEM_MTE_SETGENPROP

Exceptions

MSG_TID_MISSING MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_AUTHORIZATION_MISSING MSG_INTERNAL_ERROR MSG_NO_OWNER_OF_VARIANT MSG_CAN_NOT_CREATE_VARIANT MSG_VARIANT_NOT_DEFINED MSG_TID_INVALID MSG_WRONG_SYSTEM MSG_NO_GROUP_DATA_FOUND MSG_NO_TID_SPECIFIC_DATA_FOUND MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MTE_SETGENPROP importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 KEEP_ALERT_MAX like BAPIMTEPRP-KEEPALMAX type RFC_INT length 4 optional KEEP_ALERT_TYPE like BAPIMTEPRP-KEEPALTYPE type RFC_INT length 4 optional SEC_TILL_COLLECT like BAPIMTEPRP-SECTILCOLT type RFC_INT length 4 optional SEC_TILL_INACTIVE like BAPIMTEPRP-SECTILINAC type RFC_INT length 4 optional SEC_TILL_WARMUP like BAPIMTEPRP-SECWARMUPT type RFC_INT length 4 optional SEVERITY like BAPIMTEPRP-SEVERITY type RFC_INT length 4 optional TEXT_CLASS like BAPIMTEPRP-DTEXTCLASS type RFC_CHAR length 16 optional TEXT_ID like BAPIMTEPRP-DTEXTID type RFC_CHAR length 30 optional TID structure BAPITID length 84 number of fields 7 TID_SPECIFIC like BAPIPARAMS-BOOL_PARA default ' ' type RFC_CHAR length 1 VARIANT_NAME like BAPIVARINT-NAME type RFC_CHAR length 20 optional VISIBLE_LEVEL like BAPIMTEPRP-VISILEVEL type RFC_INT length 4 optional exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.26

Set Specific Properties of a Log Attribute (BAPI_SYSTEM_MTE_SETMLPROP)

Name

BAPI_SYSTEM_MTE_SETMLPROP

Short Description

Sets the specific properties of a log attribute

BAPI Object

MonitorTreeElement

BAPI Method

SetMessageLogProperties

Function

You can use this method to set the specific properties of a log attribute; with the exceptions of TID and EXTERNAL_USER_NAME, all parameters are optional.

Parameters (Import)

TID


EXTERNAL_USER_NAME


VARIANT_NAME


TID_SPECIFIC

Indicator that ensures, when it is set to “X“, that changes are made only for the MTE itself. Otherwise, changes are made for the MTE class to which the MTE belongs. By default, changes are made for the MTE class. (See TID_SPECIFIC)

RAISE_VALUE RAISE_SEVERITY

Color and severity above which an alert should be triggered for a message

ACTUAL_MSG_MODE

Mode that specifies which message should be displayed in the Alert Monitor for a log attribute; possible methods are defined in RSALBAPI in the constants AL_TD_MSC_VAL_MODE_*. You can choose the following settings for the display:

SAP AG

•

Current message

•

Message that generated the most important alert

•

Message that generated the most important alert during a particular time period

ACTUAL_MSG_MAX_SEV

With the setting highest value of the last xx minutes, specifies how long the period is from which the message with the highest importance should be displayed

MAX_ALERTS_PRO_ID

Number of alerts that is to be stored for this MTE

KEEP_LINE_TYPE

Specifies which messages should be stored for this MTE. You can choose between the oldest or the newest messages (We recommend the newest messages), where the total number is limited by KEEP_LINES_MAX, or as many messages as possible, where KEEP_LINES_MAX is only applied when the storage space in the monitoring segment is exhausted.

KEEP_LINE_MAX

Maximum number of messages that are to be stored for this MTE (applies only for log attributes whose messages are stored by the monitoring architecture).

FILTER

Table that describes the filter set for the log attribute (the individual entries of the table have the structure BAPIMLFLT)


November 12, 2002


Name

BAPI_SYSTEM_MTE_SETMLPROP

Parameters (Export)

RETURN

Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_SETMLPROP


importing ACTUAL_MSG_MAX_SEV like BAPIMLPROP-ACTMSGMAXS type RFC_INT length 4 optional ACTUAL_MSG_MODE like BAPIMLPROP-ACTMSGMODE type RFC_INT length 4 optional EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 KEEP_LINE_MAX like BAPIMLPROP-KEEPLINMAX type RFC_INT length 4 optional KEEP_LINE_TYPE like BAPIMLPROP-KEEPLINTYP type RFC_INT length 4 optional MAX_ALERTS_PRO_ID like BAPIMLPROP-MAXALPROID type RFC_INT length 4 optional RAISE_SEVERITY like BAPIMLPROP-RAISESEVER type RFC_INT length 4 optional RAISE_VALUE like BAPIMLPROP-RAISEVALUE type RFC_INT length 4 optional TID structure BAPITID length 84 number of fields 7 TID_SPECIFIC like BAPIPARAMS-BOOL_PARA default ' ' type RFC_CHAR length 1 VARIANT_NAME like BAPIVARINT-NAME type RFC_CHAR length 20 optional exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables FILTER structure BAPIMLFLT length 104 number of fields 7 exceptions

SAP AG


November 12, 2002


5.27 Set Specific Properties of a Performance Attribute (BAPI_SYSTEM_MTE_SETPERFPROP) Name

BAPI_SYSTEM_MTE_SETPERFPROP

Short Description

Sets the specific properties of a performance attribute

BAPI Object

MonitorTreeElement

BAPI Method

SetPerformanceAttrProperties

Function

You can use this method to set the specific properties of a performance attribute; with the exception of TID and EXTERNAL_USER_NAME, all parameters are optional.

Parameters (Import)

TID


EXTERNAL_USER_NAME


VARIANT_NAME


TID_SPECIFIC

Indicator that ensures, when it is set to “X”, that the changes are made only for the MTE itself. Otherwise, changes are made for the MTE class to which the MTE belongs. By default, changes are made for the MTE class. (See TID_SPECIFIC)

RELEVANT_VALUE

Averaging of the measured values that are used to trigger alerts; there are the following options (the values are defined in RSALBAPI in the constants AL_PERF_RV_*):

SAP AG

•

Last message

•

Average value of the last full quarter hour/hour

•

Average value of the last minute, five minutes, or 15 minutes

THRESHOLD_DIRECTION

Specifies whether a value that exceeds or a value that falls below the threshold value should trigger an alert; the possible values are defined in RSALBAPI in the constants AL_THRESHDIR_*.

THRESHOLD_GREEN_TO_YELLOW THRESHOLD_YELLOW_TO_RED THRESHOLD_YELLOW_TO_GREEN THRESHOLD_RED_TO_YELLOW

Threshold values that cause the color of the performance attribute to change when the reported value exceeds or falls below them, and which may therefore trigger an alert

XMI_MSG_CLASS

XMI message class to which the attribute is assigned; by default, this is the class T100

XMI_MSG_ID

Message ID that is assigned to this attribute

VALUE_UNIT

Unit that is to be used when displaying the performance value

DECIMALS

Number of decimal places to be displayed, by default, this number is 0


November 12, 2002


Name

BAPI_SYSTEM_MTE_SETPERFPROP

Parameters (Export)

RETURN

Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_SETPERFPROP


importing DECIMALS like BAPIPAPROP-DECIMALS type RFC_INT length 4 optional EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 RELEVANT_VALUE like BAPIPAPROP-RELVALTYPE default AL_PERF_RV_LAST type RFC_INT length 4 THRESHOLD_DIRECTION like BAPIPAPROP-THRESHDIR default AL_THRESHDIR_ABOVE type RFC_INT length 4 THRESHOLD_GREEN_TO_YELLOW like BAPIPAPROP-TRESHG2Y type RFC_INT length 4 THRESHOLD_RED_TO_YELLOW like BAPIPAPROP-TRESHR2Y type RFC_INT length 4 THRESHOLD_YELLOW_TO_GREEN like BAPIPAPROP-TRESHY2G type RFC_INT length 4 THRESHOLD_YELLOW_TO_RED like BAPIPAPROP-TRESHY2R type RFC_INT length 4 TID structure ALGLOBTID length 84 number of fields 7 TID_SPECIFIC like BAPIPARAMS-BOOL_PARA default ' ' type RFC_CHAR length 1 VALUE_UNIT like BAPIPAPROP-VALUNIT type RFC_CHAR length 4 optional VARIANT_NAME like BAPIVARINT-NAME type RFC_CHAR length 20 optional XMI_MSG_CLASS like BAPIPAPROP-MSGCLASS default 'SAP_T100' type RFC_CHAR length 16 XMI_MSG_ID like BAPIPAPROP-MSGID type RFC_CHAR length 30 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.28 Set Specific Properties of a Status Attribute (BAPI_SYSTEM_MTE_SETSMPROP) Name

BAPI_SYSTEM_MTE_SETSMPROP

Short Description

Sets the specific properties of a status attribute

BAPI Object

MonitorTreeElement

BAPI Method

SetStatusMessageAttrProperties

Function

You can use this method to set the specific properties of a status attribute; with the exceptions of TID and EXTERNAL_USER_NAME, all parameters are optional.

Parameters (Import)

TID


EXTERNAL_USER_NAME


VARIANT_NAME


TID_SPECIFIC

Indicator that ensures, when it is set to “X”, that the changes are made only for the MTE itself. Otherwise, the changes are made for the MTE class to which the MTE belongs. By default, the changes are made for the MTE class. (See TID_SPECIFIC)

ALERT_MODE

Specifies when a message for the attribute should trigger an alert (the options are defined in RSALBAPI in the constants AL_SMSG_ALMODE_*):

ALERT_SHIFT

Parameters (Export)

SAP AG

RETURN

•

With every new report

•

When the report changes

•

When the color of the report changes

•

Never

Specifies whether and how the original color of the message should be changed when being displayed in the Alert Monitor (the options are defined in RSALBAPI in the constants AL_SMSG_ALSHIFT_*): •

Do not change color

•

Transfer Yellow as Red

•

Transfer Red as Yellow

•

Transfer Red as Yellow and Yellow as Green



November 12, 2002


Name

BAPI_SYSTEM_MTE_SETSMPROP

Exceptions


RFC Interface

function BAPI_SYSTEM_MTE_SETSMPROP importing ALERT_MODE like BAPISMPROP-ALERTMODE type RFC_INT length 4 optional ALERT_SHIFT like BAPISMPROP-ALERTSHIFT type RFC_INT length 4 optional EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER type RFC_CHAR length 16 TID structure BAPITID length 84 number of fields 7 TID_SPECIFIC like BAPIPARAMS-BOOL_PARA default ' ' type RFC_CHAR length 1 VARIANT_NAME like BAPIVARINT-NAME type RFC_CHAR length 20 optional exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables exceptions

SAP AG


November 12, 2002


5.29 Create Monitoring Tree By Template (BAPI_SYSTEM_MT_CREATEBYTEMPL) Name

BAPI_SYSTEM_MT_CREATEBYTEMPL

Short Description

Creates a monitoring tree using a monitor template

BAPI Object

SystemMonitorTree

BAPI Method

CreateByTemplate

Function

This method creates a complete monitoring tree from a monitor template.

Notes

Unlike a monitor template, which contains only the virtual nodes and the top nodes of the real subtrees, the monitoring tree consists of the virtual nodes and the MTEs of all fully resolved (real) subtrees.

Parameters (Import)

EXTERNAL_USER_NAME


MAX_TREE_DEPTH

Desired tree depth (optional). A tree depth of one, for example, returns only the nodes that are directly under the specified MTE. Their children are not returned. By default, the maximum depth has the value 0, meaning that the complete subtree is returned.

VIS_ON_USR_LEVEL


TEMPLATE_NODES

Table with the nodes of the monitor template (structure BAPITMPLND)

Parameters (Export)

RETURN


TREE_NODES

Table with all node data of the monitoring tree (structure BAPITNDEXT)

Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_MONITOR_TEMPLATE_MISSING MSG_CANT_GET_MONI_PRESENTATION MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MT_CREATEBYTEMPL importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER


MAX_TREE_DEPTH like BAPIPARAMS-MAXLEVEL default 0 type RFC_INT length 4 VIS_ON_USR_LEVEL like BAPIPARAMS-VISUSRLEV default 3 type RFC_INT length 4 exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables TEMPLATE_NODES structure BAPITMPLND length 232 number of fields 13 TREE_NODES structure BAPITNDEXT length 440 number of fields 40 exceptions

SAP AG


November 12, 2002


5.30

Read Alert Data for a Monitoring Tree (BAPI_SYSTEM_MT_GETALERTDATA)

Name

BAPI_SYSTEM_MT_GETALERTDATA

Short Description

Reads the alert data for a monitoring tree

BAPI Object

SystemMonitorTree

BAPI Method

GetAlertData

Function

You can use this method to collect all alert data for a specified monitoring tree. If only alert data from particular subtrees is to be collected, you can optionally specify the top node of these subtrees.

Parameters (Import)

GET_ALERT_HISTORY

Indicator that ensures, if it is set to “X”, that the alerts that have already been completed are also returned from the alert database (optional)

EXTERNAL_USER_NAME


START_TIMESTAMP

Start timestamp of the time period for which the alert data is to be read (optional, as of SAP Basis 4.6C)

END_TIMESTAMP

End timestamp of the time period for which the alert data is to be read (optional, as of SAP Basis 4.6C)

LAST_X_MINUTES

Length of the time period in minutes for which the alerts are to be read (optional, as of SAP Basis 4.6C)

ROOT_NODES

Table with the top nodes of the subtrees for which the available alert data is to be collected (optional); the individual elements contain the TID of the top node (structure ALGLOBTID, corresponds to the structure BAPITID) By specifying ROOT_NODES, you can read only the alerts of a monitoring tree that are in subtrees below specific top nodes. However, it is also necessary here that you transfer the complete monitoring tree in TREE_NODES.

TREE_NODES

Table with all data for the MTEs of the monitoring tree for which alert data is to be collected (structure BAPITNDEXT)

Parameters (Export)

RETURN


ALERT_DATA

Table with all data for the collected alerts (structure BAPIALEXT)

Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_MONI_PRESENTATION_MISSING MSG_INVALID_MONI_TOP_NODE MSG_CANT_GET_ALERT_DATA MSG_INVALID_MONI_NODE_DETECTED MSG_NO_ALERTS_FOUND MSG_INVALID_TIME_RANGE MSG_UNKNOWN_PROBLEM

SAP AG


November 12, 2002


Name

BAPI_SYSTEM_MT_GETALERTDATA

RFC Interface

function BAPI_SYSTEM_MT_GETALERTDATA importing END_TIMESTAMP structure ALTMSTPUTC length 8 number of fields 1 optional EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER


GET_ALERT_HISTORY like BAPIPARAMS-BOOL_PARA default ' ' type RFC_CHAR length 1 LAST_X_MINUTES structure INT4 length 4 number of fields 1 optional START_TIMESTAMP structure ALTMSTPUTC length 8 number of fields 1 optional exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables ALERT_DATA structure BAPIALEXT length 1356 number of fields 46 ROOT_NODES structure ALGLOBTID length 84 number of fields 7 optional TREE_NODES structure BAPITNDEXT length 440 number of fields 40 exceptions

SAP AG


November 12, 2002


5.31 Read Current Performance Values for All Specified Performance Attributes (BAPI_SYSTEM_MT_GETPERFDATA) Name

BAPI_SYSTEM_MT_GETPERFDATA

Short Description

Reads the current performance values of all specified performance attributes (as of SAP Basis 4.6C)

BAPI Object

MonitorTreeElement

BAPI Method Function

This method returns the current values of all specified performance attributes.

Parameters (Import)

EXTERNAL_USER_NAME


PERF_NODES

Table with the TIDs (structure BAPITD) of the desired performance attributes

Parameters (Export)

RETURN


CURRENT_VALUES

Table in which every entry contains the TID (structure BAPITD), the current values of the performance attribute (structure BAPIPACVAL), and a return code (RC)

Exceptions

MSG_EXT_USER_MISSING MSG_CANT_LOG MSG_NOT_LOGGED_ON MSG_INTERNAL_ERROR MSG_C_CALL_FAILED MSG_UNKNOWN_PROBLEM

RFC Interface

function BAPI_SYSTEM_MT_GETPERFDATA importing EXTERNAL_USER_NAME like BAPIXMLOGR-EXTUSER


exporting RETURN structure BAPIRET2 length 548 number of fields 14 tables CURRENT_VALUES structure BAPIPACVAX length 192 number of fields 28 PERF_NODES structure BAPITID length 84 number of fields 7

SAP AG


November 12, 2002


6 Description of Selected Transfer Parameters 6.1

Alert ID: AID (Structure BAPIAID)

Just as an MTE is uniquely determined using the TID, alerts are uniquely defined within the monitoring segment by the Alert ID (AID). The AID contains the following fields: Name

Description

ALSYSID

Name of the SAP R/3 System

MSEGNANE

Name of the monitoring segment

ALUNIQNUM

Unique Identifier (UID) of the alert, which always remains the same for an alert, unlike the index (see below) (if, for example, a segment is restarted)

ALINDEX

Index (number in the array in which the alerts are stored within the monitoring architecture)

ALERTDATE ALERTTIME

Date and time at which the alert occurred

DUMMYALIGN

Not used

6.2

Return Messages of the Method Calls: RETURN (Structure BAPIRET2)

When each function module of this interface is called, possible messages of the module are returned in a structure of the type BAPIRET2. In addition to the error messages, it also contains, for example, the variables that were transferred with the message. The structure contains the following fields: Name

Description

TYPE

Message type: S = Success, E = Error, W = Warning, I = Info, A = Abort

ID

Message class of the message; the classes used for messages of the XMI interface are RA and XM (see Error Messages of the Function Modules [page 71])

NUMBER

Number of the message within the message class

MESSAGE

Message text

LOG_NO

Log number of an application log

LOG_MSG_NO

Internal sequence number of the message within a log (the number sequence does not necessarily specify the chronological sequence)

MESSAGE_V1 ··· MESSAGE_V4

Up to four values that can be set in variables in a T100 message. The variables are replaced in the order in which the variables appear in the message text

PARAMETER

Name of the parameter in which the error message occurred

ROW

Row number of the parameter in which the error message occurred

FIELD

ID of the field for which the error message occurred

SYSTEM

Name of the logical system in which the message was generated

SAP AG


November 12, 2002


6.3

ID of an MTE: TID (Structure BAPITID)

You can uniquely characterize an MTE using the TID. The TID contains the following fields: Name

Description

MTSYSID

Name of the SAP R/3 System

MTCLASS

Type of the MTE (performance attribute, log attribute, text, and so on); the various types are defined in RSALBAPI in the constants MT_CLASS_*

MTNUMRANGE

Number range (for detailed information about the number range, see the document “Creating a Data Supplier for the Alert Monitor” [DataSup])

MTMCNAME

Name of a monitoring context

MTUID

Unique Identifier (UID) of the MTE, which always remains the same for an MTE, unlike the index (see below) (if, for example, a segment is restarted)

MTINDEX

Index (Number within the array for the general properties within the monitoring segment)

EXTINDEX

External index; this refers to the index number in the array in which the MTE also appears. This means that, for example, a performance attribute has both general properties and specific performance attribute properties.

6.4

Importance of an Alert (Structure BAPIALDATA)

The importance of an alert is determined by the color and the severity of the alert. The color of the alert is divided into the following categories. The following colors are possible for an MTE: Color

Description

Red

Problem or error

Yellow

Warning

Green

Everything OK

Gray

Inactive or no current information available

Within the color of an alert, there is another categorization using the severity of the alert. The severity is a number between 0 and 255; the larger the number, the greater the severity. We use only the numbers up to 50. The importance of the alert is calculated from the color and the severity of the alert (for example, an alert with the color yellow and the severity 255 has a lower importance than an alert with the color red and the severity 0). The monitor reports alerts in the monitoring tree upwards. This means that the color indicator for a node always displays the highest alert in all elements of its branch. In the case of the same color, the alert with the larger severity is reported upward in the monitoring tree.

6.5

General Properties of an Alert (Structure BAPIALERT)

An alert is uniquely assigned to one MTE in the monitoring tree. The Alert Monitor evaluates the incoming information that is sent from a data supplier to an MTE in comparison with the associated threshold values. If the incoming data exceeds or falls below a threshold value, the Alert Monitor triggers an alert. The Alert Monitor creates an alert for every status that deviates from the norm and traces it until you set it to complete status. SAP AG


November 12, 2002


Name

Description

SHORTNAME

Short name of the MTE in which the alert occurred

OBJECTNAME

Name of the monitoring object in which the alert occurred

MANDT

Name of the client in the SAP R/3 System in which the alert occurred

USERID

Logon name of the user in the SAP R/3 System in which the alert occurred

ALSTATUS

Status of an alert; the possible statuses are defined in RSALEXTI in the constants AL_STAT_* . For an explanation of the alert status, see [MonSeg]

STATCHGDAT STATCHGTIM STATCHGUSR

Date (STATCHGDAT), time (STATCHGTIM), and user (STATCHGUSR) of the last status change of the alert

TIMEOUTDAT TIMEOUTTIM

Not used

REPORTEDBY

Logical name of the data supplier that reported the alert

MSCGLID

ID of a message (only for log attributes); if a message of a log attribute triggers an alert, its ID is written in this field to have the generating message available in the alert

6.6

Current Values of a Log Attribute (Structure BAPIMLCVAL)

This structure contains the current values of log attributes. A log attribute records the messages in its context. This means that the data collection method writes not only isolated messages to the Alert Monitor, but also the contents of a log or trace. Every log attribute therefore contains not only the current message for the attribute (such as the status attribute), but a complete history of messages. In the context of the XMI interface, you can use the log attributes to read any messages of the external product into the monitoring architecture. Name

Description

MSCGLLID

ID of a message (only for log attributes); if a message of a log attribute triggers an alert, its ID is written to the field, so that the generating message is available in the alert

MSCDATE MSCTIME

Date and time when the message occurred

VALUEORIG SEVERORIG

Importance of the message of a log attribute, characterized by color (VALUEORIG) and severity (SEVERORIG) (See Importance of an Alert (Structure BAPIALDATA) [page 63]); you can either accept this importance unchanged, or changed as you wish using filter settings (see below)

VALUEFLTRD SEVERFLTRD

Importance of the message by color (VALUEFLTRD) and severity (SEVERFLTRD) after an interposed filter

MANDT USERID

Client and user in which the message occurred

SAP AG


November 12, 2002


6.7

Filter Settings (Structure BAPIMLFLT)

Using the entries of this structure, you can change the color and severity of a message or a group of messages, depending on the message. When doing so, you assign one or more filter conditions to a log attribute. These conditions are processed in a fixed sequence Name

Description

LINENUMBER

Line number of a message in a log or trace external to the monitoring architecture. This is used by the retrieval function to display the message in the Alert Monitor. The retrieval function is provided for the Alert Monitor by the owner of the log or trace.

FROMSGCLAS

Using the fields FROMSGCLAS, FROMSGID, TOMSGCLAS, and TOMSGID, you

FROMSGID TOMSGCLAS TOMSGID

can define a range of messages to which you can assign a particular importance, irrespective of their original value. A message is characterized by its message class (*MSGCLAS) and its message ID (*MSGID).

•

FROMSGCLAS and TOMSGCLAS are usually identical.

•

SAP-SYSLOG and SAP-T100 are frequently used message classes; in the same way, you can filter your own messages by setting the vendor of the external product.

•

MSGVALUE SEVERITY

6.8

In the case of *MSGCLAS = SAP-T100, the message ID is, for example, RT 001.

Importance of the message by color (MSGVALUE) and severity (SEVERITY) that is to be assigned to the messages of the range mentioned above

Current Values of a Performance Attribute (Structure BAPIPACVAL)

A performance attribute contains not only the last reported value, but also the number and total of measured values for the last minute, five minutes, and 15 minutes, from which the respective average values can be calculated. As you can specify which of these values is to be relevant for the generation of alerts, you can ensure that alerts are only generated in the case of statistical variations if there is really a performance problem. Name

Description

ALRELEVVAL

Measured value that is used for the comparison with the threshold values. This can be the last measured value or an average value (see input parameter RELEVANT_VALUE under Set Specific Properties of a Performance Attribute (BAPI_SYSTEM_MTE_SETPERFPROP) [page 54]

ALRELVALDT ALRELVALTI

Date(ALRELVALDT) and time (ALRELVALTI) of the measured value relevant for alert generation

LASTALSTAT

Most recent alert status of a monitoring attribute. The alert status can be green, yellow, or red. The latter two statuses can involve an alert.

SAP AG


November 12, 2002


Name

Description

LASTPERFVAL

Most recently reported value for a performance monitoring attribute

AVG01PVAL AVG05PVAL AVG15PVAL

Average performance value for the last minute, five minutes, and 15 minutes; this is calculated from the total of the measured values for the corresponding time period and the number of measurements

AVG01SVAL AVG05SVAL AVG15SVAL

Total of the performance values of the last minute, five minutes, and 15 minutes

AVG01CVAL AVG05CVAL AVG15CVAL

Number of measurements for a performance attribute during the last minute, five minutes, and 15 minutes

MAXPFVALUE

Largest value that was measured for this performance attribute

MAXPFDATE MAXPFTIME

Date (MAXPFDATE) and time (MAXPFTIME) at which the largest value was measured for this performance attribute

MINPFVALUE MINPFDATE MINPFTIME

Analogous to the fields MAXPF* (see above), but for the smallest value

6.9

Nodes of a Monitor Template (Structure BAPITMPLND)

Name

Description

MTSYSID MTMCNAME MTNUMRANGE MTUID MTCLASS MTINDEX EXTINDEX

TID of the node; the individual components are described in ID of an MTE: TID (Structure BAPITID) [page 63]

NAME

Name of the node in the monitor that is associated with this definition

TYPE SHOWLGNAME

Information about the display of the nodes in the monitor

ND_INDEX PAR_INDEX ND_LEVEL

Information about the position of the node within the monitor definition. The nodes are indexed, and for quicker movement within the definition, the level of the node within the definition (ND_LEVEL, the uppermost level is level 1) and of the node index of the parent node (PAR_INDEX) are also specified, in addition to the node index itself (ND_INDEX).

SAP AG


November 12, 2002


6.10

Complete Set of Node Data (Structure BAPITNDEXT)

All information for the general node data of an MTE is combined in this structure. Name

Description


TID of the node; the individual components are described in ID of an MTE: TID (Structure BAPITID) [page 63]

ALTREENUM ALIDXINTRE ALLEVINTRE ALPARINTRE

Information about the position of the node within the monitoring tree. The nodes are indexes and, for quicker movement within the monitoring tree, the level of the node within the tree (ALLEVINTRE, the uppermost level has the level 1) and of the node index of the parent node (ALPARINTRE) are specified in addition to the node name itself (ALIDXINTRE).

OBJECTNAME

Name of the monitoring object to which this node belongs

MTNAMESHRT

Short name of the node

CUSGRPNAME

Name of the associated attribute group

DELIVERSTA

Specifies the status of the data messages in the node (such as “No value yet reported” or “Value is obsolete”) You can find the possible statuses in the include RSALINTI in the constants MT_DLVSTAT_*.

HIGHALVAL HIGHALSEV

Importance of the highest alert that is stored in this node (see also Importance of an Alert (Structure BAPIALDATA) [page 63])

ALSYSID MSEGNAME ALUNIQNUM ALINDEX ALERTDATE ALERTTIME DUMMYALIGN

Components of the alert ID of the highest alert that is stored in this node; the individual components are described in Alert ID: AID (Structure BAPIAID) [page 62]

LASTVALDAT LASTVALTIM LASTVALDUM

Date (LASTVALDAT) and time (LASTVALTIM) of the last value change in this node; the component LASTVALDUM has no meaning, it is used simply to adjust the length of the structure

ACTUALVAL ACTUALSEV

Importance of the last message in this node (see also Importance of an Alert (Structure BAPIALDATA) [page 63])

VALSYSID VMSEGNAME VALUNIQNUM VALINDEX VALERTDATE VALERTTIME VALERTDUM

If the last message in this node generated an alert, these components contain the associated alert ID; the individual components are described in Alert ID: AID (Structure BAPIAID) [page 62]

COUNTOFACT

Number of active alerts in this node

COUNTSUM

Number of alerts in this node

SAP AG


November 12, 2002


Name

Description

VISUSERVLEV

Not used

TDSTATUS

Status of the node (for example, whether alert generation is activated or deactivated, or whether alerts are suppressed during the warm-up phase, and so on); you can find the possible statuses in the include RSALINTI in the constants MT_DEFSTAT_*.

6.11

Alert Data in a Flat Structure (Structure BAPIALEXT)

The complete information for the general data of an alert is combined in this structure. The structure is returned by the function module BAPI_SYSTEM_MT_GETALERTDATA. The structure also contains a return value that specifies whether the associated alert could be read. Name

Description

RC

Return value

ALSYSID MSEGNAME ALUNIQNUM ALINDEX ALERTDATE ALERTTIME DUMMYALIGN

Alert ID of the alert; the individual components are described in Alert ID: AID (Structure BAPIAID) [page 62]


TID of the node associated with this alert; the individual components are described in ID of an MTE: TID (Structure BAPITID) [page 63]

VALUE SEVERITY

Importance of the alert (see also Importance of an Alert (Structure BAPIALDATA) [page 63])

FIELDNAME STATUS OBJECTNAME MANDT USERID STATCHGDAT STATCHGTIM STATCHGBY TIMEOUTDAT TIMEOUTTIM REPORTEDBY MSCGLID

General properties of the alert. The individual components are described in General Properties of an Alert (Structure BAPIALERT) [page 63], where three of the components have different names as the components of the structure BAPIALERT with the same meaning:

GONEDATE GONETIME GONEDUMMY

Date and time at which the alert was completed, the component GONEDUMMY has no meaning; it used only to adjust the length of the structure

STATCHGDUM TIMEOUTDUM

Components with no meaning; they are used only to adjust the length of the structure

SAP AG

•

BAPIALEXT-FIELDNAME corresponds to BAPIALERT-SHORTNAME

•

BAPIALEXT-STATUS corresponds to BAPIALERT-ALSTATUS

•

BAPIALEXT-STATCHGBY corresponds to BAPIALERT-STATCHGUSR


November 12, 2002


Name

Description

MSGCLASS

Company name of an external management tool (see also Log On to the XMI Interface (BAPI_XMI_LOGON) [page 18])

MSGID

Identification key for a message that was uploaded from an external product, and is used by the XMI interface and associated system management interfaces

MSGARG1 ARGTYPE1 MSGARG2 ARGTYPE2 MSGARG3 ARGTYPE3 MSGARG4 ARGTYPE4

Transfer parameters (...ARG1 - ...ARG4) and their types (...TYPE1 - ...TYPE4); the type of the transfer variable is usually C (Character). The variables are replaced in the sequence in which the variables appear in the message text

MSGTEXT

Message text

MSG

Expanded message (including the resolved parameters) for external tools

6.12

Validity Range of Properties: TID_SPECIFIC

Changes to the properties of attributes can refer to the associated MTE class or attribute group. If this is the case, the changed properties apply to all attributes that belong to this class. The changes can, however, refer to the attribute itself. In this case, the attribute overwrites the properties of the class.

6.13

Name of a Properties Variant: VARIANT_NAME

A monitoring properties variant contains settings for properties and method assignments of MTEs, MTE classes, and attribute groups. Every change to these settings is assigned to a properties variant. You can use multiple properties variants for the monitoring of your IT landscape, each of which represents a different monitoring strategy. The current settings delivered by SAP are contained in the properties variant SAP-DEFAULT. Note that the owner of a specified variant corresponds to the company name that was used in the XMI logon (see Log On to the XMI Interface (BAPI_XMI_LOGON) [page 18]). If you explicitly specify a variant, you must have created this using transaction RZ21. If no variant is specified, the changes belong to the variant with the company name from the XMI logon as its name. If no variant of this type exists, it is automatically created.

6.14 Time Basis of Records of the Data History RECTYPE (Data Element ALPDBRTYP) Data records of the performance database exist as different aggregates in various granularities, each with one day as the basic time unit. This is specified by the field RECTYPE of the data element ALPDBRTYP.

A data record of the granularity hours in the aggregate weeks contains the total and number of measured values for the 24 hours of the day, aggregated for a week:

SAP AG


November 12, 2002


Mo Tu We Th Fr Sa Su

Mo - Su

= Σ(Mo–Su[00:00 – 01:00])

00:00 – 01:00 01:00 – 02:00 02:00 – 03:00 03:00 – 04:00 04:00 – 05:00 05:00 – 06:00 ...

...

23:00 – 00:00

Basic time unit: Day; therefore, a record consists of the following, depending on the granularity:

Granularity (here: hours); Options are:

• Minutes • ¼ hours • Hours • Day

Aggregate (here: week); Options are:

• Days • x days (x = any no.) • Week • Month • Quarter • Year

• Minutes: 1440 entries • ¼ Hours: 96 entries • Hours: 24 entries • Day: 1 entry

The following table shows the RECTYPE values for all combinations of aggregation and granularity: Granularity

Aggregate Minutes

¼ Hours

Hours

Days

Day

I

R

D

H

X Days

E

F

X

G

Weeks

A

B

W

C

Month

J

K

M

L

Quarter

N

O

Q

P

Year

S

T

Y

U

SAP AG


November 12, 2002


7 Error Messages of the Function Modules The return variable RETURN of the function modules contains, among other information, data for possible error messages (ID, NUMBER, and MESSAGE). In the context of the XAL interface, the following messages exist:

Message

ID Num Short Description

MSG_AID_MISSING

RA 334

The specified alert ID is not defined.

MSG_AID_INVALID

RA 335

The specified alert ID is invalid.

MSG_C_CALL_FAILED

RA 336

The C function that was ultimately called could not be executed.

MSG_COMMUNICATION_PROBLEM

RA 337

The method could not be executed due to communication problems (you should possibly check the network connection).

MSG_INTERNAL_ERROR

RA 338

An internal problem occurred.

MSG_TID_MISSING

RA 339

The specified TID is not defined.

MSG_TID_INVALID

RA 340

The specified TID is invalid.

MSG_UNKNOWN_PROBLEM

RA 341

An unknown problem occurred during the execution of the method.

MSG_CALL_INVALID

RA 342

The underlying function call could not be performed (the function parameters may be incorrectly set).

MSG_SEGMENT_NOT_AVAILIABLE

RA 343

The required segment is not available.

MSG_NAME_UNABLE_TO_EXPAND

RA 344

Could not expand the name of the MTE.

MSG_NAME_NOT_FOUND

RA 345

The name of the MTE was note found.

MSG_DB_PROBLEM

RA 346

There was a problem accessing the database.

MSG_INVALID_TIME_RANGE

RA 347

The specified time range is invalid.

MSG_NO_MONITOR_SETS_FOUND

RA 350

No monitor sets were found.

MSG_MONI_SET_NAME_MISSING

RA 351

The name of the monitor set was not specified.

MSG_INVALID_MONI_SET_NAME

RA 352

The name of the monitor set is incorrect.

MSG_MONI_SET_IS_EMPTY

RA 353

The specified monitor set is empty or contains no monitors.

MSG_CANT_GET_DISPLAY_CONFIG

RA 354

The (display) properties could not be determined.

MSG_MONI_NAME_MISSING

RA 355

The name of the monitor was not specified.

MSG_INVALID_MONI_NAME

RA 356

The name of the monitor is invalid.

MSG_CANT_READ_MONISET_FROM_DB

RA 357

The required data could not be read from the database.

MSG_MONITOR_TEMPLATE_MISSING

RA 361

The monitor template is not defined.

MSG_CANT_GET_MONI_PRESENTATION

RA 362

The monitoring tree could not be determined.

MSG_MONI_PRESENTATION_MISSING

RA 593

The monitoring tree elements of the monitoring tree were not specified.

SAP AG


November 12, 2002


Message

ID Num Short Description

MSG_INVALID_MONI_TOP_NODE

RA 594

One of the specified top nodes is invalid.

MSG_CANT_GET_ALERT_DATA

RA 595

The alert data could not be collected.

MSG_INVALID_MONI_NODE_DETECTED

RA 594

One of the specified monitoring tree elements is invalid.

MSG_NO_ALERTS_FOUND

RA 596

No alerts were found.

MSG_REQUESTS_MISSING

RA 377

The requests for history data were not defined.

MSG_INVALID_REC_TYPE

RA 378

An invalid type of history data was requested.

MSG_INVALID_DATE_RANGE

RA 379

An invalid time range was defined for history data.

MSG_EMPTY_INPUT_DATE

RA 380

The time range was not defined.

MSG_NO_ACCESS_TO_ANOTHER_R3

RA 381

An error occurred while accessing another SAP R/3 System.

MSG_SERVICE_ID_MISSING

RA 404

The system ID was not specified.

MSG_CONTEXT_NAME_MISSING

RA 405

The name of the context was not specified.

MSG_VARIANT_NOT_DEFINED

RA 406

The specified variant is not defined.

MSG_NO_OWNER_OF_VARIANT

RA 407

The specified user is not the owner of the variant.

MSG_WRONG_SYSTEM

RA 408

The Customizing settings of the specified system cannot be changed from this system.

MSG_NO_GROUP_DATA_FOUND

RA 409

No data available for the MTE class of the MTE.

MSG_NO_TID_SPECIFIC_DATA_FOUND

RA 410

No TID-specific data available for the MTE.

MSG_CAN_NOT_CREATE_VARIANT

RA 422

The specified variant could not be created.

MSG_AUTHORIZATION_MISSING

RA 495

You are not authorized to use the specified function.

MSG_EXT_USER_MISSING

XM 048

The name of the external user was not specified in the call. This name specifies which user started the method call in the external system.

MSG_CANT_LOG

XM 031

The method call was terminated due to an error in the SAP R/3 XMI logging system.

MSG_NOT_LOGGED_ON

XM 028

The external system management tool did not log on to the CCMS XMI interface. The method call was therefore terminated.

SAP AG


November 12, 2002


8 Glossary Alert

A problem message in the CCMS Alert Monitor and monitoring architecture. Alerts direct the system administrator’s attention to critical or potentially dangerous situations in an SAP system. The CCMS Alert Monitor assess the values reported by the data suppliers and compares them to predefined alert threshold values. If the incoming data violates a threshold value, the Alert Monitor triggers an alert. The alert status of every MTE in a monitoring tree is clearly displayed and highlighted in the appropriate color.

Alert Monitor

Standard data consumer that displays the measured values and alerts for the monitored monitoring objects and monitoring attributes in a hierarchical structure.

Analysis method

Program or transaction that can be used interactively to gain information about a system component that is displayed as an MTE in the CCMS monitoring architecture.

Attribute group

Grouping of MTEs and therefore analogous to an MTE class. However, the MTE class contains the general properties of the associated MTEs, while the attribute groups contains their specific properties.

Auto-reaction method

Program or transaction that is called automatically by the CCMS monitoring architecture as soon as an alert is triggered for an MTE to which the method is assigned. For example, you can assign the auto-reaction method CCMS_OnAlert_Email to the MTE classes that are most critical in your SAP system. You are then informed by fax, e-mail, or pager if an alert occurs for these MTE classes, even if you are not working with the Alert Monitor when the alert occurs.

Color

Categorization of alerts. A red alert indicates an error or a problem, while a yellow alert means a warning. The alert status green means that everything is running properly.

CCMS agent

Independent process with an RFC-compatible interface to a central monitoring system and an interface to the shared memory. The CCMS agent establishes a connection in the CCMS monitoring architecture between the central monitoring system and the host being monitored.

Data collection method

Data supplier that is defined in the CCMS monitoring architecture. Data collection methods report data to monitoring tree elements. Since a data collection method can be started by the monitoring architecture, it is a passive data supplier.

Data Consumer

Program that uses and displays the data from the monitoring architecture (such as the CCMS monitors).

Data Supplier

Program or transaction that collects information about the SAP system and its environment and registers this information with the CCMS monitoring architecture. There are two types of data supplier:

SAP AG


November 12, 2002


•

Active data suppliers are run by a component inside or outside the SAP system that wants to report data into the monitoring architecture.

•

Passive data suppliers (or data collection methods) are run periodically by the monitoring architecture to gather data.

Importance (of an alert)

The importance of an alert is defined by its color and within the same color by its severity. If there are multiple alerts within a subtree, the most important alert is reported upwards.

Log attribute

Monitoring attribute that is similar to a status attribute in that it contains messages with an alert value. A log attribute can contain multiple messages. It provides a means of instrumenting log files and trace files for inclusion in the monitoring architecture.

Method

Report, function module, SAP transaction or URL that should be executed by the CCMS monitoring architecture if certain types of events occur. There are three types of methods that can be assigned to an MTE: Data collection methods, analysis methods, and auto-reaction methods.

Monitor

Collection of MTEs that are organized in a hierarchical tree.

Monitor set

Collection of monitors displayed in a hierarchical tree. Monitor sets are used to group individual monitors visually.

Monitoring attribute (MA)

Basic element within the monitoring tree. Describes the properties of the monitoring objects; there are four types of monitoring attributes: •

Performance attributes

•

Status attributes

•

Log attributes

•

Text attributes

Each of these attributes has specific properties, however alerts can be triggered for all attributes (except text attributes). Monitoring context

Group of monitoring objects that are organized together under a heading in a tree. Each independent tree represents a monitoring context within a monitoring segment. The monitoring tree obtains its name from the root element of the tree.

Monitoring object

MTE that contains various monitoring attributes that belong to the same real object (such as hard disks or components in the SAP system).

Monitoring segment (MS)

“Container“ that holds all active components and data required in the monitoring architecture. The monitoring segment is realized using two technical implementations:

SAP AG

•

Shared memory (memory-oriented file)

•

Range of tables in the database


November 12, 2002


Monitoring tree

Tree structure that displays the system components monitored by the monitoring architecture. Depending on the definition, a monitoring tree can display all or only a part of all of the available nodes (or MTEs).

Monitoring tree element (MTE) Nodes in the monitoring tree. There are three types: •

Monitoring attributes

•

Monitoring objects

•

Summary nodes

MTE class

Grouping of MTEs. MTE classes contain information on general properties and method assignments for monitoring objects and monitoring attributes.

Performance attribute

Monitoring attribute that collects and averages performance values that have been reported to the monitoring architecture. If these values violate the set threshold values, an alert is triggered.

Properties variant

Grouping of Customizing data that is then called in accordance with the system requirements of the administrator. In this way you can, for example, assign a properties variant to an operation mode so that you work with different Customizing settings during the day and during the night.

Severity

Categorization of alerts within the same alert color. The severity is a value between 0 and 255, with 255 as the maximum severity. The monitoring architecture uses only severity from 0 to 50 so that users can ensure that alerts for certain MTEs are always reported upwards by assigning higher severity to these MTEs.

Status attribute

Monitoring attribute in which an error message text and alert status can be reported.

Text attribute

Monitoring attribute that allows a data supplier to report technical information. The text can be updated as required. However, no values can be reported and no alerts van be triggered.

Threshold value

Value used to trigger an alert when a value in a performance attribute exceeds or falls below the threshold value.

Variant

See Properties Variant

Virtual MTE

MTE for visual structuring of monitors. No values can be reported for virtual MTEs themselves, and they are not stored in the monitoring segment.

SAP AG


November 12, 2002


9 Additional Information [AlMon]

Online Documentation for the Alert Monitor To display this documentation, call the SAP Library, and choose mySAP Technology Components → SAP Web Application Server → Computing Center Management System (BC-CCM) → Monitoring in the CCMS → The Alert Monitor.

[StdMon]

Predefined Monitors for the Alert Monitor Start the SAP Service Marketplace, and go to the System Management and Alert Monitoring area (http://service.sap.com/monitoring). Choose Monitoring in Details, and choose the Preconfigured Monitors document from the list.

[Agents]

Documentation for the CCMS Agents Start the SAP Service Marketplace, and go to the System Management and Alert Monitoring area (http://service.sap.com/monitoring). Choose Monitoring in Details, and then choose the document CCMS Agents: Features, Installation, and Usage from the list.

[DataSup]

Instructions for Creating a Data Supplier Start the SAP Service Marketplace, and go to the System Management and Alert Monitoring area (http://service.sap.com/monitoring). Choose Developer´s Zone, and choose the document How to Write a Data Supplier for the Alert Monitor from the list.

[RFC]

Online Documentation about RFC To display this documentation, call the SAP Library, and choose mySAP Technology Components → SAP Web Application Server → ABAP Programming and Runtime Environment (BCABA) → External Programming Interfaces → RFC Programming in ABAP.

SAP AG


November 12, 2002

XAL External Interface for Alert Management

Recommend Documents