Hierarchical file system element entry (distribution and target zone)

The hierarchical file system element entry describes an element that exists in a distribution library or a UNIX file system. A hierarchical file system entry is created the first time you install a SYSMOD containing an MCS for a hierarchical file system element that does not yet have an entry in the CSI data set.

SMP/E records the function and service level of the hierarchical file system element in the entry. Once a hierarchical file system element entry exists, it is updated as subsequent SYSMODs affecting the hierarchical file system element are installed.

Table 1 shows the types of entries used for hierarchical file system elements. Some types of elements may be translated into several languages. In these cases, the entry type contains xxx, which represents the language used for the element. (If an element was not translated, the entry type does not contain any xxx value. Table 2 shows the xxx values and the languages they represent.

Subentries

These are the subentries for the hierarchical file system element entries as they appear in the LIST output:

name

is the name of the hierarchical file system element represented by the entry.

The name can contain 1–8 uppercase alphabetic, numeric, or national ($, #, @) characters.

BINARY or TEXT

indicates the installation mode to be used when the HFS copy utility is invoked to install the element into a UNIX file system.

The UCL operand is BINARY or TEXT.

Binary mode means that the element is installed in its entirety as a data stream, with no breaks for logical records.
Text mode means that the element is installed with breakpoints for logical records.
BINARY and TEXT are mutually exclusive.
If there is no mode indicator in the hierarchical file system element entry, the HFS copy utility determines how to install the element.

DISTLIB

specifies the ddname of the distribution library for the hierarchical file system element.

The UCL operand is DISTLIB(ddname).

The ddname can contain any uppercase alphabetic, numeric, or national ($, #, @) character, and can be 1–8 characters long.
The DISTLIB subentry is required. Without it, SMP/E cannot process any changes for the hierarchical file system element.

FMID

identifies the functional owner of this hierarchical file system element. The functional owner is the last function SYSMOD that replaced this element.

The UCL operand is FMID(sysmod_id).

The SYSMOD ID must contain 7 uppercase alphabetic, numeric, or national ($, #, @) characters.

LASTUPD

identifies the cause of the last change to this hierarchical file system element entry.

The UCL operand is LASTUPD(value). This subentry can contain one of the following values:

UCLIN: indicates that the change was made as a result of UCLIN processing.
sysmod-id: indicates that the change was made during the installation of the indicated SYSMOD.
The SYSMOD ID must contain 7 uppercase alphabetic, numeric, or national ($, #, @) characters.

LASTUPD TYPE

indicates how the entry was last changed.

The UCL operand is LASTUPDTYPE(value). This subentry can contain one of the following values:

ADD: The entry was added.
UPD: The entry was updated.

LINK

specifies a list of alternative names by which this hierarchical file system element can be known in a UNIX file system. The full name is produced by concatenating the specified linkname with the UNIX file system directory identified by the SYSLIB subentry.

In LIST output, linknames are always enclosed in single apostrophes. If an apostrophe is part of a linkname, it is always shown as two consecutive apostrophes in LIST output.

The UCL operand is LINK(linkname…).

The linkname can be from 1 to 1023 characters.
A linkname can be enclosed in single apostrophes ('). A linkname must be enclosed in single apostrophes if any of the following is true:
- The linkname contains lowercase alphabetic characters.
- The linkname contains a character that is not uppercase alphabetic, numeric, national ($, #, or @), slash (/), plus (+), hyphen, period, or ampersand (&).
- The linkname spans more than one line in the control statement.
The single apostrophes used to enclose a linkname (the delimiters) do not count as part of the 1023-character limit.
Any apostrophes specified as part of a linkname (not the delimiters) must be doubled.
Double apostrophes count as two characters in the 1023-character limit.
The linkname can include characters X'40' through X'FE'.

PARM

specifies a character string that is to be passed to the HFS copy utility as an execution-time parameter. The maximum length of this character string is 300 bytes of nonblank data. If any blanks are specified in the PARM value, they are deleted by SMP/E during processing and do not count toward the 300-byte maximum.

The UCL operand is PARM(character_string).

PARM is an optional operand.
The character string can be entered free-form, without regard to blanks (which are compressed out of the string), and can span multiple 80-byte records.
If parentheses are specified in the PARM value, there must always be a pair (left and right); otherwise, the results are unpredictable.

RMID

identifies the last SYSMOD that replaced this hierarchical file system element. Any subsequent SYSMOD that modifies this hierarchical file system element must have defined a relationship (such as PRE or SUP) with this SYSMOD.

The UCL operand is RMID(sysmod_id).

The SYSMOD ID must contain 7 uppercase alphabetic, numeric, or national ($, #, @) characters.
If RMID is not specified but FMID is, SMP/E sets the RMID value to the specified FMID.

SHSCRIPT

specifies a UNIX shell script to run when this element is copied to (or deleted from) a directory in a UNIX file system.

The UCL operand is SHSCRIPT(scriptname). This subentry optionally contains one or both of the following values, which specify the point in SMP/E processing when the shell script is run:

PRE: The shell script is run before the element is copied to the UNIX file system directory.
POST: The shell script is run after the element is copied to the UNIX file system directory.

POST is the default; the shell script is run after the element is copied to the directory.

SYMLINK

specifies a list of one or more symbolic links, which are file names that can be used as alternate names for referring to this element in a UNIX file system. Each symbolic link name listed here is associated with a path name listed in the SYMPATH entry. See the description of the SYMPATH entry for more information about how the symbolic link names and path names are associated.

The UCL operand is SYMLINK(symlinkname…).

A hierarchical file system element entry that contains a SYMLINK entry must contain a matching SYMPATH entry. SMP/E will reject any UCLIN command that would violate this condition.
A symbolic linkname can be from one to 1023 characters. Any characters in the range X'40' through X'FE' may be specified.
A symbolic linkname can be enclosed in single apostrophes ('). A symbolic linkname must be enclosed in single apostrophes if any of the following is true:
- The symbolic linkname contains lowercase alphabetic characters.
- The symbolic linkname contains a character that is not uppercase alphabetic, numeric, national ($, #, or @), slash (/), plus (+), hyphen, period, or ampersand (&).
- The symbolic linkname spans more than one line in the control statement.
The single apostrophes used to enclose a symbolic linkname (the delimiters) do not count as part of the 1023-character limit.
Any apostrophes specified as part of a symbolic linkname (not the delimiters) must be doubled. Double apostrophes count as two characters in the 1023-character limit.

SYMPATH

specifies a list of one or more pathnames that are associated with symbolic links identified by the SYMLINK operand. The first pathname in the SYMPATH operand is associated with the first symbolic link in the SYMLINK operand, the second pathname with the second symbolic link, and so on. If there are more symbolic links listed than there are pathnames, then the last listed pathname is used for the remaining symbolic links. If more pathnames are specified than symbolic linknames, then the excess pathnames (at the end of the list) are ignored. The UCL operand is SYMPATH(sympathname…).

A hierarchical file system element entry that contains a SYMPATH entry must contain a matching SYMLINK entry. is specified, otherwise it must be omitted.
A symbolic pathname can be from one to 1023 characters. Any characters in the range X'40' through X'FE' may be specified.
A symbolic pathname can be enclosed in single apostrophes ('). A symbolic pathname must be enclosed in single apostrophes if any of the following is true:
- The symbolic pathname contains lowercase alphabetic characters.
- The symbolic pathname contains a character that is not uppercase alphabetic, numeric, national ($, #, or @), slash (/), plus (+), hyphen, period, or ampersand (&).
- The symbolic pathname spans more than one line in the control statement.
The single apostrophes used to enclose a symbolic pathname (the delimiters) do not count as part of the 1023-character limit.
Any apostrophes specified as part of a symbolic pathname (not the delimiters) must be doubled. Double apostrophes count as two characters in the 1023-character limit.

SYSLIB

specifies the ddname of the "target library" within a UNIX file system for the hierarchical file system element.

The UCL operand is SYSLIB(ddname).

Only one SYSLIB value can be specified.
The ddname can contain any uppercase alphabetic, numeric, or national ($, #, @) character, and can be 1 to 8 characters long.
The SYSLIB subentry is required. Without it, SMP/E cannot process any changes for the hierarchical file system element.

LIST Examples

To list all the generic hierarchical file system element entries in a particular zone that support the Spanish language, you can use the following commands:

SET      BDY(TGT1)          /* Set to requested zone.   */.
LIST     HFSESP             /* List all generic HFS     */
                            /* element entries (Spanish)*/.

To list specific UNIX1 element entries, you can use these commands:

SET      BDY(TGT1)          /* Set to requested zone.   */.
LIST     UNIX1(UNXEL1       /* List only these          */
             UNXEL2         /* three                    */
             UNXEL3)        /* entries.                 */.

The format of the LIST output for each hierarchical file system element entry is the same for both of these commands. The only difference is the number of hierarchical file system element entries listed. Figure 1 shows an example of LIST output for UNIX1 element entries.

Figure 1. Hierarchical file system element entry: sample LIST output

PAGE nnnn  - NOW SET TO zzzzzz ZONE nnnnnnn  DATE mm/dd/yy TIME hh:mm:ss SMP/E 36.nn SMPLIST OUTPUT

TGT1    UNIX1    ENTRIES


  NAME

UNXEL1    LASTUPD         = UNXFUNC TYPE=ADD
          LIBRARIES       = DISTLIB=APOSIXL1  SYSLIB=UNXTGTL1
          BINARY
          FMID            = UNXFUNC
          RMID            = UNXPTF1
          SHSCRIPT        = INSTAL01,PRE
          LINK            = 'linkname_1'
                          = 'linkname_2'

UNXEL2    LASTUPD         = UNXFUNC TYPE=ADD
          LIBRARIES       = DISTLIB=APOSIXL2  SYSLIB=UNXTGTL2
          TEXT
          FMID            = UNXFUNC
          RMID            = UNXFUNC
          LINK            = 'linkname_3'
                          = 'linkname_4'
          SHSCRIPT        = INSTAL02,POST
UNXEL3    LASTUPD         = UNXFUNC  TYPE=ADD
          LIBRARIES       = DISTLIB=APOSIXL2  SYSLIB=UNXTGTL2
          TEXT
          FMID            = UNXFUNC
          RMID            = UNXPTF2
          LINK            = 'linkname_5'
                            'linkname_6'
          SHSCRIPT        = INSTAL03,PRE,POST
          PARM            = This_is_another_sample_character_string_specified_as_the_value_of_PARM.__It_is_a_maximum____
                            length_character_string_for_this_subentry.__I.e.,_it_is_300_characters_long.__The_string____
                            has_no_blanks_in_it.__If_you_see_something_that_looks_like_a_blank,_it's_not.  The_previous_
                            2_characters_are_X'41'…

By specifying the FORFMID operand, you can reduce the number of hierarchical file system element entries listed. When FORFMID is specified, SMP/E lists a hierarchical file system element entry only if its FMID matches one of the FMIDs specified on the FORFMID operand. For example, to list hierarchical file system element entries whose FMIDs either are defined in FMIDSET HFS or are HFSFUNC, you can use these commands:

SET      BDY(TGT1)          /* Set to target zone.      */.
LIST     HFS                /* List all hierarchical    */
                            /* file system element      */
                            /* entries                  */
         FORFMID(HFS        /* for the HFS FMIDSET      */
                 HFSFUNC)   /* and FMID HFSFUNC.        */.

You can use the LIST command to find out the names of all SYSMODs that have modified a hierarchical file system element. To include the names of these SYSMODs in the LIST output you can use the XREF operand, as shown in these commands:

SET      BDY(TGT1)          /* Set to requested zone.   */.
LIST     HFS                /* List all hierarchical    */
                            /* file system element      */
                            /* entries                  */
         XREF               /* and related SYSMODs.     */.

Note:

XREF can be used either in mass mode or in select mode.
SMP/E obtains the data included for the XREF operand by checking all the SYSMOD entries for subentries for this hierarchical file system element. Because this data is not contained in the hierarchical file system element entry itself, you cannot use UCLIN to change it in the hierarchical file system element entry.

Figure 2 is an example of the LIST output produced when the XREF operand is used.

Figure 2. Hierarchical file system element entry: sample LIST output when XREF is specified

PAGE nnnn  - NOW SET TO zzzzzz ZONE nnnnnnn  DATE mm/dd/yy TIME hh:mm:ss SMP/E 36.nn SMPLIST OUTPUT

TGT1    UNIX1    ENTRIES


  NAME

UNXEL1    LASTUPD         = UNXFUNC TYPE=ADD
          LIBRARIES       = DISTLIB=APOSIXL1  SYSLIB=UNXTGTL1
          BINARY
          FMID            = UNXFUNC
          RMID            = UNXPTF1
          LINK            = 'linkname_1'
                          = 'linkname_2'
          SHSCRIPT        = INSTAL01,PRE
          SYSMOD HISTORY  = SYSMOD   TYPE      DATE    MCS     --STATUS--
                            UNXFUNC  FUNCTION  07.100  UNX     APP    ACC
                            UNXPTF1  PTF       07.120  UNX     APP    ACC

UNXEL2    LASTUPD         = UNXFUNC TYPE=ADD
          LIBRARIES       = DISTLIB=APOSIXL2  SYSLIB=UNXTGTL2
          TEXT
          FMID            = UNXFUNC
          RMID            = UNXFUNC
          LINK            = 'linkname_3'
                          = 'linkname_4'
          SHSCRIPT        = INSTAL02,POST
          SYSMOD HISTORY  = SYSMOD   TYPE      DATE    MCS     --STATUS--
                            UNXFUNC  FUNCTION  07.100  UNX     APP    ACC

To list the UNIX shell script (SHELLSCR) element entries for a particular zone, you can use the following commands:

SET      BDY(TGT1)          /* Set to requested zone.   */.
LIST     SHELLSCR           /* List all UNIX shell      */
                            /* script element entries   */.

Figure 3 shows an example of the LIST output for SHELLSCR element entries.

Figure 3. Hierarchical file system element entry: sample LIST output for SHELLSCR entries

PAGE nnnn  - NOW SET TO TARGET ZONE zzzzzz  DATE mm/dd/yy TIME hh:mm:ss SMP/E 36.nn SMPLIST OUTPUT

TGT1  SHELLSCR   ENTRIES


  NAME

INSTAL01  LASTUPD         = FUNC001 TYPE=ADD
          LIBRARIES       = DISTLIB=HFSDLIB  SYSLIB=UNXTGTL1
          TEXT
          FMID            = FUNC001
          RMID            = FUNC001

INSTAL02  LASTUPD         = FUNC002 TYPE=UPD
          LIBRARIES       = DISTLIB=HFSDLIB  SYSLIB=UNXTGTL1
          TEXT
          FMID            = FUNC002
          RMID            = FUNC002


INSTAL03  LASTUPD         = FUNC001 TYPE=ADD
          LIBRARIES       = DISTLIB=HFSDLIB  SYSLIB=UNXTGTL1
          TEXT
          FMID            = FUNC001
          RMID            = FUNC001

UNLOAD Examples

To dump the hierarchical file system element entries in UCL format, you can use the UNLOAD command. For example, to unload all the OS21 element entries in a particular zone, you can use the following commands:

SET      BDY(TGT1)          /* Set to requested zone.   */.
UNLOAD   OS21               /* Unload all OS21 element entries. */.

To unload specific OS21 element entries, you can use these commands:

SET      BDY(TGT1)          /* Set to requested zone.   */.
UNLOAD   OS21(OS2EL1        /* Unload only these        */
              OS2EL2        /* three                    */
              OS2EL3)       /* entries.                 */.

The format of the UNLOAD output for each OS21 element entry is the same for both of these commands. The only difference is the number of element entries listed. Figure 4 is an example of UNLOAD output for OS21 element entries.

Figure 4. OS21 element entry: sample UNLOAD output

UCLIN .
REP       OS21            ( OS2EL1   )
          LASTUPD         ( OS2FUNC  )
          LASTUPDTYPE     ( ADD )
          DISTLIB         ( OS2DSTL1 )
          SYSLIB          ( OS2TGTL1 )
          FMID            ( OS2FUNC )
          RMID            ( OS2PTF1 )
          LINK            ( 'linkname_1'
                            'linkname_2' )
          SHSCRIPT        ( INST0S2,POST )
                          .
REP       OS21            ( OS2EL2   )
          LASTUPD         ( OS2FUNC  )
          LASTUPDTYPE     ( ADD )
          DISTLIB         ( OS2DSTL2 )
          SYSLIB          ( OS2TGTL2 )
          FMID            ( OS2FUNC )
          RMID            ( OS2FUNC )
          LINK            ( 'linkname_3'
                            'linkname_4' )
          SHSCRIPT        ( INST0S2,POST )
                          .
REP       OS21            ( OS2EL3 )
          LASTUPD         ( OS2FUNC )
          LASTUPDTYPE     ( ADD )
          DISTLIB         ( APOSIXL2 )
          SYSLIB          ( OS2TGTL2 )
          TEXT
          FMID            ( OS2FUNC )
          RMID            ( OS2PTF2 )
          LINK            ( 'linkname_5'
                            'linkname_6' )
          PARM            ( This_is_another_sample_character_string_spec
                            ified_as_the_value_of_PARM.__It_is_a_maximum
                            ____length_character_string_for_this_subentr
                            y.__I.e.,_it_is_300_characters_long.__The_st
                            ring____has_no_blanks_in_it.__If_you_see_som
                            ething_that_looks_like_a_blank,_it's_not.  T
                            he_previous_2_characters_are_X'41'…
                            )
                          .
ENDUCL.

By specifying the FORFMID operand, you can reduce the number of OS21 element entries unloaded. When FORFMID is specified, SMP/E unloads an OS21 element entry only if its FMID matches one of the FMIDs specified on the FORFMID operand. For example, to unload OS21 element entries whose FMIDs either are defined in FMIDSET OS2 or are OS2FUNC, you can use these commands:

SET      BDY(TGT1)          /* Set to target zone.             */.
UNLOAD   OS21               /* Unload all OS21 element entries */
         FORFMID(OS21       /* for the OS21 FMIDSET            */
                 OS2FUNC)   /* and FMID OS2FUNC.               */.

UCLIN Examples

You can use the ADD, REP, and DEL UCL statements to change subentries in the hierarchical file system element entry. After the UCLIN changes are made, the hierarchical file system element entry must contain at least the following subentries:

DISTLIB
FMID
RMID
SYSLIB

Otherwise, there is not enough information in the entry to process the element. If any of these subentries are missing, SMP/E does not make the requested UCL updates to the entry, and the entry remains as it was before the UCL command.

The following examples are provided to help you use the hierarchical file system element entries.