View source for 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
<PRE>
    #include  "dhcalls.h"
    USHORT APIENTRY DevHelp_OpenFile (PFILEIOINFO pFileOpen);
</PRE>

Calling Sequence in Assembler
<PRE>
LES   DI, FileOpen            ; Point to FILEIOINFO structure
MOV   DL, DevHlp_OpenFile

CALL   [Device_Help]
</PRE>

==Parameters==
===C===
; pFILEIOINFO input : Pointer to the FILEIOINFO structure defined as follows
<PRE>
    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
</PRE>


===Calling convention Assembler===
* ES:DI = point to a SYIOpenFile structure
* DL = 07fh 

ES DI points to a FILEIOINFO structure defined as follows
<PRE>
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
</PRE>

==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.

==Errors== 

==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.

==Example Code==
<PRE>

</PRE>

==Related Functions==

[[Category:DevHlps]]