Downloading and Installing AbaPerls

This page gives information how to download and install AbaPerls, and what prerequisites you need.

Contents:
   Prerequisites for AbaPerls
      Perl
      Windows
      Visual SourceSafe
      Team Foundation Server
      SQL Server
      SQL Server Native Client
   Installing and Setting Up AbaPerls
      What's in the Archive
      Setting Up AbaPerls
   Running the AbaPerls Tools
   Installing the Database Part of AbaPerls
   Updating from a Previous version of AbaPerls
      Release notes
      Files
      Updating Databases
      Co-existence of Client and Database versions

Prerequisites for AbaPerls

Perl

AbaPerls comes with a Perl installation, which is build 2400 of ActiveState Perl equipped with all the extra modules needed to run AbaPerls. I strongly recommend that use this instatlation. If you want to use your own Perl installation, I list the extras here for reference, but I don't go into details.

Windows

AbaPerls have been tested on Windows 7 and later. As for earlier versions of Windows, it may work, but no guarantees.

Visual SourceSafe

This only applies if you plan to use AbaPerls with Visual SourceSafe. If you only plan to use AbaPerls with Team Foundation Server, you do not need to have SourceSafe installed.

To use AbaPerls with SourceSafe, you need to have Visual SourceSafe 2005. I recommend that you apply the service update that Microsoft released in 2007. Please observe that you cannot use AbaPerls with VSS6 and earlier.

You must register the DLL for the SourceSafe API:

regsvr32 C:\Program Files (x86)\Microsoft Visual SourceSafe\ssapi.dll

Note that the exact file path can vary depending on localisation and whether you have a 32-bit or 64-bit operating system. 

Team Foundation Server

Server side: AbaPerls supports all version of Team Foundation Server 2010 and up as long as Microsoft does not introduce any breaking changes. (Of this writing, the most recent version of TFS is TFS 2017). AbaPerls has not been tested with the cloud service for TFS.

Client side: AbaPerls comes with all assembiles it needs to access the TFS API, thus there are no particular prequisites to install client-side. Note, however, that the particular function of mapping the current folder to a TFS project only works for the versions of Visual Studio that AbaPerls knows about, which at the time of this writing is VS2010 to VS2017. Later versions of Visual Studio will require a new set of assemblies to be shipped with AbaPerls.

If you only plan to use AbaPerls with Visual SourceSafe, you don't need to have any components for Team Foundation Server installed.

SQL Server

AbaPerls supports SQL Server 2005 SP2 and later. AbaPerls does not support Windose Azure SQL Database.

SQL Server Native Client

Win32::SqlServer talks to SQL Server through OLE DB. While the SQLOLEDB provider ships with Windows, I recommend that you have a version SQL Server Native Client installed that matches or is newer to the version of SQL Server you are connecting to. SQL Server Native Client comes with SQL 2005 and later as a redistributable package. The easiest way to get SQL Server Native Client in place may be to install SQL Server Management Studio.

The tool DOBCP requires the command-line tool BCP to be available.

Installing and Setting Up AbaPerls

What's in the Archive

Once you have the prerequisites in place, download abaperls.zip and unzip the archive to the place where you want to have AbaPerls installed. For simplicity's sake I'm assuming here that you choose C:\AbaPerls.

If you go to C:\AbaPerls you will find that this folder has five subfolders:

AbaPerls
This directory contains all the AbaPerls tools. They are Perl scripts are wrapped into .bat files, so that you can invoke them without specifying a file extension. You find two subfolders here. One is also called AbaPerls and includes library modules that are shared between the tools. The other folder is named TFS and is used when AbaPerls maps folder to a TFS project.
dbinstalls
This directory contains files to install and upgrade the ABAPERLS subsystem. More about this later.
doc
Here you find the complete documentation for AbaPerls, including the documentation for the AbaPerls system tables.
misc
This directory includes a few auxiliary files that are referred to in the AbaPerls documentation.
Perl5240
This folder includes Perl itself. More precisely, this is ActiveState Perl 5.24 augmented with extra files and modules to run AbaPerls.

Setting Up AbaPerls

Before you can start using AbaPerls: you need to set two environment variables. Go to the Control Panel, select System and Advanced System Settings and then the Advanced tab. There is a button Environment variables at the bottom.

First find the PATH variable and add C:\AbaPerls\AbaPerls and C:\AbaPerls\Perl5240\bin as the first two components to path. This is quite straightforward with Windows 10 Anniversary Edition or later. With earlier versions of Windows, you need prepend the existing value with  C:\AbaPerls\AbaPerls;C:\AbaPerls\Perl5240\bin; That is, they should be separated with semicolon and there should be a terminating semicolon before the next component in the path. Also be careful not to add any extraneous spaces.

Next create a new variable with the name PERLLIB and the value C:\AbaPerls\AbaPerls.

You don't need to restart Windows for the settings to have effect, but the change only affects applications you start after the change, not those currently running.

To test that you have it all set up right, open a command-line window (don't reuse an existing!) and run

abasql -nisse

This should yield a response like:

This is label L1.0.0360 of AbaPerls.
For help on AbaPerls see U:\AbaPerls\Users\Sommar\Doc\index.html.

Unknown option: nisse
abasql {-database db [-Server server] [-User anv] [-Password pwd] | -noexec}
       [-get] [-VC VC-path [-nouse_disk]] [-label version] [-LoadRequire]
       [-log file] [-save [file]] [-subsystem subsys] [-nocreate] [-force]
       [-[no]crypt] [-[no]quoterepl] [-site site-id:s]
       [-Macro &macro=value [...]] [-undef &macro [...]]
   file1 [file2 ...]

If you get some other error message, something is wrong. Pay attention to the label (the first line in the message). If this label is lower than L1.0.0360 or not printed at all, you have an outdated installation.

One thing to troubleshoot is that you have the correct Perl in your path. Running this command

perl -v

should yield this output:

This is perl 5, version 24, subversion 0 (v5.24.0) built for MSWin32-x86-multi-thread-64int
(with 1 registered patch, see perl -V for more detail)

Copyright 1987-2016, Larry Wall

Binary build 2400 [300558] provided by ActiveState http://www.ActiveState.com
Built Jun  9 2016 21:46:33

Perl may be copied only under the terms of either the Artistic License or the
GNU General Public License, which may be found in the Perl 5 source kit.

Complete documentation for Perl, including FAQ lists, should be found on
this system using "man perl" or "perldoc perl".  If you have access to the
Internet, point your browser at http://www.perl.org/, the Perl Home Page.

Running the AbaPerls Tools

All tools are Perl scripts, packaged as .bat files. Thus you only need to specify the tool name, as long as your AbaPerls installation is in your path. Most of the commands take switches. The switches have long names, but you can abbreviate switch names as long as they unambiguous. (Often one letter suffices). Note that the switch names are case-sensitive.

Example: several commands have a switch ‑Server to specify which SQL Server to connect to. If the command has no other switch starting with ‑S, you can specify ‑S, ‑Se, ‑Ser, ‑Serv, ‑Serve or ‑Server. But ‑s won't fly. (Note: for the four connection switches, ‑Server, ‑User, ‑Password and ‑database, AbaPerls will never introduce new switches that prevent use of ‑S, ‑U, ‑P or ‑d. Thus you can rely on these four to remain unambiguous.)

To see the command-line switches, you can always type the command name with some non-existing switch, for instance ‑nisse, to see the syntax.

In the syntax descriptions the following conventions are used:

italics Placeholder for an argument – e.g. filename – to a switch or a command.
[] Optional switch or argument.
| Mutually exclusive choices. One of the alternatives must be chosen, unless the choice is enclosed in [].
{} Embraces a group of switches that together are mutually exclusive with the switch(es) on the other side of |. One of the alternatives must be chosen, unless the entire group is enclosed in [].
... Repetition any number of times.

Switches can be given in any order. The arguments must come in the order given in the syntax definition. In the syntax diagrams they always come after the switches, but AbaPerls uses the Perl module Getopt::Long to decode the command line and this module permits switches to come after the arguments.

Note that some arguments may include special characters for the DOS command-line or Getopt::Long. In this case you need to enclose the arguments in double quotes. For instance to specify a database instance with IP-address and port number, you need to say:

-Server "192.168.1.1,4711"

Installing the Database Part of AbaPerls

To install the database part of AbaPerls go to C:\AbaPerls\dbinstalls\newdb and run:

dbbuild -S yourserver -d yourdb

If you use SQL Server authentication, specify username with ‑U and password with ‑P.

This is something you will do every time when you build a new database. If you have an existing database you want to use AbaPerls in, you can run this from a query window:

EXEC zz_ap_sob_load_sp

This will load all objects into the AbaPerls system tables as part of the subsystem UNKNOWN. Once you have decided on a subsystem structure, you can set the subsystems manually. (Or with help of DBBUILD ‑restruct.)

In the dbinstalls directory there are a couple of more folders. They are only of interest if you are upgrading from an earlier public release of AbaPerls.

Updating from a Previous version of AbaPerls

Provided that you read this page from your AbaPerls installation, your AbaPerls version is L1.0.0360. To see if there is a newer version available, go to the AbaPerls home page on the web and compare with the version number there. To get a grip of what news there are, review the History page in the web edition of the AbaPerls manual.

Release notes

There are two history pages: one compact, which is updated for each public release, and one detailed which includes about every little change in AbaPerls. The compact history also includes any specific update information. For generic information, see below.

Files

  1. Note that AbaPerls now comes bundled with a Perl installation, and if you have an existing one you are adviced to uninstall it.
  2. Remove the old installation of AbaPerls (or move it as a backup).
  3. Download abaperls.zip and unzip into the same place as the old installation.
  4. Review the setting of the PATH and PERLLIB variables, as the folder names in the AbaPerls installation have changed.

That's all.

Updating Databases

In the dbinstalls directory there are a number of folders named Update-nnnn-mmmm. Each folder contains an install kit for upgrading the ABAPERLS subsystem from version nnnn to mmmm. To update a database, first run

SELECT ss_label FROM abasubsystems WHERE subsystem = 'ABAPERLS'

to see what is the current version number of the ABAPERLS subsystem. Then start in the folder where the version number falls between nnnn and mmmm. In each folder run:

perl update-nnnn-mmmm.pl -S Server -d database -noVC 

Add ‑U and ‑P if you use an SQL login rather than Windows authentication.

Note! Be careful to take a backup (or a database snapshot) of the database before you run the scripts. Some of the script performs very wild things with the AbaPerls tables. (Updating the ABAPERLS subsystem with AbaPerls itself has strong resemblance with lifting yourself in the hair.)

You may note that that mmmm for the last folder does not match the label for the release of AbaPerls. This is perfectly normal. The last changes before a public release typically do not include any SQL changes.

Known issue: if you have a database which is below L1.0.0120, the script update-0080-0120.pl produces an error for abasysobjects.tbl. You can ignore this error, as the intended table change is performed anyway.

Co-existence of Client and Database versions

It is as simple as this: The client part of AbaPerls (the .bat files in the Perl folder) must have a label that is the same or higher than the ABAPERLS subsystem in the database.

That is, if you have version L1.0.0262 of the AbaPerls tools, you can run it against a database that has version L1.0.0080 of the ABAPERLS subsystem. However, you cannot deploy files from TFS to a database, unless the ABAPERLS subsystem is at least at label L1.0.0230. In the future, I may drop support for very old labels entirely.

On the other hand, if you have version L1.0.0190 (an earlier public release) and the database has version L1.0.0250 of the ABAPERLS subsystem you will get an error when you connect to the database.