After you have entered the required information, click the Create button. The Output Log at the bottom of the screen shows the actions that Agent Builder is taking. You can use the Save Output Log command in the Edit menu to save the information in the output log.
When finished, Agent Builder displays either a success message or a warning message that it was unable to complete this step, and you should check the output log for details.
If Agent Builder completes successfully, you can Click the Next button to bring up the Configure screen, which enables you to finish generating the resource type.
Note - Although generation of a complete resource type is a two-step process, you can exit Agent Builder after completing the first step (create) without losing the information you have entered or the work that Agent Builder has completed (see Reusing Completed Work).
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.
Figure 9-3 Configure Screen
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 that have 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.
Note - Agent Builder enables you to create resource types with multiple independent process trees only if the generated source code that you specify is C. You cannot use Agent Builder to create these resource types for ksh or for GDS. To create these resource types for ksh or for GDS, you must write the code by hand.
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.
Reusing Completed Work
Agent Builder enables you leverage completed work in several ways.
You can clone an existing resource type created with Agent Builder.
You can edit the source code Agent Builder generates and then recompile the code to create a new package.
Cloning an Existing Resource Type
Follow this procedure to clone an existing resource type generated by Agent Builder.
Load an existing resource type into Agent Builder. You can do this in either of two ways:
Change the working directory on the Create screen.
You must use the Browse button to select a directory--typing a new directory name is not sufficient. After you select a directory, Agent Builder re-enables the Create button.
Make changes.
You might use this procedure to change the type of code generated for the resource type. For example, if you initially create a ksh version of a resource type but find over time that you require a C version, you can load the existing ksh resource type, change the language for the output to C, and then have Agent Builder build a C version of the resource type.
Create the cloned resource type.
Select Create to create the resource type. Select Next to bring up the Configure screen. Select Configure to configure the resource type and then Cancel to finish.
Editing the Generated Source Code
To keep the process of creating a resource type simple, Agent Builder limits the number of inputs, which necessarily limits the scope of the generated resource type. Therefore, to add more sophisticated features, such as validation checks for additional properties, or to tune parameters Agent Builder does not expose, you need to modify the generated source code or the RTR file.
The source files are in the install_directory/rt_name/src directory. Agent Builder embeds comments in the source code at places you can add code. These comments are of the form (for C code):
/* User added code -- BEGIN vvvvvvvvvvvvvvv */ /* User added code -- END ^^^^^^^^^^^^^^^ */ |
Note - These comments are identical in Korn shell code, except they use the pound sign (#) to begin the comment line.
For example, rt_name.h declares all the utility routines that the different programs use. At the end of the list of declarations are comments that enable you to declare additional routines you might have added to any of your code.
Agent Builder also generates the makefile in the install_directory/rt_name/src directory, with appropriate targets. Use the make command to recompile the source code, and the make pkg command to regenerate the resource type package.
The RTR file is in the install_directory/rt_name/etc directory. You can edit the RTR file with a standard text editor (see Setting Resource and Resource Type Properties for more information about the RTR file and Appendix A, Standard Properties for information about properties).