{
{   The purpose of this procedure is to restore data on mass storage for a file
{ cycle which has been duplicated on archive media and the mass storage space
{ released.  After the data for the file has been restored to mass storage and
{ the permanent file catalog updated, control is returned to the calling
{ procedure which must re-issue the attach in order access the file on mass
{ storage.
{
{       PFP$RETRIEVE_ARCHIVED_FILE (PATH, CYCLE_NUMBER, PASSWORD, WAIT, STATUS)
{
{ 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_NUMBER: (input)  This parameter is the cycle number of the file that is
{       to be retrieved.
{
{ 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 be considered a match if no password was registered with
{       the file.
{
{ WAIT: (input)  This parameter specifies whether or not to wait for retrieval
{       to mass storage to complete.  If PFC$NO_WAIT is specified, the request
{       to retrieve the file cycle will be queued and an immediate return to
{       the caller will be made.  If PFC$WAIT is specified, a return to the
{       caller will not be made until the retrieval to mass storage is
{       complete.
{
{ STATUS: (output) This parameter returns the request status.
{
{        CONDTIONS:  pfe$bad_cycle_number
{                    pfe$bad_cycle_option
{                    pfe$bad_family_name
{                    pfe$bad_master_catalog_name
{                    pfe$bad_nth_subcatalog_name
{                    pfe$bad_password
{                    pfe$bad_permanent_file_name
{                    pfe$incorrect_password
{                    pfe$invalid_ring_access
{                    pfe$name_not_permanent_file
{                    pfe$nth_name_not_subcatalog
{                    pfe$path_too_short
{                    pfe$pf_system_error
{                    pfe$unknown_cycle
{                    pfe$unknown_family
{                    pfe$unknown_master_catalog
{                    pfe$unknown_nth_subcatalog
{                    pfe$unknown_permanent_file
{                    pfe$usage_not_permitted
{
