{
{   The purpose of this request is to attach a permanent file to a job for its
{ use.  A local file name, to be used for all references to the file by the
{ attaching job, is also assigned.  All input/output operations made within the
{ attaching job will be directly from/to the file.
{
{   Access control information is retrieved from the catalogs identified by the
{ path parameter and is used to validate that the user may access the file as
{ requested.  The usage and share selections are verified to ensure that the
{ request does not conflict with current file usage.  NOS/VE allows file
{ sharing among jobs as well as multiple attaches within a job under different
{ local file names as long as no sharing conflicts occur.  This request
{ provides an option to place the requestor into a wait state if the file is
{ unavailable.  The requesting task will remain in the wait state until the
{ attach operation can be completed as requested.  An abort of a waiting task
{ (e.g.  due to an operator termination) will cause termination of the wait
{ state.  Other requests to attach the file that don't conflict with current
{ file usage will be allowed even though a task is waiting for the file.
{
{   If the data for the cycle has been duplicated on archive media and released
{ from mass storage, PFP$RETRIEVE_ARCHIVED_FILE is called to retrieve the data.
{ The task then waits until the retrieval completes before attempting to
{ reattach the file.
{
{       PFP$ATTACH (LFN, PATH, CYCLE_SELECTOR, PASSWORD, USAGE_SELECTIONS,
{         SHARE_SELECTIONS, WAIT, STATUS)
{
{ LFN: (input)  This parameter specifies the local file name to be used within
{       the job to reference the permanent file while attached.  If the lfn is
{       already in use by the job the request is terminated and an error status
{       is returned.
{
{ PATH: (input)  This parameter specifies the identification of the permanent
{       file.  The path parameter consists of an array of names which identify
{       the path leading through a catalog hierarchy to the desired file.  The
{       first two names specify the family name and master catalog name portion
{       of the path.  By convention, the name of a user's master catalog is the
{       same as the user name.  Subsequent names would specify subcatalogs as
{       applicable.  The last name in the path specifies the permanent file
{       that is to be attached.  Null names are allowed only for the family
{       name and master catalog name.  If the family name is OSC$NULL_NAME, the
{       family name of the job making the request will be used.  If the master
{       catalog name is OSC$NULL_NAME, the user name of the job making the
{       request will be used.
{
{ CYCLE_SELECTOR: (input)  This parameter selects the permanent file cycle that
{       is to be attached.  If PFC$LOWEST_CYCLE is specified, the lowest cycle
{       of the file will be attached.  If PFC$HIGHEST_CYCLE is specified, the
{       highest cycle of the file will be attached.  If a specific cycle is
{       specified, that cycle will be attached.
{
{ PASSWORD: (input)  This parameter specifies a password that must match the
{       password registered with the file.  If a blank password is specified,
{       it will only match if no password was registered with the file.
{
{ USAGE_SELECTIONS: (input)  This parameter specifies how the requestor would
{       like to be able to use the file.
{
{ SHARE_SELECTIONS: (input)  This parameter specifies how the requestor is
{       willing to share the file with other requestors.
{
{ WAIT: (input)  This parameter specifies the action to be taken if the
{       permanent file is not available.  If PFC$NO_WAIT is specified, the
{       request will not be performed and an immediate return to the requestor
{       will be made.  If PFC$WAIT is specified, the requestor will be held up
{       until the file is available, at which time the request will be
{       performed and a return to the requestor will be made.
{
{ STATUS: (output) This parameter returns the request status.
{
{       CONDITIONS: pfe$bad_cycle_number
{                   pfe$bad_cycle_option
{                   pfe$bad_family_name
{                   pfe$bad_last_subcatalog_name
{                   pfe$bad_local_file_name
{                   pfe$bad_master_catalog_name
{                   pfe$bad_nth_subcatalog_name
{                   pfe$bad_password
{                   pfe$bad_permanent_file_name
{                   pfe$bad_wait_option
{                   pfe$catalog_full
{                   pfe$cycle_busy
{                   pfe$cycles_media_missing
{                   pfe$incorrect_password
{                   pfe$invalid_ring_access
{                   pfe$lfn_in_use
{                   pfe$name_not_permanent_file
{                   pfe$nth_name_not_subcatalog
{                   pfe$path_too_short
{                   pfe$pf_system_error
{                   pfe$respf_modification_mismatch
{                   pfe$sharing_not_permitted
{                   pfe$undefined_data
{                   pfe$unknown_cycle
{                   pfe$unknown_family
{                   pfe$unknown_last_subcatalog
{                   pfe$unknown_master_catalog
{                   pfe$unknown_nth_subcatalog
{                   pfe$unknown_permanent_file
{                   pfe$usage_not_permitted
{
