sap conversion agent by itemfield · the version includes conversion agent engine, which is the...

SAP Conversion Agent byItemfield

Conversion Agent for Unix

Version 4

Legal Notice


Copyright © 2003-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: June 2006


Contents

Version Information..............................................................................1Supported Unix Flavors .........................................................................................................................1

Installation Procedure..........................................................................1System Requirements ........................................................................................................................... 1

General Requirements for All Unix Flavors ..................................................................................... 2Specific Requirements for Solaris ................................................................................................... 2Specific Requirements for AIX ........................................................................................................ 3Specific Requirements for Linux...................................................................................................... 5Specific Requirements for HP-UX ................................................................................................... 7

If You are Upgrading from a Previous Version ......................................................................................8Installing ................................................................................................................................................ 9

Running the Setup Program............................................................................................................ 9Loading the Conversion Agent Environment Variables .................................................................10Configuring In-Process or Out-of-Process Invocation................................................................... 11Registering and Installing a License..............................................................................................14Testing the Installation ..................................................................................................................14Troubleshooting.............................................................................................................................16

Uninstalling .......................................................................................................................................... 18

Environment Variables.......................................................................19Location of Environment-Variable Definitions......................................................................................19Required Environment Variables .........................................................................................................19Example of Environment Variables .....................................................................................................20

Configuration Editor...........................................................................21Configuration Parameters....................................................................................................................21

Upgrading Conversion Agent Services ............................................22Upgrading from Version 3.x ................................................................................................................. 22Upgrading from an Earlier Version 4 Release ..................................................................................... 22

Running the Syntax Conversion Tool in Graphical Mode..............................................................23Running the Syntax Conversion Tool in Console Mode................................................................ 24


Running Conversion Agent on Unix .................................................25

Using Conversion Agent with ODBC ................................................25Installing and Configuring an ODBC Manager ....................................................................................26Installing an ODBC Driver ...................................................................................................................26Troubleshooting................................................................................................................................... 26Defining DSNs .....................................................................................................................................27Testing a DSN in Conversion Agent....................................................................................................27Configuring Conversion Agent to Use ODBC......................................................................................27

Unsupported Features .......................................................................28


1

Version Information

This document describes Conversion Agent version 4, running on Unix-typeoperating systems.

The version includes Conversion Agent Engine, which is the runtime engine thatexecutes Conversion Agent services in production mode, and all the componentsneeded to run the services in Conversion Agent Engine. The version does notinclude the Conversion Agent Studio development environment, which you caninstall only on Microsoft Windows.

Supported Unix Flavors

Conversion Agent for Unix supports the following Unix flavors:

Sun Solaris

IBM AIX

LINUX

Hewlett-Packard HP-UX

For the specific version requirements of each Unix flavor, see the SystemRequirements below.

Installation Procedure

To install Conversion Agent on Unix, follow the instructions in this section. Exceptas noted, the instructions are identical on all Unix flavors.

System Requirements

To install and run Conversion Agent, your computer should conform to theminimum requirements listed below.


2

In the following sections, please read both the General Requirements for All UnixFlavors and the specific requirements for your Unix flavor.

General Requirements for All Unix Flavors

Hardware

The computer should have at least 256 MB of RAM; 512 MB or higher isrecommended. For a system running production Conversion Agent services, werecommend a CPU speed of at least 1 GHz.

Java Runtime Environment

A 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 Unix flavor.

If necessary, you can change the selected JRE following the installation (forinstructions, see Configuration Editor below).

If you run Conversion Agent in-process, and you use the Conversion Agent Java API toactivate a Conversion Agent service, any Java components of the service run on the JREthat is used by the external Java application. For consistency of operation, we recommendthat this be the same JRE as the one that you configured within Conversion Agent. In anyevent, it must be a JRE version that Conversion Agent supports. For more information, seeConfiguring In-Process or Out-of-Process Invocation below.

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 10

You 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


3

Package Minimum version

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

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 Space

A 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.

http://www.sun.com/


4

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

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:


5

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

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 x86You 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:

http://www.ibm.com/


6

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

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 OpteronYou can run Conversion Agent on SUSE Linux version 9 and on Red Hat Linuxversion EL4, on AMD Opteron platforms.

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.

http://www.sun.com/

http://www.ibm.com/


7

Disk Space

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

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, 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.

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 5.0.02, 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.

http://www.hp.com/

http://www.hp.com/


8

Confirming Bundles

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

/usr/sbin/swlist

Disk Space

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

If You are Upgrading from a Previous Version

From Version 4.0.2 or Earlier

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

From Version 4.0.3 or HigherIf you are upgrading from Conversion Agent version 4.0.3 or higher, 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 Components and Computers

The setup requires that you upgrade all the Conversion Agent componentstogether to the same release number. This includes:

Conversion Agent Engine

Any other optional Conversion Agent components

We recommend that you upgrade all Conversion Agent computers in yourorganization at the same time. This avoids any possible version conflicts betweenprojects that you develop on one computer and run on another computer.

Upgrading ProjectsTo upgrade your existing Conversion Agent projects and run them in the newversion, see the chapter on Upgrading Conversion Agent Projects in the ConversionAgent Administrator's Guide.


9

Installing

The main installation steps are as follows:

1. Run the Conversion Agent setup program.

2. Load the Conversion Agent environment variables.

3. Configure Conversion Agent for in-process or out-of-process invocation.

4. If necessary, register the software and install a license.

5. Test the installation.

The following sections explain the procedure for each step.

Running the Setup Program

To run the setup program:

1. If your organization has a site license for Conversion Agent, make sure thatyou have the license key. The setup wizard will prompt you to enter the key.

If you plan to use a standalone (non-site) license, you do not need a licensekey.

2. Launch a terminal, and change to the directory where you stored the setupfile.

3. To run the setup in a graphical interface, enter the following command (theexample is for AIX; substitute the name of your setup file):

./Setup_Aix.bin

If you cannot view the graphical interface (for example, if you are workingfrom a remote location), you can run the setup in a console mode. To do this,add the -console switch:

./Setup_Aix.bin -console

4. In the setup wizard, follow the on-screen instructions. The wizard promptsyou to set several directory paths:

Conversion Agent PathThe Conversion Agent installation folder. The default is /opt/SAP/ConversionAgent. You must have administrator privileges for the path.

In this document, the installation path is referred to as <USER_INSTALL_DIR>.

JRE LocationThe location of the Java Runtime Environment that you will use withConversion Agent. The default is the JRE that is installed with ConversionAgent, <USER_INSTALL_DIR>/jre1.4/jre. Optionally, you can select anothersupported JRE.


10

Conversion Agent Repository PathThis is the location where you will deploy Conversion Agent services forexecution by Conversion Agent Engine. The default location is<USER_INSTALL_DIR>/ServiceDB.

Conversion Agent Log PathThis is the location where Conversion Agent Engine stores event logs andtroubleshooting reports. The default is <USER_INSTALL_DIR>/CMReports.

5. You are prompted to install optional components, such as the documentprocessors package (for information, see the chapter on Document Processors inthe Conversion Agent Studio User's Guide).

6. 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 Upgrading Conversion Agent Servicesbelow.

7. Continue with the instructions for Loading the Conversion Agent EnvironmentVariables and Configuring In-Process or Out-of-Process Invocation below.

Loading the Conversion Agent Environment Variables

You must load the Conversion Agent environment-variables file before you cantest or use Conversion Agent (for a detailed description of the required variables,see Environment Variables below). 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, in a batch file, or inanother executable file. If you do this, you can load the environment variablesautomatically.

The following paragraphs provide instructions for these two approaches.

Loading from the Command LineIf 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:

. /<USER_INSTALL_DIR>/setEnv.sh

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

source /<USER_INSTALL_DIR>/setEnv.csh

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

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


11

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

. /<USER_INSTALL_DIR>/setEnv.sh

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

source /<USER_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 batch file oranother executable file.

Configuring In-Process or Out-of-Process Invocation

You must 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).

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.

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. Currentlythe Java API and the Conversion Agent process module support out-of-process invocation. 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.


12

Platform ConversionAgent version

If you call ConversionAgent from a 32-bitprocess, you canchoose

If you call ConversionAgent from a 64-bitprocess, you can choose

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

Out-of-process

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

Out-of-process

SUSE Linux 9 orRed Hat Linux EL3on x86

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

SUSE Linux 9 orRed Hat Linux EL4on Opteron

64-bit Out-of-process (pleasecontact SAP forinformation about in-process support)

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

Out-of-process

Configuration

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

1. Open a command prompt, change to <USER_INSTALL_DIR>, and run thecommand:

CMConfig

This opens the Conversion Agent Configuration Editor.

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

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.


13

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

<USER_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 <USER_INSTALL_DIR>/bin/cm_server.sh

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:

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.


14

Registering and Installing a License

Depending on your Conversion Agent version, you may need to install a licensefile for Conversion Agent Engine. The following paragraphs explain how to dothis.

License StatusTo determine whether you have a valid Conversion Agent license, open acommand prompt and enter the command

CM_console aaa

where aaa is a placeholder for a Conversion Agent service name (the service aaadoesn't need to actually exist). If you do not have a valid license, the commanddisplays an error message such as license file has been corrupted or doesn't exist. Inthat case, follow the procedure below to obtain a license.

If you receive an error message such as invalid service 'aaa', you can ignore it. Thereason for the message is that the aaa service doesn't exist.

Site LicenseIf your organization has a site license for Conversion Agent, follow the instructionsthat you received with the license. You must install the license on each computerthat runs Conversion Agent.

Standalone LicenseTo obtain a standalone license to use Conversion Agent on a single computer, runthe following command:

<USER_INSTALL_DIR>/CMRegister

If you prefer to work in console mode, run this command instead:

<USER_INSTALL_DIR>/CMRegister -console

Follow the on-screen instructions to complete the registration. When you receivethe license file (License.cfg), store it in <USER_INSTALL_DIR>. You can then useConversion Agent Engine.

For a detailed explanation of the registration options, see the Conversion AgentAdministrator's Guide.

In the console-mode registration on HP-UX 11.23, the email field does not accept the @symbol. You should type \@ instead. For example, instead of typing [email protected],you should type user\@example.com.

Testing the Installation

To verify that Conversion Agent is installed correctly, perform the following test:

1. Enter the CM_console command, without any parameters.


15

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

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

3. In <USER_INSTALL_DIR>/setupTests, there is a sample Conversion Agentproject called TestCME. Copy the entire TestCME directory to the ConversionAgent repository, which you defined during the setup (by default,<USER_INSTALL_DIR>/ServiceDB). This makes TestCME available as aConversion Agent service.

4. 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>

5. If you installed the optional document processors, you can run an additionalservice called TestCMDP. The service converts an Excel spreadsheet file to XML.

To run the test, copy the directory

<USER_INSTALL_DIR>/setupTests/TestCMDP

to the Conversion Agent repository. Then run the command:

CM_console TestCMDP

The output should be:

<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>


16

Troubleshooting

Environment Variables

If the installation tests fail, the system is probably not setting some or all of theenvironment variables that Conversion Agent requires. To solve the problem, trythe following steps.

If the CM_console command fails to display the usage message:

1. Confirm that you have followed the instructions to load the environmentvariables (see Loading the Conversion Agent Environment Variables above).

Open the setEnv.sh or setEnv.csh file and verify its contents (see EnvironmentVariables below).

2. 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.

LD_PRELOAD Environment Variable on HP-UXOn 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:

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

You activate the Conversion Agent service from a C++ application, such as:

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


17

Under these circumstances, you should set LD_PRELOAD to point to the libjvmshared object of the JRE. On an HP-UX PA-RISC platform, LD_PRELOAD should alsopoint to the C++ application that you are running.

For example, to run CM_console on an HP-UX PA-RISC platform, enter thefollowing command:

setenv LD_PRELOAD "<USER_INSTALL_DIR>/jre1.4/lib/PA_RISC/server/libjvm.sl CM_console"

To run a C++ application called MyCppApp, enter the command:

setenv LD_PRELOAD "<USER_INSTALL_DIR>/jre1.4/lib/PA_RISC/server/libjvm.sl MyCppApp"

On an HP-UX ia64 platform, you should omit the C++ application, for example:

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

Please note the following points:

To determine the correct path of the libjvm object, open the Conversion AgentConfiguration Editor and examine the parameter CM Configuration/CMEngine/JVM Location.

On the PA-RISC platform, the libjvm object is called libjvm.sl. On the ia64platform, it is called libjvm.so.

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

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

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

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

The LD_PRELOAD setting is incompatible with applications that call theConversion Agent Java API or that run tcsh scripts. Before you run suchapplications, you must unset the environment variable:

unsetenv LD_PRELOAD

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


18

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 Configuration Editorbelow).

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

CM Configuration/CM Engine

3. Right-click the CM Engine node and add JVM init parameters.

4. Assign a value of JVM init parameters such as Xmx512M, where 512 is the heapsize in megabytes.

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

Preventing Core DumpsWhen 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.

Emulators

You should install and run Conversion Agent on the native systems, which aredescribed in the System Requirements above. 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.

Uninstalling

To uninstall the Conversion Agent software:

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

2. If you are working in a graphical interface, run the following command(substitute your Unix flavor for AIX):

<USER_INSTALL_DIR>/uninstall/_uninstMaster/uninstaller_AIX.bin

Alternatively, to uninstall in console mode, add the -console switch:

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


19

3. When the uninstallation is complete, delete <USER_INSTALL_DIR> and any filesremaining in it.

4. Log out and then log in, to ensure that your configuration changes take effect.

Environment Variables

Conversion Agent uses certain environment variables, which the setup programconfigures. For reference and troubleshooting purposes, we describe the variableshere.

Location of Environment-Variable Definitions

The setup does not modify your profile. Instead, it creates the environment-variable definitions in an independent file:

<USER_INSTALL_DIR>/setEnv.sh if you use the sh , ksh, or bash shell

<USER_INSTALL_DIR>/setEnv.csh if you use the csh or tcsh shell

Before you can use Conversion Agent, you must load the environment-variablesfile. You can do this either by configuring your profile to load the fileautomatically, or by loading the file from the command line. For instructions, seeLoading the Conversion Agent Environment Variables above.

Required Environment Variables

The following environment variables are required for proper Conversion Agentoperation.

PATHThe setup adds <USER_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 setup adds the installation directory (<USER_INSTALL_DIR>) to the librarypath.


20

It also adds the JRE directory and its parent to the path, for example,<USER_INSTALL_DIR>/jre1.4/lib/sparc/server and<USER_INSTALL_DIR>/jre1.4/lib/sparc.

CLASSPATHThe setup adds <USER_INSTALL_DIR>/api/lib/CM_JavaAPI.jar to the path.

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

Example of Environment Variables

The 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 (seeRequired Environment Variables above).

## 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 & odbc 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}"


21

Configuration Editor

You can use the Conversion Agent Configuration Editor to customize theconfiguration. To open the Configuration Editor, change to the<USER_INSTALL_DIR> and run the command:

CMConfig

Configuration Parameters

Among the parameters you can edit in the Configuration Editor are the following:

CM Configuration/Directory services/File system/Base PathThe Conversion Agent repository, where the Conversion Agent services arestored.

CM Configuration/CM Engine/JVM LocationThis is the path to the libjvm shared object of the Java 2 RuntimeEnvironment:

For Solaris or Linux, the libjvm.so fileFor AIX, libjvm.aFor HP-UX on PA-RISC, libjvm.slFor HP-UX on ia64, libjvm.soBy default, the path is the one you selected when you installed ConversionAgent (see Running the Setup Program). You can edit the path, for example, ifyou upgrade JRE versions and you want Conversion Agent to use the newJRE.

A single JRE may have multiple copies of libjvm, installed in differentsubdirectories such as server, client, etc. These implement server and clientversions of the JRE, respectively. Conversion Agent runs equally well with theserver and client versions. In most cases, the Conversion Agent default is theserver version.

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.

CM Configuration/General/Reports directoryThe location where Conversion Agent saves event logs and certain other typesof reports (by default, <USER_INSTALL_DIR>/CMReports).

For further information about the Configuration Editor and the editableparameters, see the Conversion Agent Administrator's Guide and the Conversion AgentEngine Developer's Guide.


22

Upgrading Conversion Agent Services

If you are upgrading from a previous Conversion Agent release, you may need toupgrade your existing Conversion Agent services to the current release.

Upgrading is necessary when the Conversion Agent Engine syntax version haschanged. To determine the syntax version, run the following command:

CM_console -v

The following paragraphs present upgrade instructions. For further discussion ofthe upgrade issues, see the chapter on Upgrading Conversion Agent Projects in theConversion Agent Administrator's Guide.

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.

Upgrading from Version 3.x

If you are upgrading from Conversion Agent version 3.x, you should upgrade theservices on a Windows computer. Then re-deploy the services to the Unixcomputer.

For upgrade instructions on Windows, see the Conversion Agent Administrator'sGuide.

Upgrading from an Earlier Version 4 Release

You can use the Conversion Agent syntax conversion tool to upgrade the services.The tool also upgrades global TGP script files, which are stored in the ConversionAgent autoInclude/user directory.

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.

Alternatively, you can upgrade on a Windows computer and re-deploy the services toUnix. This lets you test the upgraded data transformations in Conversion Agent Studio onWindows, before you deploy.


23

Running the Syntax Conversion Tool in Graphical Mode

To run the syntax conversion tool in a graphical mode:

1. Open a command prompt and run the following command:

<USER_INSTALL_DIR>/bin/runSyntaxConvFromGui.sh

This opens a window with several tabs, where you can configure the upgrade.

2. At the bottom of the window, specify that you are upgrading from version 4.x.

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

Source LocationThe repository containing the old services.

Target LocationThe repository for the new services. If the target is the same as the source,the tool overwrites the existing location.

Note: Use the Configuration Editor to change the repository location to thespecified target (see Configuration Editor).

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 services, prior toupgrade.

Error LocationA location where the tool should store any services that it cannot upgrade,due 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 services, for example, alternative versions of your Conversion Agentrepository.

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.

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


24

9. Test the services to confirm that they work correctly and that their behaviorhas not changed. For a discussion of the issues that may arise, see theConversion Agent Administrator's Guide.

Running the Syntax Conversion Tool in Console Mode

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 run the command:

<USER_INSTALL_DIR>/bin/runSyntaxConvFromConsole.sh

with the command-line switches listed in the following table:

Switch Description

-v (Required) Version from which you are upgrading. The only supported value is4.

-s (Required) Path of the source repository, for example,<USER_INSTALL_DIR>/ServiceDB .

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

-si (Required to upgrade global TGP files) Path of the sourceautoInclude/user directory, for example,<USER_INSTALL_DIR>/autoInclude/user.

-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<USER_INSTALL_DIR>/SyntaxConversionLog.txt.

-b (Optional) Path of the backup directory, where the tool backs up the originalservices prior to the upgrade. The default is the value of the -s switchconcatenated with the suffix _OLD_Backup, for example,<USER_INSTALL_DIR>/ServiceDB_OLD_Backup.

-e (Optional) Path of the error directory, where the tool stores any services that itcannot upgrade due to an error. The default is the value of the -s switchconcatenated with the suffix _OLD_Failure, for example,<USER_INSTALL_DIR>/ServiceDB_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 command

<USER_INSTALL_DIR>/bin/runSyntaxConvFromConsole.sh -v 4 -s<USER_INSTALL_DIR>/ServiceDB

upgrades the services in the default repository location.


25

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

3. Use the Configuration Editor to change the repository location to the targetthat you specified (see Configuration Editor).

Running Conversion Agent on Unix

To run a project in Conversion Agent Engine, you must first deploy it as aConversion Agent service. To deploy a service on a Unix platform, follow thisprocedure:

1. Develop a project in Conversion Agent Studio on a Windows platform.

Be sure to develop the project in a platform-independent way. For guidelines,see Platform-Independent Parsers in the Conversion Agent Studio User's Guide,Chapter 3, Parsers.

2. In Conversion Agent Studio, deploy the project as a Conversion Agent serviceon the Windows platform.

For instructions, see the chapter Deploying Conversion Agent Services in theConversion Agent Studio User's Guide.

3. Copy the deployed project folder from the Conversion Agent repository on theWindows platform to the repository on the Unix platform (the locationdefined by the Base Path parameter in the Configuration Editor).

Alternatively, if the Windows system can access the Unix file system, you canconfigure Conversion Agent Studio to deploy directly to the Unix repository. Youcan then skip step 3.

The service then runs in Conversion Agent Engine on the Unix system. Anintegration application, for example, can submit data to the service and retrieve theoutput. For information, see the Conversion Agent Engine Developer's Guide.

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.


26

This chapter explains the steps for using ODBC with Conversion Agent.

Installing and Configuring an ODBC Manager

You must install an ODBC manager that supports the ODBC 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 (see Required Environment Variables).

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

1. Open the Conversion Agent Configuration Editor (see Configuration Editor).

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

3. In the right-pane, right-click and choose Add > ODBC. This adds a newparameter called ODBC to the display.

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

/usr/local/odbc/libODBCMgr.so

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 yourUnix or database vendor.

If an appropriate driver is not installed, please contact your system administrator.

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


27

Defining DSNs

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

To do this, edit the .odbc.ini file, which is typically located in the root directory ofyour account. On some systems, the ODBCINI environment variable may specify adifferent location for this file.

For instructions on how to define the DSN, see the documentation of your databasesystem. The following is an example for a MyODBC driver, which connects to aMySQL database called Employees. The DSN is called EmployeesDSN.

[ODBC Data Sources]EmployeesDSN = DSN for Employees MySQL Database

[EmployeesDSN]driver = MySQLtracefile = /home/user1/sql.logtrace = offdatabase = Employees

Testing a DSN in Conversion Agent

You can use the CM_isql utility, which is located in the Conversion Agent odbcdirectory, to test that Conversion Agent can access a DSN. To do this:

1. Launch a terminal, and change to the <USER_INSTALL_DIR>/odbc directory.

2. Run the following command (substitute your DSN name for <YOUR_DSN>):

CM_isql <YOUR_DSN>

3. The utility should display the following prompt:

SQL>

4. Type exit to leave the SQL> prompt.

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.


28

Unsupported Features

Windows-Specific FeaturesConversion Agent for Unix does not support Windows-specific features ofConversion Agent, such as:

The COM API

Custom COM components (such as ExternalCOMPreProcessor orExternalCOMAction)

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 andare supported.

Additional Information

For up-to-date information that was not available when this manual was prepared,please see the readme file supplied with the software.

sap conversion agent by itemfield · the version includes conversion agent engine, which is the...

Documents