{
{    The purpose of this deck is to document the purpose of each of
{ the components of the fmt$path_description_entry record.
{ Each referenced file or catalog path is described by one or more
{ of these records.
{    A path name is registered when SCL evaluates a file expression or
{ when a file is attached (temporary or permanent file).  Registering
{ a path causes one or more entries to be created in a tree structure.
{ Each entry in the tree is defined by the type
{ fmt$path_desription_entry.  An entry is created for each component
{ of the path. Note that the tree structure does not reflect catalog
{ heirarchies.
{    Entries are managed to avoid duplication.  For example if the
{ following paths were registered, there would only be one entry
{ each for NVE and AJL in the tree but there would be two entries
{ named 'X' in the tree because the parental path for each X is
{ different.
{
{      :NVE.AJL.X
{      :NVE.AJL.Y.X
{
{    fmt$path_description_entry:
{      active_path_participation_count:
{        Counts the number of times this node name appears as
{        the immediate parental name of an active path.  If this
{        count is zero, delete_allowed is true, and the last
{        path description is that of a file being detached, this
{        node will be deleted as a result of the detach.
{      attached_access_modes:
{      attached_share_modes:
{        The attached access and share modes define the permitted
{        capability provided the process which opens the cycle
{        to which this node points.  There may be multiple nodes
{        pointing to the same cycle object; each node may be
{        authorized for a different subset of the initial permitted
{        modes of access and share for the job.
{      cumulative_parental_path_size:
{        Counts the characters including ':' and '.' which are
{        required to express the file path up to this node. Since
{        the cycle object points back to the parental node name,
{        path names are re-constructed from right to left and this
{        makes that reconstuction simpler.
{      path_depth:
{        Counts the depth of this node in a set of path elements.  This
{        allows for reconstructing a path.
{      entry_assignment:
{        Points to a single character whose value indicates whether
{        this entry is assigned to an active path or available for
{        reuse.  It is used in conjunction with entry_assignment_
{        counter to validate a path_handle for this
{        node.
{      entry_assignment_counter:
{        When each entry is assigned a global variable which counts
{        the total number of entries assigned is incremented.  The
{        current value of this counter is stored in this component
{        of each assigned entry.  This value is encoded in the
{        path_handle of this entry for validation
{        purposes.
{      parental_path_entry:
{        This points to the entry elsewhere in the tree which
{        represents the parental node in the file path.
{        From the cycle object one can reconstruct the resolved
{        path name by following this chain back to the family
{        node, i.e. the end.
{      delete_allowed:
{        Indicates whether the path_handle for this
{        node has been handed to SCL. The lifetime of a path alias
{        which has been given to SCL cannot easily be determined.
{        Therefore, if this boolean is FALSE the entry cannot be
{        deleted.
{        If TRUE and if the active_path_participation_count is zero,
{        the node can be deleted. The attach_file and create_file
{        program interfaces always resolve the path prior to
{        registering a path in this tree.  If a program attaches or
{        creates a file and if the file path was not provided to the
{        program by SCL's clp$get_value or clp$convert_string_to_file
{        interfaces, then there are no dangling aliases to this
{        node which prevent us from deleting the entry when all
{        its child nodes are deleted.  This allows us to tidy-up
{        from the otherwise disastrous effects of BACKUP and
{        RESTORE on the size of this tree.
{      case entry_type:
{      = fmc$named_object =
{        This node is a named element of a file or catalog path.
{        parental_tree_entry:
{          This points to the parent tree node.  Note that this is not
{          necessarily the same node as the parental_path node.  It is
{          necessary to remember this in order to delete nodes.
{        left_subtree:
{          Entries to the left of this node have hashes whose
{          numerical value is less than the hashed value of this
{          entry's randomized_node_name.
{        right_subtree:
{          Entries to the right of this node have hashes whose
{          numerical value is greater than the hashed value of this
{          entry's randomized_node_name.
{        path_node_name:
{          This is the name of the node used when reconstructing the
{          file or catalog path name of which this node is a part.
{        randomized_node_name:
{          This is the hash of the node name or the hash of the
{          node name and the name of the immediate parental node,
{          depending upon whether or not there are other nodes in
{          the tree with the same name and a different parent.
{        highest_cycle:
{          If this node is the name of a file object, this points
{          to a list of cycle objects of this file sorted in
{          descending order.
{        next_cycle_alias_entry:
{          This is a pointer to the next alias entry if this named object is
{          not the only alias for a cycle object.  The first alias for a
{          cycle is pointed to by the first_cycle_alias_entry in the the
{          cycle object.
{      = fmc$file_cycle_object =
{        A cycle object is created when a unique file cycle path is
{        resolved.  This object identifies the "attachment" of the
{        file cycle to this job.  A cycle is physically attached
{        only once to a job; however, the same cycle may be logically
{        attached multiple times.  The access and share modes stored
{        in the cycle object are those authorized for the job.  The
{        access and share modes stored in named objects which point
{        to the same cycle object document "nested attaches" whose
{        access and share must be a subset of the initial attachment.
{        There is one and only one path_handle for a cycle
{        object.
{        cycle_number:
{          Numeric value of cycle portion of a resolved path name.
{        next_lower_cycle:
{          Points to an additional cycle of the same file with a
{          lower cycle number that may have been referenced within
{          the job.
{        next_higher_cycle:
{          Points to an additional cycle of the same file with a
{          higher cycle number that may have been referenced within
{          the job.
{        first_cycle_alias_entry:
{          Points to a named object that is an alias for this
{          cycle object.  If there are other alias entries for this
{          cycle object they will be pointed to from the named object by
{          next_cycle_alias_entry.
{        explicit_detach_allowed:
{          Indicates whether or not an explicit detach will be allowed.  It is
{          primarily used by SCL to prevent detaching a cycle within a block
{          structure.  This prevents the cycle from being detached and then
{          re-attached with different access or share modes.
{        implicit_detach_required:
{          Indicates that the file was implicitly attached by fsp$open_file
{          and must be detached on the last instance of fsp$close_file.
{        hide:
{          Indicates whether or not the cycle should be hidden.
{        scope:
{        block_identifier:
{        cycle_attachment_options:
{          This is a pointer to the default cycle attachment options that
{          will be used on an open.  It points to an adaptable sequence.
{        cycle_description:
{          This points to the data structure used by BAM to support
{          access to an attached file.
{
