File Management

FileCopy

Purpose:

Copy an external file.

Category:

Files

Syntax:

FileCopy "source file" "destination"

source file

The name of an existing external file on the reader’s computer.

destination

The drive and folder on the reader’s computer where the copied file is to be saved. You may optionally include a file name as part of the destination to save the copied file under a different name.

Example:

FileCopy "[PubDir]test.doc" "c:\my documents"


FileErase

Purpose:

Erase an external file.

Category:

Files

Syntax:

FileErase "file name"

file name

The name of an existing external file.

Example:

FileErase "c:\sample files\mydata.bak"


FileExists

Purpose:

Determine if an external or embedded file exists.

Category:

Files

Syntax:

FileExists "file name" "variable"

file name

The name of the file (including drive and path) to check.

variable

The name of the variable to store the result of the search. If the file exists, the variable will be set to “True”, otherwise, it will be set to “False”.

Example:

The example below displays an alert box if the file mydata.dat exists:


FileExists "c:\sample files\mydata.dat" "[Result]"
If "[Result]" "=" "True"
  AlertBox "Status" "The file was found!"
EndIf


FileSize

Purpose:

Get the size (in bytes) of an external or embedded file.

Category:

Files

Syntax:

FileSize "file name" "variable"

file name

The name of the file (including drive and path) to check.

variable

The name of the variable to store the file's size. If the file does not exist, the variable will be cleared and an error message displayed.

Example:

The example below displays an alert box containing the size of the file sample.txt:


FileSize "[PubDir]sample.txt" "[Size]"
AlertBox "Result" "The file's size is [Size]"


FolderExists

Purpose:

Determine if an external folder exists.

Category:

Files

Syntax:

FolderExists "path" "variable"

path

The name of the folder to check.

variable

The name of the variable to store the result of the search. If the folder exists, the variable will be set to “True”, otherwise, it will be set to “False”.

Example:

FolderExists "C:\Program Files" "[Result]"


CreateFolder

Purpose:

Create a new folder.

Category:

Files

Syntax:

CreateFolder "folder  name"

folder name

The path and name of the new folder.

Example:

CreateFolder "C:\MyFolder"


RemoveFolder

Purpose:

Remove an existing empty folder from the computer’s hard drive.

Category:

Files

Syntax:

RemoveFolder "folder name"

folder name

The name of the folder to remove.

Example:

RemoveFolder "c:\myfolder"


ExtractFile

Purpose:

Extract a file from your compiled publication.

Category:

Files

Syntax:

ExtractFile "source file" "destination"

source file

The name of the source file to be extracted. This file will be stored inside your compiled publication.

destination

The drive and folder on the reader’s computer where the extracted file is to be saved. You may optionally include a file name to save the extracted file under a different name.

Example:

ExtractFile "c:\samples\template.doc" "c:\my documents"


FileList

Purpose:

Generate a list of files and/or folders found in the specified path.

Category:

Files

Syntax:

FileList "file mask" "options" "variable"

file mask

The path and file name mask to search. The mask can include wildcard characters. For example, "C:\Sample\*.*" will list all files in the C:\Sample folder.

options

Can include any combination of the following:


Files

Include files in the list.

Folders

Include folders in the list

NoExt

Remove extensions from file names before adding them to the list.

variable

The name of the variable to store the list. Multiple files will be separated by carriage returns.

Example:

The following example compiles a list of all JPEG images in the "C:\My Photos" folder and stores them in a variable called [Pics]:


FileList "C:\My Photos\*.jpg" "Files+NoExt" "[Pics]"



File I/O

FileRead

Purpose:

Read data from an external text file.

Category:

Files

Syntax:

FileRead "file name" "line number" "variable"

file name

The name of an existing external file.

line number

The number of the line in the file to read. The first line in the file is 1, the second is 2 and so on. You can specify “All” here instead of a line number to read the entire file at once.

variable

The name of the variable to store the data.

Example:

The following example uses FileRead to build a menu from the contents of a file called “Parts.dat”. The file is read one line at a time and the contents added to [MenuChoices] to build the menu. Finally, the menu is displayed using the MenuEx Action command.


SetVar "[MenuChoices]" ""
FileLen "parts.dat" "[MaxLine]"
Loop "1" "[MaxLine]" "[Count]"
  FileRead "parts.dat" "[Count]" "[MenuItem]"
  If "[MenuChoices]" ">" ""
    SetVar "[MenuChoices]" "[MenuChoices]|"
  EndIf
  SetVar "[MenuChoices]" "[MenuChoices][MenuItem]"
EndLoop
MenuEx "-1" "-1" "[MenuChoices]" "[Result]"


Another way of doing the same thing would be to use “All” in place of a line number, which instructs FileRead will load the entire file at once:


FileRead "parts.dat" "All" "[MenuChoices]"
MenuEx "-1" "-1" "[MenuChoices]" "[Result]"


FileWrite 

Purpose:

Write data to an external text file.

Category:

Files

Syntax:

FileWrite "file name" "line number" "data"

file name

The name of an existing external file. You can insert the name of a communications port (COM1, COM2, etc.) here instead of a file name to send data to an external device instead.

line number

The number of the line in the file to write to. The first line in the file is 1, the second is 2 and so on. You can specify “Append” here instead of a line number to add the data to the end of the file. Use “All” here to replace the entire file at once.

data

The data to be written to the file.

Example:

The example below replaces the first line of the parts.dat file:


FileWrite "parts.dat" "1" "Calvin Klein Blazer"


By default, FileWrite will convert any pipe characters "|" contained within the text into carriage returns/line breaks. To prevent this, add an exclamation point character "!" to the beginning of the data parameter. For example:


FileWrite "filename" "All" "![Data]"


FileInsLine

Purpose:

Insert a blank line into an external text file. The external file must be in plain text/ASCII format.

Category:

Files

Syntax:

FileInsLine "file name" "line number"

file name

The name of an existing external file.

line number

The number of the line in the file where the new line should be inserted. All lines from this point forward will be moved down to make room. The first line in the file is 1, the second is 2 and so on.

Example:

The following example inserts a new first line in the file parts.dat:


FileInsLine "parts.dat" "1"


FileDelLine

Purpose:

Delete a specific line from an external text file. The external file must be in plain text/ASCII format.

Category:

Files

Syntax:

FileDelLine "file name" "line number"

file name

The name of an existing external file.

line number

The number of the line in the file to delete. The first line in the file is 1, the second is 2 and so on.

Example:

In the following example, readers are asked if they want to delete an item which is stored on a line in the parts.dat file. Their response is stored in a variable named “[Ans]”. If the response is Yes (1), the line is removed from the file.


MessageBox "Delete" "Delete #[Item]?" "Yes|No" "[Ans]"
If "[Ans]" "=" "1"
  FileDelLine "parts.dat" "[Item]"
EndIf


FileLen

Purpose:

Count the number of lines contained in an external text file.

Category:

Files

Syntax:

FileLen "file name" "variable"

file name

The name of an existing external file.

variable

The name of a variable to store the line count.

Example:

The example below calculates the size of the parts.dat file and stores the number of lines in the [Lines] variable:


FileLen "parts.dat" "[Lines]"


FileToVar

Purpose:

Read the contents of a file into a variable. This is similar to using FileRead with the “All” option, but unlike FileRead, FileToVar can be used with Embedded files.

Category:

Files

Syntax:

FileToVar "file name" "variable"

file name

The name of an existing external or embedded file.

variable

The name of the variable to store the contents of the file.

Example:

FileToVar "[Embedded]dealers.txt" "[TextEntry1]"


File Name Utiltities

ExtractFilePath

Purpose:

Extract the drive and folder portion of a file name.

Category:

Files

Syntax:

ExtractFilePath "file name" "variable"

file name

The name of a file.

variable

The name of the variable to store the file’s path. If the file doesn’t have a path, the variable will be empty.

Example:

This example places “c:\samples” in the [Path] variable:


ExtractFilePath "c:\samples\test.doc" "[Path]"


ExtractFileName

Purpose:

Extract the name and extension portion of a file name and store the result in a variable.

Category:

Files

Syntax:

ExtractFileName "file name" "variable"

file name

The name of a file.

variable

The name of the variable to store the file’s name.

Example:

This example places “test.doc” in the [Name] variable:


ExtractFileName "c:\samples\test.doc" "[Name]"


ExtractFileExt

Purpose:

Extract the extension portion of a file name. See also ChangeFileExt.

Category:

Files

Syntax:

ExtractFileExt "file name" "variable"

file name

The name of a file.

variable

The name of the variable to store the file’s extension.

Example:

This example places “.doc” in the [Ext] variable:


ExtractFileExt "c:\samples\test.doc" "[Ext]"


ExtractFileDrive

Purpose:

Extract the drive portion of a file name and store the result in a variable.

Category:

Files

Syntax:

ExtractFileDrive "file name" "variable"

file name

A complete file name including drive and path.

variable

The name of the variable to store the drive information.

Example:

This example places “c:” in the [Drive] variable:


ExtractFileDrive "c:\samples\test.doc" "[Drive]"


ChangeFileExt

Purpose:

Change a file name's extension and store the result in a variable.

Category:

Files

Syntax:

ChangeFileExt "file name" "extension" "variable"

file name

A file name

extension

The new file extension including a period. For example: “.txt”

variable

The name of the variable to store the modified file name.

Example:

ChangeFileExt "sample.dat" ".txt" "[FileName]"



Registry Utilities

RegistryRead

Purpose:

Read a value from the Windows System Registry database. The Registry contains information about the hardware and software installed on the computer.

Category:

Files

Syntax:

RegistryRead "key" "section" "variable"

key

The Registry key that contains the data you want to read. The Registry database is divided into the following key groups:


HKEY_CURRENT_USER

HKEY_CLASSES_ROOT

HKEY_LOCAL_MACHINE

HKEY_USERS

HKEY_CURRENT_CONFIG

HKEY_DYN_DAT


Most software applications store their information in the HKEY_CURRENT_USER key.

section

The Registry section that contains the actual value to read.

variable

The name of the variable to store the retrieved data.

Example:

RegistryRead "HKEY_CURRENT_USER" "Software\MyPub\UserName" "[User]"


RegistryWrite

Purpose:

Write a value to the Windows System Registry database. The Registry contains information about the hardware and software installed on the computer.


WARNING: Exercise caution when modifying the Registry. If there is an error in the Registry, your computer (or your reader’s computer) may become nonfunctional.

Category:

Files

Syntax:

RegistryWrite "key" "section" "value"

key

The Registry key that contains the section you want to modify. See RegistryRead for a list of available keys.

section

The Registry section to modify.

value

The data to write to the Registry.

Example:

RegistryWrite "HKEY_CURRENT_USER" "Software\MyPub\UserName" "Joe"