Table of Contents

This is part of Family API which allow to create dual-os version of program runs under OS/2 and DOS

Note: This is legacy API call. It is recommended to use 32-bit equivalent

2021/09/17 04:47 · prokushev · 0 Comments
2021/08/20 03:18 · prokushev · 0 Comments

DosOpen2

This call opens a new file, an existing file, or a replacement for an existing file. The opened file can have extended attributes.

Syntax

DosOpen2 (FileName, FileHandle, ActionTaken, FileSize, FileAttribute,
           OpenFlag, OpenMode, EABuf, Reserved)

Parameters

These bits may be set individually or in combination. For example, an attribute value of 0021H (bits 5 and 0 set to 1) indicates a read-only file that should be archived.

This bit is not inherited by child processes.

Media I/O errors generated through an IOCTL Category 8 function always get reported directly to the caller by way of return code. The Fail-Errors function applies only to non-IOCTL handle-based file I/O calls.

This bit is not inherited by child processes.

This bit advises FSDs and device drivers whether it is worth caching the data. Like the write-through bit, this is a per-handle bit and is not inherited by child processes.

This bit is not inherited by child processes.

Any other value is invalid. Any other combinations are invalid. File sharing requires the cooperation of sharing processes. This cooperation is communicated through sharing and access modes. Any sharing restrictions placed on a file opened by a process are removed when the process closes the file with a DosClose request.

Sharing Mode

Specify the type of access other processes may have to the file (sharing mode). For example, if it is permissible for other processes to continue reading the file while your process is operating on it, specify Deny Write. This sharing mode prevents other processes from writing to the file but still allows them to read it.

Access Mode

Specify the type of access to the file needed by your process (access mode). For example, if your process requires Read/Write access, and another process has already opened the file with a sharing mode of Deny None, your DosOpen2 request succeeds. However, if the file is open with a sharing mode of Deny Write, your process is denied access. If the file is inherited by a child process, all sharing and access restrictions are also inherited. If an open file handle is duplicated by a call to DosDupHandle, all sharing and access restrictions are also duplicated.

On input, the fpGEAList field and oError fields are ignored. The EA setting operation is performed on the information contained in FEAList. If extended attributes are not to be defined or modified, then EABuf must be set to null. Following is the FEAList format:

;list (FEA) - List of FEA structures. An FEA structure has the following format: ::Flags (BYTE) - Bit indicator describing the characteristics of the EA being defined. :::7 Critical EA. :::6-0 Reserved and must be set to zero. If bit 7 is set to 1, this indicates a critical EA. If bit 7 is 0, this means the EA is noncritical; that is, the EA is not essential to the intended use by an application of the file with which it is associated. ;cbName (BYTE):Length of EA ASCIIZ name, which does not include the null character. ;cbValue (USHORT):Length of EA value, which cannot exceed 64KB. ;szName (PSZ):Address of the ASCIIZ name of EA. ;aValue (PSZ):Address of the free-format value of EA. :'Note:' The szName and aValue fields are not included as part of header or include files. Because of their variable lengths, these entries must be built manually. :On output, fpGEAList is unchanged. fpFEAList is unchanged as is the area pointed to by fpFEAList. If an error occurred during the set, oError is the offset of the FEA where the error occurred. The API return code is the error code corresponding to the condition generating the error. If no error occurred, oError is undefined. :If EABuf is 0x00000000, then no extended attributes are defined for the file.

* Reserved (ULONG) - input : Reserved and must be set to zero.

Return Code

rc (USHORT) - return:Return code descriptions are:

Remarks

A successful DosOpen2 request for a file returns a handle to access the file. The read/write pointer is set at the first byte of the file. The pointer's position may be changed by a DosChgFilePtr request or by read and write operations on the file.

The file's date and time can be queried by calling DosQFileInfo, and is set by calling DosSetFileInfo.

FileAttribute sets attribute bits for the file object. Attributes of an existing file can be queried and set by DosQFileMode and DosSetFileMode. A file's read-only attribute may also be set with the OS/2 ATTRIB command.

FileAttribute cannot be set to Volume Label. Volume labels cannot be opened. DosSetFSInfo may be issued with a logical drive number to set volume label information.

The FileSize parameter affects the size of the file only when the file is a new file or a replacement for an existing one. If an existing file is simply opened, FileSize is ignored. DosNewSize may be called to change the existing file's size.

The value in FileSize is a recommended size for the file. If allocation of the full size fails, the open may still succeed. The file system makes a reasonable attempt to allocate the new size in as nearly contiguous an area as possible on the medium. When the file size is extended, the value of the new bytes is undefined.

The DASD Open bit provides direct access to an entire disk or diskette volume, independent of the file system. This mode of opening the volume currently mounted on the drive returns a handle to the caller, which represents the logical volume as a single file. The caller specifies this handle with a DosDevIOCtl Category 8 Function 0 request to block other processes from accessing the logical volume.

The file handle state bits can be set by the DosOpen2 and DosSetFHandState requests. An application can query the file handle state bits as well as the rest of the Open Mode field, by calling DosQFHandState.

Extended attributes can be set by an EAOP structure in EABuf when creating a file, replacing an existing file, or truncating an existing file. No extended attributes are set when simply opening an existing file.

A replace operation is logically equivalent to atomically deleting and re-creating the file. This means that any extended attributes associated with the file are also deleted before the file is re-created.

Family API Considerations

Some options operate differently in the DOS mode than in the OS/2 mode. Therefore, the following restrictions apply to DosOpen when coding for the DOS mode:

Bindings

C

typedef struct _GEA {       /* gea */
  BYTE cbName;            /* name length not including NULL */
  CHAR szName[1];         /* attribute name */
} GEA;
 
typedef struct _GEALIST {   /* geal */
  ULONG  cbList;          /* total bytes of structure including full list */
  GEA list[1];            /* variable length GEA structures */
} GEALIST;
 
typedef struct _FEA {       /* fea */
  BYTE fEA;               /* flags */
  BYTE cbName;            /* name length not including NULL */
  USHORT cbValue;         /* value length */
} FEA;
 
typedef struct _FEALIST {   /* feal */
  ULONG  cbList;          /* total bytes of structure including full list */
  FEA list[1];            /* variable length FEA structures */
} FEALIST;
 
typedef struct _EAOP {      /* eaop */
  PGEALIST fpGEAList;     /* general EA list */
  PFEALIST fpFEAList;     /* full EA list */
  ULONG  oError;
} EAOP;
 
#define INCL_DOSFILEMGR
 
USHORT  rc = DosOpen2(FileName, FileHandle, ActionTaken, FileSize,
                             FileAttribute, OpenFlag, OpenMode, EABuf,
                             Reserved);
 
PSZ              FileName;      /* File path name string */
PHFILE           FileHandle;    /* File handle (returned) */
PUSHORT          ActionTaken;   /* Action taken (returned) */
ULONG            FileSize;      /* File primary allocation */
USHORT           FileAttribute; /* File Attribute */
USHORT           OpenFlag;      /* Open function type */
ULONG            OpenMode;      /* Open mode of the file */
PEAOP            EABuf;         /* Extended attribute buffer */
ULONG            0;             /* Reserved (must be zero) */
 
USHORT           rc;            /* return code */

MASM

GEA    struc
 
  gea_cbName      db  ?          ;name length not including NULL
  gea_szName      db  1 dup (?)  ;attribute name
 
GEA    ends
 
GEALIST    struc
 
  geal_cbList     dd  ?      ;total bytes of structure including full list
  geal_list       db  size GEA * 1 dup (?) ;variable length GEA structures
 
GEALIST    ends
 
FEA   struc
 
  fea_fEA         db  ? ;flags
  fea_cbName      db  ? ;name length not including NULL
  fea_cbValue     dw  ? ;value length
 
FEA   ends
 
FEALIST struc
 
  feal_cbList     dd  ?      ;total bytes of structure including full list
  feal_list       db  size FEA * 1 dup (?) ;variable length FEA structures
 
FEALIST ends
 
EAOP    struc
 
  eaop_fpGEAList  dd  ? ;general EA list
  eaop_fpFEAList  dd  ? ;full EA list
  eaop_oError     dd  ? ;
 
EAOP    ends
 
EXTRN  DosOpen2:FAR
INCL_DOSFILEMGR     EQU 1
 
PUSH@  ASCIIZ  FileName      ;File path name string
PUSH@  WORD    FileHandle    ;File handle (returned)
PUSH@  WORD    ActionTaken   ;Action taken (returned)
PUSH   DWORD   FileSize      ;File primary allocation
PUSH   WORD    FileAttribute ;File Attribute
PUSH   WORD    OpenFlag      ;Open function type
PUSH   DWORD   OpenMode      ;Open mode of the file
PUSH@  OTHER   EABuf         ;Extended attribute buffer
PUSH   DWORD   0             ;Reserved (must be zero)
CALL   DosOpen2
 
Returns WORD