# NNS_McsOpenFile

## Syntax

      #include <nnsys/mcs.h>

      u32 NNS_McsOpenFile(
              NNSMcsFile* pFile,
              const char* fileName,
              u32         openFlag);

## Arguments

`pFile` | Pointer to the file information structure.
`fileName` | Pointer to the null-terminated string that indicates an open file or a newly created file. If `NULL` is specified, a dialog window for selecting a file opens on the PC.
`openFlag` | How to open file or create file, and type of read or write (details explained below).

## Return Values

Zero if the file opened successfully. A non-zero value otherwise. See Description for details on the possible return values.

## Description

Opens an existing file on the PC, or creates a new file and opens it.

Use `openFlag` to specify the method to use to open the file.

`NNS_MCS_FILEIO_FLAG_READ` | Opens an existing file for reading.
`NNS_MCS_FILEIO_FLAG_WRITE` | Creates a new file for writing and open the file. If the file already exists, it is first deleted.
`NNS_MCS_FILEIO_FLAG_FORCE` | If `NNS_MCS_FILEIO_FLAG_WRITE` is specified and a file already exists, the user is not prompted about overwriting the file. If this flag is not specified and a file already exists, a dialog opens on the PC, prompting the user to confirm that the file is to be overwritten.
`NNS_MCS_FILEIO_FLAG_INCENVVAR` | Specify this flag if a PC environment variable is included in the filename string specified by `fileName`. The environment variable is enclosed by percent marks ("%"), for example, `%TWLSYSTEM_ROOT%\SourceTreeMap.txt`.
`NNS_MCS_FILEIO_FLAG_CREATEDIR` | When you specify `NNS_MCS_FILEIO_FLAG_WRITE` and create a file specified by `fileName`, if the directory in which the file is supposed to reside does not exist, this creates the directory. However, if `NNS_MCS_FILEIO_FLAG_INCENVVAR` has been specified and the PC environment variable contained in the filename string specified by `fileName` does not exist, as a safety measure the function fails without creating a directory.

The return value takes one of the following values.

`NNS_MCS_FILEIO_ERROR_SUCCESS` (0) | The function was successful.
`NNS_MCS_FILEIO_ERROR_COMERROR` | A communications error occurred.
`NNS_MCS_FILEIO_ERROR_NOTCONNECT` | Not connected to the MCS server.
`NNS_MCS_FILEIO_ERROR_SERVERERROR` | An error has occurred due to a file operation on the MCS server side. The error code is a Win32 system error code that you can get with the `NNS_McsGetServerErrorCode` function.

## See Also

`NNS_McsReadFile`
`NNS_McsWriteFile`
`NNS_McsCloseFile`

## Revision History

2008/06/20 Changed the environment variable to `TWLSYSTEM_ROOT`.
2005/01/24 Added descriptions regarding error codes.
2004/10/18 Added a description of the flag `NNS_MCS_FILEIO_FLAG_INCENVVAR`.
2004/07/01 Initial version.

CONFIDENTIAL