3    Preparing Subsets

In a product kit, a subset is the smallest installable entity compatible with the setld utility. The kit developer specifies how many subsets are included in the kit and what files each subset contains.

As a kit developer, you must perform the following tasks to build subsets and associated control files:

1. Organize product files into subsets. (Section 3.1)

2. Create a master inventory file containing information about each file in the subset. (Section 3.2)

3. Create a key file to define product attributes such as the product name, product version, and subset definitions. (Section 3.3)

3.1    Grouping Files into Subsets

Files that are required for the product to work should be grouped together by function. For example, if the product has two parts such as a user interface and underlying functional code, you should group them into two subsets. A file's physical location is not necessarily a factor in determining the subset to which it belongs.

Optional files also should be grouped together by function, but should be grouped separately from mandatory files. This prevents unnecessary files from being loaded when you install the mandatory subsets.

Note

Subset names are restricted to alphanumeric characters (A-Z, a-z, 0-9) and the underscore character ( _ ). If you use any other characters in subset names, the setld utility may fail.

The fictitious ODB user product requires two subsets:

• OATODB100, a mandatory subset, contains the files needed to run the product. This includes all product files except the odb_template file.

• OATODBTEMPS100, an optional subset, contains documentation templates in the odb_template file.

By placing the documentation templates in a separate subset, the customer's system administrator can choose not to install them if storage space is limited.

Figure 3-1 shows how the files that make up the ODB product are grouped into subsets. The physical location of a file is not necessarily a factor in determining the subset to which it belongs.

Figure 3-1:  ODB Product Subsets and Files

3.2    Creating the Master Inventory File

After choosing subset names and deciding their contents, you have to create a master inventory file to specify the subset names and the files that each subset contains.

Table 3-1 describes the fields in the master inventory file.

Table 3-1:  Master Inventory File

Follow these steps to create a master inventory file:

1. You can create a master inventory file with your preferred text editor or create the file with the touch command. The master inventory file name must consist of the product code and version with the suffix .mi. The file should be located in the data directory of the kit. For example:

   % cd /mykit/data
   % touch OAT100.mi
   

2. The first time you process a kit, the master inventory file is empty. You must enter one record for each file that belongs on the kit. To get an initial list of these files, use the newinv command with the file name of the empty master inventory file and the pathname of the source hierarchy's top-level directory. For example, to invoke newinv on the master inventory file for the ODB product, specify the pathname to the source hierarchy as a relative path from the current directory (data), similar to the following:

   % newinv OAT100.mi ../src
   Scanning new baselevel files...done.
    
   Sorting inventories...done.
    
   Joining...done.
    
   Awking...done.
    
           *** THIS BUILD CONTAINS FILES THAT ARE NOT IN THE PREVIOUS BUILD ***
    
           You will be placed in the editor with the file containing
                   the names of these new files.
    
           If you wish these new files to become part of the product,
                   you must convert the line for the wanted files into
                   an inventory record.
    
           Any records remaining in the file when you exit the editor
                   will become part of the new inventory.
    
           Type <RETURN> when you are ready or CTRL/C to quit:
   

   The newinv utility produces a list of files that are present in the source hierarchy and opens a working copy of the master inventory file in the vi editor (or the editor specified by your $EDITOR environment variable) to make the required changes.

   Caution

   The first time that you run the newinv utility for a product kit, the following files are created in the /mykit/data directory in addition to the OAT100.mi file:

   OAT100.mi.bkp

   OAT100.mi.dead

   OAT100.mi.extra

   OAT100.mi.join

   OAT100.mi.tmp

   Do not modify or delete these additional files. They are used during subsequent master inventory file updates with the newinv utility.

3. First, remove the entries for any files that should not appear on the kit. Second, add the flag and subset identifier to the entry for each file that should appear in the kit.

   Note

   Be extremely careful when you edit the master inventory file. Separate fields in this file with a single [Tab] character, not spaces. File names must not contain [Space] or [Tab] characters.

   Use dot-relative pathnames for the files listed in the master inventory file; do not use absolute pathnames. By default, the setld utility operates from the system's root ( / ) directory unless you specify an alternate root with the -D option.

   Example 3-1 shows that the ODB kit has two subsets:

   • The OATODB100 subset contains mandatory commands and utilities

   • The OATODBTEMPS100 subset contains optional document templates

   Example 3-1:  Sample ODB Kit Master Inventory File

   0	./cluster	RESERVED  [1]
   0	./cluster/members	RESERVED  [1]
   0	./cluster/members/member0	RESERVED  [1]
   0	./cluster/members/member0/opt	RESERVED  [1]
   0	./cluster/members/member0/opt/OAT100	OATODB100  [2]
   2	./cluster/members/member0/opt/OAT100/odb.conf	OATODB100  [2] [3]
   0	./opt	RESERVED  [1]
   0	./opt/OAT100	OATODB100  [2]
   2	./opt/OAT100/odb.conf	OATODB100  [2] [3]
   0	./opt/OAT100/sbin	OATODB100  [2]
   0	./opt/OAT100/sbin/odb_recover	OATODB100  [2]
   0	./usr	RESERVED  [1]
   0	./usr/opt	RESERVED  [1]
   0	./usr/opt/OAT100	OATODB100  [2]
   0	./usr/opt/OAT100/bin	OATODB100  [2]
   0	./usr/opt/OAT100/bin/odb_start	OATODB100  [2]
   0	./usr/var	RESERVED  [1]
   0	./usr/var/cluster	RESERVED  [1]
   0	./usr/var/cluster/members	RESERVED  [1]
   0	./usr/var/cluster/members/member0	RESERVED  [1]
   0	./usr/var/cluster/members/member0/opt	 RESERVED  [1]
   0	./usr/var/cluster/members/member0/opt/OAT100	OATODB100  [2]
   0	./usr/var/cluster/members/member0/opt/OAT100/log_files	OATODB100  [2]
   0	./usr/var/cluster/members/member0/opt/OAT100/log_files/odb_log	OATODB100  [2] [4]
   0	./usr/var/opt	RESERVED  [1]
   0	./usr/var/opt/OAT100	OATODB100  [2]
   0	./usr/var/opt/OAT100/log_files	OATODB100  [2]
   0	./usr/var/opt/OAT100/log_files/odb_log	OATODB100  [2] [4]
   0	./usr/var/opt/OAT100/templates	OATODBTEMPS100  [5]
   0	./usr/var/opt/OAT100/templates/odb_template	OATODBTEMPS100  [5]
    
    
   

   1. Add the RESERVED identifier to the directories shown. This tells the setld utility not to overwrite the directory if it already exists on the customer's system. [Return to example]

   2. Add the OATODB100 subset identifier to the files and directories shown. This is the mandatory subset for the ODB product. [Return to example]

   3. The odb.conf file is the ODB product configuration file. The member-specific file resides in the ./cluster/members/member0/opt/OAT100 directory, and the context-dependent symbolic link (CDSL) resides in the ./opt/OAT100 directory. Change the Flags field to 2 to show that this file can change either during or after subset installation. [Return to example]

   4. The odb_log file is the ODB product log file. The member-specific file resides in the ./usr/var/cluster/members/member0/opt/OAT100/log_files directory, and the CDSL resides in the ./usr/var/opt/OAT100/log_files directory. [Return to example]

   5. Add the OATODBTEMPS100 subset identifier to the files and directories shown. [Return to example]

4. After you edit the file list and exit the editor, you see output similar to the following:

   Merging...done.
    
   Sorting...done.
    
   Master inventory update complete.
    
    
   

3.3    Creating the Key File

The key file defines product attributes such as the product name, product version, and subset definitions, as well as the name of the kit's master inventory file. It consists of a product attributes section and a subset descriptor section. The key file name must consist of the product code and version followed by .k, so that OAT100.k is the key file for the ODB kit. Create the key file in the data directory of your kit-building directory structure, for example: /mykit/data.

Example 3-2 shows the ODB product kit key file with the two sections separated by two percent signs ( %% ) on their own line:

Example 3-2:  Sample ODB Kit Key File

#
# Product-level attributes  [1]
#
NAME='Orpheus Document Builder'
CODE=OAT
VERS=100
MI=/mykit/data/OAT100.mi  [2]
COMPRESS=1  [3]
#
# Subset definitions  [4]
#
%%  [5]
OATODB100	.	0	'Document Builder Tools'  [6]
OATODBTEMPS100	OATODB100|OSFDCMT???	2	'Document Builder Templates'  [7]

1. The product attributes portion of the file describes the naming conventions for the kit and provides kit-level instructions for the kits command. This section of the key file consists of several lines of attribute-value pairs as described in Table 3-2. The order of these attribute-value pairs is not significant. Each attribute name is separated from its value by an equal sign, for example: attribute=value. You can include comment lines, which begin with a pound sign, for example: # Comment line in key file. [Return to example]

2. The value of the MI attribute contains the path to the master inventory file. This may be either an absolute path or a relative path from the directory where the kits command is executed. [Return to example]

3. The COMPRESS attribute has a value of 0 for uncompressed subsets or 1 for compressed tar format subsets. If you do not specify this attribute, the default is COMPRESS=0. User and kernel product kit subsets may be compressed or uncompressed. [Return to example]

4. The subset descriptor portion of the file describes each of the subsets in the kit and provides subset-level instructions for the kits command. This section contains one line for each subset in the kit. Each line consists of four fields, each separated by a single [Tab] character. Table 3-3 describes the subset descriptor fields. [Return to example]

5. Separate the product-level attributes and the subset definitions with two percent signs ( %% ) on their own line. If this line is not present, the kits utility terminates with an error message. You cannot include comments after this line in the key file. [Return to example]

6. In this entry, the Dependency list field value for OATODB100 is . (dot), meaning that the subset has no dependencies.

   Set the Flags field to 0 (zero), indicating that the subset is mandatory. [Return to example]

7. In this entry, the OATODBTEMPS100 subset is optional; its FLAGS field is set to 2 (two). This subset is dependent on both the OATODB100 subset, part of the ODB kit, and the OSFDCMT??? subset, part of the base operating system. The ??? notation is a wildcard to specify any version of the OSFDCMT subset.

   Enclose the Subset Description field in single quotes, for example: 'Subset Description'. [Return to example]

The key file product attributes section describes the naming conventions for the kit and provides kit-level instructions for the kits command. This section consists of attribute-value pairs as described in Table 3-2. Each attribute name is separated from its value by an equal sign ( = ). Comment lines in this section begin with a pound sign ( # ).

Table 3-2:  Key File Product Attributes

The key file subset descriptor section describes each of the subsets in the kit and provides subset-level instructions for the kits command. This section contains one line for each subset in the kit and consists of four fields, each separated by a single [Tab] character. You cannot include comments in this section of the key file. Table 3-3 describes the subset descriptor fields.

Table 3-3:  Key File Subset Descriptors

Table 3-4 describes the subset properties indicated by the key file subset descriptor Flags field values. For example, if the Flags field value is 5, the subset is protected, mandatory, and uncompressed.

Table 3-4:  Flags Field Values and Subset Properties

After preparing your subsets as described in this chapter, proceed as follows:

• If you are creating subset control programs, go to Chapter 4.

• If you are not creating subset control programs, go to Chapter 5.