Click above to get retro games delivered to your door ever month!

Function 3Dh (61)        Open a File

    Opens a file with the specified access code.

       On entry:      AH         3Dh
                      AL         Open mode
                      DS:DX      Pointer to filename (ASCIIZ string)

       Returns:       AX         File handle
                                 Error code, if CF is set

       Error codes:   1          Function number invalid
                      2          File not found
                      3          Path not found
                      4          No handle available
                      5          Access denied
                      12         Open mode invalid

                      Call Function 59h for extended error code information
                      (DOS 3.0 and above).

  --------------------------------------------------------------------------

    This function opens the file whose pathname is specified in the ASCIIZ
    string at DS:DX using the "open mode" byte to determine how the file
    may be accessed. The function opens any existing file, including
    hidden files, and sets the record size to 1 byte.

  --------------------------------------------------------------------------
  Open Mode Coding in AL

              AL
          Bit Number             Open Mode            DOS 2.x usage
        7 6 5 4 3 2 1 0
        . . . . . A A A          Access mode          Read/Write access
        . . . . R . . .          Reserved             Always 0
        . S S S . . . .          Sharing mode         Must be 0 in DOS 2
        I . . . . . . .          Inheritance flag     Must be 0 in DOS 2

  ---------------------------------------------------------------------------
  Access Mode (lower three bits of AL):

    The low-order three bits (access mode) are used in the same manner in
    both DOS 2 and 3. These bits indicate allowable access (read, write,
    or read/write).

             Bit           Hex       Access Mode
            2 1 0
            0 0 0           0        Read-only access
            0 0 1           1        Write-only access
            0 1 0           2        Read/write access

  ---------------------------------------------------------------------------
  Bit 3 Reserved (must always be zero)

  ---------------------------------------------------------------------------
  Sharing Mode (Bits 4, 5, and 6 of AL) -- DOS 3.0 and above

    In DOS 3.0 and above, bits 4, 5, and 6 specify a sharing mode (must be
    set to 0 in DOS 2.x). These bits govern the manner (if any) in which
    other users on a network may open and use the file after you have
    opened it. The following settings (and no others) are valid:

             Bit           Hex       Sharing Mode
            6 5 4
            0 0 0           0        Compatibility mode
            0 0 1           1        Deny Read/Write mode (Exclusive mode)
            0 1 0           2        Deny Write mode
            0 1 1           3        Deny Read mode
            1 0 0           4        Deny None mode

  ---------------------------------------------------------------------------
  Inheritance Flag (bit 7 of AL) -- DOS 3.0 and above

    The Inheritance Flag (bit 7), specifies whether or not child processes
    will inherit the use of this file. If bit 7 is 0, child processes
    automatically have access to the file. If bit 7 is 1, the file is not
    automatically available to child processes. Like any other process,
    however, a child process can request access to the file on a shared
    basis; see the discussion of sharing/access mode interactions, below.

            Bit 7         Inheritance Flag
              0           File is inherited by child processes
              1           File is not inherited

  ---------------------------------------------------------------------------
  Availability of an opened file to subsequent processes

    Once a file has been opened by a process, the availability of that
    file to other processes is determined by both the sharing mode and
    access mode of the original process as well as by the sharing mode and
    access mode specified by the subsequent process. Here is a case-by-
    case overview of these interactions:

     1.  The file is first opened in compatibility sharing mode.  A file
         is considered to be in "compatibility" mode if it is opened:

         .   via an FCB function
         .   via any of the CREATE functions
         .   via any handle function call in which compatibility mode is
             specified.

    A file in compatibility mode may be opened any number of times by a
    single process, unless the file is already open under one of the other
    four sharing modes. If the file has the read-only attribute, however,
    and it is currently open in Deny Write sharing mode with Read access,
    the file may be opened in Compatibility mode with Read access.

     2.  The file is opened in one of the other sharing modes.  See the
         table below.

+----------------------------------------------------------------------------+
|A file first opened in   |   May be reopened in                             |
|-------------------------+--------------------------------------------------|
|Deny Read/Write mode,    |   May not be reopened                            |
|Read Only access         |                                                  |
|        (AL=X0010000)    |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Read/Write mode,    |   May not be reopened                            |
|Write Only access        |                                                  |
|        (AL=X0010001)    |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Read/Write mode,    |   May not be reopened                            |
|Read/Write access        |                                                  |
|        (AL=X0010010)    |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Write mode,         |   Deny Write, Read Only         (AL = x0100000)  |
|Read Only access         |   Deny None, Read Only          (AL = x1000000)  |
|        (AL=X0100000)    |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Write mode,         |   Deny Read, Read Only          (AL = x0110000)  |
|Write Only access        |   Deny None, Read Only          (AL = x1000000)  |
|        (AL=X0100001)    |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Write mode,         |   Deny None, Read Only          (AL = x1000000)  |
|Read/Write access        |                                                  |
|        (AL=X0100010)    |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Read mode,          |   Deny Write, Write Only        (AL = x0100001)  |
|Read Only access         |   Deny None, Write Only         (AL = x1000001)  |
|        (AL = x0110000)  |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Read mode,          |   Deny Read,  Write Only        (AL = x0110001)  |
|Write Only access        |   Deny None,  Write Only        (AL = x1000001)  |
|        (AL = x0110001)  |                                                  |
|-------------------------+--------------------------------------------------|
|Deny Read mode,          |   Deny None,  Write Only        (AL = x1000001)  |
|Read/Write access        |                                                  |
|        (AL = x0110010)  |                                                  |
|-------------------------+--------------------------------------------------|
|Deny None mode,          |   Deny Write, Read Only         (AL = x0100000)  |
|Read Only access         |   Deny Write, Write Only        (AL = x0100001)  |
|        (AL = x1000000)  |   Deny Write, Read/Write        (AL = x0100010)  |
|                         |   Deny None,  Read Only         (AL = x1000000)  |
|                         |   Deny None,  Write Only        (AL = x1000001)  |
|                         |   Deny None,  Read/Write        (AL = x1000010)  |
|-------------------------+--------------------------------------------------|
|Deny None mode,          |   Deny Read, Read Only          (AL = x0110000)  |
|Write Only access        |   Deny Read, Write Only         (AL = x0110001)  |
|        (AL = x1000001)  |   Deny Read, Read/Write         (AL = x0110010)  |
|                         |   Deny None, Read Only          (AL = x1000000)  |
|                         |   Deny None, Write Only         (AL = x1000001)  |
|                         |   Deny None, Read/Write         (AL = x1000010)  |
|-------------------------+--------------------------------------------------|
|Deny None mode,          |   Deny None, Read Only          (AL = x1000000)  |
|Read/Write access        |   Deny None, Write Only         (AL = x1000001)  |
|        (AL = x1000010)  |   Deny None, Read/Write         (AL = x1000010)  |
+----------------------------------------------------------------------------+

  --------------------------------------------------------------------------

       Notes:         Files that end with a colon (devices) are not opened
                      with this function call.

                      File sharing must be loaded for the sharing modes of
                      this function to work.

                      Child processes that inherit files also inherit
                      their sharing and access restrictions.