ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / WLanguage functions / Standard functions / External file functions
  • Handling errors
  • Operating mode in Windows Vista (and later)
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
Creates an external file. This file is automatically opened in read/write.
Remarks:
WINDEVWEBDEV - Server codeReports and QueriesJavaUser code (UMC)PHPAjax
// Create the external file
ResCreation = fCreate("C:\MyDirectories\File.txt")
IF ResCreation <> -1 THEN 
	...
END
WINDEVWEBDEV - Server codeReports and QueriesJavaUser code (UMC)Ajax
// Create the external file
MyFile is DiskFile
ResOpen = fCreate("C:\MyDirectories\File.txt")
IF NOT ErrorOccurred THEN
	...
END
WINDEVWEBDEV - Server codeReports and QueriesJavaUser code (UMC)Ajax
// Create the external file
ResOpen is boolean
MyExternalFile is DiskFile
ResOpen = fCreate(MyExternalFile, "C:\MyDirectories\File.txt")
IF NOT ErrorOccurred THEN
	...
END
Syntax

Creating an external file Hide the details

<Result> = fCreate(<File path> [, <Creation options>])
<Result>: Integer
  • an integer:
    • the identifier of the external file. This identifier will be used by all the functions for handling the external files.
    • -1 if an error occurred. To get more details on the error, use ErrorInfo with the errMessage constant.
  • a variable of type DiskFile. If an error occurs, the ErrorOccurred variable is set to True. To get more details on the error, use ErrorInfo with the errMessage constant.
    PHP Not available.
<File path>: Character string
Name and full (or relative) path of file (up to 260 characters). The extension of the file can be specified. By default, if the file extension is not specified, the external file will have no extension. A UNC path can be used.
Remark: If the external file already exists (same directory and same name), this file is destroyed and re-created. To avoid deleting an existing file, use fOpen associated with the foCreateIfNotExist constant.
AndroidAndroid Widget This parameter can correspond to a full path or a path relative to the current directory (returned by fCurrentDir). This parameter is case-sensitive.
Reminder: In Android, an application has the rights to write into its installation directory or into one of its subdirectories, as well as onto the external memory (SDCard).
iPhone/iPadIOS WidgetMac Catalyst This parameter can correspond to a full path or a path relative to the current directory (returned by fCurrentDir). This parameter is case-sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its installation directory or into one of its subdirectories.
<Creation options>: Combination of optional constants
Options for file creation:
  • Lock options: A lock can be implemented when the external file is opened:
    foAutomaticDeletionThe file is locked when opened, and will be automatically deleted when closed (when fClose is called, or when the application is closed).
    If multiple applications are using the file, it will be automatically deleted when the last application closes it (when fClose is called, or at the end of the application).
    foReadLockThe file will be created in read-only. The other applications that use this file will not be able to read it.
    foWriteLockThe file will be created in write-only. The other applications that use this file will not be able to modify it.

    AndroidAndroid Widget iPhone/iPadIOS WidgetMac CatalystJavaPHP The lock options are not available. The external file can be freely accessed by the other applications.
  • Type of external file to create. This type is used by fReadLine and fWriteLine to define the type of information to read and write in the external file:
    foAnsiAnsi file. This constant is used to manage an Ansi file when the "Use Unicode strings at runtime" mode is enabled in the project configuration.
    This mode is used by default in the WINDEV and WEBDEV projects.
    foUnicodeUnicode file. This constant is used to manage a Unicode file when the "Use Ansi strings at runtime" mode is enabled in the project configuration.
    This mode is used by default in WINDEV Mobile projects.

    iPhone/iPadIOS WidgetMac CatalystPHP The type of the file to be created is not available. The type of the file corresponds to the default mode.

By default, if no constant is specified:
  • the external file can be freely accessed by the other applications,
  • the type of the file corresponds to the default mode.
PHP Not available in PHP

Creating an external file and associating it with a DiskFile variable Hide the details

<Result> = fCreate(<DiskFile> , <File path> [, <Creation options>])
<Result>: Boolean
  • if the file was opened and associated with variable of type DiskFile,
  • False otherwise. To get more details on the error, use ErrorInfo with the errMessage constant.
<DiskFile>: DiskFile variable
Name of the DiskFile variable to be associated with the manipulated text file.
<File path>: Character string
Name and full or relative path of the file (up to 260 characters). The extension of the file can be specified. By default, if the file extension is not specified, the external file will have no extension. A UNC path can be used.
Remark: If the external file already exists (same directory and same name), this file is destroyed and re-created. To avoid deleting an existing file, use fOpen associated with the foCreateIfNotExist constant.
AndroidAndroid Widget This parameter can correspond to a full path or a path relative to the current directory (returned by fCurrentDir). This parameter is case-sensitive.
Reminder: In Android, an application has the rights to write into its installation directory or into one of its subdirectories, as well as onto the external memory (SDCard).
iPhone/iPadIOS WidgetMac Catalyst This parameter can correspond to a full path or a path relative to the current directory (returned by fCurrentDir). This parameter is case-sensitive.
Reminder: On iPhone/iPad, an application has the rights to write into its installation directory or into one of its subdirectories.
<Creation options>: Combination of optional constants
Options for file creation:
  • Lock options: A lock can be implemented when the external file is opened:
    foAutomaticDeletionThe file is locked when opened, and will be automatically deleted when closed (when fClose is called, or when the application is closed).
    If multiple applications are using the file, it will be automatically deleted when the last application closes it (when fClose is called, or at the end of the application).
    foReadLockThe file will be created in read-only. The other applications that use this file will not be able to read it.
    foWriteLockThe file will be created in write-only. The other applications that use this file will not be able to modify it.

    AndroidAndroid Widget iPhone/iPadIOS WidgetMac CatalystJavaPHP The lock options are not available. The external file can be freely accessed by the other applications.
  • Type of external file to create. This type is used by fReadLine and fWriteLine to define the type of information to read and write in the external file:
    foAnsiAnsi file. This constant is used to manage an Ansi file when the "Use Unicode strings at runtime" mode is enabled in the project configuration.
    This mode is used by default in the WINDEV and WEBDEV projects.
    foUnicodeUnicode file. This constant is used to manage a Unicode file when the "Use Ansi strings at runtime" mode is enabled in the project configuration.
    This mode is used by default in WINDEV Mobile projects.

    iPhone/iPadIOS WidgetMac CatalystPHP The type of the file to be created is not available. The type of the file corresponds to the default mode.

By default, if no constant is specified:
  • the external file can be freely accessed by the other applications,
  • the type of the file corresponds to the default mode.
Remarks

Handling errors

fCreate throws an error in the following cases:
  • the file is locked by another computer or by another application,
  • the user has no write rights in the creation directory.
  • a Unicode string was used for <File path> in an operating system such as Windows 98 or Windows Me.
WINDEVWEBDEV - Server codeReports and QueriesUser code (UMC)

Operating mode in Windows Vista (and later)

If this function does not operate properly in Windows Vista (and later), check whether the file or directory used is not in one of the system directories (Windows directory or "Program Files" directory).
In Windows Vista (and later), with the UAC mechanism (User Account Control) enabled, you must have administrator privileges to handle and/or modify the files or directories in system directories (Windows directory or "Program Files" directory).
Programming tip: To handle and/or modify the files or directories without administrator privileges, you should:
  • avoid writing to the Windows directory or to the "Program Files" directory,
  • use the system directory of the application (returned by SysDir with the srAppDataCommun constant, for example).
Remark: In Windows Vista (and later), the virtualization mechanism is used to make the applications compatible with Vista. If the file is created in a system directory without having sufficient rights, this file will actually be created in another directory (C:\Users\<LOGIN>AppData\Local\VirtualStore\Windows\). In this case, the file cannot be shared between several applications.
Related Examples:
Handling text files Unit examples (WINDEV): Handling text files
[ + ] Handling "text" files with WINDEV:
- Create a text file
- Write into a text file
- Read in a text file
Handling text files Unit examples (WEBDEV): Handling text files
[ + ] This example explains how to handle "non HFSQL" files with WEBDEV and it allows you to:
- Create a text file
- Write into a text file
- Read in a text file
Handling text files Unit examples (WINDEV Mobile): Handling text files
[ + ] Handling external "text" files:
- Create a text file
- Write into a text file
- Read in a text file
Business / UI classification: Business Logic
Component: wd300std.dll
Minimum version required
  • Version 9
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 04/18/2024

Send a report | Local help