4    Creating Subset Control Programs

STL_NoDataless

4.6    Associating SCP Tasks with setld Utility Phases

The setld utility invokes the subset control program during different phases of its processing. The SCP can perform certain tasks during any of these phases, such as creating or deleting a file or displaying messages. Other tasks that may be required, such as creating links, should be performed only during specific phases.

Some tasks must take place during specific phases. For example, creating links between product files and the standard directory structure occurs during the POST_L phase.

Figure 4-1 shows setld utility time lines for the -l, -d, and -v options.

Figure 4-1:  Time Lines for setld Utility Phases

The actions taken by the setld utility are shown above the time lines. The SCP actions taken during each setld processing phase are shown below the time lines, along with any restrictions when the SCP is run on a cluster.

When the setld utility enters a new phase, it first sets the ACT environment variable to a corresponding value, then invokes the subset control program. The SCP determines the value of the ACT environment variable and any command line arguments to determine the required action.

Note

Do not include wildcard characters in your subset control program's option-parsing routine. Write code only for the cases the subset control program actually handles. For example, the subset control programs in this chapter provide no code for several conditions under which they could be invoked, for example, the V phase.

The following sections describe the tasks that a subset control program may perform in each setld processing phase:

• Displaying the subset menu: M phase (Section 4.6.1)

• Before loading the subset: PRE_L phase (Section 4.6.2)

• After loading the subset: POST_L phase (Section 4.6.3)

• Configuring after securing the subset: C INSTALL phase (Section 4.6.4)

• Deconfiguring before deleting a subset: C DELETE phase (Section 4.6.5)

• Before deleting a subset: PRE_D phase (Section 4.6.6)

• After deleting a subset: POST_D phase (Section 4.6.7)

• Verifying the subset: V phase (Section 4.6.8)

Caution

Any setld utility phase of your SCP must be able to run more than once without causing operational problems. This does not mean that you must repeat the SCP tasks, but that multiple executions will not cause the SCP to fail.

See setld(8) and stl_scp(4) for more information about the setld utility and conventions for subset control programs.

4.6.1    Displaying the Subset Menu (M Phase)

Whenever it performs an operation, the setld utility uses the M phase to determine if the subset should be included in that operation. Before displaying the menu, setld sets the ACT environment variable to M and calls the subset control program for each subset. At this time, the subset control program can determine whether to include its subset in the menu. The subset control program should return a value of 0 (zero) if the subset can be included in the menu.

Note

In a cluster environment, the M phase runs only on the cluster member where the setld utility is invoked.

Example 4-1 shows a sample setld installation menu, listing the subsets available for installation.

Example 4-1:  Sample setld Installation Menu

     1) Kit One Name: Subset Description
     2) Kit Two Name: Subset Description
     3) Kit Three Name: Subset Description
     4) Kit Four Name: Subset Description
     5) ALL of the above
     6) CANCEL selections and redisplay menus
     7) EXIT without installing any subsets
 
Enter your choices or press RETURN to redisplay menus.
 
Choices (for example, 1 2 4-6):

When it calls the subset control program during this phase, the setld utility passes one argument, which can have one of two values:

• The -l argument indicates that the operation is a subset load.

• The -x argument is reserved for extraction of the subset into a RIS server's product area.

When setld extracts a subset into a RIS server's product area, the server also executes the subset control program to make use of the program's code for the M phase of installation. You should code the M phase to detect the difference between extraction of the subset into a RIS area and loading of the subset for use of its contents. To make this determination, determine the value of the $1 command argument (either -x for RIS extraction or -l for loading). For RIS extraction, the subset control program should take no action during the M phase. When loading subsets, the SCP should perform a machine test.

The following Bourne shell example illustrates one way to code the M phase. In Example 4-2, the subset control program is determining the type of processor on which it is running. In this example, there is no special code for the RIS extract case.

Example 4-2:  Sample Test for Alpha Processor During M Phase

#
# The ACT variable is set by setld and determines which 
# phase of the SCP should be executed.
#
case $ACT in
#
# This is the menu phase of the SCP
#
M)
	#
	# Setld invokes the M phase with an argument and if
	# the argument is "-l" it means that a software load
	# is occurring.  
	#
	case $1 in
	-l)
		#
		# Examine the machine architecture to be sure
		# that this software is being installed on an 
		# alpha machine.  If it is not, exit with an 
		# error status so that setld will not display 
		# this subset on the menu of subsets to load.
		#
		ARCH=`./bin/machine`
		[ "$ARCH" = alpha ] || exit 1
		;;
	esac
	;;
	
.
.
.

In Example 4-2, the SCP returns the following codes to the setld utility:

Note

Installation for a dataless client uses the client's local copy of the machine shell script even though the installation is performed in a DMS area on the server. See Section 4.5 and Sharing Software on a Local Area Network for more information about DMS.

4.6.2    Before Loading the Subset (PRE_L Phase)

After presenting the menu and before loading the subset, the setld utility sets the ACT environment variable to PRE_L and calls the subset control program. At this time, the subset control program can take any action required to prepare the system for subset installation, such as protecting existing files.

Note

In a cluster environment, the PRE_L phase is run only once for the whole cluster. If you must run member-specific operations when your subset is loaded, include the code in the C INSTALL phase.

Do not decline software loading because of one cluster member.

Use the DEPS field in the subset control file (subset_id.ctrl) for subset dependency processing.

If you overwrite base operating system files, you may encounter the following problems:

• Your product can be corrupted during an Update Installation of the operating system. The Update Installation will overwrite any file that is on the system with the version of the file shipped with the operating system.

• An Update Installation may not complete successfully if you overwrite a base operating system file. This can make the system unusable.

• Your product may have to be removed from the system to complete an Update Installation. Your product would have to be reinstalled after the Update Installation is completed.

• Removing your product corrupts the operating system.

If your subset control program is designed to overwrite existing files, it first should make a backup copy of the original file during the PRE_L phase and restore the copy in the POST_D phase described in Section 4.6.7.

In Example 4-3, the subset control program examines a list of files to be backed up if they already exist on the system. If it finds any, it creates a backup copy with an extension of .OLD.

Example 4-3:  Sample Backup of Existing Files During PRE_L Phase

        
.
.
.
#
# Here is a list of files to back up if found on 
# the installed system.
#
BACKUP_FILES="\
	./usr/var/opt/$_PVCODE/templates/odb_template \  [1]
	./usr/var/opt/$_PVCODE/log_files/odb_log"  [1]
        
.
.
.
#
# The ACT variable is set by setld and determines which 
# phase of the SCP should be executed.
#
case $ACT in
        
.
.
.
#
# This is the pre-load phase of the SCP
#
PRE_L)
	#
	# Loop through the list of backup files and create 
	# backup copies for any file that is found on the 
	# system.
	#
	for FILE in $BACKUP_FILES
	do
		#
		# If the file to be backed up exists, create
		# a backup copy with a .OLD extension.
		#
		if [ -f $FILE -a ! -f $FILE.OLD ] 
		then
			cp $FILE $FILE.OLD  [2]
		fi
	done
	;;
        
.
.
.

1. The STL_ScpInit routine sets the value of the $_PVCODE global variable to OAT100. Using this variable allows the SCP to be used for the next version of the product, OAT200, without changing the pathnames. [Return to example]

2. A backup copy is made if the specified file exists and if a backup copy does not already exist. This will be restored in the POST_D phase. [Return to example]

In Example 4-3, the SCP returns the following codes to the setld utility:

4.6.3    After Loading the Subset (POST_L Phase)

After loading the subset, the setld utility sets the ACT environment variable to POST_L and calls the subset control program for each subset. At this time the subset control program can make any modifications required to subset files that usually are protected from modification when the installation is complete. The subset control program should create backward links at this time.

Note

In a cluster environment, the POST_L phase is run only once for the whole cluster. If you must run member-specific operations when your subset is loaded, include the code in the C INSTALL phase.

Do not decline software configuration because of one cluster member.

Sometimes you may need to create links within your product-specific directories that refer to files in the standard hierarchy. Such backward links must be created carefully because the layered product directories themselves can be symbolic links. This means that you cannot rely on knowing in advance the correct number of directory levels ( ../ ) to include when you create your backward links. For example, /var is frequently a link to /usr/var.

When a kit is installed on a Network File System (NFS) server, the SCP should make the backward links in the server's kit area. When the server's kit area is exported to clients, the links are already in place and you do not need to create any backward links in the client area. This is done so that installation on an NFS client cannot overwrite any existing backward links in the server's kit areas. You do not run the subset control program on an NFS client. Your subset control program should create and remove backward links in the POST_L and PRE_D phases, respectively.

Caution

NFS clients importing products with backward links must have directory hierarchies that exactly match those on the server. Otherwise, the backward links fail.

Use the STL_LinkInit and STL_LinkBack routines to create backward links as follows, and use the rm command to remove them:

STL_LinkInit

STL_LinkBack link_file file_path link_path

The SCP in Example 4-4 uses STL_LinkBack in the POST_L phase to create a link named /opt/OAT100/sbin/ls. This link refers to the real file /sbin/ls. The SCP removes the link in the PRE_D phase.

Example 4-4:  Sample Backward Link Creation During POST_L Phase

case $ACT in
        
.
.
.
#
# This is the post-load phase of the SCP
#
POST_L)
	#
	# Initializes the variables so that STL_LinkBack can be executed
	#
	STL_LinkInit
	#
	# Create a symbolic link in the ./opt/$_PVCODE/sbin
	# directory that points to the ./sbin/ls file.
	#
		STL_LinkBack ls ./sbin ./opt/$_PVCODE/sbin  [1]
	;;
PRE_D)
	#
	# Remove the links created in the POST_L phase
	#
		rm -f ./opt/$_PVCODE/sbin/ls  [2]
	;;
        
.
.
.

1. The STL_LinkBack routine creates a backward link in the product-specific area, as described in the comment above the code. The STL_ScpInit routine sets the value of the $_PVCODE global variable to OAT100. Using this variable allows the SCP to be used for the next version of the product, OAT200, without changing the pathnames. [Return to example]

2. The SCP uses the rm command to remove the links created in the POST_L phase. [Return to example]

The setld utility creates an empty subsetID.lk lock file when it loads a subset. After successful installation, that subset is then available for dependency processing and locking is performed when other subsets are installed later. A subset's lock file can then contain any number of records, each naming a single dependent subset.

For example, the ODB kit requires that some version of the Orpheus Document Builder base product must be installed for the ODB product to work properly. Suppose that the OATBASE200 subset is present. When the setld utility installs the OATODBTEMPS100 subset from the ODB kit, it inserts a record that contains the subset identifier OATODBTEMPS100 into the OATBASE200.lk file. When the system administrator uses the setld utility to remove the OATBASE200 subset, the setld utility examines OATBASE200.lk and finds a record that indicates that OATODBTEMPS100 depends on OATBASE200, displays a warning message, and requires confirmation that the user really intends to remove the OATBASE200 subset.

If the administrator removes the OATODBTEMPS100 subset, the setld utility removes the corresponding record from the OATBASE200.lk file. Thereafter, the administrator can remove the OATBASE200 subset without causing a dependency warning.

The SCP uses the DEPS field in the subset control file (subset-id.ctrl) to perform dependency locking.

4.6.4    After Securing the Subset (C INSTALL Phase)

After securing the subset, the setld utility sets the ACT environment variable to C (configuration) and calls the subset control program for each subset, passing INSTALL as an argument. At this time, the subset control program can perform any configuration operations required for product-specific tailoring. For example, a kernel kit can statically or dynamically configure a device driver at this point.

The setld utility enters the C INSTALL phase when setld is invoked with the -l (load) option.

Note

In a cluster environment, the C INSTALL phase runs multiple times, once on each cluster member. You must be able to run any SCP operations in the C INSTALL phase more than once without causing a problem.

If your SCP needs to access member-specific files, perform those operations during the C INSTALL phase.

The subset control program cannot create a layered product's symbolic links during the C INSTALL phase.

Example 4-5 shows the C INSTALL portion of the SCP that issues a message upon successful subset installation.

Example 4-5:  Sample Message Output During C INSTALL Phase

# The ACT variable is set by setld and determines which 
# phase of the SCP should be executed.
#
case $ACT in
	
.
.
.
#
# This is the configuration phase of the SCP
#
C)
	#
	# Setld invokes the C phase with an argument that is 
	# either INSTALL or DELETE.  The INSTALL argument is
	# used on a setld load, while the DELETE argument is
	# used on a setld delete.
	#
	case $1 in
	INSTALL)  [1]
		#
		# Output a message letting the user know
		# that they should check the odb.conf file
		# before using the product.
		#
				echo "
The installation of the $_DESC ($_SUB)  [2]
software subset is complete.
Please check the /opt/$_PVCODE/odb.conf file before  [3]
using the $_DESC product."  [2]
		;;
	
.
.
.
esac
	;;
	
.
.
.

1. During the C phase, the SCP determines if the first argument passed by the setld utility has the value of INSTALL. If so, the program displays a message indicating that the installation is complete. [Return to example]

2. The STL_ScpInit routine sets the value of the $_DESC global variable to Orpheus Document Builder and the $_SUB global variable to OATODB100, resulting in the following message:

   The installation of the Orpheus Document Builder (OATODB100)
   software subset is complete.
   Please check the /opt/OAT100/odb.conf file before
   using the Orpheus Document Builder product."
    
    
   

   [Return to example]

3. The STL_ScpInit routine sets the value of the $_PVCODE global variable to OAT100. Using this variable allows the SCP to be used for the next version of the product, OAT200, without changing the pathnames. [Return to example]

In Example 4-5, the SCP returns the following codes to the setld utility:

4.6.5    Before Deleting a Subset (C DELETE Phase)

When the user invokes the setld utility with the -d option, the utility sets the ACT environment variable to C and calls the subset control program for each subset, passing DELETE as an argument. At this time, the subset control program can make configuration modifications to remove evidence of the subset's existence from the system. For example, a kernel kit would deconfigure a statically or dynamically configured driver during this phase. The C DELETE phase should reverse any changes made during the C INSTALL phase.

Note

In a cluster environment, the C DELETE phase runs multiple times, once on each cluster member. You must be able to run any SCP operations in the C DELETE phase more than once without causing a problem.

The SCP always should return a zero exit status in the C DELETE phase. A nonzero return status tells the setld utility not to delete the software, but if the SCP has run the C DELETE phase on other cluster members the software already may be marked as corrupt.

If an operation fails, report the error and continue processing. The user must fix the problem after the software is removed.

The subset control program cannot remove a layered product's links during the C DELETE phase.

Example 4-6 shows the C DELETE portion of the SCP that would reverse any changes made during the C INSTALL phase.

Example 4-6:  Sample C DELETE Phase

#
# The ACT variable is set by setld and determines which 
# phase of the SCP should be executed.
#
case $ACT in
	
.
.
.
#
# This is the configuration phase of the SCP
#
C)
	#
	# Setld invokes the C phase with an argument that is 
	# either INSTALL or DELETE.  The INSTALL argument is
	# used on a setld load, while the DELETE argument is
	# used on a setld delete.
	#
	case $1 in
	INSTALL)
		#
		# Output a message letting the user know
		# that they should check the odb.conf file
		# before using the product.
		#
				echo "
The installation of the $_DESC ($_SUB)
software subset is complete.
Please check the  /opt/$_PVCODE/odb.conf file before
using the $_DESC product."
		;;
   DELETE)
       ;;  [1]
   esac
	;;
	
.
.
.

1. This phase should reverse any changes made during the C INSTALL phase. Since no changes were made in Example 4-5, no action is taken in the C DELETE phase. [Return to example]

4.6.6    Before Deleting a Subset (PRE_D Phase)

When the user invokes the setld utility with the -d option, the utility sets the ACT environment variable to PRE_D and calls the subset control program for each subset. At this time, the subset control program can reverse modifications made during the POST_L phase of installation, such as removing links.

Note

In a cluster environment, the PRE_D phase runs only once for the entire cluster. If you must run member-specific operations when your subset is deleted, include the code in the C DELETE phase.

The SCP always should return a zero exit status in the PRE_D phase. A nonzero return status tells the setld utility not to delete the software, but since the SCP has run the C DELETE phase the software is already marked as corrupt.

If an operation fails, report the error and continue processing. The user must fix the problem after the software is removed.

The SCP uses the DEPS field in the subset control file (subset-id.ctrl) to perform dependency unlocking.

In Example 4-4, the SCP used STL_LinkBack in the POST_L phase to create the /opt/OAT100/sbin/ls link, referring to the /sbin/ls file. Example 4-7 shows the SCP removing this link in the PRE_D phase.

Example 4-7:  Sample PRE_D Phase Reversal of POST_L Phase Actions

case $ACT in
        
.
.
.
#
# This is the pre-deletion phase of the SCP
#
PRE_D)
	#
	# Remove the links created in the POST_L phase
	#
		rm -f ./opt/$_PVCODE/sbin/ls  [1]
	;;
        
.
.
.

1. The SCP uses the rm command to remove the links created in the POST_L phase. [Return to example]

4.6.7    After Deleting a Subset (POST_D Phase)

During the POST_D phase, after deleting a subset, the setld utility sets the ACT environment variable to POST_D and calls the subset control program for each subset. At this time the subset control program can reverse any modifications made during the PRE_L phase of installation.

Note

In a cluster environment, the POST_D phase is run only once for the whole cluster. If you must run member-specific operations when your subset is deleted, include the code in the C DELETE phase.

The SCP always should return a zero exit status in the POST_D phase. A nonzero return status tells the setld utility not to delete the software, but the subset already has been removed. This causes cluster corruption.

If an operation fails, report the error and continue processing. The user must fix the problem after the software is removed.

In Example 4-8, the subset control program examines a list of files to be backed up if they already exist on the system. If it finds any, it restores the backup copy.

Example 4-8:  Sample File Restoration During POST_D Phase

        
.
.
.
#
# Here is a list of files to back up if found on the installed system.
#
 
BACKUP_FILES="\
	./usr/var/opt/$_PVCODE/templates/odb_template \  [1]	./usr/var/opt/$_PVCODE/log_files/odb_log"
 
#
# The ACT variable is set by setld and determines which 
# phase of the SCP should be executed.
#
case $ACT in
        
.
.
.
#
# This is the post-deletion phase of the SCP
#
 
POST_D)
 
	#
	# Restore the backup copies created during the PRE_L phase
	#
 
	for FILE in $BACKUP_FILES
	do
		 [ -f $FILE.OLD ] &&
		 mv $FILE.OLD $FILE  [2]
	done
	;;
        
.
.
.
esac

1. The STL_ScpInit routine sets the value of the $_PVCODE global variable to OAT100. Using this variable allows the SCP to be used for the next version of the product, OAT200, without changing the pathnames. [Return to example]

2. Restores any files backed up in the PRE_L phase, as shown in Example 4-3. [Return to example]

In Example 4-8, the SCP returns the following codes to the setld utility:

4.6.8    Verifying the Subset (V Phase)

When the user invokes the setld utility with the -v option, the utility sets the ACT environment variable to V and calls the subset control program for the subset. Any V phase processing included in the subset control program is executed at this time.

The setld utility determines the existence of the installed subset and if the subset exists, the setld utility verifies the size and checksum information for each file in the subset. The setld utility does not execute subset control program V phase processing during the installation process.

4.7    Determing Subset Installation Status

Subset installation status can drive conditional actions in subset control programs, and accurately determining this status is especially important for recovery processing.

The following topics are discussed in this section:

• How the current version of the operating system defines installation and determines subset status (Section 4.7.1)

• Internal installation states and how they reflect software subset status (Section 4.7.2)

• Using subset installation status library routines in your SCP (Section 4.7.3)

4.7.1    Defining Installation and Subset Status

In the current operating system environment that includes TruCluster Server, software installation status is defined as follows:

• A subset is loaded when its software is copied onto the system

• A subset is installed after it is loaded and its SCP has completed successfully

A software subset can be loaded on one cluster member, corrupt on another, and fully installed and configured on a third. The subset.lk and subset.dw files are no longer sufficient to describe software subset installation status.

The setld utility generates a r, subset.sts, for each subset. This file describes the subset's current installation state and reflects the success or failure of specific phases of the installation or deletion process. The setld utility removes the subset status file when it deletes the software subset.

Each /usr/.smdb./subset.sts file is a context-dependent symbolic link (CDSL) to the corresponding /usr/cluster/members/{memb}/.smdb./subset.sts file.

The subset.lk file still exists but now is used only to list dependent subsets.

4.7.2    Understanding Internal Codes for Installation States

Subset installation status corresponds to setld utility processing phases as shown in Figure 4-1. Internal states are provided to describe software subset installation status.

Caution

Although subset installation status is reflected in more than one place, your SCP must use these internal states to determine subset installation status. Do not use the contents of the subset status file or the output of the setld -i command.

Table 4-6 describes these internal code states:

Table 4-6:  Software Subset Installation Status

Caution

Subset control programs (SCPs) cannot use the subset.lk and subset.dw files to determine if a subset is installed.

The distinction between whether a subset is loaded or installed is important because existing SCPs can fail if they only determine the existence of subset.lk files. For example:

• If your software is dependent upon another subset being installed, confirm that the other subset's installation status is _c_install_completed.

• If your software requires that another subset's files are present on the system, you only need to confirm that the other subset's installation status is _verify_completed.

See Section 4.7.3 for information about using subset installation status library routines to determine subset installation status.

See stl_sts(4) for more information about subset status files.

See setld(8) for more information about how the setld utility processes and displays software subsets.

4.7.3    Using Subset Installation Status Library Routines

Library routines for determining subset installation status are located in the /usr/share/lib/shell/libswdb shell script. These routines are applicable to both single systems and clusters.

Caution

Do not use subset status file values or output from the setld -i command to determine software subset installation status. Although these values correspond to the internal code state reflecting subset status, they are not identical and are subject to change. Use the supplied library routines to determine subset installation status in your SCPs.

To use these library routines in your subset control program, you first must source the library shell script as in the following example:

SHELL_LIB=${SHELL_LIB:-/usr/share/lib/shell}
. $SHELL_LIB/libswdb

The /usr/share/lib/shell/libswdb shell script includes the following library routines:

SWDB_IsInstalled subset

Returns 0 if subset is installed (in the _c_install_completed state) on the current member, otherwise returns 1.

Example:

SWDB_IsInstalled OSFBASE520

SWDB_IsLocked subset

Returns 0 if subset is installed and required by another subset, otherwise returns 1, indicating either that subset is not installed or that subset is installed but that no other subset is dependent upon it.

Example:

SWDB_IsLocked OSFBASE520

SWDB_IsCorrupt subset

Returns 0 if subset either failed to load or if the SCP failed in one of the setld utility phases, otherwise returns 1.

Example:

SWDB_IsCorrupt OSFBASE520

SWDB_GetState subset

Returns the internal code state reflecting the installation status of subset.

Example:

STATE=`SWDB_GetState OSFBASE520`
 

This example retrieves the current state of the OSFBASE520 subset and stores the value in the STATE variable. See Table 4-6 for descriptions of subset installation status internal code states.

SWDB_CompareStates state1 state2

Returns 0 if state1 is before state2 in the setld utility processing sequence, 1 if state1 is the same as state2, or 2 if state1 is after state2.

Use the results of SWDB_GetState as one of the arguments to the SWDB_CompareStates library routine to compare a subset's internal code state with a fixed code state. This lets you know if the subset status has reached a particular code state and reflects the progress of the subset installation. This routine is useful in determining where to resume processing during a recovery procedure.

Example:

STATE=`SWDB_GetState OSFBASE520`
SWDB_CompareStates $STATE _verify_completed

This example determines if the OSFBASE520 subset has reached the _verify_completed state on the current member.

The following list shows samples of old SCP code along with new code that uses the new library routines to determine subset installation status.

• In the first case, the SCP must determine if the OSFBASE520 subset is installed.

  • Old SCP code determines if the OSFBASE520.lk file exists and is a regular file. For example:

    [ -f OSFBASE520.lk ] && {
    ... code to execute if software is installed...
    }
    

  • New SCP code uses the SWDB_IsInstalled routine and looks for a return code of 0. For example:

    SWDB_IsInstalled OSFBASE520
    [ "$?" = "0" ] && {
    ... code to execute if software is installed...
    }
    

• In the second case, the SCP must determine if the OSFBASE520 subset is corrupt.

  • Old SCP code determines if the OSFBASE520.dw file exists. For example:

    [ -f OSFBASE520.dw ] && {
    ... code to execute if software is corrupt...
    }
    

  • New SCP code uses the SWDB_IsCorrupt routine and looks for a return code of 0. For example:

    SWDB_IsCorrupt OSFBASE520
    [ "$?" = "0" ] && {
    ... code to execute if software is corrupt...
    }
    

• In the third case, the SCP must determine if the software is loaded regardless of whether it is installed.

  • This case did not exist in previous versions of the operating system.

  • New SCP code uses the SWDB_GetState and SWDB_CompareState routines and looks for a return code that is not zero. For example:

    STATE=`SWDB_GetState OSFBASE520`
    SWDB_CompareStates $STATE _verify_loaded
    [ "$?" != "0" ] && {
    ... code to execute if software is loaded ...
    }
    

4.8    Stopping the Installation

Depending on the tests performed, your subset control program could decide to stop the installation or deletion of its subset. For example, if it finds a later version of the product already installed, the subset control program can stop the process.

To stop the installation or deletion of the subset, the subset control program must return a nonzero status to the setld utility when it exits the phase. If the subset control program returns a status of 0 (zero), the setld utility continues, assuming that the SCP is satisfied.

4.9    Creating SCPs for Different Product Kit Types

This section provides examples of subset control programs for each of the different product kit types. The following topics are discussed:

• Creating SCPs for user product kits (Section 4.9.1)

• Creating SCPs for kernel product kits (Section 4.9.2)

4.9.1    Creating User Product Kit SCPs

User product kits do not require subset control programs. You may need to provide one if your user product requires special installation tasks.

Example 4-9 shows a subset control program for the ODB user product, illustrating the types of operations that can be performed during different setld phases and illustrating one method of using the value of the ACT environment variable to determine what actions to perform.

Example 4-9:  Sample ODB User Product SCP

#!/sbin/sh
#
# Load all of the standard SCP library routines
#
SHELL_LIB=${SHELL_LIB:-/usr/share/lib/shell}
. $SHELL_LIB/libswdb
#
# Initialize the global variables, except in the M phase
#
if [ "$ACT" != "M" ]
then
	STL_ScpInit
fi
#
# Here is a list of files to back up if found on 
# the installed system.
#
BACKUP_FILES="\
	./usr/var/opt/$_PVCODE/templates/odb_template \
	./usr/var/opt/$_PVCODE/log_files/odb_log"
#
# The ACT variable is set by setld and determines which 
# phase of the SCP should be executed.
#
case $ACT in
#
# This is the menu phase of the SCP
#
M)
	#
	# Setld invokes the M phase with an argument and if
	# the argument is "-l" it means that a software load
	# is occurring.  
	#
	case $1 in
	-l)
		#
		# Examine the machine architecture to be sure
		# that this software is being installed on an 
		# alpha machine.  If it is not, exit with an 
		# error status so that setld will not display 
		# this subset on the menu of subsets to load.
		#
		ARCH=`./bin/machine`
		[ "$ARCH" = alpha ] || exit 1
		;;
	esac
	;;
PRE_L)
	#
	# Loop through the list of backup files and create 
	# backup copies for any file that is found on the 
	# system.
	#
	for FILE in $BACKUP_FILES
	do
		#
		# If the file to be backed up exists, create
		# a backup copy with a .OLD extension.
		#
		if [ -f $FILE ] 
		then
			cp $FILE $FILE.OLD
		fi
	done
	;;
POST_L)
	#
	# Initializes the variables so that the STL_LinkBack
	# routine can be executed
	#
	STL_LinkInit
	#
	# Create a symbolic link in the ./opt/$_PVCODE/sbin
	# directory that points to the ./sbin/ls file.
	#
	STL_LinkBack ls ./sbin ./opt/$_PVCODE/sbin
	;;
PRE_D)
	#
	# Remove the links created in the POST_L phase
	#
	rm -f ./opt/$_PVCODE/sbin/ls
	;;
POST_D)
	#
	# Restore the backup copies created during the PRE_L phase
	#
	for FILE in $BACKUP_FILES
	do
		 [ -f $FILE.OLD ] &&
		 mv $FILE.OLD $FILE
	done
	;;
C)
	#
	# Setld invokes the C phase with an argument that is 
	# either INSTALL or DELETE.  The INSTALL argument is
	# used on a setld load, while the DELETE argument is
	# used on a setld delete.
	#
	case $1 in
	INSTALL)
		#
		# Output a message letting the user know
		# that they should check the odb.conf file
		# before using the product.
		#
		echo "
The installation of the $_DESC ($_SUB)
software subset is complete.
 
Please check the /opt/$_PVCODE/odb.conf file before
using the $_DESC product."
		;;
	DELETE)
		;;
	esac
	;;
esac
exit 0

4.9.2    Creating Kernel Product Kit SCPs

In addition to the optional processing described in Section 4.6, a subset control program for a kernel product such as a device driver also must configure the driver into the kernel. When building subset control programs for a kernel product, you can choose one of the following configuration strategies:

• Write one subset control program for a kit that contains the software subset associated with the single binary module for a statically configured driver.

• Write one subset control program for a kit that contains the software subset associated with the single binary module for a dynamically configured driver.

• Write one subset control program for a kit that contains the software subsets associated with the device driver that can be statically or dynamically configured.

Example 4-10 shows the subset control program for the single binary module associated with the odb_kernel driver. The user can choose to configure this single binary module into the kernel either statically or dynamically. The subset control program runs the doconfig utility to configure the driver into the kernel.

Example 4-10:  Sample ODB Kernel Product SCP

#!/sbin/sh
#
# Load all of the standard SCP library routines
#
SHELL_LIB=${SHELL_LIB:-/usr/share/lib/shell}
. $SHELL_LIB/libswdb
# Load the standard Error library routines
# (location of the Error routine)
#
. $SHELL_LIB/Error
#
# Load the standard String library routines 
# (location of the ToUpper routine)
#
. $SHELL_LIB/Strings
#
# This routine rebuilds the static kernel
#
Rebuild_Static_Kernel()
{
	HNAME=`/sbin/hostname -s`
	HOSTNAME=`ToUpper $HNAME`
	if doconfig -c $HOSTNAME
	then
		echo "\nThe /sys/${HOSTNAME}/vmunix kernel has been"
		echo "moved to /vmunix and the changes will take effect"
		echo "the next time the system is rebooted."
		return 0
	else
		Error "
An error occurred while building the static kernel."
		return 1
	fi
}
KERNEL=/cluster/members/{memb}/boot_partition/vmunix
#
# Initialize the global variables, except in M phase
#
if [ "$ACT" != "M" ]
then
	STL_ScpInit
fi
#
# The ACT variable is set by setld and determines which 
# phase of the SCP should be executed.
#
case $ACT in
C)
	#
	# The kreg database file where all of the kernel
	# layered products are registered.
	#
	KREGFILE=./usr/sys/conf/.product.list
	case $1 in
	INSTALL)
		#
		# Merge the graphics support into the existing
		# /etc/sysconfigtab file
		#
		sysconfigdb -m -f ./opt/$_PVCODE/etc/sysconfigtab odb_graphics
		echo "*** $_DESC Product Installation Menu ***\n"
		echo "1. Statically configure the graphics support"
		echo "2. Dynamically configure the graphics support"
		echo "\nType the number of your choice []: \c"
		read answer
		case ${answer} in 
		1)
			#
			# Determine if the product is already registered
			# with the kreg database, and if it is, skip
			# registering it.
			#
			grep -q $_SUB $KREGFILE
			if [ "$?" != "0" ]
			then
				#
				# Register the product with the 
				# kernel using kreg
				#
				/sbin/kreg -l $_PCODE $_SUB \
					./opt/$_PVCODE/sys/BINARY
			fi
			#
			# Rebuild the static kernel
			#
			Rebuild_Static_Kernel
			#
			# Successful rebuild, so back up the existing
			# kernel and move the new one into place.
			#
			if [ "$?" = "0" ]
			then
				#
				# Make a backup copy of the kernel
				# as it existed prior to installing
				# this subset.  Since a subset can
				# be installed more than once (due to 
				# load/configuration failures or even 
				# because the user removed files) make
				# sure that the backup does not already
				# exist. 
				#
				if [ ! -f $KERNEL.pre_${_SUB)
				then
					mv $KERNEL $KERNEL/pre_${_SUB)
				fi
 
				#
				# Move the new kernel into place
				#
				mv /sys/${HOSTNAME}/vmunix /vmunix
				#
				# Place a marker on the system so that 
				# upon subset removal the SCP can
				# determine if it needs to remove a
				# static or dynamic configuration. 
				#
				touch ./opt/$_PVCODE/sys/BINARY/odb_graphics_static
			fi
			;;
		2)
			#
			# Dynamically load the odb_graphics subsystem
			# into the kernel
			#
			sysconfig -c odb_graphics
			;;
		esac
		;;
	DELETE)
		#
		# If the marker is present then the kernel option
		# was added statically.
		#
		if [ -f ./opt/$_PVCODE/sys/BINARY/odb_graphics_static ]
		then 
			#
			# Clean-up the marker
			#
			rm -f ./opt/$_PVCODE/sys/BINARY/odb_graphics_static
			#
			# Deregister the product using kreg
			#
			/sbin/kreg -d $_SUB
			#
			# Rebuild the static kernel
			#
			Rebuild_Static_Kernel
			#
			# Successful rebuild, remove the old backup
			# copy that was created when we installed.
			#
			if [ "$?" = "0" ]
			then
				mv /sys/${HOSTNAME}/vmunix /vmunix
				rm -f $KERNEL.pre_${_SUB}
			fi
		else
			#
			# Unload the dynamic kernel module
			#
			sysconfig -u odb_graphics
		fi
		#
		# Remove the entry from the /etc/sysconfigtab file
		#
		sysconfigdb -d odb_graphics
		;;
	esac
	;;
esac
exit 0