?? RIGHT := 110 ??
?? NEWTITLE := 'PACKAGE_SOFTWARE Utility: Module RAM$OPEN_FILE.' ??
MODULE ram$open_file;

{ PURPOSE:
{   This module contains a procedures to open a file.
{
{ DESIGN:
{   The FILE is opened with the file attachment option and
{   create file definitions provided in the procedure parameters.
{
{ NOTES:
{   This procedure should be called from within a block structure
{   which has a condition handler.

?? NEWTITLE := 'Global Declarations Referenced by This Module', EJECT ??
?? PUSH (LISTEXT := ON) ??
*copyc ost$status
?? POP ??
*copyc fsp$open_file

?? TITLE := 'Global Declarations Declared by This Module', EJECT ??

?? TITLE := 'rap$open_segment_file [XDCL]', EJECT ??

{ PURPOSE:
{   This procedure opens a file.
{
{ DESIGN:
{   The FILE is opened with the attachment_option and
{        defined in the procedure parameters.
{
{ NOTES:
{   This procedure should be called from within a block structure
{   which has a condition handler.

  PROCEDURE [XDCL] rap$open_file
    (    path_ref_p: ^fst$file_reference;
         access_level: amt$access_level;
         file_attachment: fst$file_access_option;
         create_file: boolean;
         attribute_override_p: ^array [1 .. 1] of fst$file_cycle_attribute;
     VAR file_id: amt$file_identifier;
     VAR file_opened: boolean;
     VAR status: ost$status);


    VAR
      attachment_option: array [1 .. 3] of fst$attachment_option;


    status.normal := TRUE;
    file_opened := FALSE;

    attachment_option [1].selector := fsc$access_and_share_modes;
    attachment_option [1].access_modes.selector := fsc$specific_access_modes;

    IF file_attachment = fsc$read THEN

      attachment_option [1].access_modes.value := $fst$file_access_options [fsc$read];
      attachment_option [2].create_file := FALSE;

    ELSEIF file_attachment = fsc$modify THEN

      attachment_option [1].access_modes.value := $fst$file_access_options
            [fsc$read, fsc$shorten, fsc$append, fsc$modify];
      IF create_file = TRUE THEN
        attachment_option [2].create_file := TRUE;
      ELSE
        attachment_option [2].create_file := FALSE;
      IFEND;

    IFEND;

    attachment_option [1].share_modes.selector := fsc$determine_from_access_modes;
    attachment_option [2].selector := fsc$create_file;

{   The following attachment option is designed to detect offline residence of
{   the file being opened; ie. if the file has offline residence, an abnormal
{   status is returned from the open.  The allowed exceptions set below
{   includes all the current default allowed exception values, except the
{   one for offline residence (rac$data_retrieval_required).  Due to the way
{   the set is defined (ie. with several default names and several temporary
{   names to hold places for future values), the defaults had to be specified.
{   If the defaults change, the statment below sepcifying the defaults must
{   also change.

    attachment_option [3].selector := fsc$allowed_exceptions;
    attachment_option [3].allowed_exceptions.damage_symptoms :=
          $fst$cycle_damage_symptoms [];
    attachment_option [3].allowed_exceptions.access_conditions :=
           $fst$file_access_conditions[fsc$catalog_media_missing, fsc$catalog_volume_unavailable,
             fsc$cycle_busy, fsc$file_server_inactive, fsc$media_missing,
             fsc$space_unavailable, fsc$volume_unavailable];

    file_opened := TRUE;
    fsp$open_file (path_ref_p^, access_level, ^attachment_option, NIL, NIL, NIL, attribute_override_p,
          file_id, status);
    IF NOT status.normal THEN
      file_opened := FALSE;
      RETURN;
    IFEND;

  PROCEND rap$open_file;

MODEND ram$open_file;
