Creates and opens a file.

FCreateEx(cFileName [, nAttributesAndFlags [, nAccessMode [, nShareMode]]])

Parameters

cFileName

Specifies the name of the file to create. You can include a drive designator and path with the file name. If a drive designator or path isn't included, the file is created in the default directory.

nAttributesAndFlags (optional, additive)

default = FILE_ATTRIBUTE_NORMAL

The file or device attributes and flags, FILE_ATTRIBUTE_NORMAL being the most common default value for files.
This parameter can include any combination of the available file attributes (FILE_ATTRIBUTE_*). All other file attributes override FILE_ATTRIBUTE_NORMAL.
This parameter can also contain combinations of flags (FILE_FLAG_*) for control of file or device caching behavior, access modes, and other special-purpose flags. These combine with any FILE_ATTRIBUTE_* values.

File attributes:

ValueDescription
FILE_ATTRIBUTE_READONLYThe file is read only. Applications can read the file, but cannot write to or delete it.
FILE_ATTRIBUTE_HIDDENThe file is hidden. Do not include it in an ordinary directory listing.
FILE_ATTRIBUTE_SYSTEMThe file is part of or used exclusively by an operating system.
FILE_ATTRIBUTE_ARCHIVEThe file should be archived. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_NORMALThe file does not have other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_TEMPORARYThe file is being used for temporary storage.
FILE_ATTRIBUTE_OFFLINEThe data of a file is not immediately available. This attribute indicates that file data is physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software. Applications should not arbitrarily change this attribute.
FILE_ATTRIBUTE_ENCRYPTEDThe file or directory is encrypted. For a file, this means that all data in the file is encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories. For more information, see File Encryption.
This flag has no effect if FILE_ATTRIBUTE_SYSTEM is also specified.

Flags:

ValueDescription
FILE_FLAG_BACKUP_SEMANTICSThe file is being opened or created for a backup or restore operation. The system ensures that the calling process overrides file security checks when the process has SE_BACKUP_NAME and SE_RESTORE_NAME privileges.
You must set this flag to obtain a handle to a directory. A directory handle can be passed to some functions instead of a file handle. For more information, see the Remarks section.
FILE_FLAG_DELETE_ON_CLOSEThe file is to be deleted immediately after all of its handles are closed, which includes the specified handle and any other open or duplicated handles.
If there are existing open handles to a file, the call fails unless they were all opened with the FILE_SHARE_DELETE share mode.
Subsequent open requests for the file fail, unless the FILE_SHARE_DELETE share mode is specified.
FILE_FLAG_NO_BUFFERINGThe file or device is being opened with no system caching for data reads and writes.
This flag does not affect hard disk caching or memory mapped files.
There are strict requirements for successfully working with files opened with CreateFile using the FILE_FLAG_NO_BUFFERING flag.
FILE_FLAG_OPEN_NO_RECALLThe file data is requested, but it should continue to be located in remote storage. It should not be transported back to local storage. This flag is for use by remote storage systems.
FILE_FLAG_POSIX_SEMANTICSAccess will occur according to POSIX rules. This includes allowing multiple files with names, differing only in case, for file systems that support that naming. Use care when using this option, because files created with this flag may not be accessible by applications that are written for MS-DOS or 16-bit Windows.
FILE_FLAG_RANDOM_ACCESSAccess is intended to be random. The system can use this as a hint to optimize file caching.
This flag has no effect if the file system does not support cached I/O and FILE_FLAG_NO_BUFFERING.
FILE_FLAG_SEQUENTIAL_SCANAccess is intended to be sequential from beginning to end. The system can use this as a hint to optimize file caching.
This flag should not be used if read-behind (that is, backwards scans) will be used.
This flag has no effect if the file system does not support cached I/O and FILE_FLAG_NO_BUFFERING.
FILE_FLAG_WRITE_THROUGHWrite operations will not go through any intermediate cache, they will go directly to disk.

Note

For more information on the attributes and flags have a look at the CreateFile documentation.

nAccessMode (optional)

default = 0

valid values:
0 - read only
1 - write only
2 - read/write

nSharemode (optional)

default = 0 (no sharing)

One or a combination of the following values.
SharemodeDescription
0Prevents other processes from opening a file or device if they request delete, read, or write access.
FILE_SHARE_READ Enables subsequent open operations on a file or device to request read access.
Otherwise, other processes cannot open the file or device if they request read access.
If this flag is not specified, but the file or device has been opened for read access, the function fails.
FILE_SHARE_WRITEEnables subsequent open operations on a file or device to request write access.
Otherwise, other processes cannot open the file or device if they request write access.
If this flag is not specified, but the file or device has been opened for write access or has a file mapping with write access, the function fails.
FILE_SHARE_DELETEEnables subsequent open operations on a file or device to request delete access.
Otherwise, other processes cannot open the file or device if they request delete access.
If this flag is not specified, but the file or device has been opened for delete access, the function fails.
Note: Delete access allows both delete and rename operations.

Return Value

A HANDLE (numeric) value to the created file or -1 if an error occured.

Remarks

The nAccessMode and nShareMode parameters extended the functionality of FoxPro's native FCREATE().

If a file with the name you specify already exists, it is overwritten without warning.

FCreateEx( ) assigns a file handle number to the file, which you can use to identify the file in other Visual FoxPro low-level file functions. FCreateEx( ) returns the file handle number when a file is created, or returns –1 if the file cannot be created.

Example

Create a read-only INI file in the current directory, if it doesn't already exist:

Copy code
LOCAL cIniFile, nFileHandle
cIniFile = [./MyFile.ini]
IF NOT FILE(cIniFile)  && Does file exist? 
	nFileHandle= FCreateEx(cIniFile)  && If not create it in a read-only mode
	IF nFileHandle< 0     && Check for error opening file
	   WAIT "Cannot open or create INI file" WINDOW NOWAIT
	ELSE  && If no error, write to file
	   FWriteEx(nFileHandle, "[Program Information]"+CHR(13)+"DataDir="+ADDBS(GETENV("APPDATA"))+"MyApp\")
	ENDIF
	FCloseEx(nFileHandle)     && Close file
ENDIF
MODIFY FILE (cIniFile) NOWAIT  && Open file in edit window

See Also

Reference

AFHandlesEx
FChSizeEx
FCloseEx
FEoFEx
FFlushEx
FGetsEx
FLockFile
FLockFileEx
FOpenEx
FPutsEx
FReadEx
FSeekEx
FUnlockFile
FUnlockFileEx
FWriteEx

Used WinApi functions

CreateFile