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 21.3 for BMC Helix Operations Management.

Menu Commands and Infoboxes

Menu Commands

Menu commands allow developers to add administrative functions to KM's. Usually menu commands are used for administration of the KM's and the application the KM is managing. Menu commands will only be available on application instances.

When the operator selects a menu command, the menu command text will be sent to the agent and scheduled for immediate execution. Before the agent can run the script, it will compile it first.

A menu command can be executed as a task or command. We will discuss what the difference between a task and a command is.

Developer Console Only Commands

To make a command only available for a developer console, in the first line of the command text, use the following instruction in your PSL script:

"#%MODES% dev"

The result is that the menu command will only be available via the developer console and will not show up on the operator console.

Console side menu commands

If you add "#%MODES% local" to your menu command, the menu command will be run by the console as an OS process. The console will spawn an OS interpreter child process and run the command.

Some macro variables you can also use in state change actions are available to pass some context to your OS command (see sections about events).

%%{. . . } macro

This macro will ask for user input and substitute the result in the menu command text prior to sending it to the agent. Although it is useful for testing, because it is a lot easier than defining a response() function, the use of this macro should not be used in production code.

The data entered by the user will be literally replaced. Improper input by the operator can result in compiler errors. It can also allow operators to run arbitrary PSL code on an agent.

Command or Task execution

The difference in functionality between a command and a task is very limited. Both commands will result in a process created and maintained by the agent and injected in the RUNQ for immediate execution. The subtle difference between both is almost only a visual effect.

Command

When you define the menu command, you have to select if you would like to run it as a task or as a command. If you select command, then the PSL script is scheduled for execution just like a parameter. You have no control over the process after it is launched. Any output that is generated by the menu command will be sent to the system output window.

Tasks

If the command is defined to run as a task, a console object (text box) will be created when the command is started. From this console object you can select decide to kill, suspend, or restart the command. Output is directed to this task window on the console.

Extending Computer Class Menu Commands

Sometimes you would like to add menu commands to a computer class (for example, the ALL_COMPUTERS KM). Since BMC is already shipping these files, you should not ship a modified version of the file that contains the menu commands you would like to add. Instead, you should create an overlay KM.

The following explanation s one way to create an overlay KM. This feature is not limited to just computer class KM's and can sometimes be useful if you want to add parameters to any existing KM without having to modify the original file.

An example to add menu commands to ALL_COMPUTERS:

  1. Create a new KM (for example, MYCOMPCLASS.km).
  2. Load the newly created KM in the PATROL console.
  3. Add the menu commands to this new KM. These menu commands will eventually be merged with the menu commands that were already defined in the ALL_COMPUTERS.km.
  4. Save the KM.
  5. Open the KM in a text editor and rename the COMPUTER CLASS NAME from MYCOMPCLASS to ALL_COMPUTERS.
  6. Rename the APPLICATIONS tag (defined below VERSION xx.xx) to COMPUTERS.
  7. Save the KM.

Another way is to remove everything from the ALL_COMPUTERS KM but your own menu commands in the PATROL console (make sure you have a copy of the original file somewhere). Save this new KM and rename the file to MYCOMPCLASS.km. The result will be the same.

Infoboxes

When "infobox" is selected on the console, all infobox commands will be send to the agent and scheduled for immediate execution.

The Infobox has two types of entries: built-in entries at the top that are hard-coded into the agent, and KM-specific entries at the bottom. Only KM specific entries can be added by the developer to extend the functionality of an infobox.

Typically infoboxes contain information about:

  • Application version
  • Application's installed directory name
  • Knowledge Module version
  • Overall condition or status of the application

The value shown in the right-hand portion of the infobox is set via the PSL print() command.

Both PSL and OS commands can be used. Usually the OSmacro command %ECHO is used because this results in very fast execution. (No rtcell, or PSL process is created if the agent sees the user just wants to do a %ECHO command.) An easy way to print a namespace variables is:

%ECHO %{<variable>}

The output of a command defined in an infobox is sent to the text box. If you run an OS command, you have to be careful your result is in the first line, because only the first line will be visible.

Menu Commands and Infoboxes Pitfalls

The following sections describe some pitfalls that might occur when using menu commands and/or Infoboxes.

Limit the script size

Because every menu command and infobox command will be sent over the network to the agent, it is important to keep the scripts as small as possible for two reasons:

  • Minimize network traffic
  • Minimize compile time on the agent

Because of this, you should consider moving all your menu command code to libraries. The only code that will be send over the network would then typically be:

requires my_menucmdlib;
menu_show_preferences();

Delay in showing task output window

The task icon will only be created after the first line of output has been received from the agent. If your menu command will show a report and has to do some significant processing before the report is ready, it is a good practice to start the menu command with a print() statement so the operator knows the agent has received your request.

If it takes a while before you even see that first line printed, then this will probably be caused by a combination of network delay and compilation time. Try putting you menu command in a library in that case.

 




 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*