{
{   The purpose of this request is to prepare a file for access.  If the file
{ does not exist and other pre-conditions are met, this request will create the
{ file; refer to the discussion of the FILE parameter below.
{
{   This request validates the caller's ability to access the file.  The caller
{ of this request must have sufficient ring privilege and must be permitted to
{ access the file according to the file's access-control list or this request
{ is rejected.
{
{   This request returns a file_identifier.  If the same file is opened more
{ than once, each instance of open of that file is assigned a unique
{ file_identifier.  The file_identifier is the 'key' by which file access
{ requests are associated with a particular instance of open of a file.
{
{   The file_identifier is invalidated by an fsp$close_file request.  If the
{ task fails to close its files, they are automatically closed by the system
{ when the task terminates.  The use of fsp$close_file is recommended, but is
{ not required.  More efficient utilization of system resources results when
{ the file is explicitly closed.  Furthermore, the system writes all modified
{ pages of a permanent file to mass storage when the file is closed; closing a
{ file explicitly gives the task the opportunity to detect and process any
{ abnormal status that may result from the operation.
{
{   When a file is opened, it may be opened at $BOI, $EOI, or it may inherit
{ the position attained by the last accessor of the file (see the Read/Write
{ Concurrency section of the ERS for further information concerning treatment
{ of $ASIS).  The open position may be specified using the FILE_ATTACHMENT
{ parameter of this request or by appending an open position suffix ($BOI,
{ $EOI, or $ASIS) to the value of the FILE parameter of this request.  If the
{ open position is specified using both the FILE parameter and the
{ FILE_ATTACHMENT parameter, the FILE_ATTACHMENT parameter specification is
{ used.
{
{   This request provides parameters to define the attributes of a file that is
{ to be created or initially opened by this request:
{ DEFAULT_CREATION_ATTRIBUTES and MANDATED_CREATION_ATTRIBUTES.  The
{ ATTRIBUTE_VALIDATION and ATTRIBUTE_OVERRIDE parameters are available for use
{ regardless of whether or not the file is created or initially opened by this
{ request.
{
{   If the propagate_highest_cycle registration attribute (not currently
{ implemented) of the file is TRUE and an additional cycle of a file is created
{ or initially opened by this request, the DEFAULT_CREATION_ATTRIBUTES
{ parameter is ignored; the attribute values default to those of the highest
{ cycle of the file.  However, the MANDATED_CREATION_ATTRIBUTES,
{ ATTRIBUTE_VALIDATION, and ATTRIBUTE_OVERRIDE parameters are still processed.
{
{   The maximum size of a mass storage file is limited to 2.147 gigabytes
{ (2**31 bytes).
{
{       FSP$OPEN_FILE (FILE, ACCESS_LEVEL, FILE_ATTACHMENT,
{         DEFAULT_CREATION_ATTRIBUTES, MANDATED_CREATION_ATTRIBUTES,
{         ATTRIBUTE_VALIDATION, ATTRIBUTE_OVERRIDE, FILE_IDENTIFIER, STATUS)
{
{ FILE: (input)  This parameter specifies the path name of the file to be
{       opened.  The value specified is evaluated by this request as an SCL
{       <file expression>.  Refer to the discussion of <file expression> in the
{       NOS/VE Command Interface ERS.  A file cycle is created as a result of
{       this request, if any of the following conditions hold.  A mass storage
{       file must be opened for access that includes fsc$append for creation to
{       occur, in addition to one of the following being true:
{
{         1.  The CREATE_FILE file_attachment option is TRUE and either the
{             cycle reference is omitted and no cycle exists, the cycle
{             reference is $HIGH or $LOW and no cycle exists, or a specific
{             cycle is referenced and it does not exist.
{
{         2.  The cycle reference is $NEXT and the CREATE_FILE file_attachment
{             option is TRUE or omitted; a cycle one greater than the current
{             highest cycle is created.
{
{         3.  The CREATE_FILE file_attachment option is omitted, the cycle
{             reference is a specific cycle and the cycle does not exist.
{
{         4.  The CREATE_FILE file_attachment option is omitted, the cycle
{             reference is omitted and no cycle exists.
{
{             If the cycle reference is either $HIGH or $LOW and the
{             CREATE_FILE option of the file_attachment parameter is FALSE or
{             omitted, no cycle is created, regardless of the access_modes
{             specified.
{
{ ACCESS_LEVEL: (input)  This parameter specifies the means by which the file
{       is accessed.  Specification of amc$record access_level implies the task
{       will access the file using GET and/or PUT requests.  Record access is
{       required if the file organization is indexed-sequential, system-key or
{       direct-access or if the file's device class is other than mass storage.
{       Specification of amc$segment access_level implies the task intends to
{       access the file as memory using machine instructions.  An initialized
{       pointer to the segment can be obtained by issuing a subsequent
{       amp$get_segment_pointer request.  Segment access is only supported for
{       mass storage files.
{
{ FILE_ATTACHMENT: (input)  This parameter specifies the attachment options to
{       be in effect for this instance of open.  If the file is not already
{       attached to the job, this request effects the attachment.  If the
{       attachment to the job originates with this request, the file is
{       automatically detached by the fsp$close_file request for the last
{       instance of open of the file within the job.  A value of NIL for this
{       parameter specifies no attachment options are provided.
{
{       This parameter supports multiple specification of options
{       fsc$access_and_share_modes and fsc$open_share_modes as described below.
{       If other attachment options are specified multiple times in the array,
{       only the first specification is used.
{
{    fsc$access_and_share_modes:
{
{          It is recommended that the task specify only the access_modes that
{          are required by the task's access; this may promote sharing of the
{          file, improving both the performance and the usability of the
{          system.
{
{          NOS/VE validates all attachments of a file against the file's
{          access-control list and against the modes of sharing authorized by
{          other jobs that currently have the file attached.
{
{          The values of access_modes and share_modes that are authorized
{          depend upon whether or not this request creates the file or attaches
{          it to the requesting job.
{
{          If the file cycle is created by this request:
{
{          - The fsc$specific_access_modes option of access_modes causes the
{          file to be attached for the modes of access that were specified.
{
{          - The fsc$permitted_access_modes option of access_modes causes the
{          file to be attached for all modes of access because CYCLE permission
{          authorizes all modes of access to the creator of a cycle.
{
{          - The fsc$specific_share_modes option of share_modes causes the file
{          to be attached for the modes of sharing specified regardless of the
{          share_requirement in the access-control list because CYCLE
{          permission preempts any share requirement in the file's
{          access-control list.
{
{          - The fsc$required_share_modes option of share_modes causes the file
{          to be attached for exclusive access because CYCLE permission
{          dictates no sharing requirement and preempts any share requirement
{          in the file's access-control list.
{
{          - The fsc$determine_from_access_modes option of share_modes causes
{          the cycle to be attached for no sharing if the access_modes include
{          fsc$append, fsc$modify, or fsc$shorten; otherwise, the file is
{          attached for the share modes of fsc$read and fsc$execute.
{
{          If the file cycle exists and is not currently attached to the job:
{
{          - The fsc$specific_access_modes option of access_modes causes the
{          cycle to be attached for the specified modes of access.
{
{          - The fsc$permitted_access_modes option of access_modes causes the
{          cycle to be attached for those modes of access authorized by the
{          file's access-control list as qualified by the share requirements of
{          other jobs that have the cycle attached and the value of the
{          validation_ring attachment option.
{
{          - The fsc$specific_share_modes option of share_modes causes the
{          cycle to be attached for the specified modes of sharing; but the
{          proposed modes of sharing must include the share requirement in the
{          file's access-control list and include the union of access modes
{          specified by other jobs that have the cycle attached.
{
{          - The fsc$required_share_modes option of share_modes causes the
{          cycle to be attached for the modes of sharing consisting of the
{          union of the share requirement in the file's access-control list and
{          the outstanding access modes specified by other jobs that have the
{          cycle attached.  After the file is opened, the program may need to
{          validate that it can tolerate the modes of sharing that are imposed
{          by this option; the amp$fetch interface may be used to obtain the
{          required share modes (global_share_modes).
{
{          - The fsc$determine_from_access_modes option of share_modes causes
{          the cycle to be attached for no sharing if the access_modes include
{          fsc$append, fsc$modify, or fsc$shorten; otherwise, the file is
{          attached for the share modes of fsc$read and fsc$execute.
{
{          If the file cycle is already attached to the job:
{
{          - The fsc$specific_access_modes option of access_modes causes the
{          modes of access specified to be used.
{
{          - The fsc$permitted_access_modes option of access_modes causes the
{          modes of access specified by the attachment of the cycle to the job
{          to be used as qualified by the open_share_modes in effect and the
{          validation_ring attachment option.
{
{          - The fsc$specific_share_modes option of share_modes must specify
{          share modes that include the modes of sharing specified by the
{          attachment of the cycle to the job.
{
{          - The fsc$required_share_modes option causes the share_modes
{          specified by the attachment of the cycle to the job, i.e.  the
{          global_share_modes, to be used.  The program may need to validate
{          after the open that it can tolerate the modes of sharing that are
{          imposed by this option; the amp$fetch interface may be used to
{          obtain the global_share_modes.
{
{          - The fsc$determine_from_access_modes option of share_modes causes
{          the share modes to be determined from the access_modes specified.
{          If the access_modes include fsc$append, fsc$modify, or fsc$shorten,
{          then no sharing is allowed; otherwise, fsc$read and fsc$execute are
{          chosen.
{
{          If more than one record of type fsc$access_and_share_modes is
{          specified, the first record is considered to be the "preferred" one
{          and the remaining records of this type are considered to be
{          alternate specifications in the order in which they are provided in
{          the array.  The alternate specifications are processed only in the
{          event that the preferred alternative is not authorized.
{
{          Access to a cycle is only authorized if the user is permitted for
{          all the access modes specified, the task is executing in the correct
{          ring for the requested access, and the requested share modes include
{          both the minimum requirement defined in the access-control list and
{          the access modes of any other jobs that have the file attached.
{
{    fsc$allowed_exceptions:  This option determines whether or not the
{          existence of certain exception conditions are reported to the task.
{          This option not only affects the processing of exception conditions
{          by FSP$OPEN_FILE but also affects requests associated with the
{          instance of open including FSP$CLOSE_FILE and record access requests
{          (e.g.  AMP$GET_NEXT, AMP$PUT_NEXT).  Once the file is successfully
{          opened for segment access, exception conditions that occur during
{          the task's segment access are reported and handled using NOS/VE's
{          condition-handling process.
{
{          Allowed exception conditions fall into one of two categories:  1)
{          those exception conditions that identify possible inconsistencies in
{          the file's attributes or data and 2) those that temporarily block
{          access to the file.  The category 1 conditions are identified by the
{          field DAMAGE_SYMPTOMS.  The category 2 conditions are identified by
{          the field ACCESS_CONDITIONS.
{
{          If the ALLOWED_EXCEPTIONS option is explicitly specified and the
{          detected condition is in neither the DAMAGE_SYMPTOMS set nor the
{          ACCESS_CONDITIONS set, the request terminates with abnormal status
{          as soon as the condition is detected.  The request is completely
{          retracted.
{
{          If the allowed exception is in the DAMAGE_SYMPTOMS set, the
{          condition is ignored by FSP$OPEN_FILE and other requests associated
{          with the instance of open.
{
{          If the allowed exception is in the ACCESS_CONDITIONS set:
{
{          - FSP$OPEN_FILE waits for the duration of time identified in the
{          WAIT_FOR_ATTACHMENT option for the condition to clear.  If at the
{          expiration of the wait time the condition remains set, abnormal
{          status is returned.
{
{          - Record access requests, segment accessors, and FSP$CLOSE_FILE wait
{          indefinitely for the condition to clear.
{
{          If the task does not want to wait under any circumstance, a null set
{          should be specified for ACCESS_CONDITIONS and DAMAGE_SYMPTOMS.
{
{          The value specified for this option when the file is initially
{          attached to the job must be specified by all subsequent instances of
{          open within the job until the file is detached from the job.
{
{          If this option is omitted:
{
{          - For conditions in the ACCESS_CONDITIONS set, FSP$OPEN_FILE waits
{          for the duration of time specified by the WAIT_FOR_ATTACHMENT
{          option; other requests and segment accessors wait indefinitely.
{
{          - For conditions in the DAMAGE_SYMPTOMS set, abnormal status is
{          returned.
{
{    fsc$create_file:  The value TRUE authorizes both the registration and the
{          initial opening of the file.
{
{          The value FALSE prevents file and or cycle registration and initial
{          opening of the cycle.  The specification of FALSE is recommended in
{          those situations where pre-existence of the file is assumed or
{          required.  Specifying the value FALSE removes the need to use some
{          other request to validate the existence of the file prior to opening
{          it or the need to parse the FILE parameter in advance to detect the
{          use of the '$NEXT' cycle reference in situations where cycle
{          pre-existence is mandatory.
{
{          This request does not support creation of non-mass storage files.
{          Because of this, the fsc$create_file option is ignored for files
{          assigned to device classes other than mass storage.
{
{          If you intend to append to an existing cycle, ensure that you
{          specify FALSE for this option; otherwise, this request may cause
{          creation of a cycle in certain situations.  Refer to the FILE
{          parameter discussion.
{
{    fsc$delete_data:  If the value TRUE is specified and the following
{          conditions hold, the data in the file is discarded as a result of
{          the open; otherwise, any data previously written to the file is
{          unaffected by this request:
{
{             1.  The file must either already be attached to the job for
{                 exclusive access (share modes is a null set) or become
{                 attached to the job for exclusive access as a result of this
{                 request.
{
{             2.  The access modes specified (or determined by default) for the
{                 instance of open must include fsc$shorten access.
{
{             3.  The file must not be currently open within the job.
{
{             4.  The open position specified (or determined by default) is
{                 $BOI.
{
{    fsc$error_exit_procedure_name:  fsc$error_exit_procedure:  Specification
{          of error_exit_procedure_name and error_exit_procedure are mutually
{          exclusive if the value specified for error_exit_procedure_name is
{          not osc$null_name.
{
{    fsc$exception_detection:  This option specifies whether or not any
{          optional detection of exception conditions is to be performed while
{          the file is attached.  Detection of the following conditions is
{          optional:
{
{          FSC$MEDIA_IMAGE_INCONSISTENT - If a mass storage file is attached
{          for write access and detection of this condition is requested, the
{          system takes precautions to detect the possible loss of modified
{          pages from the central memory image during a system interruption.
{          If this detection is requested and there is the possibility that
{          modified pages of the file have been lost, the condition is reported
{          the next time the file is attached.  For complete protection, the
{          task must preallocate the file's mass storage space using the
{          mmp$preallocate_file_space request; otherwise, allocation
{          information could be lost, if the central memory image cannot be
{          maintained or recovered.
{
{    fsc$free_behind:  This option specifies whether or not pages previously
{          read into memory from a mass storage file are to be discarded when
{          the position of the accessor changes to a different transfer unit.
{
{    fsc$open_share_modes:  This option is used to control sharing of a file
{          within the job.  When specified by the first of several concurrent
{          instances of open, this option constrains the access modes of
{          subsequent concurrent instances of open.
{
{          If more than one open_share_modes is specified, the first one is
{          considered to be the "preferred" one and the remaining ones are
{          considered to be alternatives.  If there are no outstanding
{          instances of open, the preferred open share modes specification is
{          used to constrain the access modes allowed to subsequent, concurrent
{          instances of open.  The alternatives are considered only when there
{          is another instance of open outstanding and the preferred open share
{          modes does not include the modes of access specified by other
{          concurrent instances of open.
{
{    fsc$open_position:  This option specifies the position at which the file
{          is opened.  If specified, the value supercedes the open position
{          specified in the FILE parameter expression.
{
{    fsc$password:  This option specifies a password to be compared with the
{          value of the file's password in the catalog.  An attachment is
{          permitted only if the values are identical.  If the file is created
{          as a result of this request, the specified password is stored in the
{          catalog and used to authenticate future attachments of the file.
{
{    fsc$private_read:  This option specifies whether or not file access should
{          be private.  If the value TRUE is specified, a reader does not
{          affect the position of nonprivate accessors (i.e.  those instances
{          of open that specified FALSE for this option).  A writer can never
{          be considered a private reader.  If private_read is specified on
{          both the fsp$open_file request and an ATTACH_FILE command, the
{          fsp$open_file specification is used.  The default value of
{          private_read is determined solely by the access_modes in effect for
{          the instance of open; if the access_modes do not include write,
{          private_read defaults to TRUE; otherwise, the default is FALSE.
{
{    fsc$sequential_access:  This option specifies that access to a file opened
{          for either record or segment access is performed in a sequential
{          manner.  This implies the intent to read mass storage data at the
{          device rate.
{
{    fsc$tape_attachment:  This option specifies how a labeled tape file is to
{          be accessed.
{
{    fsc$tape_error_options:  This option specifies how media failure recovery
{          is to be performed.
{
{    fsc$transfer_size:  This option specifies the minimum amount of data that
{          is read from a mass storage file when sequential access is specified
{          or detected.
{
{    fsc$validation_ring:  This option specifies the ring to be used for access
{          validation.  This option is recommended for use by a subsystem that
{          executes in a more privileged ring than its caller; the caller's
{          ring may be used to validate the attachment.  Thus the caller is not
{          able to misuse the privilege of the subsystem to attach files to
{          which the caller would otherwise not have access.
{
{          If specified, the file or file cycle is created as a result of this
{          request, and the ring_attributes are not specified using the
{          default_creation_attributes or mandated_creation_attributes
{          parameters, the ring_attributes default to the validation_ring
{          specified.
{
{    fsc$wait_for_attachment:  This option specifies whether or not the caller
{          wants to wait for the file to be attached to the job.  If the file
{          is already attached to the job, this option is ignored.  If the
{          caller specifies the osc$wait choice, a wait duration must also be
{          provided.
{
{ DEFAULT_CREATION_ATTRIBUTES: (input)  This parameter specifies the value to
{       be given to a file attribute in the absence of a specification for that
{       attribute by a SET_FILE_ATTRIBUTES command and the
{       MANDATED_CREATION_ATTRIBUTES parameter of this request.  If FILE was
{       previously opened, this parameter is ignored.  A value of NIL for this
{       parameter specifies no default creation attributes are provided.  If
{       the same attribute is specified multiple times in the array, the last
{       specification is used.
{
{ MANDATED_CREATION_ATTRIBUTES: (input)  This parameter specifies file
{       attribute values that must be defined, if the file is initially opened
{       by this request.  If the FILE was previously opened, this parameter is
{       ignored.  Attribute values specified using this parameter have greater
{       precedence than those specified using the DEFAULT_CREATION_ATTRIBUTES
{       parameter of this request and the SET_FILE_ATTRIBUTES command.  A value
{       of NIL for this parameter specifies no mandated creation attributes are
{       provided.  If the same attribute is specified multiple times in the
{       array, the last specification is used.
{
{ ATTRIBUTE_VALIDATION: (input)  This parameter specifies the desired attribute
{       values of the file.  Values of attributes specified by this parameter
{       are compared with those in effect for the FILE.  An
{       ame$attribute_validation_error abnormal status is returned if none of
{       values specified by this parameter match the file's attribute value.
{
{       This parameter allows alternatives to be specified for each attribute
{       to be validated.  To specify an alternative value for an attribute,
{       simply provide another record in the array.  Alternatives are processed
{       in the order given.  Once an alternative is found that matches the
{       value of the corresponding file attribute, subsequent alternatives are
{       ignored.
{
{ ATTRIBUTE_OVERRIDE: (input)  This parameter specifies an attribute value to
{       be used only for this instance of open of the file or file cycle.  Only
{       record type, block type, file organization and ring attributes can be
{       overridden.  Only a ring 3 caller can override attributes for a file or
{       file cycle to be written upon.  Ring attributes may only be overridden
{       by a ring 3 caller whose requested access does not include fsc$append,
{       fsc$modify or fsc$shorten.  If the same attribute is specified multiple
{       times in the array, the last specification is used.
{
{ FILE_IDENTIFIER: (output)  This parameter specifies the identity of the
{       instance of open of the file created by this request.
{
{ STATUS: (ouput) This parameter specifies the request status.
{       CONDITION:
{                   ame$attribute_validation_error
{                   ame$concurrent_open_limit
{                   ame$concurrent_tape_limit
{                   ame$conflicting_file_access
{                   ame$damaged_file_attributes
{                   ame$file_not_known
{                   ame$fo_access_level_conflict
{                   ame$fo_device_class_conflict
{                   ame$improper_access_level
{                   ame$improper_append_open
{                   ame$improper_file_attrib_key
{                   ame$improper_file_attrib_value
{                   ame$improper_fo_override
{                   ame$improper_override_access
{                   ame$improper_record_override
{                   ame$improper_ss_block_override
{                   ame$improper_us_block_override
{                   ame$improper_write_override
{                   ame$incompatible_file_connect
{                   ame$keyed_file_fap_missing
{                   ame$local_file_limit
{                   ame$mbl_less_than_mibl
{                   ame$mbl_less_than_mrl
{                   ame$multiple_open_of_tape
{                   ame$new_file_requires_append
{                   ame$no_permission_for_access
{                   ame$no_write_ring.
{                   ame$non_ANSI_blocking
{                   ame$not_physical_access_device
{                   ame$not_virtual_memory_device
{                   ame$null_access_mode
{                   ame$ring_validation_error
{                   ame$terminal_task_limit
{                   ame$unable_to_load_collate_tabl
{                   ame$unable_to_load_error_exit
{                   ame$unable_to_load_fap
{                   ame$unable_to_load_label_exit
{                   fse$concurrent_access_conflict
{                   fse$redundant_access_choice
{                   fse$concurrent_share_conflict
{                   pfe$cycle_overflow
{                   pfe$cycle_underflow
{                   pfe$cycles_media_missing
{                   pfe$duplicate_cycle
{                   pfe$incorrect_password
{                   pfe$invalid_ring_access
{                   pfe$lfn_in_use
{                   pfe$name_already_subcatalog
{                   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_master_catalog
{                   pfe$unknown_nth_subcatalog
{                   pfe$unknown_permanent_file
{                   pfe$usage_not_permitted
{       IDENTIFIER: fsc$file_system_id.
{
