Using the Configure Screen

The Configure screen, shown in the following figure, appears after Agent Builder finishes creating the resource type and you select the Next button on the Create screen. You cannot access the Configure screen before the resource type has been created.

The Configure screen contains the following fields:

• Start Command — The full command line that can be passed to any UNIX shell to start the base application. It is required that you specify this command. You can type the command in the field provided or use the Browse button to locate a file containing the command to start the application.

  The complete command line must include everything necessary to start the application, such as hostnames, port numbers, a path to configuration files, and so on. If your application requires a hostname to be specified on the command line, you can use the $hostnames variable that Agent Builder defines (see Using the Agent Builder $hostnames Variable).

  Do not enclose the command in double quotes (““).

  ---

  Note –

  If the base application has multiple independent process trees, each of which is started with its own tag under PMF control, you cannot specify a single command. Rather, you must create a text file with individual commands to start each process tree, and specify the path to this file in the Start Command text field. See Creating Resource Types With Multiple Independent Process Trees, which lists some special characteristics this file requires to work properly.

  ---

• Stop Command — The full command line that can be passed to any UNIX shell to stop the base application. You can type the command in the field provided or use the Browse button to locate a file containing the command to stop the application. If your application requires a hostname to be specified on the command line, you can use the $hostnames variable defined by Agent Builder (see Using the Agent Builder $hostnames Variable).

  This command is optional. If you do not specify a stop command, the generated code uses signals (in the Stop method) to stop the application, as follows.

  • The Stop method sends SIGTERM to stop the application and waits for 80% of the timeout value for the application to exit.

  • If the SIGTERM signal is unsuccessful, the Stop method sends SIGKILL to stop the application and waits for 15% of the timeout value for the application to exit.

  • If SIGKILL is unsuccessful the Stop method exits unsuccessfully (the remaining 5% of the timeout value is considered overhead).

  ---

  Caution –

  Be certain the stop command does not return before the application has stopped completely.

  ---

• Probe Command — A command that can be run periodically to check the health of the application and return an appropriate exit status between 0 (success) and 100 (complete failure). This command is optional. You can type the complete path to the command or use the Browse button to locate a file that contains the commands to probe the application.

  Typically, you specify a simple client of the base application. If you do not specify a probe command, the generated code simply connects to and disconnects from the port used by the resource, and if that succeeds, declares the application healthy. You can only use a probe command with network aware applications. Agent Builder always generates a probe command, but disables it for non-network aware applications.

  If your application requires that you specify a hostname on the probe command line, you can use the $hostnames variable that Agent Builder defines (see Using the Agent Builder $hostnames Variable).

• Timeout — (for each command)—A timeout value (in seconds) for each command. You can specify a new value or accept the default value Agent Builder provides (300 seconds for start and stop; 30 seconds for probe).

Using the Agent Builder $hostnames Variable

For many applications, specifically network-aware applications, the hostname on which the application listens and services customer requests must be passed to the application on the command line. Therefore, in many cases, hostname is a parameter you must specify for start, stop, and probe commands for the target resource type (on the Configure screen). However, the hostname on which an application listens is cluster specific—it is determined when the resource is run on a cluster and cannot be determined when Agent Builder generates your resource type code.

To solve this problem, Agent Builder provides the $hostnames variable that you can specify on the command line for the start, stop, and probe commands. You specify the $hostnames variable exactly as you would an actual hostname, for example,

/opt/network_aware/echo_server -p port_no -l $hostnames

When a resource of the target resource type is run on a cluster, the LogicalHostname or SharedAddress hostname configured for that resource (in the Network_resources_used resource property of the resource) is substituted for the value of the $hostnames variable.

If you configure the Network_resources_used property with multiple hostnames, the $hostnames variable contains all of them separated by commas.

Creating Resource Types With Multiple Independent Process Trees

Agent Builder can create resource types for applications having more than one independent process tree. These process trees are independent in the sense that PMF monitors and starts them individually. PMF starts each process tree with its own tag.

In the case of a base application with multiple independent process trees, you cannot specify a single command line to start the application. Rather, you must create a text file, with each line specifying the full path to a command to start one of the application's process trees. This file must not contain any blank lines. You specify this text file in the Start Command text field in the Configure screen.

You must also make certain this text file does not have execute permissions. This enables Agent Builder to distinguish this file, whose purpose is to start multiple process trees, from a simple executable script containing multiple commands. If this text file is given execute permissions, the resources would come up fine on a cluster, but all the commands would be started under one PMF tag, precluding the possibility of monitoring and restarting the process trees individually by PMF.