{
{   The purpose of this request is to establish a new empty permanent
{ file.  As a result of this function, the permanent file is registered
{ in the specified user's catalog.
{
{   The file can be the initial cycle or an additional cycle of the
{ specified permanent file.  Only a user with CYCLE permission to a
{ file may add cycles to the file.  Only a user with CYCLE permission
{ to the catalog in which a new file is registered can create the initial
{ cycle of a permanent file.
{
{   This request records the file name, password and log selections
{ in a catalog entry when defining the initial file cycle.  These
{ attributes are the same for all cycles of the permanent file.
{ This request also creates a cycle descriptor in the catalog entry
{ that contains the cycle number, creation date and expiration
{ date associated with the new file cycle.
{
{   The permanent file name and cycle must be a unique identifier
{ relative to the catalog in which it is registered.  Otherwise
{ the request is terminated and an error is returned.
{
{   In addition to registering the new file in a catalog this request
{ attaches the file for access within the requesting job.  The usage
{ and share selections associated with this attachment allow ALL usage
{ and no sharing.
{
{       PFP$DEFINE (LFN, PATH, CYCLE_SELECTOR, PASSWORD, RETENTION, LOG, 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 the request is terminated and an error status is 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
{       permanent file being defined or to which a new cycle is to be added.
{       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 defined.  If PFC$LOWEST_CYCLE is specified, a cycle one less
{       than the current lowest cycle will be defined.  If PFC$HIGHEST_CYCLE
{       is specified, a cycle one greater than the current highest cycle will
{       be defined.  If a specific cycle is specified, that cycle will be
{       defined.  If the specific cycle already exists, an error will be
{       returned.  If the file does not exist, both PFC$LOWEST_CYCLE and
{       PFC$HIGHEST_CYCLE will cause cycle one to be created.
{
{ PASSWORD: (input) If the permanent file does not already exist, this
{       parameter specifies a password to be registered with the file.  A
{       blank password specifies that no password is to be registered.  If
{       the permanent file  does already exist, 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.
{
{ RETENTION: (input) This parameter specifies the number of days (1-999) from
{       the current date that the file is to be retained.  999 indicates an
{       infinite retention period.  This parameter is used to determine an
{       expiration date for the file cycle.
{
{ LOG: (input) This parameter specifies if the system should record the
{       identification of each user that accesses the file, the number of
{       accesses for each type of usage (read, shorten, append, modify,
{       and execute) and the date and time of the last access.  This
{       parameter will be ignored if the file already exists and a new
{       cycle is merely being added.
{
{ STATUS: (output) This parameter returns the request status.
{
{        CONDITIONS: pfe$bad_cycle_number
{                    pfe$bad_cycle_option
{                    pfe$bad_family_name
{                    pfe$bad_local_file_name
{                    pfe$bad_log_option
{                    pfe$bad_master_catalog_name
{                    pfe$bad_nth_subcatalog_name
{                    pfe$bad_password
{                    pfe$bad_permanent_file_name
{                    pfe$bad_retention_period
{                    pfe$catalog_full
{                    pfe$cycle_overflow
{                    pfe$cycle_underflow
{                    pfe$duplicate_cycle
{                    pfe$incorrect_password
{                    pfe$lfn_in_use
{                    pfe$name_already_subcatalog
{                    pfe$nth_name_not_subcatalog
{                    pfe$path_too_short
{                    pfe$pf_system_error
{                    pfe$unknown_family
{                    pfe$unknown_master_catalog
{                    pfe$unknown_nth_subcatalog
{                    pfe$usage_not_permitted
{
{        IDENTIFIER: pfc$permanent_file_manager_id
