Perl API
Contents
Copyright 2005 GroundWork Open Source Solutions, Inc. ("GroundWork").
All rights reserved. Use is subject to GroundWork commercial license.
Perl API Overview
The Perl API is a module called CollageQuery that allows a Perl program to retrieve data from Collage. The following classes and methods are available.
Classes and Methods

CollageQuery
new Create the CollageQuery object. Required to use any of the following methods.
destroy Destroy's the CollageQuery object. Should be called when the CollageQuery object is no longer needed.

CollageHostGroupQuery
getServicesForHostGroup(String hostGroup) Return a reference to a hash host-service-attributes for a designated host group.
getHostsForHostGroup(String hostGroup) Return a reference to a hash of all host names, device name for a designated host group.
getHostGroups() Return a reference to all hostgroup names, descriptions.
getHostGroup(String hgName) Return a hash containing the attributes for a host group.

CollageHostQuery
getServicesForHost(String host) Return an reference to a hash of all services-attributes for a host.
getHosts() Return a reference to a hash of all host-attributes.
getHostStatusForHost(String host) Return a hash of all the status attributes for a host.
getDeviceForHost(String host) Return a hash of the device attributes for a host.

CollageServiceQuery
getService(String serviceName, String hostName) Return a hash of service attributes
getServices() Return a reference to a hash of host-service-attributes

CollageMonitorServerQuery
getMonitorServers() Return a reference to a hash of monitorserver-attributes.
getHostsForMonitorServer(String MonitorServer) Return a reference to a hash of hosts for a designated monitorserver.
getHostGroupsForMonitorServer(String MonitorServer) Return a reference to a hash of host groups-attributes.

CollageEventQuery

 Returns a reference to a hash of events with the event ID as primary key and attributes as secondary key. Note: timeField (String) can be FirstInsertDate or LastInsertDate if it's null no range will be applied.

getEventsForDevice(String identification, String timeField, Date fromDate, Date toDate)
getEventsForService(String serviceDescription, String HostName, String timeField, Date fromDate, Date toDate)
getEventsForHost(String HostName, String timeField, Date fromDate, Date toDate)
Sample Using Collage Query Module
The following code is a sample of using the CollageQuery module.
# Use the CollageQuery module use CollageQuery ; # Declare the CollageQuery object my $t; # Create an object and make sure we can connect to Collage if ($t=CollageQuery->new()) { print "New CollageQuery object.\n"; } else { die "Error: connect to CollageQuery failed!\n"; } # Print the attributes for a host group "demo-systems" $getparam = "demo-systems"; # getHostGroup returns a hash of attributes and values my %hash = $t->getHostGroup($getparam); foreach my $key (sort keys %hash) { print "\t$key=$hash{$key}\n"; } # Now print the services and attributes for a host $getparam = "demo-host"; # getServicesForHost returns a reference to a hash of service hashes my $ref = $t->getServicesForHost($getparam); # Iterate for each service foreach my $service (sort keys %{$ref}) { print "\tService=$service\n"; # Now iterate for each attribute. foreach my $attribute (sort keys %{$ref->{$service}}) { # print the attribute and attribute value print "\t\t$attribute=".$ref->{$service}->{$attribute}."\n"; } } # Finished so destroy the object $t->destroy();
The samples that use the Perl CollageQuery API are:
test1.pl This script exercises each method in the API. It is invoked via command line and returns the result to STDOUT.
api_sample2.pl This is a CGI program that allows you to select the Collage class and method to test. The drop down selection lists use the API to give you options from the Collage data store. The form will show the results of the query.
api_sample3.pl This is a modified version of api_sample2.pl that outputs data in a more user-friendly form.