{
{   The purpose of this request is to define data for an existing permanent
{ file cycle.  The cycle must not already have data defined for it, or an error
{ condition will be returned.  File cycles with undefined data are created
{ using put_info requests.  This request does not update the file log.
{
{   A user must have CYCLE permission to the file or an error condition will be
{ returned.  The cycle created by this request is left attached with the
{ specified local file name.  The usage and share selections associated with
{ this attachment allow ALL usage and no sharing.
{
{       PFP$DEFINE_DATA (LFN, PATH, CYCLE_SELECTOR, UPDATE_CYCLE_STATISTICS,
{         PASSWORD_SELECTOR, P_MASS_STORAGE_REQUEST_INFO, P_VOLUME_LIST,
{         RESTORE_SELECTIONS, WAIT_ON_VOLUME, MANDATED_MODIFICATION_TIME,
{         DATA_RESIDENCE, STATUS)
{
{ LFN: (input)  This parameter specifies a local file name.  The new empty
{       permanent file cycle is left attached for access within the job via
{       this local file name.  If this lfn is already assigned by the job, an
{       error condition will be returned.  A blank name is not allowed.
{
{ PATH: (input)  This parameter specifies the identification of a permanent
{       file.  The path parameter consists of an array of names which identify
{       the path leading through a catalog hierarchy.  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 parmanent file for which cycle
{       data is to be defined.  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 for
{       which data is to be defined.  If the cycle does not exist, an error
{       condition will be returned.
{
{ UPDATE_CYCLE_STATISTICS: (input)  This parameter tells the permanent file
{       manager whether the cycles access date, and modification date and time
{       should be updated with the current time when the cycle is detached.
{       The cycles creation date and time and file log are not changed.
{
{ PASSWORD_SELECTOR: (input)  This parameter specifies a password that must
{       match the password registered with the file.  If
{       pfc$default_password_option is specified, it will only match for the
{       system or family administrator, or file owner, or for the non-owner if
{       no password is registered with the file.  If
{       pfc$specific_password_option is selected, the supplied password must
{       match the password registered with the file.
{
{ P_MASS_STORAGE_REQUEST_INFO: (input)  This parameter specifies additional
{       information used to assign the file to a particular mass storage device
{       with particular attributes.  A NIL pointer indicates no
{       mass_storage_request_info is supplied.  The fields of this data
{       structure are described below:
{
{       ALLOCATION_SIZE:  This field specifies the amount of contiguous mass
{             storage space, in bytes, which is to be allocated to the file
{             each time additional space is needed.
{
{   The value rmc$unspecified_allocation_size will cause the allocation size to
{ be determined by the ESTIMATED_FILE_SIZE field.
{
{       ESTIMATED_FILE_SIZE:  This field specifies the likely size of the file
{             in bytes.  This information is used to select the allocation size
{             which would minimize the amount of mass storage space assigned to
{             the file should it ultimately reach the estimated size.
{
{   The value rmc$unspecified_file_size will cause the allocation size to be
{ determined by the ALLOCATION_SIZE field.
{
{       FILE_CLASS:  This field specifies the class of the file which is to be
{             assigned.  NOS/VE supports up to 26 classes of files.  Each class
{             is identified by an alphabetic character (upper and lower cases
{             are equivalent).  NOS/VE will select a volume which belongs to
{             the class specified by this parameter; abnormal status will be
{             returned if no candidate volume belongs to the specified class.
{
{   The value rmc$unspecified_file_class will cause the candidate volume to be
{ selected independently of file class.  Specification of any non-alphabetic
{ character will cause abnormal status to be returned.
{
{       INITIAL_VOLUME:  This field specifies the identification of a specific
{             mass storage volume to which this file is to be assigned.  If
{             this volume is not affiliated with the FILE_CLASS specified, the
{             volume is full, or the volume does not exist in the active
{             configuration, this request will be rejected.  If volume overflow
{             is not allowed, the entire file will reside on this volume;
{             otherwise, this volume will be the initial volume assigned to the
{             file.  Refer to the VOLUME_OVERFLOW_ALLOWED field.
{
{   The value rmc$unspecified_vsn will cause the consideration of all candidate
{ volumes.
{
{       VOLUME_OVERFLOW_ALLOWED:  This field specifies whether or not the file
{             can be assigned to more than one volume.  If TRUE is specified,
{             the file may span any volume subject to validation and FILE_CLASS
{             constraints.  If FALSE is specified, the file will be confined to
{             the initial volume to which it is assigned.
{
{   Specification of FALSE is permitted only in a job which has system
{ administrative privilege or maintenance privilege.
{
{ P_VOLUME_LIST: (input)  This parameter specifies a list of VSN's of mass
{       storage volumes on which the file is to reside.
{
{ RESTORE_SELECTIONS: (input)  This parameter specifies the set of conditions
{       which must be present in order to restore data for a file cycle.
{
{ WAIT_ON_VOLUME: (input)  This parameter specifies whether to wait when a
{       volume is unavailable, off-line, disabled, unknown, or inactive, when
{       the server is inactive, or when there isn't enough space.
{
{ MANDATED_MODIFICATION_TIME: (input, output)  This parameter specifies whether
{       the modification date stored with the cycle must match a specified
{       value.  pfc$no_verify_modification_time - The specified modification
{       time field need not be set.  The data is restored, and the modification
{       time in the catalog is retained.  pfc$verify_modification_time - The
{       data is only defined if the specified modification time agrees with the
{       stored time.  pfc$replace_modification_time - The data is defined and,
{       if the specified modification time is not equal to the time already
{       stored in the catalog, the cycle damage symptom of
{       fsc$respf_modification_mismatch is set, and the specified time is
{       stored.
{
{ DATA_RESIDENCE: (output)  This parameter returns the data residence of the
{       file cycle prior to the restore of the cycle's data.
{
{ STATUS: (output) This parameter returns the request status.
{
{       CONDITIONS: dfe$server_not_active
{                   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$catalog_full
{                   pfe$catalog_volume_not_online
{                   pfe$catalog_volume_unavailable
{                   pfe$data_already_defined
{                   pfe$incorrect_password
{                   pfe$lfn_in_use
{                   pfe$modification_time_mismatch
{                   pfe$name_not_permanent_file
{                   pfe$nth_name_not_subcatalog
{                   pfe$path_too_short
{                   pfe$pf_system_error
{                   pfe$restore_not_selected
{                   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
{                   pfe$volume_not_online
{                   pfe$volume_unavailable
{                   rme$file_class_not_valid
{                   rme$vsn_not_part_of_set
{
