Host Integrator Log Extraction Utility: logexport

The Host Integrator logexport command line utility allows an administrator to securely perform detailed queries against the Host Integrator Log Manager.

• The utility can be run from any host on the network. (Windows or UNIX)
• Access control is integrated with the Host Integrator security architecture.
• Queries are specified through a flexible SQL SELECT expression.
• The output format is configurable and parseable by other applications.
• The utility can perform bulk extracts of messages form the Host Integrator logging system.

There are several log options available in Verastream Host Integrator.

Operation

The logexport utility can be found in the bin directory of the Host Integrator installation. You can run it from this location, or you can add this directory to your PATH for easy access. The utility has a variety of command line switch options.

Help on available options can be obtained with the use of the command line switch -help.

logexport -query sql [ -delim delim_char ] [ -escape esc_char ]
                  OR
          -purge msgserial

          -server servername
          -store ( aa | ds | vhis )
          [
            -aads aadsname
            -user username
            -password userpass
            -profile ( Administrator | Developer )
          ]
          [ -config filename ]

The utility performs two primary functions:

• Query a message store for messages. (-query switch)
• Purge old messages from a message store. (-purge switch)

One of these options must be specified, but they are mutually exclusive. The -server switch and -store switch are also required. These options specify which Log Manager to contact and which message store to operate against, respectively. Currently, up to three different message stores can be managed within the Host Integrator logging system:

• Authentication and Authorization Log - (-store aa)
• Directory Services Log - (-store ds)
• Host Integrator Server Log - (-store vhis)

If security is enabled on the Host Integrator installation in question, logs are protected from access from unauthorized users. Access to the logs under these circumstances requires a user to authenticate with AADS. The options -aads, -user, -password, -profile are required in these cases. Both administrators and developers can perform queries against the logs, but only administrators can execute message purges. If security is not enabled on a Host Integrator installation, this set of options is not required.

Querying Messages

The -query option takes a SQL select statement which specifies which messages you want to see. For example:

logexport -server s1 -store vhis -query "select msgtime, msgtext from messages"

This invocation will contact the Log Manager running on host "s1" and output the message time and message text of all messages currently in the Host Integrator server logs. The results will be directed to standard out. Any errors that occur will be directed to standard error. Columns of output will be separated with the "|" character.

Along with the -query option, two optional parameters can be specified, -delim and -escape. Each of these options takes a single character. Use the -delim switch to specify the character used to separate columns in the output. It is the "|" character by default. Use the -escape option to specify the character used to escape occurrences of the column delimiter that occur within any column of message data. It is the "\" character by default.

For details on the SQL supported by the Host Integrator logging system, see SQL Dialect of the Host Integrator Logging System.

Within the SELECT statement, specify the columns of the message entry desired in the output, and the order they will appear. To specify all columns in the default order, use "*" as the column identifier.

Each message entry has the following columns available:

The SQL SELECT statement optionally can contain a WHERE clause that allows the user to specify complex matching criteria on the message entries they desire to see.

Purging Messages

If this utility is used to perform a bulk extract of messages from the Host Integrator logging system, you will need the ability to purge messages from the system after they have been safely loaded into another database or application. All messages within a message store are tagged with a unique serial number that can be obtained by specifying the msgserial column in a query. This column is the message's primary key. The -purge option takes a message serial number, and deletes all messages in the specified message store, up to and including the serial number specified. For example:

logexport -server s1 -store vhis -purge 1234

This example deletes all messages with a msgserial number less than or equal to 1234 from the Host Integrator Server log on machine "s1".

Note: If security is enabled on the Host Integrator installation, the -aads options must be used to obtain Administrator level access for this command to succeed.

Advanced Features

Due to the relatively large number of available switches on the logexport utility, especially when security is enabled on the Host Integrator installation, you may want to specify run-time arguments from a configuration file. Specify the file containing run-time options on the command line. To employ this feature, create a file containing the desired options, and specify the path to the file as the argument to the -config switch.

logexport -config sample.config

Any switch that can be specified at the command line, with the exception of the -config switch, can be placed in the config file. The format of the file is shown below:

#
# Comments look like this.
#
# Line tags are the same as switch names.  Any number required can 
# be specified in the file.
#
# server
# store
# query
# purge
# delim
# escape
# aads
# user
# password
# profile
# 
# Here are some real entries.
#
server=s1
store=aa
query=select msgtext from messages

logexport -config myconfig -server somepc

In the above example, logexport will contact server "somepc" regardless of whether "server" is specified in the file "myconfig".

© 1999-2007 Attachmate Corporation. All rights reserved. Terms of Use.