Chat now with support
Chat with Support

InTrust 11.3.1 - Customization Kit

TextStream

NAME

TYPE

DESCRIPTION

Read([count])

method

Returns a single character (by default) or the specified number of characters according to the current encoding.

ReadLine()

method

Gets a line from the file.

Close()

method

Closes the file. If you do not close the file explicitly, it will be automatically closed during the next garbage collection session.

AtEndOfStream

property

Returns true if the file pointer is at the end of a TextStream file; false otherwise. Read-only.

TellG

property

Returns the number of bytes read from the stream and dispatched into the script. Not aligned to internal buffer boundary.

TimeOfDayInfoObject

NAME

DESCRIPTION

elapsedt

Specifies the number of seconds since 00:00:00, January 1, 1970, GMT.

msecs

Specifies the number of milliseconds from an arbitrary starting point (system reset).

hours

Specifies the current hour. Valid values are 0 through 23.

mins

Specifies the current minute. Valid values are 0 through 59.

secs

Specifies the current second. Valid values are 0 through 59.

hunds

Specifies the current hundredth of a second. Valid values are 0 through 99.

timezone

Specifies the time zone of the server. This value is calculated, in minutes, from Greenwich Mean Time (GMT). For time zones west of Greenwich, the value is positive; for time zones east of Greenwich, the value is negative. A value of -1 indicates that the time zone is undefined.

tinterval

Specifies the time interval for each tick of the clock. Each integral integer represents one ten-thousandth of a second (0.0001 second).

day Specifies the day of the month. Valid values are 1 through 31.

month

Specifies the month of the year. Valid values are 1 through 12.

year

Specifies the year.

weekday

Specifies the day of the week. Valid values are 0 through 6, where 0 is Sunday, 1 is Monday, and so on.

See also the example for the SystemInformationObject object.

InTrust-Specific Objects

Glossary

An InTrust organization parameter is a setting that affects some aspect of InTrust operation related to agents, jobs, licenses and so on. In InTrust Manager, these settings can be configured in the properties of the InTrust root node, an InTrust server or an agent.

A facet is a file with an agent's organization parameter settings. An agent has one facet per InTrust server; if an agent responds to multiple servers, it has multiple facets. The file is located in the config subfolder of the agent installation folder, and the file name is the GUID of the server from which the agent inherits organization parameter settings.

A facet can contain organization parameter values defined at the following three levels:

  1. Organization level, if any parameters are inherited all the way down

  2. Server level, if any parameters are defined for the InTrust server and inherited by the agent

  3. Agent level, if any parameters are defined specifically for the agent

Organization parameter settings can be read using the ADCEnvironment object. See Organization Parameter Editor for details about setting parameter values for organizations, servers and agents.

Generic Objects

Audit Script Object Model

The following objects are available to scripts in custom text log data sources. In addition, these data sources can use all objects available to custom scripted data sources.

Script Callbacks

Provider callbacks

NAME

DESCRIPTION

Audit_EnumInstances(host)

Returns a two-dimensional string array, where the nested arrays have two elements. Element [i][0] is the name of the i-th instance and element [i][1] is a display name. For Windows computers, the display name is the NetBIOS name. For Unix computers, it is the localhost name.

The host parameter can be one of the following:

  • Empty string for localhost

  • Host name

  • IP address

Audit_BeforeCollection

No return value.

Audit_Connect(instance, log)

Boolean.

Audit_Seek(position)

Boolean. A Position object is passed to this function. Audit_Seek uses the object to determine which event gathering stopped at when data was last collected.

If the precise position is found, true is returned, otherwise false is returned. If the result is false, InTrust session details will show that the position cannot be found.

Audit_CollectEvents()

Returns an object which is a collection of user-supplied properties. Performs log gathering.

Audit_AfterCollection(success)

No return value.

 

Comparer callback

NAME

DESCRIPTION

Audit_ComparePositions(p1, p2)

Returns a signed integer indicating the ordering of p1 and p2.

  • >0 if p1 > p2

  • 0 if p1 == p2

  • <0 if p1 < p2

where p1 and p2 are Position objects.

Audit Script Engine and Audit Script Host Cooperation

The audit script engine exposes a C++ interface to ECMAScript.

This interface does the following:

  • Supports the scripting object model

  • Dispatches calls between the audit script host and the scripting machine

  • Converts parameters from C++ types to scripting types and vice versa

Type conversion takes place as follows:

  • C++ type to script callback:

CONVERTED FROM

CONVERTED TO

AuditScriptEngine::EnumInstances

script::Audit_EnumInstances

AuditScriptEngine::GetDataName

script:: Audit_GetDataName

AuditScriptEngine::BeforeCollection

script:: Audit_BeforeCollection

AuditScriptEngine::Connect

script:: Audit_Connect

AuditScriptEngine::Seek

script:: Audit_Seek

AuditScriptEngine::CollectEvents

script:: Audit_CollectEvents

AuditScriptEngine::AfterCollection

script:: Audit_AfterCollection

  • Script object model to C++ type:

CONVERTED FROM

CONVERTED TO

AuditProvider::SubmitEventPositionPair

AuditScriptHost:: SubmitEventPositionPair

AuditProvider::LogMessage

AuditScriptHost::LogMessage

AuditProvider::OperationStatus

AuditScriptHost::OperationStatus

AuditProvider::Trace

AuditScriptHost::Trace

Audit Script Position Processor and Audit Script Host Cooperation

Audit script position processor is a middle layer between Audit script host and position comparer script. Audit script position processor should dispatch calls from AuditScriptPositionProcessor::ComparePositions to the script's Audit_ComparePositions callback.

Error Reporting

Audit script engine errors can be reported in two ways:

  • Using the ErrorInfo object (the result is written to the InTrust Server log)

  • As exceptions of the ADCException type for the audit script host to catch (the result is included in the InTrust session information)

Notes about exceptions:

  • Scripting callbacks should raise a JScript exception if they encounter any exceptional situation.

  • The audit script engine should catch such exceptions, translate them to ADCException objects and throw them again as C++ exceptions.

  • Script exceptions are translated into C++ exceptions. Exception information appears in session details.

  • The audit script position processor has the same error handling model as the audit script engine.

ADCEnvironment

The object is used for reading InTrust organization parameter settings from agents. This object is available only with the ECMAScript object model.

Methods

NAME

DESCRIPTION

EnumFacets()

Enumerates the facets available for an agent and returns an array of facet names.

GetEnvironmentValue([Facet,] Name)

Returns the value of the specified organization parameter.

The optional Facet string argument is the name of a facet, as returned by the EnumFacets() method. If this argument is not specified, the method returns the organization parameter value from the first available facet.

The Name string argument is the name of the organization parameter value.

GetEnvValueWithDefault([Facet,] Name, DefValue)

Returns the value of the specified organization parameter. This method is different from GetEnvironmentValue() in that you can specify a default return value with the DefValue argument. This default value is returned if the specified organization parameter is not found, so you do not have to perform any exception checks in your code.

The optional Facet string argument is the name of a facet, as returned by the EnumFacets() method. If this argument is not specified, the method returns the organization parameter value from the first available facet.

The Name string argument is the name of the organization parameter value.

The DefValue argument is a string or an integer.

ExpandEnvironmentString(String)

This method expands the name of the supplied InTrust-specific environment variable, such as %ADC_INSTALL_PATH% or %ADC_DATA_PATH%.

Example

Running the following script in a single-server InTrust organization:

var objEnv = new ADCEnvironment();
var Facets = objEnv.EnumFacets();
for(var i = 0; i < Facets.length; i++)
{
   var cputhrottling = objEnv.GetEnvValueWithDefault(Facets[i], "ADC_AgentCPUThrottlingValue", 100);
   Trace(40, "Facet: " + Facets[i]);
   Trace(40, "CPU: " + cputhrottling);
}
var datapath = objEnv.GetEnvironmentValue("adc_data_path");
Trace(40, "Data Path: " + datapath);
var taskpath = objEnv.ExpandEnvironmentString(datapath + "\\tasks");
Trace(40, "Tasks Path: " + taskpath);

will produce results similar to the following in the trace file:

(  392) Thu_Aug_23_21.12.32.437_2007 | 40 | [027035d8] ScriptContext_SM: Facet: {ae146e4d-9fc4-47ae-97e0-bf5cb55b0890} (string)

(  392) Thu_Aug_23_21.12.32.437_2007 | 40 | [027035d8] ScriptContext_SM: CPU: 100 (string)

(  392) Thu_Aug_23_21.12.32.437_2007 | 40 | [027035d8] ScriptContext_SM: Data Path: %ADC_INSTALL_PATH%/data (string)

(  392) Thu_Aug_23_21.12.32.437_2007 | 40 | [027035d8] ScriptContext_SM: Tasks Path: C:\WINNT\ADCAgent/data\tasks (string)

Related Documents