DevHlp OpenFile

DevHlp_OpenFile is used by base device drivers to open a file for read access during initialization. This devhlp allows to open a file for read access in the Init routine of a BASEDEV.

Syntax

Calling Sequence in C

 #include  "dhcalls.h"
 USHORT APIENTRY DevHelp_OpenFile (PFILEIOINFO pFileOpen);

Calling Sequence in Assembler

LES   DI, FileOpen            ; Point to FILEIOINFO structure
MOV   DL, DevHlp_OpenFile

CALL   [Device_Help]

Parameters

C

pFILEIOINFO input

Pointer to the FILEIOINFO structure defined as follows

    typedef struct FOPEN {
            PSZ    FileName;   /* (input) pointer to file name */
            ULONG  FileSize;   /* (output) size of file returned by FileOpen */
    } FILEOPEN;

    typedef struct FCLOSE {
            USHORT  reserved   /* reserved */
    } FILECLOSE;

    typedef struct FREAD {
            PBYTE Buffer;     /* (input) pointer to input buffer */
            ULONG ReadSize;   /* (input) number of bytes to read fromfile */
    } FILEREAD;

    typedef struct FREADAT {
            PBYTE Buffer;        /* (input) pointer to input buffer */
            ULONG ReadSize;      /* (input) number of bytes to read from file */
            ULONG StartPosition  /* (input) starting file position relative to
                                     the beginning of the file */
    } FILEREADAT;

    typedef union FILEIOOP {
            struct FOPEN FileOpen;
            struct FCLOSE FileClose;
            struct FREAD FileRead;
            struct FREADAT FileReadAt;
    } FILEIOOP;

    typedef struc _DDFileIo {
            USHORT Length; /* (input) length of imbedded structure */
            FILEIOOP Data; /* (input) imbedded file system operation structure */
    } FILEIOINFO, FAR * PFILEIOINFO

Calling convention Assembler

• ES:DI = point to a SYIOpenFile structure
• DL = 07fh

ES DI points to a FILEIOINFO structure defined as follows

FILEIOINFO struc
length        dw     8    ; length of imbedded fle system operation structure
;
FOPEN struc
name          dd     ?    ; 16 16 pointer to ASCIZ pathname
fsize         dd     ?    ; returned  size of file
FOPEN         ends
;
FILEIOINFO    ends

Return Code

Results in C

Success Indicator 0 if file was opened..

24 ERROR_BAD_LENGTH

Length in the FILEIOINFO structure is invalid.

Results in Assembler

• C Clear if file is opened. AX = zero.
• C Set if error. AX = Error code. Possible errors
• 24 ERROR_BAD_LENGTH. The length in the FILEIOINFO structure is invalid.

Remarks

DevHlp_OpenFile may be called at initialization time only. It provides a primitive interface to the mini-IFS or micro_IFS at initialization time.

Drive and path information is ignored. The system searches for the file in the root, \OS2 and \OS2\BOOT directories of the boot drive/device.

Using this interface, one file only may be opened at a time. No handle is assigned. Subsequent read and close requests assume the file is the most recent opened using DevHlp_OpenFile.

Valid at INIT time only. This routine is not handle based, so it is only possible to have only one file at a time open. This routine uses the corresponding function of the miniFSD, not normal file I/O, thus access is restricted. At this phase of boot, drive letters do not yet exist, and IFSs/DMDs might not yet have been initialized, so you can only open files on the boot drive. Depending on the type of IPL (e.g. loading from a network file system), other restrictions might apply.