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
      .Net Framework
      Visual SourceSafe
      Team Foundation Server
      SQL Server
      SQL Server Native Client
   Installing Prerequisites for AbaPerls
      Visual SourceSafe
      Perl
   Installing and Setting Up AbaPerls
      What's in the Archive
      Installing the Final Prerequisites
      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

To run AbaPerls, you need to have Perl installed. More precisely build 1202 or later of ActivePerl. Instructions for downloading and installing ActivePerl are in the next section.

I make no pretentions of supporting other binary distributions of Perl, nor installations of Perl you have built from sources, but I will leave you on your own if you want to try that. (As a hint: your chances are considerably better if you have used Visual Studio 8 or later to build Perl.)

Beside Perl itself, you need two additional Perl modules, Win32::CLR and Win32::SqlServer. For your convenience, these modules are included with the download file for AbaPerls.

Win32::CLR permits Perl to access the .Net Framework, including the API for Team Foundation Server. I am greatly indebted to Toshiyuki Yamato for having written this module and made it available on CPAN. I had to make a few small changes to module to get it to work for my purposes. Unfortunately, I have not been able to get in touch with Yamato-san, so I don't know whether he would approve of my changes. For this reason, the version of Win32::CLR that comes with AbaPerls is an unofficial release.

Win32::SqlServer is a module for accessing SQL Server from Perl through OLE DB. I am the author of this module myself, and even if the module is bundled with AbaPerls, you can always get the most recent version from http://www.sommarskog.se/mssql. The version which is bundled with AbaPerls is 2.008.

Windows

AbaPerls runs Windows 2000 or later, with the caveat that I have not tested all versions of Windows.

.Net Framework

AbaPerls requires .Net 2.0. This applies even if you are not using AbaPerls with Team Foundation Server.

Visual SourceSafe

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.

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

Team Foundation Server

Server side: AbaPerls supports Team Foundation Server 2012 and 2010. (Service Pack 1 or later recommended for TFS 2010.) AbaPerls does not support TFS 2005 or 2008. AbaPerls may work with later versions of TFS, but since they are not released as of this writing, that is not tested.

Client side: AbaPerls requires TFS Client 2012 or 2010 (again Service Pack 1 or later recommended for TFS 2010). You get TFS Client if you install the corresponding Visual Studio version. To install only the API, try this download link. Pay attention to license requirements. Note that AbaPerls will not work with a later version of TFS Client than those listed. (Because it does not know the full names of the future assemblies.)

If you only plan to use AbaPerls with Visual SourceSafe, you don't 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 tool DOBCP requires the command-line tool BCP to be available.

Installing Prerequisites for AbaPerls

In this section I only discuss the installation of prerequisites that you are not likely to have in place already.

Visual SourceSafe

If you want to use AbaPerls with Visual SourceSafe, 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

Perl

This section is written under the assumption that you are completely unfamiliar with Perl. Readers who are already acquainted with Perl may find the text tedious.

Unless you have been given a installation file from your administrator, go to http://www.activestate.com/activeperl/downloads and download a version of ActivePerl for Windows. Note that if you plan to use AbaPerls with SourceSafe, you must use the x86 version, since SourceSafe is 32-bit only.

ActiveState typically provides binaries for the most recent version of Perl and the immediately preceding version, of this writing this is version 5.12, 5.14 and 5.16. (Odd version numbers are reserved for experimental versions, so you will only see even numbers.) You need to take some care when you download. All of 5.12, 5.14 and 5.16 are fine with AbaPerls. But if 5.18 have appeared on the scene when you read this, you should be aware that you cannot use the versions of Win32::CLR and Win32::SqlServer that are bundled with AbaPerls with other versions than 5.12 to 5.16. (Both modules include DLLs, and each version of Perl requires a specific version of the DLL.) More about this below.

If you already have a Perl installation, make sure that it as least version 5.12, and that you have ActivePerl.

Once you have downloaded the .msi file, run the wizard. If you install Perl only to be able to run AbaPerls, you can reduce the installation time by unselecting the optional components. The wizard permits you to select the location for your Perl installation. There is no reason not to go with the default, but if you change the path, beware that you must select a local disk. Do not select a location on the network, as this does not work with Win32::CLR. (You cannot run .Net DLLs from network disks.) When running the wizard, you will be presented with a page with check boxes. Of these, make sure that you select the first, Add Perl to the PATH environment variable. The remaining have no importance to AbaPerls, and you may do best in unchecking them.

When the wizard has completed, open a command-line window and run perl ‑v. The output should be something like this:

This is perl 5, version 12, subversion 2 (v5.12.2) built for MSWin32-x86-multi-thread
(with 8 registered patches, see perl -V for more detail)

Copyright 1987-2010, Larry Wall

Binary build 1202 [293621] provided by ActiveState http://www.ActiveState.com
Built Sep 6 2010 23:36:03

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.

Pay particular attention to the build number. It should be at least 1202 for running AbaPerls. If you see a lower number, you may have an older version of Perl installed. In that case clean up your installation and your PATH from the Control Panel.

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. Nevertheless, in difference to Perl itself, you can put AbaPerls on a network installation, if you want developers to be able to share the installation. Note however, that each developer must complete the steps in this section.

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

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.

Perl – This directory contains all the AbaPerls tools. It includes a subfolder AbaPerls that includes library modules that are shared between the tools. If you look in Perl you will find that all files are .bat files. The Perl scripts are wrapped into .bat files, so that you can invoke them without specifying a file extension.

Prereq – This folder includes installation folders for Win32::CLR and Win32::SqlServer, which you need to run Perl.

Installing the Final Prerequisites

Before you can use AbaPerls you need to install the additional Perl modules. As long as you have installed Perl 5.12 or Perl 5.14, installing these modules is simple.

  1. CD C:\AbaPerls\Prereq\Win32-CLR-0.04
  2. perl activeperl-copy.pl
  3. CD C:\AbaPerls\Prereq\Win32-SqlServer-2.008
  4. perl activeperl-copy.pl

And you are done. (Both modules come with test scripts, and if you want to verify that they are installed properly, you can run these. For Win32::CLR, just do CD t and then perl CLR.t and make sure that it says ok all the way. Testing Win32::SqlServer is a little more complex, but look at Tests.html in Prereq\Win32‑SqlServer‑2.008.)

As discussed above, these steps will not work with Perl versions that had not been released at the time of this release of AbaPerls. If you have opted to install such a version of Perl (5.18 or later), here are some directions.

For Win32::SqlServer go to the official download site for the module, http://www.sommarskog.se/mssqlperl/index.html. Hopefully, I have a new version out that includes a binary for Perl 5.18. Download, unzip somewhere and run perl activeperl‑copy.pl from that directory.

For Win32::CLR try http://www.sommarskog.se/AbaPerls/Win32-CLR-0.04.zip. Install as above.

It's not that I build new binaries the day the new Perl version comes out, so you may not find anything in these places. If you have Visual C++ installed, you can attempt to build the modules yourself. For Win32::CLR it is as easy as open the Visual Studio Command Prompt and go to C:\AbaPerls\Prereqs\Win32‑CLR‑0.04 and run:

perl makefile.pl
nmake
nmake test
nmake install

At least it's easy as long as everything works. Win32::SqlServer follows the same pattern but requires some more precautions. Please see the README in that directory for details.

Setting Up AbaPerls

One more thing 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 check box Environment variables at the bottom.

First find the PATH variable and add C:\AbaPerls\Perl; first to the string. Pay attention to adding a semicolon before the next component in the variable. Also be careful not to add any extraneous spaces.

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

You don't need to restart Windows for the settings to have effect, but the change only affects application you start after the change.

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.0294 of AbaPerls.
For help on AbaPerls see F:\Utveckling\AbaPerls\Perl\Doc\index.html.

Unknown option: nisse
   abasql {-database db [-Server server] [-User anv] [-Password pwd] | -noexec}
   [-get] [-VC VC-path [-nouse_disk]] [-label version]
   [-log file] [-save [file]] [-subsystem subsys] [-nocreate] [-force]
   [-[no]crypt] [-[no]subscriber] [-site site-id:s]
   [-[no]Adefaults] [-[no]Anulls] [-[no]Apadding] [-[no]Aquoted]
   [-[no]quoterepl] [-Macro &macro=value [...]] [-undef &macro [...]]
   [-onlylabel regexp] [-notlabel regexp]
   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.0294 or not printed at all, you have an outdated installation.

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 name as long as they unambiguous. (Often one letter suffices). 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 ‑rebuild.)

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.0294. 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. Make sure that you have the appropriate Perl version, as described above.
  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. Go to the Prereq directory and install Win32::CLR and Win32::SqlServer as described above.

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

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.