{       PFP$R3_ATTACH_OR_CREATE_FILE
{
{   The purpose of this interface is to either attach an existing permanent
{ "phase 1" file or to optionally create a new file of the given name.  This
{ interface is intended as an internal interface for BAM's use only.  This
{ interface resides in the job_template_23D library.
{
{ PFP$R3_ATTACH_OR_CREATE_FILE (VALIDATION_RING, P_ATTACHMENT_OPTIONS,
{       P_FILE_LABEL, EVALUATED_FILE_REFERENCE, ALLOWED_ACCESS "phase 1",
{       SELECTED_ACCESS, REQUIRED_SHARING "phase 1", SELECTED_SHARING,
{       PATH_HANDLE_NAME, FILE_CREATED, LABEL_USED, STATUS)
{
{ VALIDATION_RING: (input) This parameter specifies the ring number of the
{       direct caller.
{
{ P_ATTACHMENT_OPTIONS: (input) This parameter specifies the option(s) to be
{       used on the attach or create of the file.  Only the following cases are
{       used by this interface:
{       = fsc$access_and_share_modes =
{         If more than one access_and_share_modes records are specified, then
{         the first record is considered to be the most preferred one, the
{         second record the next most preferred, etc.  If the access_mode is
{         permitted_access_modes and it implies mode(s) for which the requestor
{         is not ring validated, then access_mode will be reduced to include
{         only those implied mode(s) for which the requestor is ring validated.
{         All access_and_share_modes records, except the last one, which
{         specify an access_mode or a share_mode for which the requestor is not
{         permitted, will be ignored.  Omission will cause an access_mode of
{         permitted_access_modes and a share_mode of
{         determine_from_access_modes to be used.
{       = fsc$create_file =
{         This option may be used to authorize (true) or to prevent (false) the
{         creation of a new file or file cycle in the event that the file
{         specified by the path parameter does not exist.  Cycle permission is
{         required to create a file.  Omission will cause true to be used,
{         unless cycle $HIGH or $LOW was specified by the path parameter, in
{         which case omission will cause false to be used.
{       = fsc$password =
{         If the file is being attached, the specified password must match the
{         preserved password.  If the file is being created, the specified
{         password will be preserved with the file and will be required on all
{         subsequent attaches.  Omission will cause no password to be used.
{       = fsc$validation_ring =  "phase 2"
{         This option specifies the ring number to be used in validating the
{         requested usage for the file.  The value specified may be the ring
{         number of the direct caller, the ring number of the end user, or any
{         other ring number that is greater than or equal to the value
{         specified by the validation_ring parameter.  This ring, the rings
{         stored in the label, and the access_mode from the selected
{         access_and_share_modes record of the attachment_options parameter,
{         are used to verify that the caller has the necessary permission.
{       Note: The wait choice is ignored here.  If the cycle is busy, the
{       condition pfe$cycle_busy is returned to the caller, who must then wait.
{
{ P_FILE_LABEL: (input) This parameter specifies the file label to be
{       associated with the file.  If the label already exists, this parameter
{       is ignored and the label in the catalog entry is passed to the
{       fmp$attach_file interface.  If the label does not already exist (the
{       file may or may not already exist) and the caller has control
{       permission, then the specified label is stored in the permanent file
{       catalog and is passed to the fmp$(attach/create)_file interface and
{       LABEL_USED is set to true.
{
{ EVALUATED_FILE_REFERENCE: (input/output) This parameter identifies the file.
{
{ ALLOWED_ACCESS: (output) "phase 1" This parameter indicates the access modes
{       permitted.  (This is not necessarily the same set as the modes for
{       which the file is attached, i.e. it is a superset of the modes of
{       attachment.)
{
{ SELECTED_ACCESS: (output) This parameter indicates the access modes for which
{       the file is attached.
{
{ REQUIRED_SHARING: (output) "phase 1" This parameter indicates the share modes
{       which are required.  (This is not necessarily the same set as the modes
{       for which this attachment is willing to share the file, i.e. it is a
{       subset of the modes for which this attachment is willing to share the
{       file.)
{
{ SELECTED_SHARING: (output) This parameter indicates the share modes for which
{       this attachment is willing to share the file.
{
{ PATH_HANDLE_NAME: (output) This parameter identifies the path and cycle
{       description entries which represent the attachment of a specific cycle.
{       There is a one-to-one correspondence between the path_handle_name and
{       the file cycle.
{
{ ACTION_TAKEN: (output) This parameter indicates whether a cycle was newly
{       attached, already attached, or created as a result of this operation.
{
{ LABEL_USED: (output) This parameter indicates whether or not the file label
{       supplied was used as a result of this operation.
{
{ STATUS: (output) This parameter returns the request status.
{
