Support

Logging messages to the adTempus Job Log

Article ID: K00000264
Last Updated: June 12, 2007

Applies To

adTempus 2
adTempus 3

Summary

The adTempus Job Log reports information about the execution of jobs in adTempus. adTempus itself writes messages to the log, but it is also possible for programs and scripts run by adTempus to write to the log. For example, if your program encounters an error, you may want that program to write an error message to the job log, so that system operators can review the information from the adTempus Console, without the need to review log files or other output from your program.

Logging from adTempus-hosted scripts is available in all versions of adTempus. Logging from external scripts, programs, and batch files is available beginning in adTempus version 2.1.

Details

This documentation covers three different logging scenarios:

Logging from an adTempus-hosted script (a script run by a Script Execution Task, or any other "internal" script, such as a Response script).
Logging from a batch file.
Logging from an external program or script (a program or script run by a Program Execution Task).

Logging from an adTempus-Hosted Script

The ability to log messages from within an adTempus-hosted script is available in all versions of adTempus. When your script is run by adTempus, a global function named LogMessage (for VBScript and JScript) or adTempus.LogMessage (for VB.NET and C#) is exposed for your script. This function has the following syntax:

LogMessage messageType, messageCode, message

The parameters are as follows:

messageType: An integer indicating the type of message to report. Use one of the following values: 1 (Informational), 2 (Warning), 8 (Error), 16 (Fatal).
messageCode: An integer indicating the application-defined code for this message. The message code can be used to search for specific messages in the Job Log. You can specify any value you wish, or use 0 if you do not want to assign message codes.
message: The text of the message to log.

Logging from a Batch File

Beginning with version 2.1, adTempus includes a utility program called "adtlogmessage.exe" (found in the adTempus program directory) that can be called from a batch file (or spawned from another application) to log a message to the Job Log. This utility can only be run if the batch file (or program) that calls it is being run as part of an adTempus job.

The adtlogmessage utility has the following command-line syntax:

adtlogmessage "message" [messageType] [messageCode]

The parameters are as follows:

message: The text of the message to log. Be sure to enclose the message in quotes.
messageType: An optional string indicating the type of message to report. Use one of the following values: Informational, Warning, Error, Fatal.
messageCode: An optional integer indicating the application-defined code for this message. The message code can be used to search for specific messages in the Job Log. You can specify any value you wish, or omit this parameter if you do not want to assign message codes.

Logging From an External Program or Script

Custom application and script developers can integrate adTempus logging capability into their applications using the adTempus API. Note that an application can only log messages to adTempus when the application is being run by adTempus.

The following sections explain how to do this in various programming environments.

Logging From a .NET Application

A .NET application must reference the ArcanaDevelopment.adTempus.Server assembly, which is installed in the Global Assembly Cache. The following VB.NET code demonstrates how to log a message.

Dim engine As ArcanaDevelopment.adTempus.Server.Engine
Dim session As ArcanaDevelopment.adTempus.Server.ApplicationIntegration

'Obtain an interface to the adTempus Engine, hosted by the adTempus service.
engine = New ArcanaDevelopment.adTempus.Server.Engine

'Get the ApplicationIntegration interface, which exposes the LogMessage method.
'Note that the value of the ADTSessionToken environment variable is passed in this call.
'This token allows adTempus to identify which job is requesting the interface, so that
'the returned ApplicationIntegration object will log messages for the correct job.
session = engine.GetIntegrationInterface(Environment.GetEnvironmentVariable("ADTSessionToken"))

'Log the message
session.LogMessage(ArcanaDevelopment.adTempus.Server.ADErrorSeverity.adetInformational, 0, "Test program here!")

Logging from VBScript

A VBScript script can log messages using the following code:

Dim engine
Dim session
Dim WshShell 

'Get a shell instance so the environment variable can be read.
Set WshShell = WScript.CreateObject("WScript.Shell")

'Obtain an interface to the adTempus Engine, hosted by the adTempus service.
Set engine=CreateObject("adTempussrv.Engine.1")

'Get the ApplicationIntegration interface, which exposes the LogMessage method.
'Note that the value of the ADTSessionToken environment variable is passed in this call.
'This token allows adTempus to identify which job is requesting the interface, so that
'the returned ApplicationIntegration object will log messages for the correct job.
set session=engine.GetIntegrationInterface(WshShell.Environment("Process").Item("ADTSESSIONTOKEN"))

'Log the message
session.LogMessage 1, 0, "Test program here!"