test

Sun Cluster Data Services Developer's Guide for Solaris OS

Using Agent Builder

This section describes how to use Agent Builder. In addition, this section includes tasks that you must complete before you can use Agent Builder. This section also explains ways that you can take advantage of Agent Builder after you generate your resource type code.

The following topics are discussed:

Analyzing the Application

Before using Agent Builder, you must determine whether the application that you intend to make highly available or scalable meets the required criteria. Agent Builder cannot perform this analysis, which is based solely on the runtime characteristics of the application. Analyzing the Application for Suitability provides more information about this topic.

Agent Builder might not always be able to create a complete resource type for your application. However, in most cases, Agent Builder provides at least a partial solution. For example, more sophisticated applications might require additional code that Agent Builder does not generate by default. Examples of additional code include code that adds validation checks for additional properties or that tunes parameters that Agent Builder does not expose. In these cases, you must make changes to the generated source code or to the RTR file. Agent Builder is designed to provide just this kind of flexibility.

Agent Builder places comments at particular points in the generated source code where you can add your own resource type code. After making changes to the source code, you can use the makefile that Agent Builder generates to recompile the source code and regenerate the resource type package.

Even if you write your entire resource type code without using any code that is generated by Agent Builder, you can use the makefile and structure that Agent Builder provides to create the Solaris package for your resource type.

Installing and Configuring Agent Builder

Agent Builder requires no special installation. Agent Builder is included in the SUNWscdev package, which is installed by default when you install the Sun Cluster software. The Sun Cluster Software Installation Guide for Solaris OS contains more information.

Before you use Agent Builder, verify the following requirements:

Note –

You can use a different compiler with Agent Builder than the standard cc compiler. To use a different compiler, create a symbolic link in $PATH from cc to a different compiler, such as gcc. Or, change the compiler specification in the makefile (currently, CC=cc) to the complete path for a different compiler. For example, in the makefile that is generated by Agent Builder, change CC=cc to CC=pathname/gcc. In this case, you cannot run Agent Builder directly. Instead, you must use the make and make pkg commands to generate data service code and the package.

Agent Builder Screens

Agent Builder is a two-step wizard with a corresponding screen for each step.

    Agent Builder provides the following two screens to guide you through the process of creating a new resource type:

  1. Create screen. On this screen, you provide basic information about the resource type to create, such as its name and the working directory for the generated files. The working directory is where you create and configure the resource type template.

    You also specify the following information:

    • The kind of resource to create (scalable or failover)

    • Whether the base application is network aware (that is, if it uses the network to communicate with its clients)

    • The type of code to generate (C, Korn shell (ksh), or GDS)

    For information about GDS, see Chapter 10, Generic Data Services. You must provide all the information on this screen and select Create to generate the corresponding output. Then, you can display the Configure screen.

  2. Configure screen. On this screen, you must specify the full command line that can be passed to any UNIX shell to start your base application. Optionally, you can provide commands to stop and to probe your application. If you do not specify these two commands, the generated output uses signals to stop the application and provides a default probe mechanism. See the description of the probe command in Using the Configure Screen. The Configure screen also enables you to change the timeout values for each of these three commands: start, stop, probe.

Starting Agent Builder

Note –

If the GUI version of Agent Builder is not accessible, you can access Agent Builder through a command-line interface. See How to Use the Command-Line Version of Agent Builder.

If you start Agent Builder from the working directory for an existing resource type, Agent Builder initializes the Create and Configure screens to the values of the existing resource type.

Start Agent Builder by typing the following command:


% /usr/cluster/bin/scdsbuilder

The Create screen appears.

Figure 9–1 Create Screen for Agent Builder

Dialog box titled Sun Cluster Agent Builder that shows the main Agent Builder screen

Navigating Agent Builder

You enter information on the Create and Configure screens by performing the following operations:

The buttons at the bottom of each screen enable you to complete the task, move to the next or previous screen, or exit Agent Builder. Agent Builder emphasizes or grays out these buttons, as necessary.

For example, when you have filled in the fields and selected the preferred options on the Create screen, click Create at the bottom of the screen. Previous and Next are grayed out because no previous screen exists and you cannot go to the next step before you complete this step.

Panel at bottom of screen that shows Create, Previous, Next, and Cancel commands

Agent Builder displays progress messages in the Output Log area at the bottom of the screen. When Agent Builder finishes, it displays a success message or a warning message. Next is highlighted, or if this is the last screen, only Cancel is highlighted.

You can click Cancel at any time to exit Agent Builder.

Browse Command

Some Agent Builder fields enable you to type information in them. Other fields enable you to click Browse to browse a directory structure and select a file or a directory.

Browse command

When you click Browse, a screen similar to this screen appears.

Browse screen that shows a list of files

Double-click a folder to open it. When you move the cursor to a file, the file's name appears in the File Name field. Click Select when you have located and moved the cursor to the file that you want.

Note –

If you are browsing for a directory, move the cursor to the directory that you want and click Open. If the directory contains no subdirectories, Agent Builder closes the browse window and places the name of the directory to which you moved the cursor in the appropriate field. If this directory has subdirectories, click Close to close the browse window and redisplay the previous screen. Agent Builder places the name of the directory to which you moved the cursor in the appropriate field.

The icons in the upper right corner of the Browse screen do the following:

Icon 

Purpose 
Icon that shows up arrow

This icon moves you up one level in the directory tree. 
Icon that shows home

This icon returns you to the home folder. 
Icon that shows a new folder

This icon creates a new folder under the currently selected folder. 
Icon that you use to change views

This icon, for toggling between different views, is reserved for future use. 

Agent Builder Menus

Agent Builder provides File and Edit drop-down menus.

Agent Builder File Menu

The File menu contains two options:

Agent Builder Edit Menu

The Edit menu contains two options:

Using the Create Screen

The first step in creating a resource type is to complete the Create screen, which appears when you start Agent Builder. The following figure shows the Create screen after you type information in the fields.

Figure 9–2 Agent Builder Create Screen, After You Type Information

Dialog box that shows the create screen after information has been typed

The Create screen contains the following fields, radio buttons, and check box:

Note –

If the cc compiler is not in your $PATH variable, Agent Builder grays out the C radio button and allows you to select the ksh radio button. To specify a different compiler, see the note at the end of Installing and Configuring Agent Builder.

After you have specified the required information, click Create. The Output Log area at the bottom of the screen shows the actions that Agent Builder performs. You can choose Save Output Log from the Edit menu to save the information in the output log.

When finished, Agent Builder displays either a success message or a warning message.

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 that you have specified or the work that Agent Builder has completed. See Reusing Code That You Create With Agent Builder.

Using the Configure Screen

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

Figure 9–3 Configure Screen for Agent Builder

Dialog box that shows the Configure screen

The Configure screen contains the following fields:

Using the Agent Builder Korn Shell-Based $hostnames Variable

For many applications, specifically network-aware applications, the host name on which the application listens and services customer requests must be passed to the application on the command line. In many cases, the host name is an argument that you must specify for start, stop, and probe commands for the target resource type on the Configure screen. However, the host name on which an application listens is cluster specific. The host name is determined when the resource is run on a cluster. The host name 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.

Note –

The $hostnames variable is supported for use with Korn shell-based services only. The $hostnames variable is not supported for use with C-based and GDS-based services.

You specify the $hostnames variable exactly as you would an actual host name, 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 host name that is configured for that resource is substituted for the value of the $hostnames variable. The host name is configured for that resource in the Network_resources_used resource property of the resource.

If you configure the Network_resources_used property with multiple host names, the $hostnames variable contains all host names, each host name separated by a comma.

Using Property Variables

You can also retrieve the values of selected Sun Cluster resource type, resource, and resource group properties from the RGM framework by using property variables. Agent Builder scans your start, probe, or stop command strings for property variables and substitutes these variables with their values before Agent Builder executes the command.

Note –

Property variables are not supported for use with Korn shell-based services.

List of Property Variables

This section lists the property variables that you can use. The Sun Cluster resource type, resource, and resource group properties are described in Appendix A, Standard Properties.

Resource Property Variables

Resource Type Property Variables

Resource Group Property Variables

Syntax of Property Variables

You include a percent sign (%) before a property name to indicate a property variable, as shown in this example:

/opt/network_aware/echo_server -t %RS_STOP_TIMEOUT -n %RG_NODELIST

Given the preceding example, Agent Builder might interpret these property variables and start the echo_server script with the following values:

/opt/network_aware/echo_server -t 300 -n phys-node-1,phys-node-2,phys-node-3

How Agent Builder Substitutes Property Variables

Agent Builder interprets the types of property variables, as follows:

Reusing Code That You Create With Agent Builder

Agent Builder enables you to reuse completed work in the following ways:

ProcedureHow to Clone an Existing Resource Type

Follow this procedure to clone an existing resource type that is generated by Agent Builder.

  1. Load an existing resource type into Agent Builder.

    Use one of the following methods:

    • Start Agent Builder from the working directory for an existing resource type that you created with Agent Builder. Ensure that the working directory contains the rtconfig file. Agent Builder loads the values for that resource type in the Create and Configure screens.

    • Use the Load Resource Type option from the File drop-down menu.

  2. Change the working directory on the Create screen.

    You must use Browse to select a directory. Typing a new directory name is not sufficient. After you select a directory, Agent Builder re-enables the Create button.

  3. Make the changes that you want to the existing resource type.

    You might change the type of code that is generated for the resource type.

    For example, if you initially create a Korn shell version of a resource type but find over time that you require a C version, you can do the following:

    • Load the existing Korn shell resource type.

    • Change the language for the output to C.

    • Click Create to have Agent Builder build a C version of the resource type.

  4. Create the cloned resource type.

    1. Click Create to create the resource type.

    2. Click Next to display the Configure screen.

    3. Click Configure to configure the resource type, and click Cancel to finish.

Editing the Generated Source Code

To simplify the process of creating a resource type, Agent Builder limits the amount of information that you can specify, which necessarily limits the scope of the generated resource type. Therefore, to add more sophisticated features, you need to modify the generated source code or the RTR file. Examples of additional features include code that adds validation checks for additional properties or that tunes parameters that Agent Builder does not expose.

The source files are in the install-directory/rt-name/src directory. Agent Builder embeds comments in the source code where 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 source code, except the comment mark (#) indicates the beginning of a comment.

For example, rt-name.h declares all the utility functions that the different programs use. At the end of the list of declarations are comments that enable you to declare additional functions that you might have added to your code.

Agent Builder also generates the makefile in the install-directory/rt-name/src directory with corresponding targets. Use the make command to recompile the source code. Use 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. See Appendix A, Standard Properties for information about properties.

ProcedureHow to Use the Command-Line Version of Agent Builder

The command-line version of Agent Builder follows the same basic process as the GUI. However, instead of typing information in the GUI, you pass arguments to the scdscreate and scdsconfig commands. See the scdscreate(1HA) and scdsconfig(1HA) man pages for more information.

Follow these steps to use the command-line version of Agent Builder.

  1. Use scdscreate to create a Sun Cluster resource type template for making an application highly available or scalable.

  2. Use scdsconfig to configure the resource type template that you created with scdscreate.

    You can specify property variables. Property variables are described in Using Property Variables.

  3. Change directories to the pkg subdirectory in the working directory.

  4. Use the pkgadd command to install the packages that you created with scdscreate.


    # pkgadd -d . package-name

  5. (Optional) Edit the generated source code.

  6. Run the start script.