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:Value Description FILE_ATTRIBUTE_READONLY The file is read only. Applications can read the file, but cannot write to or delete it. FILE_ATTRIBUTE_HIDDEN The file is hidden. Do not include it in an ordinary directory listing. FILE_ATTRIBUTE_SYSTEM The file is part of or used exclusively by an operating system. FILE_ATTRIBUTE_ARCHIVE The file should be archived. Applications use this attribute to mark files for backup or removal. FILE_ATTRIBUTE_NORMAL The file does not have other attributes set. This attribute is valid only if used alone. FILE_ATTRIBUTE_TEMPORARY The file is being used for temporary storage. FILE_ATTRIBUTE_OFFLINE The 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_ENCRYPTED The 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:
Value Description FILE_FLAG_BACKUP_SEMANTICS The 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_CLOSE The 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_BUFFERING The 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_RECALL The 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_SEMANTICS Access 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_ACCESS Access 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_SCAN Access 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_THROUGH Write 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. Sharemode Description 0 Prevents 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_WRITE Enables 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_DELETE Enables 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:
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