www.sap.

com

SAP®
Advanced SQL Migration
Migration Tool Installation Guide
v.3.5.2.1 community edition

© 2023 SAP SE. All rights reserved.

PUBLIC SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP BusinessObjects Explorer, StreamWork, SAP HANA, and other SAP products and
services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE in Germany and other countries.

Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business
Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects
Software Ltd. Business Objects is an SAP company.
Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL Anywhere, and other Sybase products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of Sybase Inc. Sybase is an SAP company.

Crossgate, m@gic EDDY, B2B 360°, and B2B 360° Services are registered trademarks of Crossgate AG in Germany and other countries. Crossgate is
SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

TABLE OF CONTENTS

1 INTRODUCTION .......................................................................................................................... 3
1.1 Intended Audience ........................................................................................................................... 3
1.2 What is SAP Advanced SQL Migration? ......................................................................................... 3
1.3 Usage restrictions and copyright .................................................................................................... 3
1.4 Contact ............................................................................................................................................. 3
1.5 More information: see User Guide .................................................................................................. 3
2 INSTALLATION ........................................................................................................................... 4
2.1 Hardware/software requirements .................................................................................................. 4
2.2 Installation pathnames/locations in this Installation Guide ......................................................... 4
2.3 Cygwin required component ........................................................................................................... 4
2.4 Installing Cygwin 3.2 64 bits. .......................................................................................................... 5
2.5 Verifying the Cygwin installation (new users only) ........................................................................ 5
2.6 Installing SAP Advanced SQL Migration for new users ................................................................. 6
2.7 Installing SAP Advanced SQL Migration updates ...........................................................................7
2.8 Customizing the command prompt window .................................................................................. 8
2.9 Upgrading from version 2.8 or later ................................................................................................ 9
2.10 Upgrading from version 2.x to 2.8 or later (renamed migration tool) .......................................... 9
2.11 Troubleshooting (1) .......................................................................................................................... 9
2.12 Troubleshooting (2) ........................................................................................................................10
2.13 Support ............................................................................................................................................10
3 RUNNING THE MIGRATION TOOL FROM A USB DRIVE ............................................................ 11
4 CONNECTIVITY GATEWAY INSTALLATION .............................................................................. 12
5 UNINSTALLATION ..................................................................................................................... 13

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 2

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

1 INTRODUCTION

1.1 Intended Audience

This document is intended for anyone who will be installing the SAP Advanced SQL Migration tool.

1.2 What is SAP Advanced SQL Migration?

SAP Advanced SQL Migration is an SAP-developed tool to assist with migrating custom (non-SAP)
applications from a non-SAP database to an SAP database. This migration tool is primarily focused on
assessing migration complexity and migrating schema and server-side SQL code.
SAP Advanced SQL Migration is expected to be used as part of a broader approach that also covers all
other aspects of a migration project.
For more information about using SAP Advanced SQL Migration, see the User Guide in the docs
subdirectory of your Migration tool installation.

1.3 Usage restrictions and copyright

SAP Advanced SQL Migration is copyright © of SAP SE. The SAP Advanced SQL Migration software
contains confidential information and trade secrets of SAP SE. Use, disclosure, reproduction or
distribution of this program is prohibited except as expressly allowed by the governing license
agreement or written permission of SAP SE. Modification, reverse engineering, de-obfuscation and
modifying or removing registration data are not permitted.

In addition, it is not permitted to circumvent the migration tool's connectivity gateway (see User Guide)
when connecting to the source DBMS of a customer whose application is being migrated.

1.4 Contact
For information about SAP Advanced SQL Migration, or about migration-related aspects in general,
contact [email protected].

1.5 More information: see User Guide

For more information about using SAP Advanced SQL Migration, see the User Guide in the docs
directory of your migration tool installation.

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 3

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

2 INSTALLATION

2.1 Hardware/software requirements

The SAP Advanced SQL Migration tool is supported on Windows 7, Windows 10 (Professional or
Enterprise editions), Windows 2008 Server and Windows 2012 Server. According to reports from users,
the migration tool also runs fine on Windows XP and Windows 8 but SAP has not actively tested the
migration tool on these platforms.
The migration tool is not supported, and will not work correctly, on Unix/Linux.

The migration tool only writes into locations that are explicitly specified by the user (e.g. the installation
directory and project directories). The migration tool does not write into the Windows Registry.

The migration tool requires Cygwin to be installed. Cygwin 64 bits minimum version 3.2.0-1 is required
for SAP Advanced SQL Migration tool. Cygwin is not distributed as part of the migration tool, but
installation instructions are provided in this manual (see sections 2.3-2.4).

Performance of the migration tool is primarily bound by available CPU and memory. The recommended
minimum hardware resources are:
• 2-core, 2.5 GHz
• 8GB RAM
• 2 GB of free space on C:\ (not including space for extracted and converted SQL code)
• A minimum display size of 1280x768 is required for displaying the GUI (which is used to set
configuration options).

2.2 Installation pathnames/locations in this Installation Guide

In this document, the following locations will be assumed:

• C:\cygwin64 : Cygwin run-time environment

• C:\cygwin64\start_bash.bat : .bat file to start a Cygwin bash sessions
• C:\sapdbmtk : location of the SAP Advanced SQL Migration installation

2.3 Cygwin required component

The migration tool requires Cygwin 64 bits minimum version 3.2.0-1 with some specific components.

Please ensure that Windows Powershell is not in the %PATH% being used by the migration tool session,
as this could lead to errors and malfunction.

For reference, at least the following components must be present in the Cygwin environment:

• Perl Perl v.5.32 or later

• Perl Win32::GUI package
• file utility
• iconv utility

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 4

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

2.4 Installing Cygwin 3.2 64 bits.

Cygwin is an open-source library that is available under the GNU GPL license (for further details see
https://cygwin.com/licensing.html_for Cygwin licensing terms)

The following Cygwin installation steps need to be performed only once.

When The migration tool is already running on your system, there is no need to reinstall the Cygwin
environment again, including when installing updates of the migration tool itself.

1. Install latest Cygwin version from the official web site (https://cygwin.com/install.html) using
the 64 bits installer called “setup-x86_64.exe”. Keep the default folder (“c:\cygwin64”) for
Cygwin software installation. As indicated in the previous bullet you need to install the four
required components, so be sure you select:

Perl minimum version 5.32:

Perl-Win32-GUI (latest version suggested):

Libiconv so that iconv utility is installed:

In current Cygwin versions “file” utility is already installed by default so no need to select any
specific component for it.

2. Download the migration tool distribution .zip from SAP (check section 2.6). This file is named
something like sapdbmtk.v.3.5.2.1-X.community_edition.zip.
Unzip this file into C:\, so it creates directory C:\sapdbmtk.

3. Copy the files called start_bash.bat and cygwin.bashrc from C:\sapdbmtk\install to

C:\cygwin64. Throughout this document, the files C:\cygwin64\start_bash.bat and
C:\cygwin64\cygwin.bashrc are expected to already exist.

2.5 Verifying the Cygwin installation (new users only)

Before proceeding, verify that all required components are correctly installed, through the following
steps. Do not proceed unless all items below are correctly installed.

1. First, open a Cygwin shell session by running or double-clicking C:\cygwin64\start_bash.bat.

This will open a command prompt window under the bash shell with a prompt like this:
(tip: since such windows may be used often, drag this .bat file to the Start Menu for a quick and
convenient way to start it).

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 5

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

2. In the above window, verify the Perl version by typing the following command at the prompt:

/usr/bin/perl –v

The output should indicate Perl version 5.32.x or later. If an earlier version of Perl is indicated,
this needs to be fixed first otherwise the migration tool will not run.

3. In the above window, type the following lines at the prompt:

iconv -h
file -h

For both commands, 'usage' information should be displayed, indicating that these utilities were
installed correctly in the Cygwin environment. If not, re-install Cygwin.
The migration tool will not function correctly without these utilities.

2.6 Installing SAP Advanced SQL Migration for new users

You can download SAP Advanced SQL Migration from the SAP official download link under SAP Hana
tools:
https://tools.hana.ondemand.com/#hanatools

To install the migration tool, the Cygwin environment must have been installed first as described in
sections 2.3, 2.4 and 2.5 of this Installation Guide.

For new users, take these steps:

1. Unzip the SAP Advanced SQL Migration .zip file into C:\. This will create directory C:\sapdbmtk.

2. Open a Cygwin shell window by running this .bat file:

C:\cygwin64\start_bash.bat.
Make sure this window is started with Administrator
privileges, i.e. right-click and choose Run as
Administrator (enlarge this document to view the
screenshot on the right ➔➔➔)

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 6

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

3. Type the following command at the command prompt:

cd c:/sapdbmtk # NB: note the forward slash !
chmod –R 777 *
4. Type the following command at the command prompt:
sapdbmtk config c:/mytestdir # NB: note the forward slash !!
A window should now pop up with a menu to select the source and target DBMS type, as shown
below. This window will typically appear towards the top-left corner of the screen; note that it
may not always be immediately shown on the foreground.

Select a source DBMS and target DBMS and click the "Save & Next" button.
Another, larger and scrollable menu should now be displayed, with all applicable configuration
settings (no screenshot shown in this document, see the User Guide). Change a random setting
and click the "Validate & Save Changes" button. Then click the Exit button.

Now run the same command again:

sapdbmtk config c:/mytestdir # NB: note the forward slash !!

The menu should pop up again, showing the selections and changes made in the previous step.
When this all works successfully, the installation was done correctly.
A directory c:\mytestdir will have been created, where the subsequent menu selections will be
stored. This directory was for testing the installation only and can now be deleted.

2.7 Installing SAP Advanced SQL Migration updates

It is recommended to check regularly the SAP official download link to see if any migration tool updates
are available:

https://tools.hana.ondemand.com/#hanatools

To install a migration tool update, the Cygwin installation steps described in this Installation Guide do
not need to be repeated. It is sufficient to extract the SAP Advanced SQL Migration distribution .zip file
into the C:\ directory, thus overwriting the files in C:\sapdbmtk (and its subdirectories) that were

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 7

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

created when an earlier version of the migration tool was installed. Ensure the migration tool is not
running when performing this operation.
It is generally recommended to save a copy of the existing version of SAP Advanced SQL Migration
before overwriting it with a new version.

Note that migration tool configuration settings in existing project directories, that were changed by the
user to a value different from their defaults, are retained, and not overwritten, when a migration tool
update is installed.

2.8 Customizing the command prompt window

(optional) It is recommended to change the dimensions of the DOS/bash command prompt window
where SAP Advanced SQL Migration will be run from, so as to avoid too many lines from being wrapped
around inconveniently.
These are some suggestions for best use of the migration tool:

1. Set the line length to 120 and increase the window height to 50 lines:

2. Enable automatic copy & paste directly from the command prompt window:

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 8

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

2.9 Upgrading from version 2.8 or later

Upgrading to versions pre-v3.5.2.1 was as simple as unzip the .zip file containing the migration tool into
C:\ so that C:\sapdbmtk is replaced with the new files, existing project directories were not affected
and they were automatically upgraded when the first migration tool command is executed on them. But
now in version 3.5.2.1 or later the upgrade process is slightly different because a new Cygwin version is
required, take the following steps (assuming all filenames and directories are the installation defaults):

a. Uninstall the current Cygwin version you had installed for previous version of SAP Advanced
SQL Migration tool. This basically means to remove “c:\cygwin” folder because the installation
was done decompressing the .zip file containing the Cygwin distribution provided by SAP.
b. Install latest Cygwin 64 bits version (3.2.0-1 or later) as indicated in sections 2-3, 2.4 and 2.5.
c. Download the new version (3.5.2.1 or later) of the migration tool distribution .zip file from SAP.
d. Unzip this file into C:\, so that directory C:\sapdbmtk is replaced with the new files.
e. Copy the files called start_bash.bat and cygwin.bashrc from C:\sapdbmtk\install to the news
Cygwin folder C:\cygwin64.
f. Existing project directories are not affected by upgrading to the renamed migration tool, they
will be automatically upgraded when you run any migration tool command for the first time on
them,

2.10 Upgrading from version 2.x to 2.8 or later (renamed migration tool)
In version pre-2.8, SAP Advanced SQL Migration was called ‘Exodus’, and some aspects were different
compared to v.2.8. For example, pre-2.8 assumes C:\Exodus to be the installation directory, while 2.8
assumes C:\sapdbmtk (though any directory name/path could be used, the documentation assumes
C:\sapdbmtk). Also, the main exodus command has been renamed to sapdbmtk. Another important
aspect is that the Cygwin version now is newer and 64 bits.

Upgrading an existing pre-2.8 environment is quick and easy.

Take the following steps (assuming all filenames and directories are the installation defaults):

a. Uninstall the current Cygwin version you had installed for SAP Advanced SQL Migration tool
version pre-2.8. This basically means to remove “c:\cygwin” folder because the installation was
done decompressing the .zip file containing the Cygwin distribution provided by SAP.
b. Install latest Cygwin 64 bits version (3.2.0-1 or later) as indicated in sections 2-3, 2.4 and 2.5.
c. Download the new version of the migration tool (2.8 or later) distribution .zip file from SAP.
d. Unzip this file into C:\, so that a new directory C:\sapdbmtk is created.
e. Rename or remove the existing C:\Exodus directory to ensure it is no longer used.
f. Copy the files called start_bash.bat and cygwin.bashrc from C:\sapdbmtk\install to the news
Cygwin folder C:\cygwin64.
g. Modify any user-created settings -like environment variables- or files that reference the ‘old’
installation directory, and change this to point to the ‘new’ installation directory.
h. The command name exodus has changed to sapdbmtk. Any scripts using the exodus command
must be modified accordingly.
i. Existing project directories are not affected by upgrading to the renamed migration tool, they
will be automatically upgraded when you run any migration tool command for the first time on
them,

2.11 Troubleshooting (1)

In case the migration tool does not run, check the following points:
1. Verify that C:\cygwin64\bin is in the Windows %PATH% environment variable (Control
Panel➔System). While this should not normally be required with the SAP-provided Cygwin
package, it may be needed in non-standard scenarios.

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 9

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

2. If the command sapdbmtk is not successful but ./sapdbmtk runs fine, this means that the
migration tool directory is not in the PATH. Verify/ensure that at least one of the following
applies:
a. C:\sapdbmtk is in the Windows %PATH%
b. /cygdrive/c/cygwin64 is in the bash $PATH (set in the cygwin.bashrc file)
c. . (='dot') is in the bash $PATH (set in the cygwin.bashrc file)

3. Verify that Perl is properly installed (type which perl)

4. Verify (with ls –l) that file protections on C:\cygwin64\Cygwin.bat, C:\sapdbmtk\sapdbmtk
and C:\sapdbmtk\sapdbmtk.pl allow reading and execution; if not, run chmod 777 * to fix.
5. If it looks like sapdbmtk is not executed at all, run dos2unix sapdbmtk in a bash command
window; then retry.

In case C:\cygwin64\start_bash.bat cannot be executed, an error message may be reported like this:
Windows cannot access the specified device, path or file. You may not have the appropriate
permissions to access the item
In this case, the file protections on C:\cygwin64\start_bash.bat may not be set properly. To resolve
this, double-click on C:\cygwin64\Cygwin.bat which opens a command prompt window.
Then type:
cd /cygdrive/c/cygwin64
chmod 777 *.bat
Now, retry running C:\cygwin64\start_bash.bat.

2.12 Troubleshooting (2)

There have been some reports of permission errors on C: when running the command:

sapdbmtk config c:/myprojectdir , despite the user having Administrator rights.

If this happens, take these steps:

1. Edit the file C:\cygwin64\etc\fstab

2. Add ',noacl' as shown in red below (without the quotes)

Before:
none /cygdrive cygdrive binary,posix=0,user 0 0

After:
none /cygdrive cygdrive binary,posix=0,user,noacl 0 0

3. Close all 'bash' windows and stop all Cygwin-related programs

4. Re-open a bash window and re-run sapdbmtk config c:/myprojectdir
a. If the error is still raised, reboot Windows first.

2.13 Support
For support, please contact [email protected] or make a question in the official SAP
Advanced SQL Migration tool community:

https://community.sap.com/topics/advanced-sql-migration

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 10

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

3 RUNNING THE MIGRATION TOOL FROM A USB DRIVE

It may occur that customers do not allow external laptops to be connected to their corporate networks.
In such cases, it is possible to run the migration tool from a USB drive plugged into a Windows PC on the
customer network (assuming this is allowed).
In the steps below, the USB drive is assumed to be known to Windows as drive X:
Take these steps:
1. First install the migration tool on a Windows laptop as described in this document.
2. Then, copy the C:\cygwin64 and C:\sapdbmtk directories to a USB drive.
3. On the target Windows system where the migration tool will be run from the USB drive, verify
that no Cygwin installation already exists. If so, temporarily rename the existing Cygwin
directory to avoid a clash between the two Cygwin environments.
4. Plug the USB drive into the Windows system where the migration tool will be executed from, and
verify it is seen as drive X:
5. On the target Windows system where the migration tool will be run from the USB drive, add
X:\cygwin64\bin to the Windows %PATH% environment variable.(Control Panel➔System);
also ensure the X:/sapdbmtk or . (='dot') are in the bash PATH.
6. On the USB drive, edit the files X:\cygwin64\start_bash.bat and X:\cygwin64\cygwin.bashrc,
and change all references of C: to X:.
7. Start a command prompt window through X:\cygwin64\start_bash.bat, and run the migration
tool as described in the User Guide.
8. In case the migration tool does not run, see the troubleshooting tips above; it is possible that file
protections need to be changed or dos2unix needs to be executed.

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 11

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

4 CONNECTIVITY GATEWAY INSTALLATION

For connecting to the source DBMS which hosts the application to be migrated, the migration tool uses
a separate gateway program. This connectivity gateway is a small Java program which is typically
started on the customer system where the properly licensed connectivity libraries for the source DBMS
are installed. The system where the connectivity gateway program will run, must have Java/JRE 1.7 (or
later) installed.
For more details on the connectivity gateway, please refer to the User Guide.

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 12

SAP® Advanced SQL Migration community ed. Installation Guide Version 3.5.2.1 – Feb 2023

5 UNINSTALLATION
As described in the installation section the installation process consists basically in installing Cygwin
and decompressing the .zip file you download with the migration tool software, so nothing is written and
kept in the Windows registry or other config files outside the migration tool software folder itself.
If you want to uninstall SAP Advanced SQL Migration tool you only must remove the migration tool
folder under “c:\sapdbmtk” and follow the official instructions to uninstall Cygwin.

Copyright© 2023 SAP SE. All rights reserved. PUBLIC 13