![[Return to Library]](BOOKSHLF.GIF)
![[TOC]](TOC.GIF)
![[PREV]](REW.GIF)
![[NEXT]](FF.GIF)
![[INDEX]](INDEX.GIF)
![[Help]](HELP.GIF)
A subset control program can perform all of these tasks. Layered product kits designed according to the guidelines in Chapter 2 must have subset control programs to create the required links.
This chapter describes how to write subset control programs for layered products.
The following sections describe the characteristics shared by all subset control programs.
Usually subset control programs are short. If written as a shell script, a subset control program should be under 100 lines in length. If your subset control program is lengthy, it is likely that you are trying to make up for a deficiency in the architecture or configuration of the product itself.
Place all subset control programs that you write in the scps directory, a subdirectory of the data directory. The subset control program's file name must match the subset name to which it belongs, and it must end with the scp suffix. For example, the ODB product defines two subsets, named OATODB100 and OATODBDOC100. If both subsets required a subset control program, the source file names would be OATODB100.scp and OATODBDOC100.scp.
When you create the subsets as described in Chapter 4, the kits utility copies the subset control programs from the scps directory to the instctrl directory. If a subset has no subset control program, the kits utility creates an empty subset control program file for it in the instctrl directory.
Do not copy these routines into your subset control program. Such a design would prevent your kit from receiving the benefit of enhancements or bug fixes made in future releases. Use the shell's source command to call in the routines, as follows:
. /usr/share/lib/shell/libscp
Figure 3-1 shows time lines of the setld utility when invoked with the -l, -d, and -v options. The actions that setld takes are written above the lines; the value of the ACT environment variable and the actions that the subset control program takes at each phase are written below the lines.
When it enters a new phase, the setld utility sets the ACT environment variable to a value that corresponds to the phase, then it invokes your subset control program. The subset control program checks the value of the environment variable to determine what action it needs to take. In some cases, setld also passes arguments to the subset control program. The subset control program uses the argument values to further determine the actions it needs to take.
Do not include a wildcard 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 can be invoked. The case statements that choose an action simply exit with zero status in these undetected cases, and setld continues.
To abort the installation or deletion of the subset, the subset control program must return a nonzero status to setld upon exiting from the particular phase for which it was called. If the subset control program returns a status of 0 (zero), setld assumes that the subset control program is satisfied that the setld process should continue.
| Variable | Description |
|---|---|
| _SUB | Subset identifier, for example, OATODB100 |
| _DESC | Subset description, for example, Document Building Tools |
| _PCODE | Product code, for example, OAT |
| _VCODE | Version code, for example, 100 |
| _PVCODE | Concatenation of product code and version code, for example, OAT100 |
| _PROD | Product description, for example, Orpheus Authoring Tools |
| _ROOT | The root directory of the installation |
| _SMDB | The location of the subset control files, ./usr/.smdb. |
| _INV | The inventory file, for example, OATODB100.inv |
| _CTRL | The subset control file, for example, OATODB100.ctrl |
| _OPT | The directory specifier /opt/ |
| _ORGEXT | File extension for files saved by the STL_LinkCreate routine, set to pre$_PVCODE |
| _OOPS | The NULL string, for dependency checking |
You can call the STL_ScpInit routine to define these variables and initialize them to their values for the current subset. This routine eliminates the need to hard code subset information in your subset control program. Use STL_ScpInit in all phases except the M phase to initialize global variables. All variable names begin with an underscore (_) for easy identification.
A subset control program may need to perform differently in a dataless environment, or disallow installation of the subset on such a system. In particular, you should be concerned with the following issues when writing a subset control program for installing in a dataless environment:
STL_IsDataless
Checks to see if a subset is being installed into a dataless environment.
Declines installation of a subset into a dataless environment.
Some tasks must take place during specific phases. For example, checking dependency relationships between subsets must take place during the PRE_L phase; creating links between product files and the standard directory structure must take place during the POST_L phase.
The following sections describe the tasks that a subset control program may take in each phase.
When it calls the subset control program during this phase, the setld utility passes one argument, which can have one of two values:
For example, during this phase the subset control program can issue the machine command to verify that the subset is being installed on the correct hardware platform. If the command returns a nonzero status, the subset control program exits with a nonzero status.
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, check the value of the $1 command argument (either -x for RIS extraction or -l for loading). For RIS extraction, the subset control program should do nothing during the M phase. When loading subsets, it should make this machine test.
case $ACT in
M)
case $1 in
-l)
[ "`/bin/machine`" = alpha ] || exit 1
;;
esac
;;
.
.
.
esac Installation for a dataless client requires that the
client's local copy of the machine command be used even
though the installation is being performed in the dataless area on a different
platform. Because the machine command is a shell script,
it can be executed on any platform.
For example, the subset might contain files with the same names as existing files. Duplicating existing file names is usually considered a poor practice. However, you might do this when installing a kit that contains binary files that would usually be installed by other kits but which must be replaced when your kit is installed.
The subset control program should also check for subset dependencies at this time. A subset dependency is a condition under which a subset depends on the existence of one or more other subsets. Because setld can both install and remove subsets, the system administrator could attempt to remove one or more subsets on which your product depends. Because those subsets do not in turn depend on your product's subsets, setld usually removes them without question, leaving your product disabled. You can prevent this inadvertent destruction of your product's environment by locking the subsets on which your subset depends. Subset locking can occur during the POST_L phase (see Section 3.2.3.3).
To make dependency management easier to implement, Digital provides a set of routines in the form of Bourne shell script code. These routines are in the file /usr/share/lib/shell/libscp.
depexp ::= wc_subset_id
| depexp not
| depexp depexp and
| depexp depexp or
The elements of a dependency expression (depexp)
are as follows:wc_subset_id
Represents a subset identifier that can contain file name expansion
characters (asterisks, question marks, or bracketed sets of characters) as
in OAT[RV]DOA*2??.
Requires two
dependency expressions. The dependency is satisfied if both expressions are
satisfied.
Requires two
dependency expressions. The dependency is satisfied if at least one of the
expressions is satisfied.
Requires one
dependency expression. The dependency is satisfied if the expression is not
satisfied.
The following are valid dependency expressions:
SUBSETX??0 SUBSETY200 not SUBSET[WX]100 SUBSETY200 and SUBSETX100 SUBSETY200 or SUBSETX100 SUBSETY200 and SUBSETZ300 or notThe last of these expressions evaluates as follows:
You can call the following routines to perform dependency checking:
STL_DepInit
Establishes
objects that the STL_DepEval routine uses. Before you
use STL_DepEval to check your subset's dependencies, you
must execute STL_DepInit once. This routine has no arguments
and returns no status.
Evaluates
the dependency expression that you specify as an argument. You can use as
many invocations of STL_DepEval as you need to verify that
all your subset dependencies are met.
As indicated in Chapter 2, a layered product's files should be installed in the /usr/opt and /var/opt areas and accessed by means of symbolic links in the standard UNIX directory structure, such as /usr/bin. These symbolic links, referred to as forward links, must be created during the POST_L phase, after the referent files are in place. Do not try to create these links during the C INSTALL phase because the /usr file system is not guaranteed to be writeable at that time. If your product includes links in /var, create these links also in POST_L. To maintain symmetry, you must remove links during the PRE_D phase, not during the C DELETE phase.
Symbolic links for layered products are usually created in the standard UNIX directories to refer to files that are actually in the layered product areas /usr/opt and /var/opt. These links are relatively straightforward.
Sometimes you may need to create links within your product's directories in the layered product areas that refer to files in the standard hierarchy. Such backward links must be created carefully because the layered product directories can themselves be symbolic links. This means that you cannot rely on knowing in advance the correct number of directory levels (../) to include in the ln commands for your backward links. For example, /var is frequently a link to /usr/var.
NFS clients importing products with backward links must have directory hierarchies that exactly match those on the server. Otherwise, the backward links fail. Note
Any nonempty directories in the inventory should leave the link bit unset (set to 0) to maximize the performance of STL_LinkCreate. See Example 3-2 for a subset control program that creates and removes symbolic links.
The following routines create forward links:
Creates
forward links from the installed system to the product areas, such as the /opt areas. Call STL_ScpInit first to initialize
required global variables. A forward link from the system to the product areas
(under /usr/opt or /var/opt) is created
for each file whose link flag is set in the master inventory file. For example,
the link bit of the ./usr/opt/OAT100/bin/attr file is set
as follows in the master inventory file:
4 ./usr/opt/OAT100/bin/attr OATODB100
After STL_LinkCreate runs, a symbolic link from ./usr/bin/attr points to ../../usr/opt/OAT100/bin/attr. If a file already exists in the same name space, setld saves it before the link takes its place. In the previous example,
if a ./usr/bin/attr file already exists, it is saved to ./usr/bin/attr.preOAT100 before the link gets created. All links
are created relative to the install root and are dataless safe.
Use the STL_LinkInit and STL_LinkBack routines to create backward links as follows, and use the rm shell command to remove them:
STL_LinkBack link_file file_path link_path
Example 3-1 uses STL_LinkInit and STL_LinkBack in the POST_L phase to create a link named /usr/opt/OAT100/lib/odb_users that refers to the real file /etc/odb_users, and removes the link in the PRE_D phase.
#! /sbin/sh case $ACT in
.
.
.
POST_L) STL_LinkInit STL_LinkBack odb_users ./etc ./usr/opt/OAT100/lib ;; PRE_D) rm -f ./usr/opt/OAT100/lib/odb_users ;; esac
For example, the ODB kit requires that some version of the Orpheus Authoring Tools base product be installed for the ODB product to work properly. Suppose that the OATBASE200 subset is present. When setld installs the OATODB100 subset from the ODB kit, it inserts a record that contains the subset identifier OATODB100 into the OATBASE200.lk file. When the system administrator uses setld to remove the OATBASE200 subset, setld checks OATBASE200.lk and finds a record that indicates that OATODB100 depends on OATBASE200. Then setld displays a warning message with this information and requires confirmation that the user really intends to remove the OATBASE200 subset.
If the administrator removes the OATODB100 subset, setld removes the corresponding record from the OATBASE200.lk file. Thereafter, the administrator can remove OATBASE200 without causing a dependency warning.
You can call the following routines to lock subsets:
STL_LockInit
Used
in the POST_L and PRE_D phases to establish
objects for the STL_DepLock and STL_DepUnLock routines. Before you use STL_DepLock or STL_DepUnLock to manipulate subset locks, you must execute STL_LockInit once. Because locking and unlocking are managed by
different invocations of your subset control program, STL_LockInit must appear in both the POST_L and PRE_D phases. You should code two instances of STL_LockInit rather than calling it once before you make a decision based on
the value of the ACT environment variable. This routine
has no arguments and returns no status.
Used
in the POST_L phase to add the new subset's name to the
lock lists for each of the subsets named as arguments. (You can use dependency
expressions as arguments.) The name of the new subset is the first argument
to STL_DepLock. For example, the following call to STL_DepLock places OATODB100 in the OATTOOLS100.lk and OATBASE2??.lk files:
STL_DepLock OATODB100 OATTOOLS100 OATBASE2??
The setld utility enters this phase at the following times:
The utility does not pass through this phase if the user loads the subset and specifies an alternate root directory with the -D flag.
The setld utility verifies the size and checksum information for each file in the subset during loading (when the user invokes setld with the -l option). Therefore, the setld utility does not call the subset control program for verification during the installation process. However, in a kit that contains multiple subsets, the last subset control program to be called could execute an installation verification program (IVP) or a suite of IVPs to ensure that the product works properly.
You can call the following routines to remove links and unlock subsets:
STL_LinkRemove
Removes
links created by STL_LinkCreate and restores any original
files that STL_LinkCreate saved. Call STL_ScpInit first to initialize required global variables. The STL_LinkRemove routine cannot remove modified links.
STL_DepUnLock subset depexp ...
Removes
the new subset's name from the lock lists for each of the subsets named as
arguments.
Not all subset control programs need to use the subset control file. It can be a convenient way to pass information between subsets, if such communication is necessary.
If you must use the subset control file, do so with extreme care. Bits 0 through 7 of the flags field are reserved by the setld utility, and you should not use or modify these bits in any way. Caution
To find the current settings of the flags field, the subset control program should read the subset control file, looking for a line that lists the settings. For example, the OATODBDOC100.ctrl file contains the following line:
FLAGS=34816The value of the flags field is expressed as a decimal integer. You can use the BitTest shell routine, contained in the file /usr/share/lib/shell/BitTest, to test an individual bit. The following example tests bit 11 of the flags field for the OATODBDOC100 subset:
#! /sbin/sh
. /usr/share/lib/shell/BitTest
flags=`sed -n '/FLAGS=/s///p' usr/.smdb./OATODBDOC100.ctrl`
BitTest $flags 11 && {
.
.
.
}
The program does not handle the V phase or the C DELETE phase. When setld invokes the program at these times, the program simply exits with a success status.
#!/sbin/sh
#
# Subset Control Program for OATODB??? subset
# INCLUDE SCP LIBRARY FUNCTIONS
[ `/bin/machine` = alpha ] &&
. /usr/share/lib/shell/libscp [1]
# BEGIN EXECUTION HERE
case $ACT in [2]
M) [3]
case $1 in
-l)
# hardware platform check
[ "`./bin/machine`" = alpha ] || exit 1
;;
esac
;;
PRE_L) [4]
# dependency checking
STL_ScpInit
STL_DepInit
STL_DepEval ${_PCODE}TOOLS??? ||
{
_OOPS="$_OOPS
Orpheus Authoring Tools (${_PCODE}TOOLS)"
}
STL_DepEval ${_PCODE}BASE[2-9]?? ||
{
_OOPS="$_OOPS
Orpheus Authoring Base Tools, Version 2.0 or later (${_PCODE}TOOLS)"
}
[ "$_OOPS ] &&
{
echo "
The $_DESC requires the existence of
the following uninstalled subset(s):
$_OOPS
Please install these subsets before retrying the installation.
" >&2
exit 1
}
;;
POST_L) [5]
# create symbolic links
STL_ScpInit
STL_LinkCreate
# dependency locking
STL_LockInit
STL_DepLock $_SUB ${_PCODE}TOOLS??? ${_PCODE}BASE[2-9]?? and
;;
C) [6]
STL_ScpInit
case $1 in
INSTALL)
echo "
Installation of the $_DESC ($_SUB)
subset is complete.
Before using the tools in this subset, please read the README.odb
file located in the /usr/lib/br directory for information on the
kit's contents and for release information.
"
;;
esac
;;
PRE_D) [7]
# remove symbolic links
STL_ScpInit
STL_LinkRemove
# dependency unlocking [8]
STL_LockInit
STL_DepUnLock $_SUB ${_PCODE}TOOLS??? ${_PCODE}BASE[2-9]?? and
;;
esac
exit 0 [9]
Example 3-3 shows the subset control program for the single binary module associated with the /dev/none 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.
#!/sbin/sh
#
#
# NONE.scp - Install the files associated with the /dev/none
# device driver. This driver, implemented as a single binary
# module (.mod file), can be statically or dynamically configured
# into the kernel.
#
case "$ACT" in [1]
C)
case $1 in
INSTALL) [2]
echo "***** /dev/none Product Installation Menu *****"
echo "***** *****"
echo "1. Install the static device driver subset."
echo "2. Install the dynamic device driver subset."
echo" Type the number for your choice [] "
read answer
case ${answer} in
1) [3]
# Register the files associated with the static
# /dev/none device driver product.
kreg -l EasyDriverInc ESANONESTATIC100 /usr/opt/ESA100 [4]
# Add the files associated with the statically configured
# /dev/none device driver product to the customer's
# /etc/sysconfigtab database
sysconfigdb -a -f /usr/opt/ESA100/sysconfigtab none [5]
echo "The rest of the procedure will take 5-15 minutes"
echo "to rebuild your kernel, depending on the processor"
echo "type."
echo ""
echo "Starting kernel rebuild... "
if doconfig -c $HOSTNAME [6]
then
echo "Kernel built successfully"
else
1>&2 echo "Error building kernel."
return 1
fi
;;
2) [7]
# Add the files associated with the dynamically configured
# /dev/none device driver product to the customer's
# /etc/sysconfigtab database
sysconfigdb -a -f /usr/opt/ESA100/sysconfigtab none [8]
# Copy the none.mod file to the /subsys directory. Create
# the none.mth driver method by linking to device.mth
# /subsys/none.mth -> /subsys/device.mth
cp /usr/opt/ESA100/none.mod /subsys/none.mod [9]
ln -s /subsys/device.mth /subsys/none.mth [10]
# Load the /dev/none device driver and create the device
# special files
sysconfig -c none [11]
echo "The /dev/none device driver was added to your
echo "/etc/sysconfigtab database." [12]
;;
esac
;;
DELETE) [13]
echo "***** /dev/none Product Installation Menu *****"
echo "***** *****"
echo "1. Delete the static /dev/none device driver subset."
echo "2. Delete the dynamic /dev/none device driver subset."
echo" Type the number for your choice [] "
read answer
case ${answer} in
1)
kreg -d ESANONESTATIC100 [14]
# Delete the /dev/none device driver's entry from the
# /etc/sysconfigtab database
sysconfigdb -d none [15]
echo "The rest of the procedure will take 5-15 minutes"
echo "to rebuild your kernel, depending on the processor"
echo "type."
echo ""
echo "Starting kernel rebuild... "
if doconfig -c $HOSTNAME [16]
then
echo "Kernel built successfully"
else
1>&2 echo "Error building kernel."
return 1
fi
;;
2)
# Make sure the /dev/none device driver is not currently
# loaded
sysconfig -u none [17]
# Delete the /dev/none device driver's entry from the
# /etc/sysconfigtab database
sysconfigdb -d none [18]
;;
esac
;;
esac
;;
esac
exit 0
This flag indicates that the subset was loaded, and it directs kreg to register the device driver product as a new kernel extension.
The company name is EasyDriverInc. The kreg utility places this name in the company name field of the customer's /usr/sys/conf/.product.list file.
The software subset name for this device driver product is ESANONESTATIC100. The subset name consists of the product code, subset mnemonic, and 3-digit version code. The kreg utility extracts information from the specified subset data and loads it into the customer's /usr/sys/conf/.product.list file.
The directory on the customer's system where kreg copies the files associated with this driver product is /usr/opt/ESA100. The kreg utility places this directory in the driver files path field of the customer's /usr/sys/conf/.product.list file.
This flag causes sysconfigdb to add the device driver entry to the customer's /etc/sysconfigtab database.
This flag precedes the name of the sysconfigtab file fragment whose device driver entry is to be added to the /etc/sysconfigtab database. This flag is used with the -a flag.
The kit developer at EasyDriver, Inc. specifies the path /usr/opt/ESA100/sysconfigtab to indicate the location of the sysconfigtab file fragment for the /dev/none device driver.
The kit developer at EasyDriver, Inc. specifies none as the name of the driver whose associated information is added to the /etc/sysconfigtab database. This name is obtained from the entry_name item of the sysconfigtab file fragment, as described in Writing Device Drivers: Tutorial.
The RIS utility provides the ability to install kits into a RIS area for subsequent installation on a client system. When installing the kit into a RIS area, the RIS installation procedure calls the subset control program, passing EXTRACT as an argument. The RIS utility, not the setld utility, defines this phase. The subset control program must set the ACT environment variable to EXTRACT in this situation.
The RIS utility invokes the subset control program at the end of the extract procedure when installing the kit on a RIS server. During this phase, the subset control program needs to invoke the kreg utility to register the new product with the kernel so that the driver is properly installed when the RIS server builds a new install kernel. In addition, the subset control program invokes the sysconfigdb utility to modify the /etc/sysconfigtab database. The modifications to the server by kreg and sysconfigdb occur only in the RIS area, as opposed to the server's root directory.
A kit for a foreign device may be installed by osfboot or by the RIS utility during bootstrap linking of the kernel. The subset control program in Example 3-4 supports both types of installation. The subset control program does not provide a menu of configuration options because a driver for a foreign device must be statically configured.
#!/sbin/sh
#
#
# EDGD.scp - Install files associated with the statically
# configured /dev/edgd device driver product.
#
#
#
# RIS server installation of a foreign kit
#
# In the case of RIS extract, the variable ACT is NULL, and
# the first parameter passed to the subset control program
# specifies the phase.
#
[ "$ACT" ] || [1]
ACT=$1
case "$ACT" in
#
# Configuration INSTALL phase takes place after the subsets
# are loaded. This phase configures the device driver into
# the system. It is invoked on all installations of the kit
# during CD-ROM or RIS-client Digital UNIX installation, and
# setld -l on an installed system.
#
C)
case $1 in
INSTALL) [2]
echo "INSTALL phase "
# Register the files associated with the static
# /dev/edgd device driver product.
kreg -l EasyDriverInc EDGSTATIC100 /usr/opt/EDG100 [3]
# Add the sysconfigtab file fragment associated with the
# static /dev/edgd device driver product to the customer's
# /etc/sysconfigtab database.
sysconfigdb -a -f /usr/opt/EDG100/sysconfigtab edgd [4]
;;
esac
;;
#
# RIS server kit installation phase
#
EXTRACT) [5]
echo "EXTRACT phase "
#
# The RIS server does this with ROOT set to the RIS area,
# and the RIS area must be extracted, not linked to a CD-ROM.
#
# Register the files associated with the static /dev/edgd
# device driver product.
kreg -l EasyDriverInc EDGSTATIC100 /usr/opt/EDG100 [6]
# Break link between /etc/sysconfigtab and /etc/.new..sysconfigtab
# so the subset control program can run sysconfigdb for the RIS
# installation.
rm /etc/sysconfigtab [7]
# Copy the /etc/sysconfigtab database to client system.
cp /etc/.new..sysconfigtab /etc/sysconfigtab [8]
# Add the files associated with the static /dev/edgd device
# driver product to the customer's /etc/sysconfigtab database.
sysconfigdb -a -f /usr/opt/EDG100/sysconfigtab edgd [9]
;;
#
# This phase is executed on a setld -d command, which removes
# the subset from the system.
#
POST_D) [10]
kreg -d EDGSTATIC100 [11]
rm -rf /usr/opt/EDG100 [12]
sysconfigdb -d edgd [13]
echo "The /dev/edgd device driver is no longer on the system." [14]
echo "Remember to build a new kernel by running doconfig to"
echo "remove the /dev/edgd driver functionality."
;;
esac
exit 0
This flag indicates that the subset was loaded, and it directs kreg to register the device driver product as a new kernel extension.
The company name is EasyDriverInc. The kreg utility places this name in the company name field of the customer's /usr/sys/conf/.product.list file.
The software subset name for this device driver product is EDGSTATIC100. The subset name consists of the product code, subset mnemonic, and 3-digit version code. The kreg utility extracts information from the specified subset data and loads it into the customer's /usr/sys/conf/.product.list file.
The directory on the customer's system where kreg copies the files associated with this driver product is /usr/opt/EDG100. The kreg utility places this directory in the driver files path field of the customer's /usr/sys/conf/.product.list file.
This flag causes sysconfigdb to add the device driver entry to the customer's /etc/sysconfigtab database.
This flag precedes the name of the sysconfigtab file fragment whose device driver entry is to be added to the /etc/sysconfigtab database. This flag is used with the -a flag.
The kit developer at EasyDriver, Inc. specifies the path /usr/opt/EDG100/sysconfigtab to indicate the location of the sysconfigtab file fragment for the /dev/edgd device driver.
The kit developer at EasyDriver, Inc. specifies edgd as the name of the driver whose associated information is added to the /etc/sysconfigtab database. This name is obtained from the entry_name item of the sysconfigtab file fragment, as described in Writing Device Drivers: Tutorial.