Important

   

This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.1 for BMC Helix Operations Management. Open link

blackout()

Hide PATROL object state changes for a specific period of time.

Syntax

blackout([object],[period])

Parameters

Parameter

Definition

object

name of the PATROL application or instance that has its state changes hidden If object is omitted, period must also be omitted.

period

length of time the PATROL application or instance remains blacked out If period is specified, object must also be specified. Valid Values 
A character string in the following format: 
dd : hh : mm 
where dd is days, hh is hours (0 - 23), and mm is minutes (0 - 59)

Description

The blackout() function starts and stops the blacking out of state changes (that is, OK ⇔ WARN ⇔ ALARM transitions) for an instance or application displayed on the PATROL Console. 

The effect of the blackout() function is similar to that of the Alarm Snooze option on the PATROL Console object menus. However, while the Alarm Snooze option clears alarm states for the specified period on a specific console, the blackout() function suppresses the current state of the object for the specified period on all consoles because it is applied at the agent. 

When the blackout() function is specified for an object that is currently not available, but will be online in the future, the blackout will take effect immediately upon the creation of the object. 

The blackout() function performs the following actions depending on how you specify its parameters:

  • The blackout() function with no parameters returns a list of all PATROL objects that are currently blacked out. The object names in the returned list are separated by new-line characters (\n).
  • The blackout (object) function where object is an instance returns the blackout status for single instance as the following character string:

instance \n blackoutend
Where instance is the instance name and blackoutend is the system time when the blackout is to end.

  • The blackout (object) function where object is an application returns the blackout status for all instances that belong to the application as the following character string:

instance \n blackoutend \n instance \n blackoutend \n ... ... instance \n blackoutend
Where instance is the instance name and blackoutend is the system time when the blackout is to end.

  • The blackout (object, period) function sets the blackout for object to period and returns the string OK if successful.
    When the requested object is an application, the blackout() function will blackout all instances that belong to the application and reset any existing blackout periods for this application to the requested period .
    If an application is blacked out, the blackout() function can be applied to an instance belonging to the application, but the blackout period may only be increased. The blackout period for an instance cannot be shorter than the blackout period of its application.
  • The blackout (object,"") function ends the blackout of object and returns the string OK if successful.
    The blackout of an instance cannot be ended if its application has a blackout in effect. If an instance has a longer blackout period than its application, and the blackout is ended for the instance, the blackout period will be reset to the applications blackout period.

Example

The following examples demonstrate how the blackout() function performs differently when the object is an instance and when it is an application. 

Behavior of blackout() function when an object is an instance

The PSL statements use the blackout() function to perform the following operations:

  • Set a blackout for an instance.
  • List all instances that are blacked out.
  • Return the blackout information for an instance.
  • End the blackout for instance.

function main() {
instance = "/FILESYSTEM/tmp_mnt-home-dherr"; 
print("Test instance is ",instance, "\n"); 
print("Blacking out instance . . . ",blackout(instance,"00:00:05"),"\n"); 
print("Return all blacked out objects . . .\n",blackout(),"\n"); 
print("Return blackout information for ",instance,"\n"); 
output = blackout(instance);
instance_name = nthlinef(output,1);
blackout_time = nthlinef(output,2); 
print(" Instance : ",instance_name); 
print("Blackout Expires : ",asctime(blackout_time),"\n");
print("End blackout for ",instance," . . . ",blackout(instance,""),"\n");
}

The preceding PSL statements return the following output:

Test instance is /FILESYSTEM/tmp_mnt-home-dherr
Blacking out instance . . . OK
Return all blacked out objects . . .
/FILESYSTEM/tmp_mnt-home-dherr
Return blackout information for /FILESYSTEM/tmp_mnt-home-dherr
Instance : /FILESYSTEM/tmp_mnt-home-dherr
Blackout Expires : Mon May 05 15:12:28 1998
End blackout for /FILESYSTEM/tmp_mnt-home-dherr . . . OK

Behavior of blackout() function when an object is an application

The following PSL statements use the blackout() function to perform the following operations:

  • Set a blackout for an application
  • List all applications that are blacked out
  • Return blackout information for an application
  • End the blackout for application

application = "/FILESYSTEM/";}}
print("Test application is ",application,"\n");
print("Blacking out...",blackout(application,"00:00:05"),"\n");
print("Return all blacked out objects . . .\n",blackout(),"\n");
print("Return blackout information for ",application,"\n");
output = blackout(application);
for(i =1; i < lines(output); i+=2) {
instance_name = nthlinef(output,i);
blackout_time = nthlinef(output,i+1);
print(" Instance : ",instance_name);
print("Blackout Expires : ",asctime(blackout_time),"\n"); 
}
print("End blackout for ",application,"...",blackout(application,""),"\n");


The above PSL statements return the following output:

Test application is /FILESYSTEM/
Blacking out . . . OK
Return all blacked out objects . . .
/FILESYSTEM/stand /FILESYSTEM/usr
/FILESYSTEM/tmp /FILESYSTEM/local
Return blackout information for /FILESYSTEM/
Instance : /FILESYSTEM/stand
Blackout Expires : Mon May 05 15:12:28 1998
Instance : /FILESYSTEM/usr Blackout Expires : Mon May 05 15:12:28 1998
Instance : /FILESYSTEM/tmp Blackout Expires : Mon May 05 15:12:28 1998 
Instance : /FILESYSTEM/local Blackout Expires : Mon May 05 15:12:28 1998 
End blackout for /FILESYSTEM/. . . OK
Was this page helpful? Yes No Submitting... Thank you

Comments