sap conversion agent by itemfield...available from sap support. conversion agent...

SAP Conversion Agent by Itemfield

Conversion Agent Administrator's Guide

Version 4

Legal Notice

Conversion Agent Administrator's Guide

Copyright © 2004-2006 Itemfield Inc. All rights reserved.

Itemfield may have patents, patent applications, trademarks, copyrights, or other intellectual propertyrights covering subject matter in this document. Except as expressly provided in any written licenseagreement from Itemfield, the furnishing of this document does not give you any license to thesepatents, trademarks, copyrights, or other intellectual property.

The information in this document is subject to change without notice. Complying with all applicablecopyright laws is the responsibility of the user. No part of this document may be reproduced ortransmitted in any form or by any means, electronic or mechanical, for any purpose, without theexpress written permission of Itemfield Inc.

SAP AGhttp://www.sap.com

Publication Information:

Version: 4Date: September 2006

Conversion Agent Administrator's Guide Contents

i

Contents

1. Overview ...........................................................................................1Essential Administrative Tasks.............................................................................................................. 1

Installing Conversion Agent on Windows ........................................................................................ 1Installing Conversion Agent on Unix ............................................................................................... 1Testing the Conversion Agent Installation....................................................................................... 1Running Data Transformations ....................................................................................................... 2Configuring Conversion Agent ........................................................................................................ 2Upgrading Existing Conversion Agent Data Transformations .........................................................2Using ODBC Database-Support Features ......................................................................................2Deploying Conversion Agent in an Organization............................................................................. 2

Conversion Agent Modules ................................................................................................................... 3Conversion Agent Concepts ..................................................................................................................4

2. System Requirements ......................................................................5Supported Operating Systems .............................................................................................................. 5General Requirements for All Operating Systems................................................................................. 6Specific Requirements for Windows...................................................................................................... 6Specific Requirements for Solaris ......................................................................................................... 7Specific Requirements for AIX...............................................................................................................8Specific Requirements for Linux.......................................................................................................... 10Specific Requirements for HP-UX ....................................................................................................... 12Requirements Associated with Third-Party Applications .....................................................................13

3. Installation ......................................................................................14If You are Upgrading from a Previous Version ....................................................................................14Running the Setup Wizard...................................................................................................................15Required Post-Setup Steps ................................................................................................................. 17Optional Post-Setup Steps ..................................................................................................................17Testing the Installation.........................................................................................................................17Uninstalling .......................................................................................................................................... 18


ii

4. Environment Variables...................................................................19Loading the Environment Variables on Unix Platforms ....................................................................... 19Unix Environment-Variable Reference................................................................................................ 20Windows Environment-Variable Reference.........................................................................................22

5. Registration and Licensing............................................................23License Status .....................................................................................................................................23

6. Testing and Troubleshooting ........................................................24Conversion Agent Engine Test ............................................................................................................24Document Processor Test ...................................................................................................................25Installation Troubleshooting................................................................................................................. 25

Unix Environment Variables .......................................................................................................... 25Log Files........................................................................................................................................26Java Heap Size .............................................................................................................................27Preventing Core Dumps ................................................................................................................27LDR_CNTRL Environment Variable on AIX ..................................................................................27LD_PRELOAD Environment Variable on HP-UX.......................................................................... 28Memory Allocation on HP-UX........................................................................................................29Emulators ...................................................................................................................................... 29Asian Fonts ................................................................................................................................... 29

7. Running Data Transformations .....................................................30Designing and Configuring Data Transformations...............................................................................30Deploying Conversion Agent Services ................................................................................................ 30Running Conversion Agent Services................................................................................................... 31

8. Running In-Process or Out-of-Process.........................................33Relative Advantages............................................................................................................................ 33Determining whether to Run In-Process or Out-of-Process ................................................................ 33Configuration ....................................................................................................................................... 34

9. Configuration Editor.......................................................................37Backing Up the Configuration File ....................................................................................................... 37Using the Configuration Editor.............................................................................................................37Configuration Settings .........................................................................................................................38Copying the Configuration File ............................................................................................................39Multiple Configurations ........................................................................................................................ 39


iii

10. Upgrading Conversion Agent Projects .......................................42When Is Upgrading Necessary?.......................................................................................................... 42Terminology.........................................................................................................................................42Upgrading an Individual Project...........................................................................................................43Syntax Conversion Tool ......................................................................................................................43

Before Running the Tool: Organize Your Projects ........................................................................44Running the Syntax Conversion Tool............................................................................................ 44Running from the Command Line .................................................................................................46

Upgrade Issues ................................................................................................................................... 47New and Modified Components ....................................................................................................47Modified Namespace for Variables ............................................................................................... 47Unsupported File and Directory Names ........................................................................................ 48XSD Schemas ............................................................................................................................... 48Additional Upgrade Issues ............................................................................................................48

11. Using Conversion Agent with ODBC ..........................................49Installing and Configuring an ODBC Manager on Unix ....................................................................... 49Installing an ODBC Driver ...................................................................................................................50Troubleshooting................................................................................................................................... 50Defining DSNs .....................................................................................................................................50Configuring Conversion Agent to Use ODBC......................................................................................50

12. Administration and Deployment Policies ...................................51Security................................................................................................................................................51

Conversion Agent Studio Permissions ..........................................................................................51Conversion Agent Engine Runtime Permissions...........................................................................52Standard Windows User Categories .............................................................................................52

Multiple-Server Environments .............................................................................................................52Running on a Cluster Server .........................................................................................................53Sizing Guidelines for SAP XI.........................................................................................................54

Backup Requirements .........................................................................................................................54Failure Handling ..................................................................................................................................55

Index....................................................................................................56

Conversion Agent Administrator's Guide 1. Overview

1

Overview

This book explains how to administer the Conversion Agent data-transformationsoftware. It covers subjects such as installing and configuring Conversion Agent,diagnosing and solving system problems, and policies for administeringConversion Agent on a network.

Essential Administrative Tasks

The following paragraphs outline some of the essential administrative tasks thatare covered in this book.

Installing Conversion Agent on Windows

For information about installing Conversion Agent on Microsoft Windowssystems, you should read the following chapters:

Chapter 2, System Requirements

Chapter 3, Installation

Installing Conversion Agent on Unix

Conversion Agent runs on Unix-type operating systems such as Solaris, AIX, HP-UX, and Linux. For the installation and required configuration instructions, pleaseread:

Chapter 2, System Requirements

Chapter 3, Installation

Chapter 4, Environment Variables

Testing the Conversion Agent Installation

To confirm that Conversion Agent is correctly installed, see:

Chapter 6, Testing and Troubleshooting

1


2

Running Data Transformations

If you are a system administrator who is responsible for Conversion Agentoperations, you should be aware of the ways in which users may run datatransformations and services in Conversion Agent. The following chapter providesa brief overview:

Chapter 7, Running Data Transformations

Configuring Conversion Agent

After you have installed Conversion Agent, you can edit the configuration, forexample, to:

Invoke Conversion Agent either in-process or out-of-process of its callingapplication

Move the locations where Conversion Agent stores deployed services or errorlogs

Change the Java Runtime Environment (JRE) that Conversion Agent uses

Adjust performance parameters

For these subjects, see:

Chapter 8, Running In-Process or Out-of-Process

Chapter 9, Configuration Editor

Upgrading Existing Conversion Agent Data Transformations

If you have upgraded from a previous Conversion Agent version, you must alsoupgrade the data-transformation projects and services that you run in ConversionAgent. To do this, see:

Chapter 10, Upgrading Conversion Agent Projects

Using ODBC Database-Support Features

If you plan to use the Conversion Agent ODBC database-support features, youshould read:

Chapter 11, Using Conversion Agent with ODBC

Deploying Conversion Agent in an Organization

If you are deploying Conversion Agent to multiple computers throughout anorganization, you should perform tasks such as:

Installing Conversion Agent on multiple workstations and servers

Implementing security policies


3

Replicating the Conversion Agent services on multiple servers

Backing up the Conversion Agent configurations, projects, services, and data

For these subjects, see:

Chapter 12, Administration and Deployment Policies

Conversion Agent Modules

This book describes the installation and administration of the following mainConversion Agent modules:

Conversion Agent Engine (required)The runtime module that executes Conversion Agent data transformations.This module is required in all Conversion Agent installations.

Conversion Agent Engine runs on both Windows and Unix-type platforms.

Conversion Agent Studio (optional)The design and configuration environment where you can create and deploydata transformations.

Conversion Agent Studio is hosted within Eclipse on Windows platforms. TheEclipse setup is included in the Conversion Agent installation package.

Document Processors (optional)A set of components that perform preprocessing operations on documents, forexample, transforming their file formats.

All the document processors run on Windows platforms, and most of themrun on Unix-type platforms.

Libraries (optional)Libraries of predefined Conversion Agent data transformations, which youcan use with industry messaging standards such as EDI, AL3, HL7, HIPAA,and SWIFT. Each library contains parsers, serializers, and XSD schemas for theappropriate messaging standard.

You can install the libraries on Windows platforms. Then, you can useConversion Agent Studio to import the library components to your projects,and deploy the projects to Windows or Unix-type platforms.

Online Documentation (optional)An online help library, containing all the Conversion Agent manuals.

You can install the documentation on Windows platforms. For use on Unix-type platforms, you can use the PDF versions of the manuals, which areavailable from SAP support.


4

Conversion Agent Concepts

In the course of installing and administering the Conversion Agent software, youare likely to encounter the following Conversion Agent concepts. The concepts areexplained in detail in other manuals, such as Getting Started with Conversion Agent.The following are brief definitions.

Data transformationThe conversion of data from one structure or format to another, possiblyaccompanied by modification of the data values.

ProjectA collection of files and resources that are necessary to define and execute adata transformation. Each project is stored in a directory.

Conversion Agent serviceA data transformation that is available to be executed in Conversion AgentEngine.

Conversion Agent repositoryThe location where Conversion Agent services are stored.

DeployCopy a project to the Conversion Agent repository, thereby making itavailable as a Conversion Agent service.

JREJava Runtime Environment, required to install and run Conversion Agent.Also known as JVM, Java Virtual Machine.

Conversion Agent Administrator's Guide 2. System Requirements

5

System Requirements

To install the Conversion Agent software, your computer should meet theminimum requirements that are described in this chapter.

In the following sections, please read both the General Requirements for All OperatingSystems and the specific requirements for your system.

Supported Operating Systems

You can install and run Conversion Agent on the following operating systems. Forthe version requirements of each system, see the detailed system requirementsbelow in this chapter.

Microsoft WindowsOn Microsoft Windows, you can install all Conversion Agent modules such asConversion Agent Engine, Conversion Agent Studio, the document processors,and the libraries.

Unix-Type SystemOn Unix-type operating systems, you can install Conversion Agent Engine and thedocument processors. Conversion Agent supports the following Unix-typesystems:

Sun Solaris

IBM AIX

LINUX

Hewlett-Packard HP-UX

Features that are Not Available on UnixThe following Conversion Agent features are not available on Unix:

The COM API, which requires the Microsoft Windows COM architecture

Custom COM components (such as ExternalCOMPreProcessor orExternalCOMAction)

2


6

Document processors that require Microsoft Office applications on the samecomputer (such as ExcelToHtml, ExcelToTxt, PowerpointToHtml, WordToHtml,WordToTxt, and WordToRtf)

The Java document processors for Microsoft Office documents (such asExcelToXml, WordToXml, and XmlToExcel) do not require the Office applications andoperate on Unix.

General Requirements for All Operating Systems

HardwareThe minimum RAM requirement is at least 128 MB on Windows and 256 MB onUnix. For a system running production Conversion Agent services, we recommendat least 512 MB of RAM and a CPU speed of at least 1 GHz.

Java Runtime EnvironmentA Java 2 Runtime Environment (JRE) is required. By default, the Conversion Agentsetup installs a JRE on your computer.

If you prefer, you can use another JRE version, which you install independently onthe computer. For the supported JRE versions, see the specific requirements foryour operating system.

If necessary, you can change the selected JRE following the installation. Forexample, you change from a client JRE to a server JRE. To change the JRE settingon Windows, see Chapter 9, Configuration Editor). For Unix, see Unix Environment-Variable Reference in Chapter 4, Environment Variables .

If You Plan to Use the Conversion Agent Java API

If you use the Conversion Agent Java API to activate a Conversion Agent service,any Java components of the service run on the JRE that is used by the external Javaapplication.

For consistency of operation, we recommend that this be the same JRE as the onethat you configured within Conversion Agent. In any event, it must be a JREversion that Conversion Agent supports.

For more information, see Chapter 8, Running In-Process or Out-of-Process.

Specific Requirements for Windows

You can install Conversion Agent on a system conforming to the followingrequirements:

Microsoft Windows 2000, XP Professional, or 2003 Server (32-bit or 64-bitedition)

Microsoft Internet Explorer, version 6.0 or higher


7

(For Conversion Agent Studio) Microsoft .NET Framework, version 1.1 orhigher. If you do not already have this, the Conversion Agent setup installs it.

JRE VersionA Sun Java 2 Runtime Environment, version 1.4.2_9, must be installed on thecomputer. You can use the JRE that is installed with Conversion Agent, or you candownload a JRE from http://www.sun.com.

The JRE does not need to be defined in your PATH environment variable. In rareinstances, the Conversion Agent Java document processors may require that theJRE be defined in the PATH for proper operation.

Disk SpaceThe Conversion Agent Engine and Studio software require approximately 200 MBof disk space.

If you plan to install the optional Conversion Agent libraries, you should reserveadditional space (see Conversion Agent Libraries for the space requirements).

Specific Requirements for Solaris

Conversion Agent is supported on Sun Solaris on the SPARC platform. Thefollowing paragraphs provide details of the version, package, and patchrequirements.

For information about Solaris on the Intel platform or other Solaris versions, pleasecontact SAP support.

Solaris 10You can run Conversion Agent on Solaris 10 (also known as SunOS 5.10), on theSPARC platform. The following packages must be installed:

Package Minimum version

SUNWcsl 11.10.0,REV=2005.01.21.15.53

SUNWcslr 11.10.0,REV=2005.01.21.15.53

SUNWcsr 11.10.0,REV=2005.01.21.15.53

SUNWlibC 5.10,REV=2004.12.22

SUNWlibms 5.10,REV=2004.11.23

SUNWlibmsr 5.10,REV=2004.11.23

SUNWuiu8 1.5,REV=2004.11.24.10.12

http://www.sun.com/


8

Confirming Packages and Patches

To confirm that a required package has been installed, run the followingcommand:

pkginfo -l package_name

For example, to determine whether the SUNWcsl package is installed, run thecommand:

pkginfo -l SUNWcsl

To confirm that a required patch has been installed, run the command:

showrev -p | grep patch_number

For example:

showrev -p | grep 111711

The commands display whether a package or patch is installed, and its versionnumber.

JRE Version

The Sun Java 2 Runtime Environment, version 1.4.2_9, is supported. You can usethe JRE that is installed with Conversion Agent, or you can download a JRE fromhttp://www.sun.com.

Disk SpaceA full Conversion Agent installation on Solaris requires approximately 160 MB ofdisk space.

Specific Requirements for AIX

Conversion Agent is supported on IBM AIX. The following paragraphs providedetails of the version and package requirements.

AIX 5.3

You can run Conversion Agent on AIX 5.3 with maintenance level 0. The followingpackages must be installed:

Package name Version PTF Comment

bos.rte.bind_cmds 5.3.0.10 ML 0

bos.rte.libc 5.3.0.10 ML 0

bos.rte.libpthreads 5.3.0.10 ML 0

xlC.rte 6.0.0.0 ML 0

http://www.sun.com/


9

On some AIX 5.3 computers, the Conversion Agent setup may fail to run unlessyou configure the LDR_CNTRL environment variable. If the setup does not start,configure the variable as follows:

1. Determine the existing value of the LDR_CNTRL variable (if any). To do this,enter the following command:

echo $LDR_CNTRL

If the result isn't empty, save the result.

2. If you use the sh, ksh, or bash shell, add the following lines to .profile :

LDR_CNTRL=NOKTRLexport LDR_CNTRL

In the first line, if the result of step 1 was not empty, you should append it tothe NOKTRL value. Substitute the following syntax, including the quotationmarks:

LDR_CNTRL="NOKTRL result_of_step_1"

3. If you use the csh or tcsh shell, add the following line to your ~/.cshrc or~/.tcshrc file:

setenv LDR_CNTRL NOKTRL

In this line, if the result of step 1 was not empty, you should append it to theNOKTRL value. Substitute the following syntax, including the quotation marks:

setenv LDR_CNTRL "NOKTRL result_of_step_1"

4. Log out and log in, to ensure that the environment variable takes effect.

Confirming Packages

To determine which maintenance level is installed, run the following command:

oslevel -r

To determine whether a required package has been installed:

1. Run the following command, which opens the system management console:

smitty

2. Select the options Software Installation and Maintenance > List Software andRelated Information > List Installed Software and Related Information > ListInstalled Software.

The package name (for example, xlC.rte) should be displayed in the list.

3. To confirm the version number of a package, run the following command:

lslpp -l | grep package_name

For example, to determine whether the xlC package is installed, run thecommand:

lslpp -l | grep xlC


10

The version number is displayed.

JRE VersionThe Java 2 Runtime Environment, version 1.4.2 SR3, is supported. You can use theJRE that is installed with Conversion Agent, or you can download a JRE fromhttp://www.ibm.com.

Recommended ConfigurationIn the AIX system configuration, we recommend not limiting the data size. Todetermine whether there is currently a limitation, run the following command:

ulimit –d

If you process very large documents using Conversion Agent, you may need toadjust system parameters such as the memory size and the file size.

Disk SpaceA full Conversion Agent installation on AIX requires approximately 190 MB ofdisk space. The setup requires that you have at least this amount of free space inthe temp directory. You can confirm this by running the following command:

df -k

Specific Requirements for Linux

Conversion Agent is supported on SUSE and Red Hat versions of Linux. Thefollowing paragraphs provide detailed version and platform information.

SUSE Linux 9 and Red Hat Linux EL3 on x86

You can run Conversion Agent on SUSE Linux version 9 and on Red Hat Linuxversion EL3, on an Intel x86 or compatible platform. The following packages mustbe installed:

Package Version Minimumrevision

Comment

glibc 2.3.2 11.9

libgcc 3.2.2 5

libstdc++ 3.2.2 5

compat-glibc 7.x-2.2.4.32.5.i386.rpm Required if you use the SunJRE; not required for IBMJRE

http://www.ibm.com/


11

Package Version Minimumrevision

Comment

compat-libstdc++ 7.3-2.96.122.i386.rpm Required if you use the SunJRE; not required for IBMJRE

A Sun Java 2 Runtime Environment, version 1.4.2_9, must be installed on thecomputer. You can use the JRE that is installed with Conversion Agent, or you candownload a JRE from http://www.sun.com.

SUSE Linux 9 and Red Hat Linux EL4 on x86-64You can run Conversion Agent on SUSE Linux version 9 and on Red Hat Linuxversion EL4, on x86-64 platforms such as AMD Opteron.

An IBM Java 2 Runtime Environment, version 1.4.2 SR3, must be installed on thecomputer. You can use the JRE that is installed with Conversion Agent, or you candownload a JRE from http://www.ibm.com.

Confirming PackagesTo determine whether a required package is installed, run the following command:

rpm -qa | grep package_name

For example, to determine whether the glibc package is installed, run thecommand:

rpm -qa | grep glibc

The version number of the package is displayed.

Recommended ConfigurationIn the Linux system configuration, we recommend not limiting the data size andthe stack size. To determine whether there is currently a limitation, run thefollowing command:

limit

If you process very large documents using Conversion Agent, you may need toadjust system parameters such as the memory size and the file size.

Disk SpaceA full Conversion Agent installation on Linux requires approximately 150 MB ofdisk space.

http://www.sun.com/

http://www.ibm.com/


12

Specific Requirements for HP-UX

Conversion Agent is supported on Hewlett-Packard HP-UX. The followingparagraphs provide details of the platform and bundle requirements.

HP-UX 11.23 on PA-RISCYou can run Conversion Agent on HP-UX 11.23 (also known as version B.11.239000/800), on the PA-RISC architecture. The following bundles must be installed:

Bundle Version

BUNDLE11i B.11.23.0409.3

FEATURE11i B.11.23.0505.022e

HPUXBaseOS B.11.23

HWEnable11i B.11.23.0505.022b

PHCO_32489

PHKL_31500

PHKL_33312

PHSS_32502

PHSS_33263

PHSS_33349

QPKAPPS B.11.23.0505.022

QPKBASE B.11.23.0505.022

An HP Java 2 Runtime Environment version 1.4.2_09 and the Java "-AA" add-onmust be installed on the computer. You can use the JRE that is installed withConversion Agent, or you can download a JRE from http://www.hp.com.

HP-UX 11.23 on ia64

You can run Conversion Agent on HP-UX 11.23 (also known as version B.11.239000/800), on the ia64 architecture (Intel Itanium).

For information about the required bundles, please contact SAP support.

An HP Java 2 Runtime Environment, version 1.4.2.10, must be installed on thecomputer. You can use the JRE that is installed with Conversion Agent, or you candownload a JRE from http://www.hp.com.

Confirming BundlesTo confirm that the required bundles have been installed, run the followingcommand:

http://www.hp.com/

http://www.hp.com/


13

/usr/sbin/swlist

Disk SpaceA full Conversion Agent installation on HP-UX requires approximately 280 MB ofdisk space.

Requirements Associated with Third-PartyApplications

You can use Conversion Agent with documents that are generated by a largenumber of third-party applications. The following applications are among thosethat are currently supported.

Please contact SAP support for information about other applications, file formats,or versions.

Microsoft Office Applications

To help you parse Microsoft Office documents (Word, Excel, or PowerPoint),Conversion Agent offers several document processors, which convert thedocuments to a format such as text, HTML, RTF, or XML. Office versions 97 andhigher are supported.

The text, HTML, and RTF processors require that the Office application be installedon the Conversion Agent computer. Therefore, these processors run only onMicrosoft Windows platforms.

The XML processors do not require the Office application. They run on bothWindows and Unix-type platforms.

For detailed information, see the Document Processors chapter in the ConversionAgent Studio User's Guide.

PDF and COBOL SupportConversion Agent contains built-in support for the Adobe Acrobat (PDF) formatand for COBOL data formats. You do not need to install any Acrobat or COBOLsoftware to process these file types.

For information about the PDF support, see Document Processors chapter in theConversion Agent Studio User's Guide. For the COBOL support, see the manualProcessing COBOL Data in Conversion Agent.

Conversion Agent Administrator's Guide 3. Installation

14

Installation

This chapter explains how to install Conversion Agent on your computer. It coversinstallation on both Windows and Unix-type platforms.

If You are Upgrading from a Previous Version

From Version 3.x or Earlier

If you are upgrading from Conversion Agent version 3.2 or earlier, you mustuninstall your existing version before installing the new version.

From Version 4.xIf you are upgrading from an earlier Conversion Agent 4 release, or if you areinstalling a Conversion Agent service pack, you do not need to uninstall beforeinstalling the new version.

Before starting the upgrade, you must shut down all applications that useConversion Agent. Otherwise, the setup cannot replace certain files, and theupgrade may fail.

Upgrading Multiple Computers

We recommend that you upgrade all Conversion Agent computers andcomponents in your organization at the same time. This avoids any possibleversion conflicts between projects that you develop on one computer and run onanother computer.

Upgrading ProjectsTo upgrade your existing Conversion Agent projects and run them in the newversion, see Chapter 10, Upgrading Conversion Agent Projects.

Installing Multiple Conversion Agent Versions

In Windows, it is not possible to install multiple versions or copies of ConversionAgent on the same computer.

On Unix-type systems, it is possible to install multiple versions or copies indifferent directories, provided that you start each copy with the appropriateenvironment variables (see Chapter 4, Environment Variables).

3


15

Running the Setup Wizard

To install the Conversion Agent software, you should run the setup wizard byperforming the following steps.

In some Conversion Agent versions, the sequence of the setup wizard pages may differslightly from the sequence described here.

1. Open the setup wizard.

On Windows: Log on as a user with administrative privileges for the localcomputer, and double-click the Setup.exe file.

On Unix in graphical mode: Enter the following command (the example is forAIX; substitute the name of your setup file).

./Setup_Aix.bin

On Unix in console mode: If you cannot view the graphical setup interface (forexample, if you are working from a remote location), add the -console switchto the command.

./Setup_Aix.bin -console

2. You are prompted to select the language of the setup wizard.

This option also sets the default language of the Conversion Agent userinterface and (on Windows) of the online documentation. Followinginstallation, you can change the user-interface language in the ConversionAgent Configuration Editor.

On Windows: If you plan to change the language in the Configuration Editor,you must select a non-English language for the setup. If you select English,some of the services required for other languages may not be installed.

3. Follow the on-screen instructions to start the setup and accept the ConversionAgent license.

4. On the next wizard page, if your organization has a site license for ConversionAgent, enter the license key. For more information, see Chapter 5, Registrationand Licensing.

5. On the Install Path page, select the directory path where the setup shouldinstall the Conversion Agent software.

On Windows: The default path is c:\Program Files\SAP\ConversionAgent.

On Unix: The default path is /opt/SAP/ConversionAgent.

Throughout this book, we refer to the directory path that you select as<INSTALL_DIR>.

6. You are prompted to select the Conversion Agent components to install.Depending on the components in your setup package, there may be optionsfor modules such as:


16

EngineInstalls Conversion Agent Engine.

Eclipse Development EnvironmentInstalls Conversion Agent Studio (on Windows only), which is hostedwithin the Eclipse environment.

Document ProcessorsInstalls the document processors package.

LibrariesInstalls the Conversion Agent project libraries (on Windows only).

For more information about the modules, see Conversion Agent Modules inChapter 1, Overview.

7. On the Java Path page, select the Java Runtime Environment that you will usewith Conversion Agent. The default is a JRE that the setup installs in theConversion Agent directory. Optionally, you can browse to another supportedJRE, which is already installed on your computer.

On Windows: The default JRE path is <INSTALL_DIR>\jre1.4.

On Unix: The default JRE path is <INSTALL_DIR>/jre1.4/jre.

Following installation, it is possible to change the path and use a different JRE.On Windows, you can edit the JRE path in the Configuration Editor (seeChapter 9, Configuration Editor). On Unix, you must edit the environment-variables file (see Unix Environment-Variable Reference in Chapter 4,Environment Variables).

8. On the next page, you are prompted for the Service Repository Path Selection.This is the storage location for data transformations that are deployed asConversion Agent services.

On both Windows and Unix: The default is <INSTALL_DIR>\ServiceDB.

To change the repository location following installation, see Chapter 9,Configuration Editor.

9. On the Log Path page, select the location where Conversion Agent Engineshould store its log files (also known as the reports path).

On Windows: The default is c:\Documents and Settings\<USER>\ApplicationData\SAP\ConversionAgent\4.0\CMReports, where <USER> is your user name.

On Unix: The default is <INSTALL_DIR>/CMReports.

To change the log path following installation, see Chapter 9, ConfigurationEditor.

10. On Windows: If you selected the option to install the Eclipse DevelopmentEnvironment, the wizard displays an Eclipse Configuration page. The pagelets you select the copy of Eclipse where you wish to run Conversion AgentStudio.

- The default is to install a new, standalone copy of Eclipse 2.1.3.


17

- Optionally, If Eclipse 2.1.2 or 2.1.3 is already installed on the computer, youcan choose to run Conversion Agent Studio in it. Enter the directory pathof the eclipse.exe file, for example, c:\eclipse212\eclipse.

Note: It is possible to install multiple copies of Eclipse on the same computer.Each copy has its own workspace and projects. If you choose the defaultoption, the setup installs a new copy of Eclipse, which is independent of anyexisting copies. The second option is convenient if you already use Eclipse forother purposes, and you wish to store Conversion Agent projects in yourexisting workspace.

11. On the Summary page, review the setup options that you have selected. ClickInstall to complete the installation.

12. If you are running an upgrade setup from a previous Conversion Agent 4release, the setup may prompt you to upgrade your existing ConversionAgent services. For more information, see Chapter 10, Upgrading ConversionAgent Projects.

13. Continue with the Required Post-Setup Steps and the Optional Post-Setup Steps,described below.

Required Post-Setup Steps

On Unix: When the setup is complete, you must configure your system to load theConversion Agent environment variables. For instructions, see Chapter 4,Environment Variables.

Optional Post-Setup Steps

You can configure Conversion Agent Engine to run either in-process or out-of-process. This is especially important if you have a 32-bit Conversion Agent version,and you plan to activate it from 64-bit applications. See Chapter 8, Running In-Process or Out-of-Process.

If you have existing projects from a previous Conversion Agent version, you mayneed to upgrade them to the new version. See Chapter 10, Upgrading ConversionAgent Projects.

If you plan to use the ODBC database-support features of Conversion Agent, youmay need to configure an ODBC driver. See Chapter 11, Using Conversion Agentwith ODBC.

Testing the Installation

We recommend that you test the installation and confirm that Conversion Agentoperates properly. For more information, see Chapter 6, Testing and Troubleshooting .


18

Uninstalling

To uninstall Conversion Agent:

1. If you are uninstalling prior to a version upgrade, we recommend that youback up the Conversion Agent repository (by default,<INSTALL_DIR>/ServiceDB). If necessary, you can restore the services after theupgrade.

2. Run the uninstall program.

On Windows: Open the Add or Remove Programs option of the WindowsControl Panel. Select the option to remove Conversion Agent.

On Unix in graphical mode: Run the following command (substitute your Unixflavor for AIX).

<INSTALL_DIR>/uninstall/_uninstMaster/uninstaller_AIX.bin

On Unix in console mode: Add the -console switch to the above command.

<INSTALL_DIR>/uninstall/_uninstMaster/uninstaller_AIX.bin -console

3. When the uninstallation is complete, you can delete <INSTALL_DIR> and anyfiles remaining in it.

4. On Unix: Remove the configuration that loads the Conversion Agentenvironment variables (see Chapter 4, Environment Variables). Then log out andlog in, to ensure that the configuration changes take effect.

Conversion Agent Administrator's Guide 4. Environment Variables

19

Environment Variables

The Conversion Agent setup assigns several environment variables, which point tothe Conversion Agent installation directory and to other locations that the systemneeds. On Unix-type platforms, you must configure the system to load theseenvironment variables. On Windows platforms, the loading is automatic.

On Unix, you must perform the step described in Loading the Environment Variableson Unix Platforms. Until you do this, you cannot run Conversion Agent. On Windows,this step is unnecessary.

Loading the Environment Variables on Unix Platforms

On Unix-type platforms, the Conversion Agent setup creates an environment-variables file. You must load the file before you can test or use Conversion Agent.You can do this in either of the following ways:

You can load the file manually, from the command line. You must execute thecommand each time you log in, before you use Conversion Agent.

You can insert the appropriate command in your profile or in a script file. Ifyou do this, you can load the environment variables automatically.

The following paragraphs provide instructions for these two approaches.

Loading from the Command Line

If you prefer not to load the environment variables automatically, you can loadthem manually from the command line. You must do this each time you log in,before you use Conversion Agent.

If you use the sh, ksh, or bash shell, the command is:

. /<INSTALL_DIR>/setEnv.sh

If you use the csh or tcsh shell, the command is:

source /<INSTALL_DIR>/setEnv.csh

For <INSTALL_DIR>, you should substitute your installation path.

4


20

Loading Automatically

To configure your system to load the environment-variables file automaticallywhen you log in:

If you use the sh, ksh, or bash shell, insert the following line in your .profilefile.

. /<INSTALL_DIR>/setEnv.sh

If you use the csh or tcsh shell, insert the following line in your .login file.

source /<INSTALL_DIR>/setEnv.csh

You should then log out and log in, so that your configuration changes will takeeffect.

Alternatively, you can execute the appropriate command line from a script file.

Unix Environment-Variable Reference

For reference purposes, we describe the environment variables, which ConversionAgent requires on Unix-type platforms.

Required Environment Variables

The following environment variables are required for proper Conversion Agentoperation.

PATHThe environment-variables file adds <INSTALL_DIR>/bin to the paths.

Note: In rare instances, the Conversion Agent Java document processors mayrequire that the JRE be added to the path.

On AIX: LIBPATHOn Solaris and Linux: LD_LIBRARY_PATHOn HP-UX: SHLIB_PATH and LD_LIBRARY_PATH

The environment-variables file adds the installation directory (<INSTALL_DIR>)to the library path.

It also adds the JVM directory of the JRE and its parent directory to the path,for example, <INSTALL_DIR>/jre1.4/lib/sparc/server and<INSTALL_DIR>/jre1.4/lib/sparc. You can edit this value to use anothercompatible JRE.

CLASSPATHThe environment-variables file adds <INSTALL_DIR>/api/lib/CM_JavaAPI.jarto the Java class path.

IFCONTENTMASTER_HOMEThe environment-variables file creates this variable, which points to theConversion Agent installation directory (<INSTALL_DIR>).


21

Optional Environment Variable

Optionally, you can define the following environment variable:

IFConfigLocation4The path of the Conversion Agent configuration file (see MultipleConfigurations in Chapter 9, Configuration Editor).

Example of Environment VariablesThe following is an example of the environment-variables file (setEnv.csh) on anAIX system.

The variable names and values may differ slightly on other Unix flavors.

## Conversion Agent Environment settingssetenv IFCMPath /opt/SAP/ConversionAgentsetenv CMJAVA_PATH /opt/SAP/ConversionAgent/jre1.4/jre/bin/classic:/opt/SAP/ConversionAgent/jre1.4/jre/bin

# Prepend Conversion Agent to the PATHif ( ! $?PATH ) then

setenv PATH ""endifsetenv PATH "${IFCMPath}/bin:${PATH}"

# Add CM & java path to LIBPATHif ( ! $?LIBPATH ) then

setenv LIBPATH ""endifsetenv LIBPATH "${IFCMPath}/bin:${CMJAVA_PATH}:${LIBPATH}"

# Update IFCONTENTMASTER_HOME.setenv IFCONTENTMASTER_HOME "${IFCMPath}"

# Prepend CM path CLASSPATHif ( ! $?CLASSPATH ) then

setenv CLASSPATH ""endifsetenv CLASSPATH "${IFCMPath}/api/lib/CM_JavaAPI.jar:.:${CLASSPATH}"


22

Windows Environment-Variable Reference

On Windows, the Conversion Agent setup creates or modifies the followingenvironment variables. This information is for reference only. You do not need toperform any special steps to configure or load the variables.

PathThe setup adds <INSTALL_DIR>\bin to the path.

Note: In rare instances, the Conversion Agent Java document processors mayrequire that the JRE be added to the path.

CLASSPATHThe setup adds <INSTALL_DIR>\api\lib\CM_JavaAPI.jar to the path.

IFCONTENTMASTER_HOMEThe setup creates this environment variable, which points to the ConversionAgent installation directory (<INSTALL_DIR>).

Optionally, you can define the following environment variable:

IFConfigLocation4The path of the Conversion Agent configuration file (see MultipleConfigurations in Chapter 9, Configuration Editor).

Conversion Agent Administrator's Guide 5. Registration and Licensing

23

Registration and Licensing

Conversion Agent requires a license file, License.cfg, in order to run. The fileshould be located in your main Conversion Agent installation directory.

The license file is supplied with your Conversion Agent version. The informationin this chapter is for reference only. You do not need to register and install thelicense.

In case of any question about the license terms or validity, or to purchaseadditional licenses, please contact SAP.

License Status

To determine the status of your Conversion Agent license, open a commandprompt and enter the command:

CM_console -v

The command displays information such as the location and validity of yourlicense file.

5

Conversion Agent Administrator's Guide 6. Testing and Troubleshooting

24

Testing and Troubleshooting

After you install Conversion Agent, we recommend that you perform a quick testto verify that it operates correctly.

Following the test procedure, we provide some troubleshooting hints that mayhelp you if the test fails or if you experience any other difficulty with theConversion Agent installation.

Conversion Agent Engine Test

The following test verifies that Conversion Agent Engine is installed and operatescorrectly.

1. Open a command prompt.

2. Enter the CM_console command, without any parameters.

3. CM_console should display a usage message such as the following:

Usage:CM_console Service name [Additional options]...

4. In the directory <INSTALL_DIR>\setupTests, there is a sample ConversionAgent project called testCME. Copy the entire testCME directory to theConversion Agent repository, which you defined during the setup (by default,<INSTALL_DIR>\ServiceDB). This makes testCME available as a ConversionAgent service.

5. Enter the following command, which executes testCME.

CM_console testCME

The service performs a simple data transformation on an HL7 sourcedocument. The following result should be displayed:

<Result>Test Succeeded</Result>

6


25

Document Processor Test

If you installed the document processors, you can test the installation by running aservice called testCMDP. The service converts an Excel spreadsheet file to XML. Ituses the ExcelToXml document processor to perform an initial conversion stage.

To run the test:

1. In the directory <INSTALL_DIR>\setupTests, there is a sample ConversionAgent project called testCMDP. Copy the entire testCMDP directory to theConversion Agent repository.

2. Run the command:

CM_console testCMDP

3. The command should display the following output:

<Report><Name>John Doe</Name><Age>29</Age><Sex>Male</Sex><Report><Q Year="2000" Q="1">5</Q><Q Year="2000" Q="2">6</Q><Q Year="2000" Q="3">7</Q><Q Year="2000" Q="4">3</Q><Q Year="2001" Q="1">5</Q><Q Year="2001" Q="2">8</Q><Q Year="2001" Q="3">3</Q><Q Year="2001" Q="4">3</Q><Q Year="2002" Q="1">3</Q><Q Year="2002" Q="2">4</Q><Q Year="2002" Q="3">2</Q><Q Year="2002" Q="4">8</Q></Report></Report>

Installation Troubleshooting

If you experience difficulty installing or running Conversion Agent, please checkthe following points.

Unix Environment Variables

On a Unix-type platform, if the Conversion Agent Engine Test or the DocumentProcessor Test fails, the system is probably not setting some or all of theenvironment variables that Conversion Agent requires. To solve the problem, trythe following steps.


26

1. Confirm that you have followed the instructions to load the environmentvariables (see Loading the Environment Variables on Unix Platforms in Chapter 4,Environment Variables).

2. Open the setEnv.sh or setEnv.csh file and verify its contents (see the UnixEnvironment-Variable Reference).

3. If you load the environment variables from your profile:

Log out and log in to the computer, and try the CM_console command again. Ifthe test still fails, your system is probably configured not to load the profileduring startup. Try the following steps to solve the problem.

If you use the sh or ksh shell within CDE (Common Desktop Environment),edit the file ~/.dtprofile and uncomment the following line:

DTSOURCEPROFILE=true

If you use the bash shell, edit your ~/.bashrc file and add the following line:

. ./.profile

Log out and log in, and try the tests again.

If the tests still do not succeed, please contact your system administrator or SAPsupport.

Log Files

Conversion Agent generates several log files, which are useful for troubleshootingpurposes.

Installation Logs

The setup creates a set of logs in the <INSTALL_DIR>\Inst_logs directory. You canexamine the logs for any error messages.

Conversion Agent Studio Log

By default, Conversion Agent Studio keeps a log of its operations.

To enable or disable the log, and to determine the log location, choose the Window> Preferences command on the Conversion Agent Studio menu. In the left pane,select Conversion Agent. In the right pane, set the logging options.

Conversion Agent Studio Event LogsWhen Conversion Agent Studio runs a data transformation, it saves an event logcalled Events.cme in the Results directory of the project. The log is displayed inthe Events view. For information, see the chapter on Running and Testing Projects inthe Conversion Agent Studio User's Guide.


27

Conversion Agent Engine Event Logs

If a failure occurs in a Conversion Agent service, Conversion Agent Engine createsan event log. You can view the log by dragging the *.cme file to the Events view ofConversion Agent Studio.

On SAP XI systems, you can use the remote support interface to view event logs in aweb browser over an HTTP connection. For information, see the manual Deployingand Using Conversion Agent.

For more information, see the chapter on Event Logs in the Conversion Agent EngineDeveloper's Guide.

Java Heap Size

If a Java component of Conversion Agent, such as a document processor that usesJava, fails to process very large documents, the problem may be an inadequate Javaheap size. You can control the heap size by this procedure:

1. Open the Conversion Agent Configuration Editor (see Chapter 9, ConfigurationEditor).

2. In the left pane, expand the tree to display:

CM Configuration/CM Engine/JVM init parameters

3. Right-click the JVM init parameters node and add an InitParam.

4. Assign a value of InitParam such as -Xmx512M, where 512 is the heap size inmegabytes.

You should define the JVM init parameters only if needed. Setting a large Javaheap size increases the Conversion Agent memory requirement.

You can pass additional parameters to the Java Virtual Machine by adding multipleInitParam lines. Enter each parameter on a separate line.

Preventing Core Dumps

When processing very large inputs, a Java out-of-memory condition may cause acore dump. This has been observed in IBM JRE versions running on AIX platforms.

In IBM JRE 1.4, you should start Java with the -Xdisablejavadump flag.

LDR_CNTRL Environment Variable on AIX

On some AIX 5.3 computers, the Conversion Agent setup may fail to run unlessyou configure the LDR_CNTRL environment variable. For information, see SpecificRequirements for AIX in Chapter 2, System Requirements.


28

LD_PRELOAD Environment Variable on HP-UX

On HP-UX systems, you may need to set the LD_PRELOAD environment variable torun certain types of Conversion Agent applications. Specifically, you need to setthe environment variable if:

The Conversion Agent service is configured with a Java document processor,such as:

- ExcelToDataXml- ExcelToTextML- ExcelToXml- PowerpointToTextML- WordToTextML- WordToXml- XmlToExcel

You activate the Conversion Agent service in the process of a C++ application(see Chapter 8, Running In-Process or Out-of-Process), such as:

- The CM_console command- An application that calls the Conversion Agent C++ API

Under these circumstances, you should set LD_PRELOAD to point to the libjvmshared object of the JRE.

Examples

On an HP-UX PA-RISC platform, the libjvm object is called libjvm.sl. You shouldenter a command such as:

setenv LD_PRELOAD "<INSTALL_DIR>/jre1.4/lib/PA_RISC2.0/server/libjvm.sl"

On an HP-UX ia64 platform, the object is called libjvm.so . The correspondingcommand is:

setenv LD_PRELOAD "<INSTALL_DIR>/jre1.4/lib/IA64N/server/libjvm.so"

The above examples are for 32-bit Conversion Agent versions, and point to 32-bitJREs. If you run a 64-bit version, LD_PRELOAD should point to a 64-bit JRE. The twoexamples become:

setenv LD_PRELOAD "<INSTALL_DIR>/jre1.4/lib/PA_RISC2.0W/server/libjvm.sl"

setenv LD_PRELOAD "<INSTALL_DIR>/jre1.4/lib/IA64W/server/libjvm.so"


29

Incompatibilities

The LD_PRELOAD setting is incompatible with applications that call the ConversionAgent Java API or that run tcsh scripts. Before you run such applications, youmust unset the environment variable:

unsetenv LD_PRELOAD

If you frequently run both C++ and Java applications in the same HP-UXenvironment, you can configure them to run in different shells. In the shell thatyou use for the C++ application, you can add the LD_PRELOAD setting to the profile.

Alternatively, you can create two shell scripts, which set or unset the LD_PRELOADvariable. C++ applications should run the script that sets LD_PRELOAD, before theyactivate Conversion Agent Engine. Java applications should run the script thatunsets LD_PRELOAD, before activating Conversion Agent Engine.

Memory Allocation on HP-UX

By default, HP-UX systems allocate virtual memory to a process in four 1-GBquadrants, as follows:

Q1: main executable code and data

Q2: main executable heap and stack

Q3: shared modules code and data

Q4: shared modules code and stack

When processing very large inputs, you may need to modify the allocation toprovide more memory for Conversion Agent Engine. One way to do this is byrunning the chatr utility. For more information, please refer to the HP-UXdocumentation or contact SAP support.

Emulators

You should install and run Conversion Agent on the native systems, which aredescribed in Chapter 2, System Requirements. Running on emulators is notsupported.

For example, do not run Conversion Agent for HP-UX PA-RISC on an HP-UX ia64machine with a PA-RISC emulator.

Asian Fonts

The Conversion Agent Studio views may fail to display Asian fonts correctly underWindows 2000. To correct the problem, open the Window > Preferences command,select the Workbench/Fonts node, and set the font for each view.

Conversion Agent Administrator's Guide 7. Running Data Transformations

30

Running Data Transformations

This chapter is a brief overview, intended for system administrators, of theprocedures that users can perform to run data transformations in ConversionAgent. This information can help you understand the users' needs.

Designing and Configuring Data Transformations

Conversion Agent users can design, configure, and test data transformations byusing Conversion Agent Studio on a Windows platform. Among the possibletransformation components are:

Parsers, which convert any data format to XML

Serializers, which convert XML to any format

Mappers, which convert XML to another XML vocabulary or schema

Transformers, which modify the data in any format

For instructions on using Conversion Agent Studio, see the following manuals:

Getting Started with Conversion Agent—provides basic instructions and tutorialexercises for using the entire Conversion Agent system

Conversion Agent Studio User's Guide—explains how the data transformationsoperate and how to configure them

Conversion Agent Studio in Eclipse—explains how to use the Conversion AgentStudio user interface, which is hosted in the Eclipse development environment

Deploying Conversion Agent Services

To run a data transformation in Conversion Agent Engine, a user must first deployit as a Conversion Agent service. The deployment procedure copies the ConversionAgent Studio project to the Conversion Agent repository, where it is available torun in Conversion Agent Engine. For details, see the chapter on DeployingConversion Agent Services in the Conversion Agent Studio User's Guide.

7


31

Repository Location

On both Windows and Unix, the default repository location is<INSTALL_DIR>\ServiceDB.

To deploy a project, a user must have write permission for the repository. You canchange the repository location by setting the Base Path parameter in theConfiguration Editor (see Chapter 9, Configuration Editor).

Deploying on the Conversion Agent Studio ComputerTo deploy a Conversion Agent service to the repository on a Windows computerwhere Conversion Agent Studio is installed:

1. Configure the data transformation in Conversion Agent Studio.

2. On the menu, choose Project > Deploy.

Deploying on Another Computer

To deploy a Conversion Agent service to the repository on another computer, suchas a Unix-type platform:

1. Deploy the service on the Conversion Agent Studio computer, as describedabove.

2. Copy the deployed project directory from the repository on the ConversionAgent Studio computer to the repository on the remote computer.

3. Conversion Agent Engine determines whether any services have been revisedby periodically examining (by default, every 30 seconds) the timestamp of afile called update.txt. This file exists in the repository root directory (bydefault, the ServiceDB directory). The content of the file can be empty.

If this is the first time that you have deployed a service to the remoterepository, update.txt may not exist. If so, copy it from the local repository.

If update.txt exists, you should update its timestamp as follows.

On Windows: Open update.txt in Notepad and save it.

On Unix: Open a command prompt, change to the repository directory, andenter the following command.

touch update.txt

Re-Deploying

If you later edit the data transformation in Conversion Agent Studio, you mustdeploy it again by repeating the above procedure.

Running Conversion Agent Services

Users can run Conversion Agent services by any of the following methods:


32

By using the Conversion Agent command-line interface (the CM_consolecommand; see the Conversion Agent Engine Developer's Guide)

By programming an application that calls one of the Conversion Agent APIs(see the Conversion Agent Engine Developer's Guide and the API references)

By using the HTTP protocol to access the Conversion Agent CGI interface (seethe Conversion Agent Engine Developer's Guide)

By using the Conversion Agent process module in SAP XI (see the manualDeploying and Using Conversion Agent)

Conversion Agent Administrator's Guide 8. Running In-Process or Out-of-Process

33

Running In-Process or Out-of-Process

You can configure Conversion Agent Engine to run either in the process of thecalling application or out-of-process.

Out-of-process invocation requires the use of Conversion Agent Server (seeConversion Agent Server in the Conversion Agent Engine Developer's Guide).

This option has no effect on Conversion Agent Studio or on the CM_consolecommand, which always run data transformations in-process.

Relative Advantages

Running out-of-process has the following advantages:

It allows 64-bit processes to activate 32-bit versions of Conversion AgentEngine.

An Engine failure is less likely to disrupt the calling application.

It can help prevent binary collisions with other modules that run in theprocess of the calling application.

Out-of-process invocation has the following disadvantages:

Running in-process may give faster performance than out-of-process.

Some of the APIs may be unavailable when running out-of-process. Out-of-process invocation is currently supported by the Java API and the ConversionAgent process module. Regarding other APIs or ways to activate ConversionAgent, please contact SAP support.

Determining whether to Run In-Process or Out-of-Process

Please consult the following table to determine whether you need to run in-processor out-of-process.

The first and second columns of the table list the available Conversion Agentversions. The third and fourth columns list the invocation methods, such as callingfrom a 32-bit Java process or a 64-bit Java process.

8


34

Platform Conversion Agent version

If you call Conversion Agent from a 32-bit process, you can choose

If you call Conversion Agent from a 64-bit process, you can choose

Windows 32-bit In-process or out-of-process

Out-of-process

Solaris 64-bit In-process or out-of-process

AIX 64-bit In-process or out-of-process

SUSE Linux 9 or Red Hat Linux EL3 on x86

32-bit In-process or out-of-process

SUSE Linux 9 or Red Hat Linux EL4 on x86-64

64-bit In-process or out-of-process

HP-UX 64-bit In-process or out-of-process

Determining Your Conversion Agent Version If you are not sure whether you have a 32-bit or 64-bit Conversion Agent version, open a command prompt and run the command:

CM_console -v

Among other information, the command displays a package identifier, which is a code that uniquely identifies your Conversion Agent version. The code contains the substring 32bit or 64bit.

Configuration

To select in-process or out-of-process invocation, follow this procedure:

1. Open the Conversion Agent Configuration Editor (see Chapter 9, Configuration Editor).

On Windows: On the Start menu, open SAP Conversion Agent > Configuration.

On Unix: Enter the following command:

<INSTALL_DIR>/CMConfig

2. In the left pane, expand the tree to display the following node:


35

CM Configuration/CM Engine

3. In the right pane, edit the following setting. If the setting is not displayed,right-click the CM Engine node and add it.

InvocationSelect the value InProc for in-process invocation.

Select Server for out-of-process invocation. This causes requests toConversion Agent Engine to be routed via Conversion Agent Server. Foreach client process (that is, for each process that submits requests), theServer starts an independent Conversion Agent Engine process.

4. Edit the settings under the following node:

CM Configuration/CM Engine/CM Server

These settings have an effect only if you have set Invocation = Server. If thesettings are not displayed, right-click the CM Server node and add them.

Server Path(Required on Unix) The path to the CM_Server.sh shared object. Set its valueto:

<INSTALL_DIR>/bin/cm_server.sh

You should also confirm that cm_server.sh has execute permission. You cando this by running the command:

chmod a+x <INSTALL_DIR>/bin/cm_server.sh

Note: The Server Path setting is unnecessary on Windows platforms. Youcan leave it blank.

Thread pool size(Optional) The maximum number of Conversion Agent Engine threads,which can run client requests concurrently, per process. If the number ofclient requests exceeds the number of available threads, the Server queuesthe requests until a thread is available. The default is 4.

Thread Stack Size(Optional) The stack size, in kilobytes, that the Server allocates to eachthread. The default is 1024.

Init Engine(Optional) If the value of this parameter is OnDemand, the Server starts theEngine when the client application first issues a request. If the value isOnStartup, the Server starts the Engine when the client application isloaded. The default is OnDemand.

Number of retries, Restart timeout(Optional) In the event that a client process receives no response from theServer, it attempts a Server restart. These parameters control the restartbehavior:


36

The Number of retries is the maximum number of permitted restarts, andthe Restart timeout is the time interval in seconds. If the number ofrequired restarts exceeds the specified value, within the time interval, theclient process ceases all further attempts.

The default values are Number of retries = 4 and Restart timeout = 900.This means that if the client process needs to restart the server more than 4times in 900 seconds, it ceases the attempts.

This behavior is regardless of the number of successful requests during thetimeout period. In the above example, if the client process successfullycommunicates with the server 100 times during the 900-second interval, butit fails 5 times, it ceases further attempts.

The behavior is per client process. If there are multiple client processes, theneach of them is permitted 4 restarts during the timeout interval.

The restarts refer only to the communication between the client process andthe Server. If Conversion Agent Engine returns an error response (forexample, due to invalid input data), the Server reports the error status to theclient, but the Server does not require a restart.

Conversion Agent Administrator's Guide 9. Configuration Editor

37

Configuration Editor

Conversion Agent has a Configuration Editor, which lets you edit the basicparameters of a Conversion Agent installation.

Usually, you need to use the Configuration Editor only in the followingcircumstances:

If you need to change one of the directory locations that you configuredduring the setup, such as the JRE location or the Conversion Agent repositorylocation.

If instructed in the Conversion Agent documentation or by SAP support.

Backing Up the Configuration File

The Configuration Editor saves the configuration in an XML file. By default, thefile is <INSTALL_DIR/CMConfig.xml> (for other possibilities, see MultipleConfigurations below).

Before you edit the configuration, we recommend that you save a backup copy ofCMConfig.xml. In the event of a problem, you can restore the backup.

The file <INSTALL_DIR>CMConfig.bak is a backup of the original<INSTALL_DIR/CMConfig.xml>, which the setup program created when youinstalled Conversion Agent. Restoring CMConfig.bak returns Conversion Agent toits original configuration.

Using the Configuration Editor

To open the Configuration Editor:

On Windows: On the Start menu, open SAP Conversion Agent > Configuration.

On Unix in graphical mode: Enter the following command:

<INSTALL_DIR>/CMConfig

Please note that the Configuration Editor is not supported in a Unix console mode.

9


38

Some of the Configuration Editor settings are available in all Conversion Agentinstallations. Some additional settings may vary depending on the ConversionAgent version and on the optional components that you have installed.

Assigning the SettingsThe editor has an Explorer type window. In the left pane, expand the tree andselect the desired setting. In the right pane, double-click to assign a setting value.

Some settings require that you type a value, whereas others offer a drop-down listor a browse option. If a setting has a gray background, it has a read-only value thatcannot be edited.

Some settings accept a table of values. For such settings, you can right-click to addor remove table rows.

Missing Settings

If a setting is not displayed, Conversion Agent uses its default value. To displaythe setting and edit its value, right-click its parent node and choose the Addoption.

Saving the Configuration File

Click the Save icon to save the edited settings. If you forget to save, theConfiguration Editor displays a reminder when you exit.

Configuration Settings

The following are the most common configuration settings that you may need toedit. You can assign these settings when you run the Conversion Agent setup. Ifnecessary, you can change the settings afterwards in the Configuration Editor.

There are many additional settings, which are described in the relevant locationsthroughout the Conversion Agent documentation.

Directory LocationsWhen you ran the Conversion Agent setup (see Running the Setup Wizard inChapter 3, Installation), you were prompted for the directory locations of theConversion Agent repository, log files, and JRE. If necessary, you can alter thelocations by editing the following parameters:

CM Configuration/Directory services/File system/Base PathThe Conversion Agent repository location, where you store Conversion Agentservices that you deploy.

CM Configuration/CM Engine/JVM LocationOn Windows: The JRE location, for example:

<INSTALL_DIR>/jre1.4/bin/client


39

If you edit the path, do not uninstall the previous JRE version until after yousave the new setting and exit the Configuration Editor. This is importantbecause the Configuration Editor itself requires a JRE.

On Unix: This parameter is not available in the Configuration Editor on Unix-type platforms. To change the JRE on Unix, see Unix Environment-VariableReference in Chapter 4, Environment Variables.

CM Configuration/General/Reports directoryThe log path (also called the reports path) where Conversion Agent savesevent logs and certain other types of reports.

Conversion Agent ServerYou can configure Conversion Agent Engine to run either in-process or out-of-process. The latter option uses the Conversion Agent Server. For information, seeChapter 8, Running In-Process or Out-of-Process.

Copying the Configuration File

You can copy a configuration file between identical computers, running the sameoperating system and the same Conversion Agent version. This is a convenientway, for example, to ensure that a set of identical servers all use the sameConversion Agent configuration.

We do not recommend copying between non-identical systems, as theconfigurations may be incompatible. For example, the configuration file on aWindows system contains the JVM Location parameter. On a Unix-type system,this parameter must not exist; if it does, Conversion Agent does not run correctly.

Multiple Configurations

It is possible to create multiple Conversion Agent configurations. At runtime, youcan select which configuration Conversion Agent Engine should use.

You might do this, for example, if you wish to use different Conversion Agentrepositories for different types of services. You can create configurations that havedifferent values of the repository location setting.

Creating Multiple ConfigurationsTo create multiple configurations, you can edit and copy the default configurationfile.

1. Make a backup copy of the default configuration file,<INSTALL_DIR/CMConfig.xml>. At the end of the procedure, you will restore thebackup.

2. Use the Configuration Editor to edit the original copy of CMConfig.xml . Saveyour editing.


40

3. Copy the edited CMConfig.xml to another location or another filename.

4. Repeat steps 2 and 3, creating additional versions of the configuration file. Inthis way, you can define as many configurations as you need.

5. Restore the backup that you created in step 1. This ensures that the defaultconfiguration remains as before.

Selecting the Configuration at RuntimeYou can set the configuration file that Conversion Agent Engine should use in anyof the following ways:

1. Define an environment variable called IFConfigLocation4. The value of thevariable must be the path of a valid configuration file, for example:

c:\MyIFConfigLocation4\CMConfig1.xml

2. On Unix only: Store the configuration file under the name CMConfig.xml, in theuser's home directory.

3. Use the default configuration file, <INSTALL_DIR>/CMConfig.xml.

When Conversion Agent Engine starts, it searches these locations in sequence. Ituses the first configuration file that it finds.

Example 1

Suppose you want to run two applications, which run Conversion Agent Enginewith different configuration files. Each application should set the value ofIFConfigLocation4 before starts Conversion Agent Engine.

Example 2Two users want to run Conversion Agent Engine with different configurations, onthe same Unix-type platform. Store their respective configuration files in theirhome directories. Both files must have the name CMConfig.xml.

Alternatively, store a CMConfig.xml file in the home directory of one of the users.The other user uses the default configuration file, <INSTALL_DIR>/CMConfig.xml.

Multiple JREs

On Windows platforms, the JVM Location parameter of the configuration filedefines the JRE that Conversion Agent should use. By using multiple configurationfiles, you can switch JREs.

On Unix-type systems, the configuration file does not contain a JVM Locationparameter. To switch JREs, you must load a different environment-variable file.For information, see Chapter 4, Environment Variables.

Running Multiple Configurations Concurrently

Conversion Agent Engine loads the configuration file and the environmentvariables when it starts. After it starts, changing the configuration file or theenvironment variables has no effect.


41

This means that two applications can use different configurations concurrently.Each application uses the configuration that was in affect when its instance ofConversion Agent Engine started.

Conversion Agent Administrator's Guide 10. Upgrading Conversion Agent Projects

42

Upgrading Conversion Agent Projects

If you are upgrading from a previous Conversion Agent release, you may need toupgrade your existing projects and your deployed Conversion Agent services tothe current release.

The upgrade of projects from Conversion Agent version 3.1 or higher is automatic.You can upgrade an individual project by opening or importing it in ConversionAgent Studio, or you can run a syntax conversion tool, which can upgrade all yourprojects or services together.

If you run an upgrade setup from a previous Conversion Agent 4 release, the setup promptsyou to upgrade your existing services. In other cases, you should perform the upgradeyourself, after you complete the setup.

When Is Upgrading Necessary?

Upgrading is necessary when the Conversion Agent Engine syntax version haschanged.

To determine the syntax version, open a command prompt and run the followingcommand:

CM_console -v

Terminology

In Conversion Agent 3.x and 4, the terms project, workspace, etc., are used inslightly different ways. To prevent confusion, we use the Conversion Agent 4terminology throughout the upgrade instructions, unless otherwise stated.

The following table presents the corresponding terms.

Conversion Agent 4 Conversion Agent 3.x Description

project workspace A directory containing a data-transformationconfiguration (a single CMW file, one or moreTGP script files, etc.)

10


43

Conversion Agent 4 Conversion Agent 3.x Description

workspace (no correspondingterm)

The default parent directory, where ConversionAgent Studio 4 stores projects

service service A project that has been made available to run inConversion Agent Engine

deploy publish Make a project available as a service

repository services databaselocation

The parent directory where Conversion Agentservices are stored

Upgrading an Individual Project

On a Windows computer, you can upgrade an individual project by opening orimporting it in Conversion Agent Studio.

Perform the import by running the File > Import command. In the Import window,select the option to import an Existing Conversion Agent Project into Workspace.

Conversion Agent Studio prompts you to upgrade the project if necessary. Theupgrade is fully automatic.

Following the upgrade, you should test the project and confirm that it runscorrectly.

Upgrading a Service

You can upgrade the development copy of a project and re-deploy it as aConversion Agent service.

To do this, open or import the development copy in Conversion Agent Studio. Testthe project, and re-deploy it as a service.

Syntax Conversion Tool

You can use the Conversion Agent syntax conversion tool to upgrade multipleprojects and services quickly, in an automated operation. You can also use it toupgrade global TGP script files, which are stored in the Conversion AgentautoInclude\user directory. The following paragraphs explain the procedure.

The tool is fail-safe. It creates an automatic backup of your existing projects andfiles, prior to the upgrade. It creates a log file and reports any upgrade errors that itdetects. In case of an error, you can restore the backup, correct the problem, andrun the tool again.


44

Version Support on Windows

On Windows, the syntax conversion tool can upgrade projects or services fromConversion Agent 3.1 and higher.

Version Support on UnixOn Unix-type platforms, the tool can upgrade services from earlier ConversionAgent 4 releases.

If you have Conversion Agent 3.x services, you should use the followingprocedure:

1. Run the tool on a copy of the project or service directories on a Windowscomputer.

2. Re-deploy the services to the Unix computer.

Before Running the Tool: Organize Your Projects

The tool operates on projects or services that are stored in a single parent directory.It can operate on:

A Conversion Agent Studio version 4 workspace

A Conversion Agent repository

Any other directory that contains Conversion Agent Studio projects or services

Within the parent directory, the projects must be at the top level of nesting, forexample:

Parent DirectoryProject1Project2Project3...

If your projects are not currently stored in a single parent directory, you can re-organize them before running the tool. Alternatively, you can run the toolseparately, on the individual parent directories.

The tool also operates on:

The Conversion Agent autoInclude\user directory, which contains globalTGP script files

Running the Syntax Conversion Tool

To run the syntax conversion tool:

1. The tool is a window with several tabs, where you can configure the upgrade.To open the tool:

On Windows: In the Conversion Agent folder on the Start menu, choose SyntaxConversion Tool.


45

On Unix: Run the following command:

<INSTALL_DIR>/bin/CM_DBConverter.sh

2. At the bottom of the window, specify whether you are upgrading fromversion 3.x or 4.x.

On Unix: Only 4.x is supported.

3. On the Services tab, set the following options:

Source LocationThe parent directory containing the old projects, or the repositorycontaining the old services.

Target LocationThe parent directory where the tool should store the new projects, or therepository for the new services. If the target is the same as the source, theoriginal files are overwritten.

Note: If you are upgrading services, use the Configuration Editor to changethe repository location to the specified target (see Chapter 9, ConfigurationEditor). If you are upgrading development projects, use the File > Importcommand to open the projects for the first time in Conversion Agent Studio.

4. If you have any TGP files in the autoInclude\user directory, set the followingoptions on the AutoInclude tab:

Source LocationThe old autoInclude\user directory.

Target LocationThe new autoInclude\user directory.

5. Set the following options on the Result Files tab:

Backup LocationA location where the tool should back up your existing projects, prior toupgrade.

Error LocationA location where the tool should store any projects that it cannot upgradedue to an error.

Log LocationA location for the upgrade log.

6. Click the Start button. The tool reports its progress and results.

7. You can repeat steps 3, 5, and 6 on any additional parent directories thatcontain projects or services. For example, you may need to upgrade both aConversion Agent Studio workspace (where you store development projects)and a repository (where you store deployed services).

The AutoInclude options should be blank on the repeat runs. The AutoIncludefiles were already upgraded on the first run and do not need to be upgradedagain.


46

8. If the tool reports any errors, review the log to determine their cause, correctthem, and run the tool again.

9. Test the projects and services to confirm that they work correctly and that theirbehavior has not changed. For a discussion of the issues that may arise, seeUpgrade Issues below.

Running from the Command Line

Optionally, you can run the syntax conversion tool from the command line,without displaying the graphical user interface. To do this:

1. Open a command prompt, and change to the Conversion Agent bin directory.

2. Run the following command:

On Windows: CM_DBConverter.bat <switches>

On Unix: CM_DBConverter.sh –console <switches>

The <switches> are listed in the following table.

Switch Description

-v (Required) Version from which you are upgrading (3 or 4). On Unix, only 4 issupported.

-s (Required) Path of the source directory, containing projects or services.

-d (Optional) Path of the target directory. If you omit this switch, the tooloverwrites the existing directory.

-si (Required to upgrade global TGP files) Path of the sourceautoInclude\user directory.

-di (Optional) Path of the target autoInclude\user directory. If you omit thisswitch, the tool overwrites the existing directory.

-l (Optional) Path of the upgrade log file. The default is<INSTALL_DIR>\SyntaxConversionLog.txt.

-b (Optional) Path of the backup directory, where the tool backs up the originalprojects or services prior to the upgrade. The default is the value of the -sswitch concatenated with the suffix _OLD_Backup.

-e (Optional) Path of the error directory, where the tool stores any projects orservices that it cannot upgrade due to an error. The default is the value of the-s switch concatenated with the suffix _OLD_Failure.

Following each switch, leave a space and type the value. If a path containsspaces, you must enclose it in quotation marks. For example, the Windowscommand

CM_DBConverter.bat -v 4 -s "c:\Program Files\SAP\ConversionAgent\ServiceDB"


47

upgrades version 4 services in the default repository location.

3. The tool notifies you when the upgrade is complete. If there were errors, itprompts you to examine the log file.

4. If you are upgrading services, use the Configuration Editor to change therepository location to the target that you specified (see Chapter 9, ConfigurationEditor).

Upgrade Issues

The automatic upgrade tools successfully upgrade nearly all the Conversion Agentfeatures that existed in previous Conversion Agent versions. Nonetheless, it isimportant that you test the data transformation following the upgrade. If you findthat an upgraded project does not operate correctly, you can edit its configurationin Conversion Agent Studio.

The following paragraphs discuss some upgrade issues that you may encounter.

New and Modified Components

In version 4, some of the Conversion Agent components that you can use in datatransformations have been revised, renamed, or replaced by new components.When you upgrade a project, Conversion Agent inserts the new componentsautomatically.

For a list of some components that have been modified, see the document What'sNew in Conversion Agent 4. In most cases, the modifications do not change thebehavior of upgraded projects.

You may find that an upgraded project containing the Locator component behavesslightly differently from the original version 3.2 project, where the Locatorcomponent did not exist, and the analogous functionality was implemented in adifferent way.

In projects upgraded from version 4.0.4 and earlier, the behavior of theEnsureCondition and CalculateValue actions may change slightly, due to theintroduction of a new JavaScript processor. For details of the supported JavaScriptsyntax, see the EnsureCondition action in the Conversion Agent Studio User's Guide.

Modified Namespace for Variables

Starting in version 4.0.6, the namespace for variables has been changed towww.Local-Project.com/Variables. If you upgrade a project from version 4.0.5 orearlier, the Schema view and the project properties display both the old namespace(which is empty) and the new namespace (which contains your variables). This hasno effect on the operation of your project.


48

Unsupported File and Directory Names

In Conversion Agent 4, the names of project files and directories can containEnglish letters (A-Z, a-z), numerals (0-9), spaces, and the following symbols:

# % & + , - = @ [ ] _ { }

If a version 3.x project uses names that don't conform to this convention, theproject may fail to upgrade. If this occurs, change the names in version 3.x beforerunning the tool.

XSD Schemas

In Conversion Agent 3.1, the XML schema was defined in the TGP files of theproject. Starting in Conversion Agent 3.2, the XML schema is an XSD file.

When you upgrade a version 3.1 project to version 4, Conversion Agent Studiocreates an XSD schema automatically. You should review the schema and confirmthat it meets your needs. You can edit the schema or create your own schema, asrequired.

For information, see the Data Holders chapter of the Conversion Agent Studio User'sGuide.

Additional Upgrade Issues

If you have any additional questions about upgrading Conversion Agent projects,please contact SAP support.

Conversion Agent Administrator's Guide 11. Using Conversion Agent with ODBC

49

Using Conversion Agent with ODBC

Conversion Agent offers ODBC connectivity features, which allow it to interactwith database systems. For example, see the ODBCLookup transformer and theODBCAction action in the Conversion Agent Studio User's Guide.

On Windows platforms, Conversion Agent uses the built-in Microsoft ODBCmanager. On Unix-type platforms, you must configure an ODBC manager beforeyou can use the ODBC features. This chapter explains the procedure.

On both Windows and Unix, you may need to install an ODBC driver. You shoulddefine one or more DSNs, which Conversion Agent uses to connect to thedatabase.

Installing and Configuring an ODBC Manager on Unix

On Unix-type platforms, you must install an ODBC manager that supports theODBC 3.0 API.

You can use an open-source ODBC manager, or one that you obtain from yourUnix or database vendor. For detailed advice on this subject, please contact SAPsupport.

You should add the directory location of the ODBC manager to your LIBPATH orLD_LIBRARY_PATH environment variable.

In Conversion Agent, you should configure the ODBC manager as follows:

1. Open the Conversion Agent Configuration Editor (see Chapter 9, ConfigurationEditor).

2. In the left pane, select the CM Engine node.

3. In the right-pane, right-click and choose the following command:

Add > ODBC manager shared library path

This adds a new parameter called ODBC manager shared library path to thedisplay.

4. Set the value of the parameter to the location of the ODBC manager sharedobject, for example:

/usr/local/odbc/libODBCMgr.so

11

Conversion Agent Administrator's Guide 11. Using Conversion Agent with ODBC

50

Installing an ODBC Driver

An ODBC driver for your database system must be installed on the computer. Thedriver may be supplied with the database system, or you can obtain it from yourplatform or database vendor.

Troubleshooting

If an incorrect ODBC manager version is installed, Conversion Agent may displaythe following error when it tries to run a service that uses ODBC:

Function not found in ODBC API

If an ODBC driver is not installed, Conversion Agent may display the followingerror:

Failed to load ODBC API

Defining DSNs

You should define one or more DSNs, which Conversion Agent can use to connectto the required databases.

On Windows: You can use the Control Panel > Administrative Tools > Data Sourcesoption to define and test DSNs.

On Unix: Use the utilities provided with your ODBC manager to define and testDSNs.

Configuring Conversion Agent to Use ODBC

To connect to a database, configure a Conversion Agent data transformation with acomponent such as ODBCLookup or ODBCAction. In the db_connection property ofthe component, specify the DSN that you defined above.

Conversion Agent Administrator's Guide 12. Administration and Deployment Policies

51

Administration and Deployment Policies

If you are administering Conversion Agent in a large organization, you need toestablish policies and methods for:

Deploying the Conversion Agent software throughout the organization

Security and user permissions

Deploying Conversion Agent services and configurations in multiple-serverenvironments

Backup requirements

Failure handling

This chapter discusses the key issues and recommends some approaches forimplementing the policies.

Security

Below, we list the typical permissions that are required by users who installConversion Agent, who use Conversion Agent Studio, and who run ConversionAgent Engine. Of course, there may be exceptions to the list, and additionalpermissions may be required, depending on the Conversion Agent applicationsthat you organization runs.

Conversion Agent Studio Permissions

Users who configure data transformations in Conversion Agent Studio typicallymust have the following permissions:

Read and write permission for their Eclipse workspace location (by default, MyDocuments\SAP\ConversionAgent\4.0\workspace).

Read and execute permission for the Conversion Agent installation directory<INSTALL_DIR> and for all its subdirectories.

Read and write permission for the Conversion Agent repository, where theywill deploy Conversion Agent services (by default, <INSTALL_DIR>\ServiceDB).

Read and write permission for the log location (by default, c:\Documents andSettings\<USER>\Application Data\SAP\ConversionAgent\4.0\CMReports).

12


52

Conversion Agent Engine Runtime Permissions

The user accounts under which applications run Conversion Agent Engine musthave the following permissions:

Read and execute permission for the Conversion Agent installation directory<INSTALL_DIR> and for its subdirectories.

Read permission for the Conversion Agent repository.

Read and write permission for the Conversion Agent log path, or for any otherlocation where you configure Conversion Agent applications to store errorlogs.

Standard Windows User Categories

For convenience, we list below the capabilities of two standard Windows usertypes: administrators and limited users. You can choose these user types when youregister users in the Windows Control Panel.

AdministratorsWindows users who have administrative privileges can perform all ConversionAgent operations.

Limited Users

Typically, limited users do not have write permission for the Conversion Agentprogram directory. Therefore, they are subject to the following restrictions:

They cannot install or uninstall the Conversion Agent software.

They cannot deploy services to the default Conversion Agent repository. Youcan relax this restriction by moving the Conversion Agent repository toanother directory, where the users have write permission (see Chapter 9,Configuration Editor).

They cannot add custom components such as document processors ortransformers.

They can view the settings in the Conversion Agent Configuration Editor, butthey cannot change the setting values.

Multiple-Server Environments

For high performance, you can install Conversion Agent on multiple Windows orUnix servers. The following discussion assumes that you use a load balancingmodule to connect to multiple, identically configured servers.


53

Copying the Conversion Agent Configuration File

You can copy the configuration file (by default, <INSTALL_DIR>\CMConfig.xml) fromone server to other, identical servers. This ensures that all the servers have thesame Conversion Agent repository path, reports path, operation parameters, etc.

For more information, see Copying the Configuration File in Chapter 9, ConfigurationEditor.

Deploying ServicesThe servers should share the same Conversion Agent services. There are two waysto implement this:

Shared file systemYou can locate a single copy of the Conversion Agent repository on a shareddisk. You can configure all servers to access the shared repository.

Replicated file systemEach server can have its own, local Conversion Agent repository. You can usean automatic file deployment tool to mirror the Conversion Agent repositoryfrom a source location to the individual servers.

When you do this, you must replicate or touch the file update.txt, whichexists in the repository directory. The timestamp of this file notifiesConversion Agent Engine when the last service update was performed.

For more information, see Deploying Conversion Agent Services in Chapter 7,Running Data Transformations.

Running on a Cluster Server

If you install Conversion Agent on a cluster server, you must either replicate theConversion Agent repository among the cluster nodes, or you must locate therepository on a shared disk.

Installing on Microsoft Cluster Server

The following procedure illustrates how to install Conversion Agent on MicrosoftCluster Server on Windows XP. For Windows 2000, the procedure is similar withminor variations.

1. Run the Conversion Agent setup on the active node.

2. When you are prompted for the repository location, assign a path on thequorum disk.

3. Make the other node active, and repeat steps 1-2.

Be sure to assign an identical path to the installation folder and to therepository location on both nodes.


54

4. On each node, open the Conversion Agent Configuration Editor and edit theCMConfig/General/Reports Directory setting (the location where ConversionAgent Engine stores log files). The settings on both nodes must point to thesame folder on the quorum disk.

Sizing Guidelines for SAP XI

The following table provides some rough sizing guidelines for using theConversion Agent process module in SAP XI. The guidelines were developed byusing the SAP Standard Application Benchmarks. The results are expressed as theadditional SAP Application Performance Standard units (SAPS) required forrunning Conversion Agent transformations in SAP XI.

The table presents results for four typical data transformations:

Excel: Demonstrates the required resources for parsing unstructured MicrosoftOffice documents to XML.

HL7: Demonstrates the parsing of semi-structured formats and flat files toXML.

HL7 Serializer: Demonstrates the serialization of XML data to semi-structuredformats and flat files.

PDF: Demonstrates parsing unstructured PDF documents to XML.

Requiredmessagesper hour

Required SAPSfor processing50 KB messages

Required SAPS forprocessing 100 KBmessages

Required SAPS forprocessing 1000 KBmessages

3600 142 339 3876Excel

36000 577 2523 38760

3600 257 405 3073HL7

36000 2566 4048 30729

3600 17 26 189HL7Serializer 36000 174 264 1889

3600 116 279 3212PDF

36000 1158 2788 32124

Backup Requirements

Conversion Agent Engine EnvironmentYou should back up the following locations regularly:


55

The Conversion Agent configuration file (by default,<INSTALL_DIR>\CMConfig.xml; see Chapter 9, Configuration Editor).

The Conversion Agent repository. By default, this is<INSTALL_DIR>\ServiceDB. You should confirm the location by checking thevalue of the following parameter in the Conversion Agent ConfigurationEditor:

CM Configuration/Directory services/File system/Base Path

The <INSTALL_DIR>\autoInclude\user directory, which stores custom globalcomponents.

If you use identical configurations on multiple servers, you need to back up only asingle copy of these items.

In the event of a server failure, in which you need to re-install Conversion Agent,you should install Conversion Agent in the same location as on the failed server,replace the configuration file with the backup, and restore the repository. Thesesteps re-establish the Conversion Agent environment.

Conversion Agent Studio EnvironmentYou should back up the Conversion Agent Studio workspaces of the developers inyour organization. By default, the workspace location of each user is:

My Documents\SAP\ConversionAgent\4.0\workspace

You should also back up the locations that are listed above for the ConversionAgent Engine environment.

Failure Handling

If a Conversion Agent service fails to execute successfully, it returns a failure statusto the calling application. It is the responsibility of the calling application to handlethe error.

For example, the application can transmit failed input data to a failure queue. Theapplication can package related inputs in a transaction to ensure that importantdata is not lost.

If you use the Conversion Agent process module for SAP XI, the XI adapterframework provides robust failure-handling and transaction services.

In the event of failure, Conversion Agent Engine generates an event log. Forinformation about viewing and interpreting the log, see Event Logs in theConversion Agent Engine Developer's Guide. Also see the chapter about Running andTesting Projects in the Conversion Agent Studio User's Guide.

Conversion Agent Administrator's Guide Index

56

Index

6

64-bitplatforms, 33

64-bit processesactivating Conversion Agent in, 33

A

AIXConversion Agent for, 5

autoIncludeupgrading, 43

B

backup requirementsConversion Agent services and data, 54

C

CLASSPATHenvironment variable, 20, 22

CMReportssetting log location, 39

COBOLsystem requirements, 13

Configuration EditorConversion Agent, 37using, 37

configuration filebacking up, 37

configuration filesmultiple, 39

Conversion Agent Engine, 3Conversion Agent for HP-UX, 5Conversion Agent for IBM AIX, 5Conversion Agent for Linux, 5Conversion Agent for Sun Solaris, 5Conversion Agent repository

default location, 16setting location, 38

Conversion Agent Serverconfiguring, 33

Conversion Agent servicesupgrading, 43

Conversion Agent Studio, 3core dump

preventing, 27

D

database connectivityODBC, 49

document processors, 3DSNs

defining, 50

E

Eclipseinstalling, 3

emulatorsnot supported, 29

environment variablesloading on Unix, 17troubleshooting Unix, 25Unix, 20

environment-variables fileloading on Unix, 19using multiple, 40

event logssetting location, 39

Excelsystem requirements, 13

F

failure handlingadministrative approaches, 55

filenameseffect on upgrade, 48

fontsdisplaying Asian, 29


57

H

heap sizeJava, 27

HP-UXConversion Agent for, 5

I

IBM AIXConversion Agent for, 5

IFConfigLocation4environment variable, 21, 22

IFCONTENTMASTER_HOMEenvironment variable, 20, 22

in-process invocation, 33install path

default, 15INSTALL_DIR

Conversion Agent installation directory, 15installation

Conversion Agent, 14invocation

in- or out-of-process, 33

J

Javaheap size, 27JRE system requirement, 6JVM initialization parameters, 27preventing core dump, 27

JREJVM initialization parameters, 27

JRE pathchanging on Unix, 20changing on Windows, 38default, 16

JVMinitialization parameters, 27

L

LD_LIBRARY_PATHenvironment variable, 20

LDR_CNTRLAIX environment variable, 9

LIBPATHenvironment variable, 20

libraries, 3license

confirming validity, 23licensing

Conversion Agent software, 23limited users

restrictions, 52

LinuxConversion Agent for, 5

load balancingmultiple Conversion Agent servers, 52

log fileslocation of, 26

log pathdefault, 16setting location, 39

M

Microsoft Officesystem requirements, 13

N

namespacevariables, 47

O

ODBCconfiguring, 49installing driver, 50installing manager on Unix, 49using, 50

operating systemsConversion Agent supported on, 5

out-of-process invocation, 33

P

Pathenvironment variable, 22

PATHenvironment variable, 20

PDFsystem requirements, 13

permissionsrequired for Conversion Agent users, 51

policiesadministration, 51

PowerPointsystem requirements, 13

projectdefinition, 4

projectsupgrading, 43upgrading from previous version, 42

R

remote support interface, 27reports path

default, 16setting location, 39


58

repository pathdefault, 16setting location, 38

roll-outConversion Agent deployment, 51

S

schemasupgrading, 48

Serverconfiguring Conversion Agent, 33

serversmultiple Conversion Agent, 52

servicesdeploying, 30upgrading, 43

setup wizardConversion Agent, 15

SHLIB_PATHenvironment variable, 20

sizing guidelinesmultiple servers, 54

SolarisConversion Agent for, 5

Sun SolarisConversion Agent for, 5

syntax conversion tool, 43syntax version

Conversion Agent Engine, 42system requirements

AIX, 8Conversion Agent, 5for all operating systems, 6HP-UX, 12JRE, 6

Linux, 10Solaris, 7Windows, 6

T

temp directoryfree space requirement, 10

testingConversion Agent Engine, 24

troubleshootingConversion Agent installation, 25Unix environment variables, 25

U

uninstallingConversion Agent, 18

unsupported featureson Unix systems, 5

upgradingmodified components, 47multiple computers, 14projects, 42services and projects, 43

user permissionsrequired for Conversion Agent, 51

usersWindows user types, 52

V

variablesnamespace, 47

versionConversion Agent Engine syntax, 42

W

Wordsystem requirements, 13