Monitoring a command return code

Define a data source to monitor an application or system by using a command return code.

1. On the Agent Initial Data Source page or the Data Source Location page, select Command or script in the Monitoring Data Categories area.
   Figure 1. Adding data from a command

   
2. In the Data Sources area, click A command return code.
3. Click Next.
4. On the Command Return Code page, Command return code information area, type the display name.
   Figure 2. Command Return Code page

   
5. Use the following substeps to define and describe command lines that you want your command return code to use.
   Note: Define a command for each operating system that is supported by the agent. Commands can be shared, but the total set of operating systems for all of the commands must equal the set of agent supported operating systems.
   1. Click Add in the Commands area of the Command Return Code window to open the Command Information window.
      Figure 3. Command Information window

      
   2. Type a command line and select an operating system from the list in the Operating Systems area of the Command Information window.
      Note:

      1. For a Windows command, you must type the full name of the command. For example, command_to_run.bat and not just command_to_run.
      2. Place quotation marks around the name so that it is not parsed by the command interpreter. For example, type "this is a test.bat"argument and not this is a test.bat argument.
      3. You can click a command and click Edit to modify it, or click Remove to delete it.
   3. Click Add in the Return Codes area of the Command Information window.
   4. Select a return code type from the list that is shown in the Return Code Definition window

      You can assign the following states to the test return codes:

      • ALREADY_RUNNING
      • DEPENDENT_NOT_RUNNING
      • GENERAL_ERROR
      • NOT_RUNNING
      • OK
      • PREREQ_NOT_RUNNING
      • WARNING
      Figure 4. Return Code Definition window: Return code type

      
   5. Type a numeric value for the return code type that you selected. The return code value is an integer that specifies a defined return code for the command return code. For portability between operating systems, use a return code value of 0 - 255. For a command that runs only on Windows, the return code value can be -2147483648 - 2147483647.
      Figure 5. Return Code Definition window: Return code value

      
   6. Define a message for each return code so that the message and code can be shown together. Click Browse to set up the message text.
      The message window lists messages that are defined in the agent. The Messages (list) window opens.

      Note:

      1. You can select text that was entered previously by selecting it in the Message text menu instead of clicking Browse. Then, continue to Step 5k.
      2. Until you define messages, the list remains blank. You can use Edit to alter a defined message and Remove to delete one or more messages that you defined.

      Figure 6. Messages window

      
   7. In the Messages (list) window, click Add The Message Definition window opens.
      Figure 7. Message Definition window

      
      Note: The message identifier is automatically generated for you.
   8. Enter some text that describes the meaning of the new message in the Message text field.
   9. Click OK. The Messages (list) window opens showing the new message (Figure 11).
   10. To verify the message and make it permanent, select it in the list and click OK. The new return code type, value, and text are shown in the Return Code Definition window.
   11. If you want this return code to be available to other commands on other operating systems for this command return code, select Global return code applies to all commands. If you want this return code to be available only to this command, leave Local return code applies only to this command selected.
       Figure 8. Return Code Definition window completed

       
   12. Click OK in the Return Code Definition window.
   13. Define at least two return codes before you leave the Command Information window. One return code to indicate no problems with the availability, another to indicate whether a problem occurred. If you want to add another return code, return to step c.
   14. Optional: In the Command Information window (Figure 3), Command files area, click Add if you want to select one or more scripts or executable files for the agent to run. The file or files are copied into the project folder of the agent under scripts/operating system, where operating system is a variable that depends on what you selected in (Figure 3). These files are also packaged and distributed with the agent. To edit the definition of an existing command file, or the original command file since copied into the project, select the file and click Edit. See (Editing a command file definition).
   15. Click OK in the Command Information window.
       Figure 9. Command Information window completed

       
       Note: The command files table is where you define any external files that you want to include in the agent package. These files are copied into the project directory and packaged with the agent for distribution.
6. If you have other return codes that are not already defined, define and describe global return codes that your command return code can use.
   1. Click Add in the Global return codes area of the Command Return Code page (Figure 2).
      Note: The return codes that are defined here are global. This means that the return codes are appropriate for all of the commands that are defined for the command return code. (They are not shared between command return codes). In addition, you can define return codes when you enter the command information (Figure 3). The return codes that are defined here can be global or local. Local return codes are only appropriate for this specific command. This hierarchy is useful if you have a return code that is the same across all operating systems. (For instance, a return code of 0 means that everything is functioning correctly. You can define it at the global level, and then all defined commands interpret 0 in this way.) If none of the other operating systems return a 5, you can define the return code of 5 only for the Windows command. If you define a return code at the local command level that is already defined at the global level, the command level is used. You can use this method to override return codes on specific operating systems. For instance, if on all UNIX operating systems, a return code of 2 means one thing, but, on Windows, it means something different. You can define a return code of 2 at the global level as expected by the UNIX operating systems. Then, in the command for Windows, you can redefine return code 2 for the meaning on Windows.
   2. Select a return code type from the list that is shown in the Return Code Definition window (Figure 4).

      You can assign the following states to the test return codes:

      • ALREADY_RUNNING
      • DEPENDENT_NOT_RUNNING
      • GENERAL_ERROR
      • NOT_RUNNING
      • OK
      • PREREQ_NOT_RUNNING
      • WARNING
   3. Type a numeric value for the return code type that you selected (Figure 10). The return code value is an integer that specifies a defined return code for the command return code.
      Figure 10. Return Code Definition window: Message text

      
   4. Click Browse to set up the message text and its associated meaning. You must define a message for each return code so that the message and code are shown together.

      The Messages window lists messages that are defined in the agent. The Messages (list) window opens(Figure 11).

      Note:

      1. Until you define messages, the list remains blank. You can use Edit to alter a defined message and Remove to delete one or more messages you defined.
      2. You can select text that was entered previously by selecting it in the Message text list instead of clicking Browse. Then, continue to Step 6h.
      Figure 11. Messages window

      
   5. In the Messages (list) window, click Add to see a Message Definition window, where you can type text that describes the meaning of the new message.
   6. Click OK.
   7. The Messages (list) window opens with the new message (Figure 6). To verify the message and make it permanent, select it in the list and click OK.
   8. When the new text, type, and value are shown in the Return Code Definition window, (Figure 12), click OK.
      Figure 12. Return Code Definition window

      
   9. On the Command Return code page, when you finish defining the return codes and commands for all supported operating systems, do one of the following steps:
      • If you are using the New Agent wizard, click Next or click Finish to save the data source and open the Agent Editor.
      • If you are using the New Agent Component wizard, click Finish to return to the Agent Editor.
      Figure 13. Command Return Code page completed