ARSperl: ARS2.x-3.0 / Perl5 integration kit

Overview

ARSperl is an integration kit for Perl5.x and Remedy ARS 2.x and 3.0 API. It provides a subset of the functionality found in the ARS C API. The source code to the integration kit and example scripts is made available under the GPL.

We hope that other ARS fans find the kit useful.

Version

The current release it Version 1.53 and will compile against ARS 2.0, 2.1 and 3.0 API libraries.

Release Notes

1.53

minor doc fixes

1.5206 (beta)

added ars_GetVUI to the ARS.pm exports line.
added refreshCode to GetCharMenu hash
fixed bug in groupList value change in 1.5205

1.5205 (beta)

updated groupList returned by GetSchema() call so that it contains the correct keywords.

1.5204 (beta)

added ars_GetControlStructFields()

1.5203 (beta)

beginnings of a WinNT port (not completed yet)
added "timestamp" to the return hash of GetEscalation()
added some extra malloc/free debugging stuff

1.5202 (beta)

removed some debugging code that was left in

1.5201 (beta)

fixed problem in GetEscalation

1.52 (beta)

fixed core dump problem due to uninitialized variable(s)

1.51 (beta)

fixed some typos/symbol errors. added a missing routine.

1.50 (beta)

removed ars_errstr from C code. replaced with ars_errhash. modified ARS.pm to refer to hash when $ars_errstr is accessed. $ars_errstr no longer tie'd to main:: package.
bug fix (Sid Van den Heede) "affecting getting of displayInstanceList"
bug fix (James LewisMoss) for ars_GetCharMenu()
bug fix (Ian Flanigan) for perl_ARIndexStruct()
modified GetListEntry(), GetEntry(), SetEntry() and DeleteEntry() to make operations on join schemas transparent.
added a ARVerifyUser call to ars_Login so that ars_Login() || die() will work as one would expect it to.
added $VERSION to the perl module file.
added "log to file" action to GetFilter action hash (requested by D.J.Adams@soton.ac.uk)
added updated doc tree to main distribution (contributed by D.J.Adams@soton.ac.uk)
new functions and doc on new functions and new examples for some of these new functions.
altered return value of perl_ARStatusStruct so that it returns a hash of the various StatusStruct members so that reversing the operation is simpler. scripts that, for example, retrieve active link definitions and print them out that previous expected the {message} key to point to a string will need to be updated.
added valueType to the assign structure to assist in reversing the operation (converting perl to C API assign structure).
added displayTag as an optional parameter to ars_LoadQualifier() so that you can build queries against customized views (that are stored on the server).

1.46

bug fixes
ars_MergeEntry() added

1.45

minor bug fix to the GetListSchema routine

1.44

added some extra code to assist in decoding qualifier structures
included PrintQual.pl and ars_QualDecode.pl examples to show how to do it.
modified GetFilter.pl example to dump the qualification that is on the filter.

1.43

fixed some bad pointer/bad free problems

1.42

Minor bug fix for HP-UX
Compiled with -Wall and cleaned up quite a few questionable pieces of code.
Added destructors for the package that will correctly call ARTermination() when the script exits.

1.41

Bug fixes to 1.4
Added ars_GetCurrentServer()
Modification made to ars_Login() (suggested by Peter de Salis)
NT (notifier) function documentation add to programmer's guide.

1.4

Bug fixes to 1.32
NT (notifier) functions added.
Improved documentation.

1.32 (beta)

ARS3.0 integration

1.31

minor fix to allow v1.3 to work with ARS2.0

1.3

Profiling code added to keep track of number of queries made.
Field caching code added to make some of the functions more efficient.
New functions: ars_GetFilter(), ars_GetCharMenu(), ars_GetServerStatistics
Internal GetField call now caches results to minimize number of queries made.
Examples of new functions.
"WhoUsesIt.pl" utility

1.22

fixed the bug in arsperl that caused SetEntry to not always work correctly. The bug only appeared when you passed that fields in an array.

Support OS's

The perl extension has only been tested on the following OS's:

Solaris 2.x
SunOS 4.x
Irix
HP-UX
AIX

FAQs

We have some useful excerpts from the mailing lists online.

Bug Reports

If you come across a bug (i.e. it crashes with a SEGV or something like that) you can report them to:

arsperl-bugs@smurfland.cit.buffalo.edu

Be sure to include the following information in your message:

OS (operating system) version (example: Solaris 2.5)
Perl version (example: 5.003)
ARS version (example: 2.1.3)
ARSperl version (example: 1.42)

A fragment of the script that causes the crash.
Example:

       ars_CreateEntry($ctrl, $schema, $id, $val, $id2, $val2);

The values of any parameters that you pass to the call that fails.
Example:
```
        $schema = "AD-Help Desk"
        $id = 12345678
        $val = "foo"
        $id = 24681357
        $val = "yadda"
       
```
The best way to obtain these values is to use a "print" statement right before the call that fails.

If you have any other questions or comments you should subscribe to the mailing list and ask them there.

Mailing List

A mailing list is available for discussions of this perl extension. Archives of the mailing list are also available.

How to subscribe

Send an email message to majordomo@lurch.cit.buffalo.edu with a body of ``subscribe arsperl''. The subject line is ignored.

Installation

Utilities

Utilities that we've written with ARSperl that are handy to have. These can be found in the examples directory of the distribution.

WhoUsesIt.pl
A script to help you track down filters, schemas etc. Good for when you try to document your system layout.
DumpSetup.pl
A utility for maintaining backup copies of server definitions (when run nightly as a cron job).

Programmer's Guide

An online guide is available to help use the functions that this kit adds to the standard perl distribution.

Last Updated: 13 Jan 96
arsperl@smurfland.cit.buffalo.edu

The Remedy Logo is a trademark of Remedy Corporation.