![[Return to Library]](BOOKSHELF.GIF)
![[Contents]](TOC.GIF)
![[Previous Chapter]](REW.GIF)
![[Next Section]](NEXT.GIF)
![[Next Chapter]](FF.GIF)
![[Index]](INDEX.GIF)
![[Help]](HELP.GIF)
Subset control programs perform special tasks beyond the basic installation managed by setld. If your kit requires no special installation handling, you do not need subset control programs. The following are some of the reasons why you might need a subset control program:
All of these tasks can be performed by a subset control program. 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.
Regardless of the specific tasks that they perform, all subset control programs perform these common tasks:
The following sections describe the common tasks that all subset control programs perform.
![[Previous Section]](PREV.GIF)
You create one subset control program for each subset that requires special handling during installation. The program can be written in any programming language, but you must take care that your subset control program can be executed on all platforms on which the kit can be installed. If your product works on more than one hardware platform, you cannot write your subset control program in a compiled language. For this reason, Digital recommends that you write your subset control program as a script for /sbin/sh.
Usually subset control programs are very short programs. 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.
Digital UNIX provides a set of routines in the form of Bourne shell script code. These routines are in the file /usr/share/lib/shell/libscp.
You should 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
Your kit does not need to do anything to invoke its subset control program. The setld utility invokes it at various times, or phases. Before invoking your program, setld sets the ACT environment variable to indicate the current phase. The subset control program can perform any tasks that it needs during a phase, such as creating or deleting a file or displaying messages. Certain tasks, such as performing dependency checks or creating forward and backward links, should be performed only during specific phases, if the installation requires them.
Table 3-1 lists the phases at which setld calls the subset control program and the value of the ACT environment variable at each phase. Tasks performed during specific phases are also mentioned in the table.
| ACT Variable | Description |
| M | Before displaying the menu of subsets available for installation. At this phase, the subset control program can determine whether the subset should be included in the menu. |
| PRE_L | Before loading the subset. During this phase, the subset control program can perform any necessary dependency checks. |
| POST_L | After loading the subset. During this phase, the subset control program can create any forward or backward links that it needs and lock any subsets on which it depends. |
| C INSTALL | After securing the subset. During this phase, the subset control program can perform any configuration operations that are necessary. |
| V | When verifying the subset. During this phase, the subset control program can run an installation verification procedure. |
| C DELETE | Before deleting the subset. During this phase, the subset control program can perform any unconfiguration operations that may be necessary before deleting the subset. |
| PRE_D | Before deleting a subset. During this phase, the subset control program can reverse any actions that may have been taken during the POST_L phase, such as removing links and dependency locks. |
| POST_D | After deleting the subset. During this phase, the subset control program can reverse any actions that may have been taken during the PRE_L phase. |
When it enters a new phase, the setld utility sets the ACT environment variable to a value corresponding to the phase. 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.
Depending on the tests it makes, your subset control program could decide at some point to abort the installation or deletion of its subset. For example, if it checks for the existence of subsets upon which your product depends and fails to find one or more of them, the subset control program can abort the process.
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 zero (0), setld assumes that the subset control program is satisfied that the setld process should continue.
The subset control program can use global variables to store information about the current subset. These variables are listed in Table 3-2.
| 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 | Set to /opt/ |
| _ORGEXT | File extension for files saved by the STL_LinkCreate routine, set to pre$_PVCODE |
| _OOPS | For dependency checking, set to NULL string |
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.
In many environments, every computer has a copy of the operating system software on its own disk. In a dataless environment, one computer acts as a server by storing the software on its disk. Other computers, called clients, access the software across the Local Area Network (LAN) rather than from their local disks. Sharing software across the network saves disk space on each of the computers in the network.
A subset control program may need to perform differently in a dataless environment, or disallow installation of the subset on such a system. You can use the following routines to handle dataless environments:
The setld utility calls the subset control program at each of the phases listed in Table 3-1. Before calling the subset control program, setld sets the ACT environment variable to a value indicating the current phase. The subset control program uses this variable to determine what action to take. You can write the subset control program as a series of case statements, where each statement handles one phase.
Some tasks must take place during specific phases. For example, establishing 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.
At the beginning of installation, the setld utility presents a menu of subsets that it can install. Before displaying the menu, it 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 if it will permit its subset to be offered in the menu. The subset control program should return a value of 0 (zero) if the subset can be included in the menu.
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 verify that the subset is being installed on the correct hardware platform, by issuing the machine(1) command. 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 actually executes the subset's subset control program to make use of the subset control 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. The following Bourne shell example illustrates one way to code the M phase. The subset control program checks to see if it is running on Digital's Alpha processor:
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.
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 for each subset. At this time, the subset control program can take any action required to protect existing files.
For example, the subset might contain files with names duplicating those of existing files. Duplicating existing file names is usually considered a poor practice. One example of a situation in which you might do so is for the installation of a kit that contains binary files that would usually be installed by other kits but which must be different when your kit is installed.
The subset control program should also check for subset dependencies at this time. Subset dependencies are conditions 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 will remove them without question, leaving your product unable to work. 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.
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.
The dependency management routines use dependency expressions to examine conditions on the system. A dependency expression is a postfix logical expression that describes the conditions on which the subset depends. Dependency expressions are recursive left to right and processed using conventional postfix techniques. Dependency expressions are defined in Backus-Naur form, as follows:
|
depexp
|
::=
|
wc_subset_id
|
OAT[RV]DOA*2??
The following are valid dependency expressions:
SUBSETX??0 SUBSETY200 not SUBSET[WX]100 SUBSETY200 and SUBSETX100 SUBSETY200 or SUBSETX100 SUBSETY200 and SUBSETZ300 or not
The last of these expressions evaluates as follows:
You can call the following routines to perform dependency checking:
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 are usually protected from modification when the installation is complete, such as moving them to a different location. The subset control program should create links and perform subset dependency locking at this time.
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 PRE_D, not during C DELETE.
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.
Under certain circumstances, however, you might 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.
When a kit is installed on an NFS server, all the backward links are made in the server's kit area. Then, when that area is exported to clients, the links are already in place for the client. Clients do not need to create any backward links.
Note
NFS clients importing products with backward links must have directory hierarchies that exactly match those on the server. Otherwise, the backward links fail.
You create forward links during the POST_L phase. To create the link, you must first call the STL_ScpInit routine to initialize global variables, then call the STL_LinkCreate routine. The STL_ScpInit routine looks in the master inventory file for any entries flagged for linking. The entry in the master inventory indicates where the file has been installed. The STL_LinkCreate routine creates a link to that file from a directory within the standard directory structure, such as /usr/bin. Thus, for the STL_LinkCreate routine to work correctly, you must specify the files that require symbolic links by setting the link bit in the master inventory file. (See Chapter 4 for more information on the master inventory file.)
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 the creation and removal of symbolic links.
The following routines creates forward links:
This routine has no arguments and returns no status.
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.
The subset control program should create backward links, not the link management program, 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.
Use the STL_LinkInit and STL_LinkBack routines to create backward links as follows, and use the rm shell commmand to remove them:
This routine has no arguments and returns no status.
This routine returns no status.
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
Every subset in the system's inventory has two lock files:
When a subset is installed, setld creates one of these two lock files. At that time, the lock file is empty. Assuming successful installation, that subset is then available for dependency checks and locking performed on behalf of subsets installed later. A subset's lock file can contain any number of records, each naming a single dependent subset.
For example, the ODB kit requires that some version of the Orpheus Authoring Tools base product be installed in order 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 containing 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 indicating 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, OATBASE200 can be removed without flagging a dependency warning.
You can call the following routines to lock subsets:
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.
STL_DepLock OATODB100 OATTOOLS100 OATBASE2??
After securing the subset, the setld utility sets the ACT environment variable to C 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 would statically or dynamically configure a device driver at this point. The subset control program cannot create a layered product's symbolic links at this time.
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.
When the user invokes setld with the -v option, the utility sets the ACT environment variable to V and calls the subset control program for each subset. At this time the subset control program can perform tests to verify that the subset is installed correctly.
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 containing multiple subsets, the last subset control program to be called could execute an installation verification program (IVP) or suite of IVPs to ensure that the product works properly.
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 unconfigure a statically or dynamically configured driver during this phase. The subset control program cannot remove a layered product's links at this time.
When the user invokes setld 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 dependency locks and links, or restoring moved files to their default installation locations so that setld can delete them properly. A return status of 0 (zero) allows the delete operation to continue.
You can call the following routines to remove links and unlock subsets:
Modified links cannot be removed by using STL_LinkRemove.
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.
As explained in Table 4-3, you can use bits 8 to 15 of the subset control file's FLAGS attribute to specify special subset-related information. The subset control program can read these bits from the subset control file into which this information is placed when the kit is built. During installation, the setld utility moves the subset control file to the ./usr/.smdb. directory, where the subset control program can read the file as needed.
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 attribute are reserved by the setld utility, and you should not use or modify these bits in any way.
To find the current settings of the FLAGS attribute, 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=34816
The value of the
FLAGS
attribute 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
attribute for the OATODBDOC100 subset:
#! /sbin/sh
. /usr/share/lib/shell/BitTest
flags=`sed -n '/FLAGS=/s///p' usr/.smdb./OATODBDOC100.ctrl` BitTest $flags 11 && {
.
.
.
}
Example 3-2 shows a subset control program for the ODB product. This program illustrates one correct method for obtaining the value of the ACT environment variable. It uses the value of the variable to determine what actions to perform, as follows:
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 require 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 ;; POST_D) [8] # dependency unlocking STL_ScpInit STL_LockInit STL_DepUnLock $_SUB ${_PCODE}TOOLS??? ${_PCODE}BASE[2-9]?? and ;;
esac
exit 0 [9]
After creating the links, the subset control program secures the subset by locking the subsets on which it depends to ensure that they are not deleted without warning the user of potential problems. The subset control program uses the $_SUB and $_PCODE global variables to define the subsets in the dependency relationship. [Return to example]
When building subset control programs for a kernel product, such as a device driver, you can choose one of the following strategies:
Example 3-3 shows the subset control program for the single binary module associated with the /dev/none driver. This single binary module can be statically or dynamically configured 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 # sysconfigtab database sysconfigdb -a -f /usr/opt/ESA100/sysconfigtab none [5]
# Reminder [6] echo "The /dev/none device driver is installed on your echo "system. Before your utilities can make use of echo "the driver, you must build a new kernel by running echo "doconfig." ;;
2) [7] # Add the files associated with the dynamically configured # /dev/none device driver product to the customer's # 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 " global 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 # sysconfigtab database
sysconfigdb -d none [15] echo "The /dev/none device driver is no longer on the echo "system. Remember to build a new kernel to remove echo "the /dev/none driver functionality." [16] ;;
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 # sysconfigtab database sysconfigdb -d none [18] ;; esac ;; esac ;; esac exit 0
The SCP calls kreg with the following arguments:
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/.products.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/.products.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/.products.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 attribute of the sysconfigtab file fragment, as described in Writing Device Drivers: Tutorial.
A foreign device driver must be statically configured. Therefore, the subset control program for this driver does not need to provide a menu of configuration options. However, the subset control program must support the Remote Installation Services (RIS) utility, as this is the mechanism for installing foreign devices.
The RIS utility provides the ability to install foreign device driver product kits into a RIS area for subsequent installation on a client system. The RIS installation procedure bypasses setld's C INSTALL phase, where the subset control program would ordinarily configure the driver into the system. Instead, the RIS installation procedure calls the subset control program at two times, passing either EXTRACT or INSTALL as an argument. These two phases are defined by the RIS utility, not by the setld utility. The subset control program must set the ACT environment variable in this situation.
The subset control program needs to contain an EXTRACT action phase for RIS. This phase 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 invokes 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.
The /etc/sysconfigtab database created during this phase of the subset control program is copied onto the client system as part of the installation. This copy replaces the /etc/sysconfigtab database installed as part of the base operating system subset load. This ensures that the proper support for the driver exists on the system.
The subset control program is called with the INSTALL argument the first time the newly installed system boots up. At this time, the subset control program calls the kreg utility to register the driver with the new system. This adds the driver into the kernel that is built as part of the installation process. No modification to the /etc/sysconfigtab database is required at this point because the installation process has taken care of the required modification as part of the installation, during the EXTRACT phase.
A foreign device driver product may also be installed as a kernel product. If so, the subset control program must contain code to support both types of installation, as shown in Example 3-4.
#!/sbin/sh # # # EDGD.scp - Install files associated with the statically # configured /dev/edgd device driver product. # #
# # RIS server installation of a foriegn kit # # In the case of RIS extract, the variable ACT is NULL, and # the first parameter passed to the SCP specifies the phase. # [ "$ACT" ] || [1] ACT=$1
case "$ACT" in
# # Configuration install phase takes place after the susbsets # 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 files associated with the static /dev/edgd # device driver product to the customer's sysconfigtab # database. sysconfigdb -a -f /usr/opt/EDG100/sysconfigtab edgd [4]
# Reminder [5] echo echo "The /dev/edgd device driver is installed on your system." echo "Before you can make use of the driver, you" echo "must build a new kernel by running doconfig." echo echo "See /usr/opt/EDG100/README for complete" echo "installation instructions" echo ;; esac ;;
# # RIS Server kit installation phase # EXTRACT) [6]
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 [7]
# Break link between /etc/sysconfigtab and /etc/.new..sysconfigtab # so we can run sysconfigdb for the RIS installation rm /etc/sysconfigtab [8]
# Copy the /etc/sysconfigtab database to client system. cp /etc/.new..sysconfigtab /etc/sysconfigtab [9]
# Add the files associated with the loadable /dev/edgd device # driver product to the customer's sysconfigtab data base. sysconfigdb -a -f /usr/opt/EDG100/sysconfigtab edgd [10] ;;
# # This phase is executed on a setld -d command which # is used to remove the subset from the system. # POST_D) [11]
kreg -d EDGSTATIC100 [12] rm -rf /usr/opt/EDG100 [13] sysconfigdb -d edgd [14]
echo "The /dev/edgd device driver is no longer on the system." [15] echo "Remember to build a new kernel to remove the /dev/edgd" echo "driver functionality." ;;
esac exit 0
The SCP calls kreg with the following arguments:
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/.products.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/.products.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/.products.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/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 attribute of the sysconfigtab file fragment, as described in Writing Device Drivers: Tutorial.