FileAccess ActiveX Reference Documentation

FileAccess

API for reading and writing files, creating and deleting directories, deleting directory trees, splitting and re-joining large files, etc. This is a freeware class. The reason for its existence is that in some programming languages, file I/O API's are limited or difficult to understand/use. This API provides an identical FILE I/O API across all programming languages supported by Chilkat.

Object Creation

(Visual Basic 6.0)
Dim obj As New CkFileAccess

(ASP)
set obj = Server.CreateObject("Chilkat_9_5_0.FileAccess")

(VBScript)
set obj = CreateObject("Chilkat_9_5_0.FileAccess")

(Delphi)
obj := TCkFileAccess.Create(Self);

(FoxPro)
loObject = CreateObject('Chilkat_9_5_0.FileAccess')

(PowerBuilder)
lole_object = create oleobject
li_rc = lole_object.ConnectToNewObject("Chilkat_9_5_0.FileAccess")

(SQL Server)
EXEC @hr = sp_OACreate 'Chilkat_9_5_0.FileAccess', @obj OUT

(Javascript)
var obj = new ActiveXObject("Chilkat_9_5_0.FileAccess");

Properties

CurrentDir As String (read-only)

The current working directory of the calling process.

DebugLogFilePath As String

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

EndOfFile As Long (read-only)

Returns 1 if the current open file is at the end-of-file.

FileOpenError As Long (read-only)

This property is set by the following methods: FileOpen, OpenForRead, OpenForWrite, OpenForReadWrite, and OpenForAppend. It provides an error code indicating the failure reason. Possible values are:

  1. Success (No error)
  2. Access denied.
  3. File not found.
  4. General (non-specific) open error.
  5. File aleady exists.
  6. Path refers to a directory and the access requested involves writing.
  7. Too many symbolic links were encountered in resolving path.
  8. The process already has the maximum number of files open.
  9. Pathname is too long.
  10. The system limit on the total number of open files has been reached.
  11. Pathname refers to a device special file and no corresponding device exists.
  12. Insufficient kernel memory was available.
  13. Pathname was to be created but the device containing pathname has no room for the new file.
  14. A component used as a directory in pathname is not, in fact, a directory.
  15. Pathname refers to a regular file, too large to be opened (this would be a limitation of the underlying operating system, not a limitation imposed by Chilkat).
  16. Pathname refers to a file on a read-only filesystem and write access was requested.

FileOpenErrorMsg As String (read-only)

The error message text associated with the FileOpenError code.

LastBinaryResult As Variant (read-only)

Introduced in version 9.5.0.52

The binary data returned by the last (binary data returning) method called. Only available if Chilkat.Global.KeepBinaryResult is set to 1. This provides a means for obtaining large varbinary results in the SQL Server environment (where limitations exist in getting large amounts of data returned by method calls, but where temp tables can be used for binary properties).

LastErrorHtml As String (read-only)

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

LastErrorText As String (read-only)

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

Concept of LastErrorText

LastErrorText Standard Information

LastErrorXml As String (read-only)

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

LastMethodSuccess As Long

Introduced in version 9.5.0.52

Indicate whether the last method call succeeded or failed. A value of 1 indicates success, a value of 0 indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = 1 and failure = 0.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to 1. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

LastStringResult As String (read-only)

Introduced in version 9.5.0.52

The string return value of the last (string returning) method called. Only available if Chilkat.Global.KeepStringResult is set to 1. This provides a means for obtaining large string results in the SQL Server environment (where limitations exist in getting long strings returned by method calls, but where temp tables can be used for string properties).

Long Strings Returned by ActiveX Methods in SQL Server

LastStringResultLen As Long (read-only)

Introduced in version 9.5.0.53

The length, in characters, of the string contained in the LastStringResult property.

VerboseLogging As Long

If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

Version As String (read-only)

Version of the component/library, such as "9.5.0.63"

Methods

AppendAnsi(text As String) As Long

Appends a string using the ANSI character encoding to the currently open file.

Returns 1 for success, 0 for failure.

AppendText(str As String, charset As String) As Long

Appends a string using the character encoding specified by str to the currently open file.

Returns 1 for success, 0 for failure.

AppendUnicodeBOM() As Long

Appends the 2-byte Unicode BOM (little endian) to the currently open file.

Returns 1 for success, 0 for failure.

AppendUtf8BOM() As Long

Appends the 3-byte utf-8 BOM to the currently open file.

Returns 1 for success, 0 for failure.

DirAutoCreate(filePath As String) As Long

Same as DirEnsureExists, except the argument is a file path (the last part of the path is a filename and not a directory). Creates all missing directories such that filePath may be created.

Returns 1 for success, 0 for failure.

DirCreate(dirPath As String) As Long

Creates a new directory specified by dirPath.

Returns 1 for success, 0 for failure.

DirDelete(dirPath As String) As Long

Deletes the directory specified by dirPath.

Returns 1 for success, 0 for failure.

DirEnsureExists(dirPath As String) As Long

Creates all directories necessary such that the entire dirPath exists.

Returns 1 for success, 0 for failure.

FileClose()

Closes the currently open file.

FileContentsEqual(filePath1 As String, filePath2 As String) As Long

Compares the contents of two files and returns 1 if they are equal and otherwise returns 0. The actual contents of the files are only compared if the sizes are equal. The files are not entirely loaded into memory. Instead, they are compared chunk by chunk. This allows for any size files to be compared, regardless of the memory capacity of the computer.

FileCopy(existingFilepath As String, newFilepath As String, ByVal failIfExists As Long) As Long

Copys existingFilepath to newFilepath. If failIfExists is 1 and newFilepath already exists, then an error is returned.

Returns 1 for success, 0 for failure.

FileDelete(filePath As String) As Long

Deletes the file specified by filePath.

Returns 1 for success, 0 for failure.

FileExists(filePath As String) As Long

Returns 1 if filePath exists, otherwise returns 0.

FileExists3(path As String) As Long

Introduced in version 9.5.0.45

Returns 1 if the file exists, 0 if the file does not exist, and -1 if unable to check because of directory permissions or some other error that prevents the ability to obtain the information.

FileOpen(filePath As String, ByVal accessMode As Long, ByVal shareMode As Long, ByVal createDisposition As Long, ByVal attributes As Long) As Long

This method should only be called on Windows operating systems. It's arguments are similar to the Windows Platform SDK function named CreateFile. For Linux, MAC OS X, and other operating system, use the OpenForRead, OpenForWrite, OpenForReadWrite, and OpenForAppend methods.

Opens a file for reading or writing. The arguments mirror the Windows CreateFile function:

Access Modes:
GENERIC_READ	(0x80000000)
GENERIC_WRITE (0x40000000)

Share Modes:
FILE_SHARE_READ(0x00000001)
FILE_SHARE_WRITE(0x00000002)

Create Dispositions
CREATE_NEW          1
CREATE_ALWAYS       2
OPEN_EXISTING       3
OPEN_ALWAYS         4
TRUNCATE_EXISTING   5

// Attributes:
FILE_ATTRIBUTE_READONLY         0x00000001
FILE_ATTRIBUTE_HIDDEN           0x00000002
FILE_ATTRIBUTE_SYSTEM           0x00000004
FILE_ATTRIBUTE_DIRECTORY        0x00000010
FILE_ATTRIBUTE_ARCHIVE          0x00000020
FILE_ATTRIBUTE_NORMAL           0x00000080
FILE_ATTRIBUTE_TEMPORARY	   0x00000100

Returns 1 for success, 0 for failure.

FileRead(ByVal maxNumBytes As Long) As Variant

Reads bytes from the currently open file. maxNumBytes specifies the maximum number of bytes to read. Returns an empty byte array on error.

Returns a zero-length byte array (as a Variant) on failure.
An empty array will have a UBound of -1 meaning 0 elements.

FileReadBd(ByVal maxNumBytes As Long, binData As ChilkatBinData) As Long

Introduced in version 9.5.0.64

Reads bytes from the currently open file. maxNumBytes specifies the maximum number of bytes to read. Appends the bytes to the binData.

Returns 1 for success, 0 for failure.

(Classic ASP) Determine File Type from Binary Content of File

(Visual FoxPro) Determine File Type from Binary Content of File

(PowerBuilder) Determine File Type from Binary Content of File

(SQL Server) Determine File Type from Binary Content of File

(Visual Basic 6.0) Determine File Type from Binary Content of File

(VBScript) Determine File Type from Binary Content of File

FileRename(existingFilepath As String, newFilepath As String) As Long

Renames a file from existingFilepath to newFilepath.

Returns 1 for success, 0 for failure.

FileSeek(ByVal offset As Long, ByVal origin As Long) As Long

Sets the file pointer for the currently open file. The offset is an offset in bytes from the origin. The origin can be one of the following:

0 = Offset is from beginning of file.
1 = Offset is from current position of file pointer.
2 = Offset is from the end-of-file (offset may be negative).

Returns 1 for success, 0 for failure.

FileSize(filePath As String) As Long

Returns the size, in bytes, of a file. Returns -1 for failure.

Returns 1 for success, 0 for failure.

FileWrite(data As Variant) As Long

Writes bytes to the currently open file.

Returns 1 for success, 0 for failure.

FileWriteBd(binData As ChilkatBinData, ByVal offset As Long, ByVal numBytes As Long) As Long

Introduced in version 9.5.0.64

Writes the contents of binData to the currently open file. To specify the entire contents of binData, set both offset and numBytes equal to 0. To write all remaining data starting at offset, then set numBytes equal to 0.

Returns 1 for success, 0 for failure.

(Classic ASP) Unzip Binary File to Stream

(Visual FoxPro) Unzip Binary File to Stream

(PowerBuilder) Unzip Binary File to Stream

(SQL Server) Unzip Binary File to Stream

(Visual Basic 6.0) Unzip Binary File to Stream

(VBScript) Unzip Binary File to Stream

GenBlockId(ByVal index As Long, ByVal length As Long, encoding As String) As String

Introduced in version 9.5.0.58

This is purely a utility/convenience method -- initially created to help with block file uploads to Azure Blob storage. It generates a block ID string that is the decimal representation of the index in length chars, and then encoded according to encoding (which can be an encoding such as "base64", "hex", "ascii", etc.) For example, if index = 8, length = 12, and encoding = "base64", then the string "00000012" is returned base64 encoded.

Returns Nothing on failure

GetDirectoryName(path As String) As String

Introduced in version 9.5.0.64

Returns the directory information for the specified path string.

GetDirectoryName('C:\MyDir\MySubDir\myfile.ext') returns 'C:\MyDir\MySubDir\'
GetDirectoryName('C:\MyDir\MySubDir') returns 'C:\MyDir\'
GetDirectoryName('C:\MyDir\') returns 'C:\MyDir\'
GetDirectoryName('C:\MyDir') returns 'C:\'
GetDirectoryName('C:\') returns 'C:\'

Returns Nothing on failure

(Classic ASP) Demonstrate Directory Path Functions

(Visual FoxPro) Demonstrate Directory Path Functions

(PowerBuilder) Demonstrate Directory Path Functions

(SQL Server) Demonstrate Directory Path Functions

(Visual Basic 6.0) Demonstrate Directory Path Functions

(VBScript) Demonstrate Directory Path Functions

GetExtension(path As String) As String

Introduced in version 9.5.0.64

Returns the extension of the specified path string.

GetExtension('C:\mydir.old\myfile.ext') returns '.ext'
GetExtension('C:\mydir.old\') returns ''

Returns Nothing on failure

(Classic ASP) Demonstrate Directory Path Functions

(Visual FoxPro) Demonstrate Directory Path Functions

(PowerBuilder) Demonstrate Directory Path Functions

(SQL Server) Demonstrate Directory Path Functions

(Visual Basic 6.0) Demonstrate Directory Path Functions

(VBScript) Demonstrate Directory Path Functions

GetFileName(path As String) As String

Introduced in version 9.5.0.64

Returns the file name and extension of the specified path string.

GetFileName('C:\mydir\myfile.ext') returns 'myfile.ext'
GetFileName('C:\mydir\') returns ''

Returns Nothing on failure

(Classic ASP) Demonstrate Directory Path Functions

(Visual FoxPro) Demonstrate Directory Path Functions

(PowerBuilder) Demonstrate Directory Path Functions

(SQL Server) Demonstrate Directory Path Functions

(Visual Basic 6.0) Demonstrate Directory Path Functions

(VBScript) Demonstrate Directory Path Functions

GetFileNameWithoutExtension(path As String) As String

Introduced in version 9.5.0.64

Returns the file name of the specified path string without the extension.

GetFileNameWithoutExtension('C:\mydir\myfile.ext') returns 'myfile'
GetFileNameWithoutExtension('C:\mydir\') returns ''

Returns Nothing on failure

(Classic ASP) Demonstrate Directory Path Functions

(Visual FoxPro) Demonstrate Directory Path Functions

(PowerBuilder) Demonstrate Directory Path Functions

(SQL Server) Demonstrate Directory Path Functions

(Visual Basic 6.0) Demonstrate Directory Path Functions

(VBScript) Demonstrate Directory Path Functions

GetFileTime(path As String, ByVal which As Long) As CkDateTime

Introduced in version 9.5.0.71

Gets one of the following date/times for a file:

0: Last-modified
1: Last-access
2: Creation
The "path" argument indicates which time to return. The values can be 0, 1, or 2.

Note: Linux filesystems do not keep a file's creation date/time. In such a case, this method will return the last-modified time.

Returns Nothing on failure

GetLastModified(path As String) As CkDateTime

Introduced in version 9.5.0.66

Gets the last-modified date/time for a file.

Returns Nothing on failure

GetNumBlocks(ByVal blockSize As Long) As Long

Introduced in version 9.5.0.58

Returns the number of blocks in the currently open file. The number of bytes per block is specified by blockSize. The number of blocks is the file size divided by the blockSize, plus 1 if the file size is not evenly divisible by blockSize. For example, if the currently open file is 60500 bytes, and if the blockSize is 1000 bytes, then this method returns a count of 61 blocks.

Returns -1 if no file is open. Return 0 if the file is completely empty (0 bytes).

(Classic ASP) File Read Blocks

(Visual FoxPro) File Read Blocks

(PowerBuilder) File Read Blocks

(SQL Server) File Read Blocks

(Visual Basic 6.0) File Read Blocks

(VBScript) File Read Blocks

GetTempFilename(dirPath As String, prefix As String) As String

Creates a temporary filepath of the form dirPath\prefix_xxxx.TMP Where "xxxx" are random alpha-numeric chars. The returned filepath is guaranteed to not already exist.

Returns Nothing on failure

OpenForAppend(filePath As String) As Long

Opens a file for appending. If filePath did not already exists, it is created. When an existing file is opened with this method, the contents will not be overwritten and the file pointer is positioned at the end of the file.

If the open/create failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns 1 for success, 0 for failure.

OpenForRead(filePath As String) As Long

Opens a file for reading. The file may contain any type of data (binary or text) and it must already exist. If the open failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns 1 for success, 0 for failure.

OpenForReadWrite(filePath As String) As Long

Opens a file for reading/writing. If filePath did not already exists, it is created. When an existing file is opened with this method, the contents will not be overwritten, but the file pointer is positioned at the beginning of the file.

If the open/create failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns 1 for success, 0 for failure.

OpenForWrite(filePath As String) As Long

Opens a file for writing. If filePath did not already exists, it is created. When an existing file is opened with this method, the contents will be overwritten. (For example, calling OpenForWrite on an existing file and then immediately closing the file will result in an empty file.) If the open/create failed, then error information will be available in the FileOpenError and FileOpenErrorMsg properties.

Returns 1 for success, 0 for failure.

ReadBinaryToEncoded(filePath As String, encoding As String) As String

Reads the entire contents of a binary file and returns it as an encoded string (using an encoding such as Base64, Hex, etc.) The encoding may be one of the following strings: base64, hex, qp, or url.

Returns Nothing on failure

(Classic ASP) Base64 Encode a File

(Visual FoxPro) Base64 Encode a File

(PowerBuilder) Base64 Encode a File

(SQL Server) Base64 Encode a File

(Visual Basic 6.0) Base64 Encode a File

(VBScript) Base64 Encode a File

ReadBlock(ByVal blockIndex As Long, ByVal blockSize As Long) As Variant

Introduced in version 9.5.0.58

Reads the Nth block of a file, where the size of each block is specified by blockSize. The first block is at blockIndex 0. If the block to be read is the last in the file and there is not enough data to fill an entire block, then the partial block is returned.

Returns a zero-length byte array (as a Variant) on failure.
An empty array will have a UBound of -1 meaning 0 elements.

(Classic ASP) File Read Blocks

(Visual FoxPro) File Read Blocks

(PowerBuilder) File Read Blocks

(SQL Server) File Read Blocks

(Visual Basic 6.0) File Read Blocks

(VBScript) File Read Blocks

ReadEntireFile(filePath As String) As Variant

Reads the entire contents of a binary file and returns the data.

Returns a zero-length byte array (as a Variant) on failure.
An empty array will have a UBound of -1 meaning 0 elements.

ReadEntireTextFile(filePath As String, charset As String) As String

Reads the entire contents of a text file, interprets the bytes according to the character encoding specified by charset, and returns the text file as a string.

Returns Nothing on failure

ReassembleFile(partsDirPath As String, partPrefix As String, partExtension As String, reassembledFilename As String) As Long

Reassembles a file previously split by the SplitFile method.

Returns 1 for success, 0 for failure.

(Classic ASP) Example: Reassemble a Previously Split File

(Visual FoxPro) Example: Reassemble a Previously Split File

(PowerBuilder) Example: Reassemble a Previously Split File

(SQL Server) Example: Reassemble a Previously Split File

(Visual Basic 6.0) Example: Reassemble a Previously Split File

(VBScript) Example: Reassemble a Previously Split File

ReplaceStrings(filePath As String, charset As String, existingString As String, replacementString As String) As Long

Replaces all occurrences of existingString with replacementString in a file. The character encoding, such as utf-8, ansi, etc. is specified by charset.

SetCurrentDir(dirPath As String) As Long

Sets the current working directory for the calling process to dirPath.

Returns 1 for success, 0 for failure.

SetFileTimes(filePath As String, createTime As CkDateTime, lastAccessTime As CkDateTime, lastModTime As CkDateTime) As Long

Sets the create date/time, the last-access date/time, and the last-modified date/time for a file. For non-Windows filesystems where create times are not implemented, the createTime is ignored.

SetLastModified(filePath As String, lastModified As CkDateTime) As Long

Sets the last-modified date/time for a file.

SplitFile(fileToSplit As String, partPrefix As String, partExtension As String, ByVal partSize As Long, destDir As String) As Long

Splits a file into chunks. Please refer to the example below:

Returns 1 for success, 0 for failure.

(Classic ASP) Example: Split File into Chunks

(Visual FoxPro) Example: Split File into Chunks

(PowerBuilder) Example: Split File into Chunks

(SQL Server) Example: Split File into Chunks

(Visual Basic 6.0) Example: Split File into Chunks

(VBScript) Example: Split File into Chunks

TreeDelete(path As String) As Long

Deletes an entire directory tree (all files and sub-directories).

Returns 1 for success, 0 for failure.

WriteEntireFile(filePath As String, fileData As Variant) As Long

Opens/creates filePath, writes fileData, and closes the file.

Returns 1 for success, 0 for failure.

WriteEntireTextFile(filePath As String, textData As String, charset As String, ByVal includedPreamble As Long) As Long

Opens filePath, writes textData using the character encoding specified by charset, and closes the file. If includedPreamble is 1 and the charset is Unicode or utf-8, then the BOM is included at the beginning of the file.

Returns 1 for success, 0 for failure.

(Classic ASP) Base64 Encode a File

(Visual FoxPro) Base64 Encode a File

(PowerBuilder) Base64 Encode a File

(SQL Server) Base64 Encode a File

(Visual Basic 6.0) Base64 Encode a File

(VBScript) Base64 Encode a File