AP 7.

00
Implementing (p)functions in the Configuration Engine

VERSION 1.0 DECEMBER 2005

CHANGE LOG
Version 0.1 1.0 Date 01.11.2005 14.12.2005 Editor Thomas Leichtweiss Thomas Leichtweiss Modification Creation Corrections

Copyright 2003, 2004 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft , WINDOWS , NT , EXCEL , Word , PowerPoint and SQL Server are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, TM Tivoli, Informix and Informix Dynamic Server are trademarks of IBM Corporation in USA and/or other countries. ORACLE is a registered trademark of ORACLE Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.

Citrix, the Citrix logo, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, MultiWin and other Citrix product names referenced herein are trademarks of Citrix Systems, Inc. HTML, DHTML, XML, XHTML are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. JAVA is a registered trademark of Sun Microsystems, Inc. JAVASCRIPT is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MarketSet and Enterprise Buyer are jointly owned trademarks of SAP AG and Commerce One. SAP, R/3, mySAP, mySAP.com, xApps, xApp, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies.

Version 1.0 May 2005 - SAP AG 2005

DEVELOPMENT FORECAST CALL DOCUMENTATION

CONTENTS
Change Log ......................................................................................................................................2 Contents ...........................................................................................................................................3 1 Motivation to run the configurator on VMC ...............................................................................4 2 Developing Functions and Pfunctions.......................................................................................5
2.1 Setting up Java .............................................................................................................................................5 2.2 Setting up Eclipse .........................................................................................................................................5 2.3 Downloading the configurator-libraries .........................................................................................................5 2.4 Setting up the eclipse project........................................................................................................................6 2.5 Creating a (p)function ...................................................................................................................................6 2.6 Jaring the (p)function ....................................................................................................................................6 2.7 Uploading the (p)functions ............................................................................................................................6 2.8 Deleting uploaded (p)functions .....................................................................................................................7 2.9 Tracing errors within (p)functions..................................................................................................................7 2.10 Differences to 4.0 (p)functions ..............................................................................................................8

3 Debugging.....................................................................................................................................9
3.1 Set VMC in Debug Mode ..............................................................................................................................9 3.2 Attach Eclipse Java Debugger......................................................................................................................9

4 VMC logging and tracing overview...........................................................................................10

4.1 Prerequisites ...............................................................................................................................................10 4.2 Using VMC logging and tracing ..................................................................................................................10 4.2.1 Use .........................................................................................................................................................10 4.2.2 Features ................................................................................................................................................10 4.2.3 Activities ...............................................................................................................................................11 4.3 Displaying Log Messages ...........................................................................................................................11 4.3.1 Use .........................................................................................................................................................11 4.3.2 Procedure..............................................................................................................................................12 4.4 Displaying and Changing Log Settings .......................................................................................................12 4.4.1 Use .........................................................................................................................................................12 4.4.2 Procedure..............................................................................................................................................13 4.4.3 Result.....................................................................................................................................................15

THE VMC 1 MOTIVATION TO RUN THE CONFIGURATOR ON VMC

The VM Container technology enables a Java VM to be integrated in the ABAP work process (see Architecture of the SAP NetWeaver Application Server, section Technical Components). Formerly the configurator was executed within a server infratructure called IPC. Now it is run on the SAP VM Container. The execution of applications on the Java VM integrated in the ABAP work process is only intended for components developed by SAP. The VM container technology in connection with a Java VM integrated in the ABAP work process provides the following advantages: Reliability and maintainability as in the ABAP environment The integration of the Java VM into the ABAP work process enables strict isolation between active user sessions, which guarantees a large degree of robustness and maintainability. One work process can only process one user request at a time, which means that even if one entire Java VM crashes, only the one user active at this time is affected. Close ABAP/Java communication (in-process) Since the ABAP and Java VMs run in the same work process, a quick and efficient communication path can be implemented between the two languages, which means that the security and speed of the communications is significantly increased. For more information see SAP JCo and VM Container. Administration and Sharing of Resources While a request is being processed a Java VM works exclusively for one user. There is a pool of VMs dynamically assigned to the work processes. These VMs can access shared data in the shared memory. o Java shared closures Java objects can be moved across process boundaries and shared by processes. This enables an efficient session failover to be implemented. At the same time shared closures offer the option of reducing the memory consumption of the entire system through process-wide caching. Shared class pool Java classes only have to be loaded into the memory once, the same as for ABAP PXA, and they can be used by all the processes in the system. This reduces the memory consumption and the start time of further processes.

High Supportability Since the JTS uses existing SAP kernel technology, the monitoring functions of the CCMS can be used. For the reason, the familiar SAP statistics can also be used (see Statistics in the VM Container). Debugging Each user can dynamically switch to and fro between normal operation and debugging.

Version 1.0 May 2005 - SAP AG 2005

DEVELOPMENT FORECAST CALL DOCUMENTATION

2 DEVELOPING FUNCTIONS AND PFUNCTIONS

This chapter describes how to develop functions and pfunctions for the configurator in AP 7.00.

2.1 Setting up Java

The (p)functions (configuration userexits) shall be compiled with the J2SE 1.4.x or a compatible java compiler of version 1.4.x. Also the used libraries must be compatible with J2SE 1.4.x. The java development kit is available for download using http://java.sun.com/downloads. A standard installation of the JDK is sufficient

2.2 Setting up Eclipse

Eclipse 3.0 or 3.1 is recommended and can be downloaded using http://www.eclipse.org/downloads. A simple unpacking of the downloaded file is all that is needed to install eclipse. The eclipse-IDE manages the files in projects and the projects in workspaces. A workspace contains all administrative data of eclipse. Project files, like java source files, may lie also in that workspace but can also be outside.

configurator2.3 Downloading the configurator-libraries

Start your SAP GUI, log in and start transaction cfg_user_exit_dev1. Create an folder for to place the classes.

Check the 'download' section, type the above folder (or use F4 to navigate there) and press F8 to download the classes into the already created folder, lets call this folder $SCE_CLASSES$ for further references. The class files can be found in $SCE_CLASSES$/lib_api.

note that this transaction uses /SAPCND/UE_DEV but allows to upload classes to path com.sap.sce.user

2.4 Setting up the eclipse project

Assumptions: Eclipse is installed a workspace is created, a project is set up for developing user functions for the configurator. All you have to do is including the $SCE_CLASSES$/lib_api to your projects libraries. This folder includes all needed libraries from com.sap.sce.*. Moreover it contains the pricing classes as well and the classes of com.sap.spc.*.

2.5 Creating a (p)function

Within the above created project you can create now (p)functions using the same APIs as in IPC 4.0. To name the most important ones: com.sap.sce.user.scelib com.sap.sce.engine.* com.sap.sce.kb.*. Create a class that has exactly the name of your (p)function referenced in the knowledgebase. The class to be created has to be in package com.sap.sce.user, has to implement the interface com.sap.sce.user.sce_user_fn Make sure NOT to overwrite existing classes in package com.sap.sce.user!

2.6 Jaring the (p)function

The above created (p)functions and the helper classes have to be packed into a jar-file. A manifest should be added to the META-INF-folder to identify the creation date and the version by using the VMC-administration. Hint: you should add the sources to the jar-file. Doing this you can always download the matching sources for error analysis, debugging and you can use the system as your source code repository for your (p)functions. Eclipse provides a jar packager that easily allows to create the needed jar-file. You can start the packeager using the context menu of the project and choosing Export JAR file and you reach the wizard for creating jar-files. For convenience save your entries in the project. Lets call the jar-file for simplicity customer_cfg_userexits.jar (can be named arbitrarily).

2.7 Uploading the (p)functions

Uploading the customer_cfg_userexits.jar file to the database is done via transaction cfg_user_exit_dev,. This task requires advanced authority settings. Following authorization objects are concerned: S_CTS_ADMI S_DATASET S_DEVELOP S_GUI Administration Functions in Change and Transport System Authorization for file access ABAP Workbench

Authorization for GUI activities

S_TCODE Transaction Code Check at Transaction Start S_VMC_TRAN The library upload needs a modifiable workbench request which must be already existing an ABAP package created by the customer beforehand, Transport of Java Development Objects

Version 1.0 May 2005 - SAP AG 2005

DEVELOPMENT FORECAST CALL DOCUMENTATION

the path to customer_cfg_userexits.jar. The uploading is triggered by the execute button or pressing F8. The jar-file shall only contain customer coding. Uploading any other class belonging to a package com.sap.* than to package com.sap.sce.user would possibly overwrite existing classes and therefor lead to an unexpected behaviour of SAP applications running on VMC. Hence it is checked and not possible. Other files than *.class, *.java and the manifest cannot be uploaded.

If you upload (p)functions to an (Abap)package that was already used for uploading (p)functions all Java classes previously uploaded to the package are deleted and replaced by the new Java classes contained in the jar-file. The VMC can cope with hot-deployment of Java-classes. No server restart is necessary. If you upload an empty jar-file, you delete the previously uploaded Java classes. The transport of Java classes is as transparent as the transport of Abap code.

2.8 Deleting uploaded (p)functions

As already said in the previous chapter you delete already uploaded (p)functions by repeating the upload with an empty jar-file. This is the only way of deleting uploaded (p)functions.

2.9 Tracing errors within (p)functions

For tracing the following API can be used to make trace-entries. You will find your traces under the location com.sap.sce.user.sce_user_fn_logging.

public class sce_user_fn_logging

extends java.lang.Object writeLogDebug public void writeLogDebug(com.sap.sce.user.sce_user_fn function, java.lang.String logMessage) Writes an log entry with the severity DEBUG Parameters: function - denotes the sce_user_fn implementation to be logged for, used as location logMessage - denotes the logmessage

writeLogInfo public void writeLogInfo(com.sap.sce.user.sce_user_fn function, java.lang.String logMessage) Writes an log entry with the severity INFO Parameters: function - denotes the sce_user_fn implementation to be logged for, used as location logMessage - denotes the logmessage

writeLogWarning public void writeLogWarning(com.sap.sce.user.sce_user_fn function, java.lang.String logMessage) Writes an log entry with the severity WARNING Parameters: function - denotes the sce_user_fn implementation to be logged for, used as location

8 logMessage - denotes the logmessage

writeLogError public void writeLogError(com.sap.sce.user.sce_user_fn function, java.lang.String logMessage) Writes an log entry with the severity ERROR Parameters: function - denotes the sce_user_fn implementation to be logged for, used as location logMessage - denotes the logmessage

writeLogError public void writeLogError(com.sap.sce.user.sce_user_fn function, java.lang.String logMessage, java.lang.Throwable throwable) Writes an log entry with the severity ERROR Parameters: function - denotes the sce_user_fn implementation to be logged for, used as location logMessage - denotes the logmessage throwable - denotes the Throwable that should be logged with stacktrace

2.10 Differences to 4.0 (p)functions

In 4.0 (p)functions where part of the knowledgebase. An instance of the (p)function existed as a singleton and was used across multiple sessions without being synchronized. In 5.0 the (p)function exists once per VM. Each VM is exclusively used for one function module. The (p)function is not stored in the knowledgebase because the (p)function would have to fulfill 'shareability' criterias of the VM Container. This would be a potential source of errors. Therefor you should not buffer any data at the (p)function instance, because it may happen that the session is rolled out and processed in a different VM afterwards. You may not be able to access the buffer even within one session. For improving the performance buffers can be used if the buffers are session independent, knowledgebase independent because the instance can be used by multiple knowledgebases, build up if not available. The VMC closes VMs that are not used for some time. In most cases a VM is used for one session.

Version 1.0 May 2005 - SAP AG 2005

DEVELOPMENT FORECAST CALL DOCUMENTATION

3 DEBUGGING
3.1 Set VMC in Debug Mode
The logical application server is usually hosted on different servers and load balanced via the message server. To debug the VMC the user has to know on which host his work process run. In the SAPGUI menu System -> Status the Server name (first part) is displayed. On the next page (3rd button) also the corresponding IP address is given. Switching between hosts of one server can be done via transaction sm51. Run transaction sm52 to display the available VMCs. This window will later show the servers running virtual machines and also the debug state and port of each one. A VMC work process switches into debug mode when a program flow from ABAP to Java (RFC function module) is passed and ABAP was in debug mode (with /h). Debugging RFCs from the WebUI is quite hard and has to be reworked! While running the transaction (e.g. order processing) each call to pricing will hold and with a step-into debugging into the RFC module (F5) a VMC debug port will be activated. This VMC will stay attached as long the ABAP transaction runs.

Debugger 3.2 Attach Eclipse Java Debugger

After a VMC work process has an open debug port, which can be viewed with transaction sm52, the eclipse debugger can be attached to it. Because attaching the debugger to the VMC will run directly the code, the java breakpoint must be set before attaching. Attaching eclipse works as follow: 1. 2. 3. 4. 5. Open menu Run->Debug Create a new Remote Java Application Configuration Enter as host the server where the VMC work process is running on Enter the debug port as the one VMC work process debug port shown in transaction sm52 Click on Debug

The debugging view will normally popup automatically and a successful attachment will show all working threads of that VMC work process. Because debugging real RFC-calls is quite hard the following chapter explains tracing and logging concepts.

10

TRACING 4 VMC LOGGING AND TRACING OVERVIEW

4.1 Prerequisites
With the VMC System Administration (transaction SM53) you can monitor all the settings in the environment of the SAP Virtual Machine Container (VMC) and carry out administration tasks. The transaction is intended for use by administrators, SAP consultants, and SAP support. You need authorization for the transaction. This is configured in authorization object S_VMCADMIN. Profile S_VMCADMIN_1 gives display and change authorization. Profile S_VMCADMIN_2 only gives you display authorization. The profile S_VMCADMIN_2 suffices to change the loglevels and changing jarm-settings. Thus this profile is the minimum prerequisite to work with tracing and logging! In transaction SM52 you can see an overview of all the running Java VMs in the VM Container

4.2 Using VMC logging and tracing 4.2.1 Use

Logging and tracing are invaluable tools for handling any problems that may occur in programs. Users can look up in log files what the exact problem is. Administrators and developers can identify from the traces what the cause of the problem is and how it can be solved.

4.2.2 Features
The VMC logging and tracing system is called up by Java programs to output messages that enable errors to be found later and to reproduce the program flow. These Java programs can be components of the VMC environment itself, or even applications that use the VMC to execute Java code. The Java program uses a log controller object created earlier to write the message. There are two types of log controllers. Categories to write the log messages These correspond to logical components such as /system/database, the parts of the name are separated by a forward slash (/). Locations to write traces for developers and administrators. The names of locations correspond normally to Java class names or packages, the parts of the name are separated by a point. When you choose Log Administration Log Display on the left-hand side, a new tree appears.

Version 1.0 May 2005 - SAP AG 2005

DEVELOPMENT FORECAST CALL DOCUMENTATION

11

This contains the hierarchical structure for the locations. Beneath this the categories are listed. Each message has a Severity level that together with the log controller setting determines whether the message is output or not. This allows you to restrict the number of messages to those of real interest. Each log controller can enter separate settings. The path-like names of the log controllers enable them to be uniquely arranged in the tree, as settings are passed downwards in the tree. For instance, if a location is configured in such a way that it only outputs traces with a severity of at least WARNING, this is also valid for all the subordinate locations, unless these have their own settings.

4.2.3 Activities
You can view the log messages in the log administration in SM53, and you can also display and change the log settings. The sections below contain more details:

4.3

Displaying Log Messages

4.3.1 Use
You can display all VMC log messages in the VMC Administration (SM53). The log viewer has been developed for this purpose. It combines all the logs written by VMC logging and tracing and allows you to select messages according to the log controller, severity, time, and so on.

12

Normally, messages are written to text files located in the $DIR_HOME directory, and they can be read directly or in transaction AL11. Older logs or traces are located in the logs subdirectory. Applications that run on the VMC normally use files vmc_w<WORK PROCESS ID>.trc for tracing, and files vmc_w<WORK PROCESS ID>.log for logging. This directory also contains diverse trace files whose names begins with dev_. As you can configure which log controller writes to which file, there is no default log controller and file.

4.3.2 Procedure 1. In the left frame of the VMC administration (SM53) choose Log Administration Log Display. 2. Select a log by choosing in the top left of the hierarchical structure the available locations and categories as the
sources of the messages for which you want to see the. If a node of a tree is selected or deselected, all the nodes of the subtree are automatically selected/deselected too.

3. Use the filter settings to further restrict the amount of messages found.
To search specifically for errors you can for instance hide messages with a severity smaller than WARNING and restrict the time period. Errors that occurred in a specific session may be traced more easily if messages from this session only are displayed. You can restrict the number of hits in the lower left area according to the following criteria: o o o o o Severity: Severity of the message. Displays only messages with the selected or higher level of severity. Log Name: Displays only log messages with this name (for very specific searches). User: Displays only log messages that were created under the user specified. Client: Displays only log messages that were written in this client. Session: Displays only log messages from this session. You can view the session IDs of the active sessions if you choose Sessions in the initial screen of the VMC system administration and then look in the column Session ID. Thread: Displays log messages from this thread only (for very specific searches) Messages by Date/Time: Displays only log messages written after this date and time. Messages up to Date/Time: Displays only log messages written before this date and time.

o o o

4. Choose the icon Update Log Messages. The requested log messages are now displayed in the top right area.

A maximum of 1000 messages can be retrieved at one time. If more than 1000 messages exist, this is indicated in the status bar and you can scroll through them using the scrolling buttons in the function key menu bar. The messages last transferred are listed in the table. You can sort them, search them, or export them to a file. If a single line display in the table is not sufficient, you can view individual messages in detail by double-clicking on them.

4.4

Displaying and Changing Log Settings

4.4.1 Use
You can change the severity level for single log controllers in the productive system at any time using the VMC Administration (transaction SM53). Choose Log Administration Log Configuration.

Version 1.0 May 2005 - SAP AG 2005

DEVELOPMENT FORECAST CALL DOCUMENTATION

13

Here you can specify which log messages get recorded by the system. If you display the log messages, you can restrict the number of hits (see Displaying Log Messages).

You can find all the options for setting the VMC log system in the configuration file logging.xml, in subdirectory cfw/conf/vmc_runtime/base (for the configuration delivered by SAP) or in cfw/conf/vmc_runtime/custom (for customer configurations). Among other things, here you can specify which messages, and in what detail are written to which files. Changes to this configuration should only be made be experienced administrators and only in the custom directory. They only become active when the VMC is started or reset.

4.4.2 Procedure
In the left frame of the VMC administration (SM53) choose Log Administration Log Configuration. The following screen appears:

14

Configure the log settings according to your wishes. You can select any location or category you like and change their severity settings. Any changes and their effects on lower-level nodes are immediately visible in the tree displayed. You can also insert log controllers unknown up to now, by entering the full name in the input field and copying the relevant setting.

Version 1.0 May 2005 - SAP AG 2005

DEVELOPMENT FORECAST CALL DOCUMENTATION 4.4.3 Result

15

The changes you made are effective immediately, but they are not saved they are valid only until the VM is restarted or reset.