Running AbaPerls on Your Machine

This page decsribes how to set up your machine so you can run AbaPerls on it, and a general overview on how to run the tools.

Contents:
Setting Up Your Machine for AbaPerls
Running the AbaPerls Tools

Setting Up Your Machine for AbaPerls

(Users outside the AbaSec sphere will have to accept that this section contains some material which is local to AbaSec. Just read through to the end anyway.)

First, determine where the Perl binaries and the AbaPerls .BAT files are installed at your site. Consult your local administrator, if you do not know this. If you are an administrator yourself, and have not yet installed AbaPerls at your site, read the page Downloading and installing AbaPerls on how do this, and also learn how to find Perl.

If you work in the AbaSec group, the Perl binaries are in Y:\PERL\BIN and the AbaPerls .BAT files are in Y:\ABAPERLS. For the remaining of this section, we will use these two values; non-ABaSec readers should understand these strings as placeholders for the locations at your site.

To set up AbaPerls on your machine, open the System applet in the Control Panel and find the dialogue to set environment variables. (the exact location of this dialogue varies somewhat between the various versions of Windows) and make these changes:

Modify PATH to include Y:\PERL\BIN and Y:\ABAPERLS. Put these first in your PATH.
Add the variable PERLLIB with the value of Y:\ABAPERLS.

Be careful to use the values exactly as above. Particularly extraneous spaces can be deceivable. (There should be no spaces at all.) Press OK until you are out from the applet.

To start using AbaPerls, you don't need to reboot the machine, but beware that the new/changed variables do not propagate to running programs and open command-line windows. Thus, if you have TextPad running, you must restart the editor before you can access AbaPerls from TextPad. (The same is applies to any other external editor you might be using.) If you have a command-line window open, you can change PATH and PERLLIB locally in that window rather then closing the window and open a new one.

If you are working remotely, or want to be able to use AbaPerls on your laptop when you are disconnected the following applies:

Copy the Perl installation on Y: to your local machine. If you got a Perl installation with your machine, just delete it, as it may not be correct. The Perl on Y: includes an add-on for connection to SQL Server. It does happen that changes in AbaPerls requires a new Perl version, but this happens rarely.
If possible, try running AbaPerls tools from Y:. They are small in size, and there are frequent updates. If you copy to your local machine, you will need to set up a mechanism, so that your local installation is updated when you are connected to Y:.

To test that you have everything set up correctly, open a Command-Prompt window and say perl -v. The output should be something like:

This is perl, v5.8.7 built for MSWin32-x86-multi-thread
(with 7 registered patches, see perl -V for more detail)

Copyright 1987-2005, Larry Wall

Binary build 813 [148120] provided by ActiveState http://www.ActiveState.com
ActiveState is a division of Sophos.
Built Jun 6 2005 13:36:37

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 attention to the version and build numbers, and check with the above, so that you are not using a version that is outdated with regards to AbaPerls. If you are using ActivePerl, the build number should be at least 809.

Next, to check that AbaPerls is set up properly, say:

abasql -nisse

This should yield the response:

This is label L1.0.0190 of AbaPerls.
Unknown option: nisse
abasql -database db [-Server server] [-User anv] [-Password pwd]
       [-VSS VSS-path [-nouse_disk]] [-label version] [-log file]
       [-save [file]] [-subsystem subsys] [-nocreate] [-force]
       [-charset CP] [-[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.

Also, pay attention to the label (the first line in the message). If this label is lower than L1.0.0054 or not printed at all, you have an outdated installation. Note that the opposite does not necessarily not apply: 1) This page may not have been updated with the latest label. 2) Changes in AbaPerls that only affect the Perl code, does typically not result in a new label.

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 AbaPerls is in your path. (See above.) Most of the commands takes switches. The switches have long names, but you can abbreivate 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 three connection switches, -Server, -Password and -database, AbaPerls will never introduce new switches that prevents use of -S, -P or -d. Thus you can rely on this particular three 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 last, and in the order given in the syntax definition.