blackout()
Hide PATROL object state changes for a specific period of time.
Syntax
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 |
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.
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:
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
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:
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