Synopsis:

        file_handle=sys_fhopen(filename,flags)

Arguments:

        filename          -   The path of the file to open

        flags                -   Defines how the file is to be opened.

Description:    This function opens the file specified by filename and returns a file_handle to the file.        Flags is a string that defines how the file should be opened.      Each character of the string in flags has a different meaning as follows:

        r        -   Open the file for reading

        w        - Open the file for writing

        s        -   Open the file in shared mode

        c        -   Create the file if it deosn't exist

        t        -   Truncate the file to 0 bytes when it is opened.

At least one of the flags r or w should be specified (or both), whereas the other flags (s, t or c) are optional.

For example, the following code specifies that "myfile.txt" should be opened for reading and writing in shared mode and it should be created if it doesn't exist:

    file_open("myfile.txt","rwsc");

The following specifies that "myfile.txt" should be opened for reading in exclusive mode (non shared).  

    file_open("myfile.txt","r");       

The file handle returned will actually be an integer between 0 and the maximum number of open files allowed by the library - it will not be an operating specific file handle.    To obtain the operating system file handle (say for use by other DLL libaries) then the function sys_gethandle() can be used.

Note that if the same file is opened by multiple tasks then each task will receive its own unique handle to the file.

Return Value:

The function will return a unique file handle or an negative error value if the file could not be opened.    The value returned will be that which is returned by the Windows GetLastError() function.