Administer > Monitoring > Policy Templates > Policy Objects for Scripts

Policy Objects for Scripts

The objects listed here are available for scheduled task policieseach policy and can be manipulated with Visual Basic Scripting Edition or with Perl. These policy objects can only be used in scripts that run within a policy. They cannot be used in standalone scripts that are executed at a command prompt.

Caution Policy scripts provide administrators with a powerful tool to evaluate and manipulate data. If, however, a script is incorrectly written, it could cause the agent to fail. Hewlett-Packard Company is not responsible for agent failures resulting from incorrectly written scripts.

ClosedPolicy Object

This object is used to access the attributes of a policy.

Policy Method: Source
Parameter: name (The Short name indicated in the policy's source properties.)
Return Type: VB Script: IDispatch object of type "Source" (This is the default method for the Policy object.)
Perl: source object
VB Script Syntax: Policy.Source("name")
Perl Syntax: $Policy->Source("name");
Description: Returns the source object for the defined source and metric. Measurement type sources must use a separate source for each metric.

Note To improve performance, assign the source object to a variable instead of using the Source method every time it is needed.

Policy Method: Name
Parameter: void
Return Type: VB Script: BSTR, Perl: string
VB Script Syntax: Policy.Name()
Perl Syntax: $Policy->Name();
Description: Returns the name of the policy that started the script.

Policy Method: CreateObject
Parameter: progID (string of format: [Vendor.]Component[.Version])
Return Type: VB Script: IDispatch   Perl: not applicable
VB Script Syntax: Policy.CreateObject("progID")
Perl Syntax: not applicable
Description: Creates a component instance of a COM object. Note that this method is valid only on Windows nodes, and cannot be used in a Perl script.

Policy Method: SourceEx
Parameter: expression (See Description, below, for valid expressions.)
Return Type: VB Script: IDispatch object of type "Source"   Perl: source object
VB Script Syntax: Policy.SourceEx("expression")
Perl Syntax: $Policy->SourceEx("expression");
Description:

Returns the source object instance of the source defined by the expression. This source object is identical to the object returned by the Policy.Source method, but because it does not have to be configured in the policy, it can be used for scheduled tasks, as well as for measurement threshold policies. The expression can have the following format depending on which component the performance metric will be collected from:

  • NTPERFMON\\Object\\Counter\\Instance

    Access a perflib metric (not supported on UNIX nodes). Object, Counter, and Instance are strings as specified in the current monitor configuration for NT performance monitors.

    Example: NTPERFMON\\Process\\Elapsed Time\\*

  • SNMP\\object id[\\hostname]

    Perform an SNMP get on the specified object id (OID). By default, the collection will be done on the managed node but can be elsewhere if the optional hostname is given. For SNMP, the method will have to wait until the value is returned which might take some time

    Example: SNMP\\.1.3.6.1.2.1.1.7.0\\onion.veg.com

  • PROGRAM\\command[\\monname]

    Run the specified command or script for gathering the monitored value. The command or script must at some point run the opcmon command to return the value associated with the monitor. If no monitor name is specified, then the default DynPROGRAM must be used. For example, to specify the monitor mymonname: opcmon mymonname=value; to specify the default, opcmon DynPROGRAM=value.

    Examples:
    PROGRAM\\opcmon DynPROGRAM=12
    PROGRAM\\opcmon testmon=25\\testmon

  • EXTERNAL[\\monname]

    Wait for a value returned by the execution of the opcmon command. This is similar to the PROGRAM expression but a command is not directly carried out. An external command previously triggered by the ExecuteCommand object must provide the monitor value. The default value is DynEXTERNAL (opcmon DynExternal=10)

    Examples:
    EXTERNAL
    EXTERNAL\\testmon

  • WBEM\\namespace\\class name\\property name

    WMI interface (not supported on UNIX nodes). Get access to WBEM values. Namespace, class name and property name are strings as specified in the current monitor configuration for WBEM.

    Example: WBEM\\ROOT\CIMV2\\Win32_PerfRawData_PerfDisk_LogicalDisk\\DiskReadBytesPersec

  • CODA\\data source\\collection\\metric name

    Query a metric from the embedded performance component. Data source, collection and metric name are strings as specified in the monitor configuration for the embedded performance component. Currently if the data source is empty, the string Coda will be used.

    Example: CODA\\\\CPU\\BYCPU_CPU_TOTAL_UTIL

    You can view a of list of available metrics in the Performance Agent Dictionary of Operating System Performance Metrics which is available at HP Software Product Manuals. (Select the product Performance Agent, the required version, OS, and language.)

    Note In Perl, the backslash character '\' is an escape code. A backslash is only introduced in a string when preceded by another backslash. Because of this, tokens in expressions need to be separated by quadruple backslashes '\\\\'. Example for Perl: my $TestSource = $Policy->SourceEx("PROGRAM\\\\/tmp/script.sh\\\\testmon");

Policy Method SourceExTimeout
Parameter: seconds (integer)
Return Type: VB Script: void   Perl: void
VB Script Syntax: Policy.SourceExTimeout = seconds
Perl Syntax: $Policy->SourceExTimeout(seconds);
Description: Specifies the maximum amount of time, in seconds, the SourceEx and SourceCollection methods will wait before a value is returned. Default is 30 seconds.

Policy Method: Execute
Parameter: command (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: Policy.Execute("command")
Perl Syntax: $Policy->Execute("command");
Description: Run the specified command asynchronously. The command is executed in the context of agent security, so could be run as Local System or any other user-selected user to run the agent. The method will return immediately. See the ExecuteCommand method Command for more information about how to indicate commands.

Policy Method: Output
Parameter: string
Return Type: VB Script: void   Perl: void
VB Script Syntax: Policy.Output("string")
Perl Syntax: $Policy->Output("string");
Description: Appends the string to the annotation field of the event sent to BSM in response to the success or failure of a scheduled task. This method is valid only for scheduled task policies.

Policy Method: ExecuteEx
Parameter: command (string)
Return Type: VB Script: BSTR   Perl: string
VB Script Syntax: Policy.ExecuteEx("command")
Perl Syntax: $Policy->ExecuteEx("command");
Description:

Run the specified command synchronously and wait for it to complete before returning the output of the command.

  • Security. The command is executed in the context of agent security, so could be run as Local System or any other user-selected user to run the agent.

  • Return values. If the command is successful, STDOUT is returned. If the command is not successful (return value non-zero), the string "ERROR:\n" followed by STDERR will be returned.

    To handle non-zero return values, run ExecuteEx in an eval function and then check the result, for example for the string ERROR.

    Perl script example:

    eval '$ReturnText = $ExecuteCommand->ExecuteEx()';
    $ReturnText =$@ if $@;

  • Paths. You must use complete paths or ensure that any needed path is included in the PATH variable.

    Example: dir_con = Policy.ExecuteEx ("cmd /c dir c:\")

Policy Method: StoreCollection
Parameters:
  • expression: (An embedded performance component metric in the format:
    CODA\\data source\\collection\\metric name[\\category])
  • sourceobj: (Any valid source object)
Return Type: VB Script: void   Perl: void
VB Script Syntax: Policy.StoreCollection("expression", sourceobj)
Perl Syntax: $Policy->StoreCollection("expression", sourceobj);
Category Type:
Describes available Closedcategory types.

  • UNDEFINED: Ignored

  • NOTAPPLICABLE: Ignored

  • ATTRIBUTE: Static definitions or values, such as the OS name, version, release, physical memory, and CPU clock speed.

  • DELTA: Show the activity during the last interval, such as intervalized counts, rates, and utilizations.

  • GAUGE: Numeric value that shows the current use or value at the time of the observation, such as the run queue, number of users, and files system space utilization.

  • COUNTER: Cumulative counts of activity, such as CPU times, physical IOs, paging, network packet counts, and interrupts.
Description: Stores the source object into the embedded performance component data source identified by the expression. Example: Policy.StoreCollection "CODA\\DBSPI\\TABLE\\SPACE",Source

Policy Method: SourceCollection
Parameters:

  • expression: An embedded performance component metric in the format:
    CODA\\data source\\collection\\metric name.

  • rangeofseconds: The number of seconds for which metrics should be returned.

  • endtime: End time for rangeofseconds. The format of time is of type DATE for VB Script or a string (format DD/MM/YYYY HH:MM:SS) for Perl. The date is optional.

    Perl example for endtime: 

    my $currentDate = time();
    my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) 
= localtime($currentDate);
    my $currentDateStr = sprintf("%02d/%02d/%d %02d:%02d:%02d", 
$mday, $mon+=1,$year+=1900,$hour,$min,$sec);

    You can then use $currentDateStr as endtime.
Return Type: VB Script: IDispatch object of type "Source"   Perl: source object
VB Script Syntax: Policy.SourceCollection ("expression", rangeofseconds, endtime)
Perl Syntax: $Policy->SourceCollection ("expression", rangeofseconds, endtime);
Description:

Returns the source object containing all values collected by the specified embedded performance component metric. For each instance, all metrics collected between the expression "endtime - rangeofseconds" and "rangeofseconds" will be returned. If endtime is 0 (NULL for Perl) it is evaluated with the current time. Example: Policy.SourceCollection ("CODA\\\\CPU\\BYCPU_CPU_TOTAL_UTIL",300,0)The number of seconds specified should usually be less than 3600 (one hour), since retrieving a large number of values takes time and consumes resources.

ClosedSource Object

The source object is used to access the current values of the metrics. The source object instances can be created by any method that returns the source object.

Source Method: Value
Parameter: void
Return Type: VB Script: variant (This is the default method for the Source object.)
Perl: string
VB Script Syntax: Sourceobj.Value()
Perl Syntax: $Sourceobj->Value();
Description: Current instance value if the option Process each instance separately is selected in the policy's processing options.

Source Method: Name
Parameter: void
Return Type: VB Script: BSTR   Perl: string
VB Script Syntax: Sourceobj.Name()
Perl Syntax: $Sourceobj->Name();
Description: Returns the name of the current instance if option Process each instance separately is selected in the processing options of the measurement threshold policy.

Source Method: InstanceCount
Parameter: void
Return Type: VB Script: Int, Perl: integer
VB Script Syntax: Sourceobj.InstanceCount()
Perl Syntax: $Sourceobj->InstanceCount();
Description: Returns the number of instances that the source has.

Source Method: Count
Parameter: void
Return Type: VB Script: Int   Perl: integer
VB Script Syntax: Sourceobj.Count()
Perl Syntax: $Sourceobj->Count();
Description: Same as InstanceCount. This parameter exists to provide backwards compatibility.

Source Method: Item
Parameter: index
Return Type: VB Script: IDispatch object of type "Source"   Perl: source object
VB Script Syntax: Sourceobj.Item(index)
Perl Syntax: $Sourceobj->Item(index);
Description: Access to the instance defined by the index. The index is a number from 0 to InstanceCount - 1. The returned source object can be extracted using the Value and Name methods. This parameter exists to provide backwards compatibility.

Source Method: ValueOf
Parameter: index (integer)
Return Type: VB Script: variant   Perl: string
VB Script Syntax: Sourceobj.ValueOf(index)
Perl Syntax: $Sourceobj->ValueOf(index);
Description: Direct access to the value of the instance defined by the index. This method is useful for looping over all instances, if the option Process all instances once is defined. The index is a number from 0 to InstanceCount - 1.

Source Method: NameOf
Parameter: index (integer)
Return Type: VB Script: BSTR   Perl: string
VB Script Syntax: Sourceobj.NameOf(index)
Perl Syntax: $Sourceobj->NameOf(index);
Description: Direct access to the name of the instance defined by the index. The index is a number from 0 to InstanceCount - 1. This method is useful for looping over all instances, if the option Process all instances once is selected in the policy's processing options.

Source Method: Top
Parameter: number
Return Type: VB Script: IDispatch object of type "Source"   Perl: source object
VB Script Syntax: Sourceobj.Top(number)
Perl Syntax: $Sourceobj->Top(number);
Description: Returns a new source object instance that contains only the instances with the <number> highest values. For example, if these three instances exist: c: = 90%; d = 80%; e = 40% then Sourceobj.Top(2) returns c: and d:.

Source Method: Bottom
Parameter: number
Return Type: VB Script: IDispatch object of type "Source"   Perl: source object
VB Script Syntax: Sourceobj.Bottom(number)
Perl Syntax: $Sourceobj->Bottom(number);
Description: Returns a new source object instance that contains only the instances with the <number> lowest values. For example, if these three instances exist: c: = 90%; d = 80%; e = 40% then Sourceobj.Bottom(2) will return d: and e:.

Source Method: Exclude
Parameter: namepattern, valuepattern
Return Type: VB Script: IDispatch object of type "Source"   Perl: source object
VB Script Syntax: Sourceobj.Exclude("namepattern", "valuepattern")
Perl Syntax: $Sourceobj->Exclude("namepattern", "valuepattern");
Description: Returns a new source object instance excluding values specified by the patterns. You can specify two parameters, one for the name of the variable (type, object, and instance) and one for the value. Specify NULL if no matching is required for one argument. Patterns should be valid HPE Operations Agent pattern-matching expressions.

Source Method: Include
Parameter: namepattern, valuepattern
Return Type: VB Script: IDispatch object of type "Source"   Perl: source object
VB Script Syntax: Sourceobj.Include("namepattern", "valuepattern")
Perl Syntax: $Sourceobj->Include("namepattern", "valuepattern");
Description: Returns a new source object instance including only values specified by the patterns. You can specify two parameters, one for the name of the variable (type, object, and instance) and one for the value. Specify NULL if no matching is required for one argument. Patterns should be valid HPE Operations Agent pattern-matching expressions.

Source Method: Time
Parameter: void
Return Type: VB Script: DATE   Perl: string (format: DD/MM/YYYY HH:MM:SS)
VB Script Syntax: Sourceobj.Time()
Perl Syntax: $Sourceobj->Time();
Description: Returns the time when the expression was evaluated.

Source Method: TimeOf
Parameter: index (integer)
Return Type: VB Script: DATE   Perl: string (format: DD/MM/YYYY HH:MM:SS)
VB Script Syntax: Source.TimeOf(index)
Perl Syntax: $Sourceobj->TimeOf(index);
Description: Returns the time when the expression was evaluated for a specific instance. The index is a number from 0 to InstanceCount - 1.

Source Method: Add
Parameter: instancename, value
Return Type: VB Script: void   Perl: void
VB Script Syntax: Sourceobj.Add "instancename:",value
Perl Syntax: $Sourceobj->Add("instancename:",value);
Category Type:
Describes available Closedcategory types.

  • UNDEFINED: Ignored

  • NOTAPPLICABLE: Ignored

  • ATTRIBUTE: Static definitions or values, such as the OS name, version, release, physical memory, and CPU clock speed.

  • DELTA: Show the activity during the last interval, such as intervalized counts, rates, and utilizations.

  • GAUGE: Numeric value that shows the current use or value at the time of the observation, such as the run queue, number of users, and files system space utilization.

  • COUNTER: Cumulative counts of activity, such as CPU times, physical IOs, paging, network packet counts, and interrupts.
Description:

Adds the instance name to the source object and sets the value. If this instance is already part of the source object, the new instance will not be added and the value will be replaced. This method can be used on a newly created object or an object retrieved from any method returning a source object. This method is used to store data into the embedded performance component.

VB Script example:

set Sourceobj = Policy.CreateObject
   ("Ito.OvEpScriptMetric")
Sourceobj.Add "a:",10
Sourceobj.Add "b:",25
Policy.StoreCollection "CODA\\floppy
   \\disk\\space\\\\gauge",Sourceobj

Perl example:

my $Sourceobj = new Source;
$Sourceobj->Add("a:",10);
$Sourceobj->Add("b:",25);
$Policy->StoreCollection("CODA\\\\floppy
   \\\\disk\\\\space\\\\gauge",$Sourceobj);

Source Method: DataAvailable
Parameter: void
Return Type: VB Script: Boolean   Perl: integer
VB Script Syntax: Sourceobj.DataAvailable
Perl Syntax: $Sourceobj->DataAvailable;
Description: Returns TRUE if the source object contains any value, otherwise, returns FALSE.

Source Method: ValueOfInstance
Parameter: instancename
Return Type: VB Script: variant   Perl: string
VB Script Syntax: Sourceobj.ValueOfInstance("instancename")
Perl Syntax: $Sourceobj->ValueOfInstance("instancename");
Description: Direct access to the value of the instance defined by the instance name.
ClosedSession Object

The Session object can be used to store data and to access it later within the script running at a different interval. The session object can also be used to transfer data from the script to the policy actions using the action variable <$SESSION(KEY)>. The Session object is unique for each policy.

Session Method: IsPresent
Parameter: key
Return Type: VB Script: Boolean   Perl: integer
VB Script Syntax: Session.IsPresent("key")
Perl Syntax: $Session->IsPresent("key");
Description: Returns TRUE if a value for key exists. Returns FALSE if no value for key exists. Keys are set with the Session.Value method.

Session Method: Remove
Parameter: key
Return Type: VB Script: void   Perl: void
VB Script Syntax: Session.Remove("key")
Perl Syntax: $Session->Remove("key");
Description: Removes the key specified from the session object.

Session Method: RemoveAll
Parameter: void
Return Type: VB Script: void   Perl: void
VB Script Syntax: Session.RemoveAll()
Perl Syntax: $Session->RemoveAll();
Description: Removes all keys from the session object.

Session Method: Value
Parameter: key
value (for Perl only)
Return Type: VB Script: variant (This is the default method for the Session object.)
Perl: string
VB Script Syntax: for put: Session.Value("key")=value
for get: value=Session.Value("key")
Perl Syntax: for put: $Session->Value("key","value");
for get: Value = $Session->Value("key");
Description: Gets or puts a value for the defined key.
ClosedRule Object

The Rule object is used to indicate to the policy whether a threshold has been crossed or not. TRUE = threshold crossed, FALSE = threshold not crossed.

In scheduled task policies, the Rule object is used to indicate whether the command has succeeded or failed. TRUE = command succeeded, FALSE = command failed.

Rule Method: Status
Parameter: void
Return Type: VB Script: Boolean   Perl: integer
VB Script Syntax: for put: Rule.Status = boolvalue
for get: boolvalue = Rule.Status
Perl Syntax: for put: $Rule->Status(boolvalue);
for get: boolvalue = $Rule->Status();
Description: For measurement threshold policies, puts or gets the value for threshold status. For scheduled task policies, FALSE indicates that the scheduled task failed.
ClosedConsoleMessage Object

The ConsoleMessage object provides a method for sending events directly to BSM. Events sent in this way are not intercepted by an open message interface policy, but instead are sent directly to the server. Multiple uses of the Send method are supported. The same script can then send multiple events to OMi depending on which problem it detects.

Note You cannot use action variables with the ConsoleMessage object.

ConsoleMessage Method: Application
Parameter: application (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.Application = "application"
Perl Syntax: $ConsoleMessage->Application("application");
Description: This optional method sets the content of Application in the event properties.

ConsoleMessage Method: Object
Parameter: object (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.Object = "object"
Perl Syntax: $ConsoleMessage->Object("object");
Description: This optional method sets the content of Object in the event properties.

ConsoleMessage Method: MsgText
Parameter: msgtext (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.MsgText = "msgtext"
Perl Syntax: $ConsoleMessage->MsgText("msgtext");
Description: This method sets the message text for the event.

ConsoleMessage Method: Severity
Parameter: severity
(valid strings are: Unknown|Normal|Warning|Minor|Major|Critical)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.Severity = "severity"
Perl Syntax: $ConsoleMessage->Severity("severity");
Description: Sets the severity of the event that is sent. If not specifically set with this method, the default is Normal. If an invalid string is supplied, severity Unknown will be used.

ConsoleMessage Method: MsgGrp
Parameter: messagegroup (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.MsgGrp = "messagegroup"
Perl Syntax: $ConsoleMessage->MsgGrp("messagegroup");
Description: Sets the value for the Message Group in event properties. If this method does not supply a value, Misc is used.

ConsoleMessage Method: Node
Parameter: nodename (IP address or fully qualified hostname)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.Node = "nodename"
Perl Syntax: $ConsoleMessage->Node("nodename");
Description: Sets the value for Primary Node Name that will be displayed in the event properties. IP addresses and fully qualified hostnames are valid. If this method does not supply a value, the hostname of the system is used by default.

ConsoleMessage Method: ServiceId
Parameter: serviceid (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.ServiceId = "serviceid"
Perl Syntax: $ConsoleMessage->ServiceId("serviceid");
Description: This optional method sets the Service ID for the event.

ConsoleMessage Method: MessageType
Parameter: messagetype (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.MessageType = "messagetype"
Perl Syntax: $ConsoleMessage->MessageType("messagetype");
Description: This optional method sets the value for the message type field of the event properties.

ConsoleMessage Method: MessageKey
Parameter: messagekey (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.MessageKey = "messagekey"
Perl Syntax: $ConsoleMessage->MessageKey("messagekey");
Description: This optional methods sets a key for event correlation.

ConsoleMessage Method: AcknowledgeMessageKey
Parameter: messagekey (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.AcknowledgeMessageKey = "messagekey"
Perl Syntax: $ConsoleMessage->AcknowledgeMessageKey("messagekey");
Description: This optional method sets the message key to indicate which events are automatically closed.

ConsoleMessage Method: TroubleTicket
Parameter: Booleanvalue
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.TroubleTicket = Booleanvalue
Perl Syntax: $ConsoleMessage->TroubleTicket(Booleanvalue);
Description: This optional method specifies if the event is to be sent to a trouble ticket interface. Default is FALSE.

ConsoleMessage Method: Notification
Parameter: Booleanvalue
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.Notification = Booleanvalue
Perl Syntax: $ConsoleMessage->Notification(Booleanvalue);
Description: This optional method specifies if the event is sent to the notification mechanism. Default is FALSE.

ConsoleMessage Method: AgentMSI
Parameter: type (valid strings are: copy|divert|none)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.AgentMSI = "type"
Perl Syntax: $ConsoleMessage->AgentMSI("type");
Description: This optional method specifies if the event is to be sent through the message stream interface on the agent. Default (or if string misspelled) is none.

ConsoleMessage Method: ServerMSI
Parameter: type (valid strings are: copy|divert|none)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.ServerMSI = "type"
Perl Syntax: $ConsoleMessage->ServerMSI("type");
Description: This optional method specifies if event is sent through the event stream interface on the server. Default (or if string misspelled) is none.

ConsoleMessage Method: Send
Parameter: void
Return Type: VB Script: void   Perl: void
VB Script Syntax: ConsoleMessage.Send()
Perl Syntax: $ConsoleMessage->Send();
Description: This method sends the event to the OMi server. The MsgText method must set the message text before using this method. Multiple uses of the Send method are supported. Policy variables will not be expanded.
ClosedExecuteCommand Object

Object used for requesting a command to be run. It starts a command to be run by the HPE Operations Agent.

ExecuteCommand Method: Command
Parameter: command (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ExecuteCommand.Command = "command"
Perl Syntax: $ExecuteCommand->Command("command");
Description:

This mandatory method is the name of the command to run with all necessary parameters.

Note For scripts that will run on Windows systems, internal commands such as Copy, Rename, and DIR use a command interpreter that must be started before the command can be run. For commands of this type, the command must be preceded with cmd /k, followed by any other parameters required.

ExecuteCommand Method: KillonTimeout
Parameter: seconds (integer)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ExecuteCommand.KillonTimeout = seconds;
Perl Syntax: $ExecuteCommand->KillonTimeout(seconds);
Description: This method sets the maximum time, in seconds, that the command will run. The default is unlimited. Valid only with the StartEx method.

ExecuteCommand Method: UserName
Parameter: username (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ExecuteCommand.UserName = "username"
Perl Syntax: $ExecuteCommand->UserName("username");
Description: User name under which the command should be run. Optional, default is $AGENT_USER.

ExecuteCommand Method: Password
Parameter: password (string)
Return Type: VB Script: void   Perl: void
VB Script Syntax: ExecuteCommand.Password = "password"
Perl Syntax: $ExecuteCommand->Password("password");
Description:

Password for accessing the specified user account. To prevent the password from being visible in the script, use the following instructions:

  1. Open a command prompt.

  2. Change directory to the agent install directory:
    <install_dir>/bin/<arch>/OpC/install

  3. Encrypt your password with the command: opcpwcrpt <yourpassword>

  4. Use the output string as the password in your script.

In some cases it is better not to supply a password.

ClosedShould I provide the password or not?

Executing the command without the password is the easier of the two methods, but it has some restrictions that make it unsuitable in some situations. The lists below show the restrictions and advantages of both methods.

Without a password:

  • For Windows systems, resources accessed through the network are not available.
  • For Windows systems, if a domain user is specified, the agent must be installed on the domain controller that authenticates the user.
  • For all systems, changed passwords do not invalidate the policy.

With a password:

  • For all systems, resources accessed through the network are available.
  • For all systems, the encrypted password is sent over the network.
  • For all systems, if the password changes, the policy must be updated and redeployed.

ExecuteCommand Method: Start
Parameter: void
Return Type: VB Script: void   Perl: void
VB Script Syntax: ExecuteCommand.Start()
Perl Syntax: $ExecuteCommand->Start();
Description: Run the command specified by ExecuteCommand.Command and return immediately the control to the script so the next lines can be processed right away.

ExecuteCommand Method: StartEx
Parameter: void
Return Type: VB Script: BSTR   Perl: String
VB Script Syntax: ExecuteCommand.StartEx
Perl Syntax: $ExecuteCommand->StartEx();
Description:

Run ExecuteCommand.Command and wait until it finishes. Commands can be run synchronously or asynchronously, as needed. Multiple uses of the Start method are supported. This way, the same script can trigger multiple external commands.

If the command is successful, STDOUT is returned. If the command is not successful (return value non-zero), the string "ERROR:\n" followed by STDERR will be returned.

To handle non-zero return values, run StartEx in an eval function and then check the result, for example for the string ERROR.

Perl script example:

eval '$ReturnText = $ExecuteCommand->StartEx()';
$ReturnText =$@ if $@;

Send Help Center feedback