Advanced File Processing

Purpose:

Copy or upload a list of files to a connection. Files will be copied to the connection's current directory. The fmCopyTo action can be used if you want to initiate a file copy or upload programmatically without interaction from the user. (See fmCopyFrom to download files from a remote connection.)

Category:

Syntax:

fmCopyTo "connection id" "files" "options"

connection id

The name assigned to the connection you want to copy the files to. The connection must have already been opened with fmConnectLocal or fmConnectRemote.

files

A list of local file names to be copied or uploaded. Separate multiple file names with a semicolon (;). Each file name must point to a local file and include a fully qualified path.

options

This is a compound parameter and can contain any combination of the following items:

GetConfirmation=yes/no

Yes = display a confirmation dialog before overwriting any existing files. No = do not display a confirmation dialog.

Note: The confirmation dialog provides users with the opportunity to OK or cancel file operations that would overwrite existing files. The confirmation dialog can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the copy process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmCopyTo "Local1" "C:\Test\Sales.doc;C:\Test\Inventory.doc" "GetConfirmation=Yes;ShowProgress=Yes"

Purpose:

Move a list of files to a connection. Files will be moved to the connection's current directory. The fmMoveTo action can be used if you want to initiate a file move programmatically without interaction from the user.

IMPORTANT: Moving of files is not supported for remote/FTP connections. If the destination is a remote connection, fmMoveTo will copy the files instead.

Category:

Advanced File Processing

Syntax:

fmMoveTo "connection id" "files" "options"

connection id

The name assigned to the connection you want to move the files to. The connection must have already been opened with fmConnectLocal.

files

A list of local file names to be moved. Separate multiple file names with a semicolon (;). Each file name must point to a local file and include a fully qualified path.

options

This is a compound parameter and can contain any combination of the following items:

GetConfirmation=yes/no

Yes = display a confirmation dialog before overwriting any existing files. No = do not display a confirmation dialog.

Note: The confirmation dialog provides users with the opportunity to OK or cancel file operations that would overwrite existing files. The confirmation dialog can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the move process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmMoveTo "Local1" "C:\Test\Sales.doc;C:\Test\Inventory.doc" "GetConfirmation=Yes;ShowProgress=Yes"

Purpose:

Copy or download a list of files from a connection to a local folder. The fmCopyfrom action can be used if you want to initiate a file copy or download programmatically without interaction from the user. (See fmCopyTo to upload files to a remote connection.)

Category:

Advanced File Processing

Syntax:

fmCopyFrom "connection id" "files" "dest path" "options"

connection id

The name assigned to the connection containing the files you want to copy or download. The connection must have already been opened with fmConnectLocal or fmConnectRemote.

files

A list of file names to be copied or uploaded. Separate multiple file names with a semicolon (;). Each file name must include a fully qualified path.

dest path

The local path where the files will be copied.

options

This is a compound parameter and can contain any combination of the following items:

GetConfirmation=yes/no

Yes = display a confirmation dialog before overwriting any existing files. No = do not display a confirmation dialog.

Note: The confirmation dialog provides users with the opportunity to OK or cancel file operations that would overwrite existing files. The confirmation dialog can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the copy process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

AllowResume=yes/no

Yes = Allow resume for FTP downloads. If a confirmation dialog is displayed, it will contain a check box allowing users the option of enabling or disabling the Resume feature. No = Do not allow resume to be used.

Note: Resume can be useful when a download is interrupted before completion. Resume allows you to continue a download from where it left off rather than starting over. Resume can only be used with binary transfer mode and must be supported by the FTP server. This option only affects files copied from an FTP server to a local drive.

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmCopyFrom "Remote1" "/webspace/httpdocs/index.html;/webspace/httpdocs/logo.jpg" "C:\Downloads" "GetConfirmation=No;ShowProgress=Yes"

Purpose:

Move a list of files from a connection to a local folder. The fmMoveFrom action can be used if you want to initiate a file move programmatically without interaction from the user.

IMPORTANT: Moving of files is not supported for remote/FTP connections. If the destination is a remote connection, fmMoveFrom will copy the files instead.

Category:

Advanced File Processing

Syntax:

fmMoveFrom "connection id" "files" "dest path" "options"

connection id

The name assigned to the connection containing the files you want to move. The connection must have already been opened with fmConnectLocal.

files

A list of file names to be moved. Separate multiple file names with a semicolon (;). Each file name must include a fully qualified path.

dest path

The local path where the files will be moved.

options

This is a compound parameter and can contain any combination of the following items:

GetConfirmation=yes/no

Yes = display a confirmation dialog before overwriting any existing files. No = do not display a confirmation dialog.

Note: The confirmation dialog provides users with the opportunity to OK or cancel file operations that would overwrite existing files. The confirmation dialog can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the move process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmMoveFrom "Local1" "C:\Test\Sales.doc;C:\Test\Inventory.doc" "C:\Backup" "GetConfirmation=Yes;ShowProgress=Yes"

Purpose:

Copy a list of embedded files from inside a compiled publication to a connection. The files to be extracted must be included in your publication's Embedded Files list.

Category:

Advanced File Processing

Syntax:

fmCopyEmbedded "connection id" "files" "options"

connection id

The name assigned to the connection you want to extract the file to. The connection's current directory will be the destination for the extracted files. The connection must have already been opened with fmConnectLocal or fmConnectRemote.

files

A list of embedded files to be extracted. Separate multiple file names with a semicolon (;). Each file name must included in your publication's Embedded Files list. It is not necessary to include the "[Embedded]" prefix as part of the file name. For example, either of the following are acceptable:

[Embedded]filename.xyz

filename.xyz

options

This is a compound parameter and can contain any combination of the following items:

GetConfirmation=yes/no

Yes = display a confirmation dialog before overwriting any existing files. No = do not display a confirmation dialog.

Note: The confirmation dialog provides users with the opportunity to OK or cancel file operations that would overwrite existing files. The confirmation dialog can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the copy process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmCopyEmbedded "Remote1" "[Embedded]index.html;[Embedded]products.html;[Embedded]sitemap.html;[Embedded]logo.gif;[Embedded]header.jpg;[Embedded]footer.gif" "GetConfirmation=Yes;ShowProgress=Yes"

Purpose:

Permanently delete a list of files from a connection. The fmDelete action can be used if you want to delete files programmatically without interaction from the user.

Note: The fmDeleteFrom action cannot be undone, so use it with caution. If you need a more forgiving way to remove files and folders, use the fmRecycle action instead.

Category:

Advanced File Processing

Syntax:

fmDelete "connection id" "files" "options"

connection id

The name assigned to the connection containing the files or folders you want to delete. The connection must have already been opened with fmConnectLocal or fmConnectRemote.

files

A list of file names to be deleted. Separate multiple file names with a semicolon (;). Each file name must include a fully qualified path.

options

This is a compound parameter and can contain any combination of the following items:

GetConfirmation=yes/no

Yes = display a confirmation dialog before deleting anything. No = do not display a confirmation dialog.

Note: The confirmation dialog provides users with the opportunity to OK or cancel the delete. The confirmation dialog can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the delete process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmDelete "Local1" "C:\Test\Sales.bak;C:\Test\Inventory.bak" "ShowProgress=Yes"

Purpose:

Move a list of files from a connection to the Windows recycle bin. The fmRecycle action can be used if you want to recycle files programmatically without interaction from the user.

Note: Recycling of files is not supported for remote/FTP connections.

Category:

Advanced File Processing

Syntax:

fmRecycle "connection id" "files" "options"

connection id

The name assigned to the connection containing the files or folders you want to recycle. The connection must have already been opened with fmConnectLocal.

files

A list of file names to be recycled. Separate multiple file names with a semicolon (;). Each file name must include a fully qualified path.

options

This is a compound parameter and can contain any combination of the following items:

GetConfirmation=yes/no

Yes = display a confirmation dialog before recycling anything. No = do not display a confirmation dialog.

Note: The confirmation dialog provides users with the opportunity to OK or cancel the recycle. The confirmation dialog can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the recycle process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmRecycle "Local1" "C:\Test\Sales.bak;C:\Test\Inventory.bak" "ShowProgress=Yes"

Purpose:

Rename a list of files or folders in a connection. The fmRename action can be used if you want to rename files programmatically without interaction from the user.

Category:

Advanced File Processing

Syntax:

fmRename "connection id" "files" "new name mask" "options"

connection id

The name assigned to the connection containing the items you want to rename. The connection must have already been opened with fmConnectLocal or fmConnectRemote.

files

A list of file names to be renamed. Separate multiple file names with a semicolon (;). Each file name must include a fully qualified path.

new name mask

A mask that defines what the items' new names will look like. You can use wildcards (* and ?) as part of the name. The characters represented by the wildcards will be identical to the corresponding characters in the item's original name. For example, the following will change the extensions of all files in the list to .txt while leaving the base file names intact:

"*.txt"

options

This is a compound parameter and can contain any combination of the following items:

ShowProgress=yes/no

Yes = Display the progress window. No = do not display the progress window.

Note: The progress window provides feedback to the user about the status of the renaming process. It also provides the user with an option to abort the procedure before completion. The progress window can be customized using the fmTranslateStrings action, or replaced entirely with something of your own design (see Special Subroutines).

Separate multiple items in a compound parameter with semicolons (;).

Example:

fmRename "FileList1" "C:\Test\Photo1.jpeg;C:\Test\Photo2.jpeg;C:\Test\Photo3.jpeg" "*.jpg" "ShowProgress=Yes"

Purpose:	Determine if a specific file exists on a local or remote connection.
Category:	Advanced File Processing
Syntax:	fmFileExists "connection id" "file" "variable" connection id The name assigned to the connection. The connection must have already been opened with fmConnectLocal or fmConnectRemote. file The name (including path) of the file or folder to check. Only one file name may be specified at a time. 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:	fmFileExists "Remote1" "/webspace/httpdocs/index.html" "[Result]" If "[Result]" "=" "True" AlertBox "Status" "The file was found!" Else AlertBox "Status" "The file was NOT found!" EndIf

Purpose:

Get the size, type, date, time, attributes or permissions for a specific file or folder. (To obtain information about multiple items at the same time use fmGetSelectedInfo.)

Category:

Advanced File Processing

Syntax:

fmGetItemInfo "connection id" "file" "info type" "info format" "variable"

connection id

The name assigned to the connection. The connection must have already been opened with fmConnectLocal or fmConnectRemote.

file

The name (including path) of the file or folder. Only one file name may be specified at a time.

info type

The type of information you want to retrieve. Use one of the following types:

Size	The item's size. Note: This action cannot be used to calculate the size of folders. When used with folders it will return a size of zero.
Type	The item's type. This is a descriptive string obtained from Windows. The exact description can vary depending on the Windows version and configuration.
Date	The date the item was last modified.
Time	The time the item was last modified.
Attributes	For local file system connections this will be the item's Windows/DOS attributes (A=Archive, R=Read-Only, H=Hidden, S=System). For remote/FTP file systems, this will be the item's numeric permissions (CHMOD number).

info format

The formatting to be used for the retrieved information. The format depends on the info type parameter above. Valid formats for each info type are:

info type

format

Size

One of the following:

Plain

The size will be returned as an integer value with no formatting. This option is best if you want to use the size in a mathematical calculation.

Formatted

The size will be formatted to include a thousands separator (if necessary) and reduced to the nearest gigabyte, megabyte, kilobyte or byte. For example:

2.78 MB

1.5 KB

108 Bytes

Type

Not used.

Date

Use the codes from the following table to compose the date format:

d	Show the day as a number without a leading zero (1-31).
dd	Show the day as a number with a leading zero (01-31).
ddd	Display the day as an abbreviation (Sun-Sat).
dddd	Display the day as a full name (Sunday-Saturday).
ddddd	Display the date using the system short date format as defined in the Windows Control Panel.
dddddd	Display the date using the system long date format as defined in the Windows Control Panel.
m	Show the month as a number without a leading zero (1-12).
mm	Show the month as a number with a leading zero (01-12).
mmm	Display the month as an abbreviation (Jan-Dec).
mmmm	Display the month as a full name (January-December).
yy	Show the year as a two-digit number (00-99).
yyyy	Show the year as a four-digit number (0000-9999).
/	Display the date separator character as defined in the Windows Control Panel.
Default	Use the system’s default short date format. (Same as ddddd above.)

For example, "m/d/yyyy" will result in a date formatted as Month/Day/Year or "1/15/2011". Entering "dddd, mmmm d, yyyy" will result in a date formatted as "Saturday, January 15, 2011".

Time

Use the codes from the following table to compose the time format:

h	Display the hour without a leading zero (0-23).
hh	Display the hour with a leading zero (00-23).
n	Display the minute without a leading zero (0-59).
nn	Display the minute with a leading zero (00-59).
s	Display the second without a leading zero (0-59).
ss	Display the second with a leading zero (00-59).
t	Display the time using the short (without seconds) system time format as defined in the Windows Control Panel.
tt	Display the time using the long (with seconds) system time format as defined in the Windows Control Panel.
ampm	When used with the "h" or "hh" codes, this option will display the time in 12-hour format followed by the "AM" or "PM" symbols as defined in the Windows Control Panel.
:	Display the time separator character as defined in the Windows Control Panel.
Default	Use the system’s default short time format. (Same as "t" above.)

For example, "h:nn ampm" will result in a time that looks like "5:30 pm".

Attributes

Not used.

variable

The name of the variable where the retrieved information will be stored.

Example:

fmGetItemInfo "FileList1" "C:\Test\Photo1.jpg" "Size" "Formatted" "[Info1]"

fmGetItemInfo "FileList1" "C:\Test\Photo1.jpg" "Type" "" "[Info2]"

fmGetItemInfo "FileList1" "C:\Test\Photo1.jpg" "Date" "m/d/yyyy" "[Info3]"

fmGetItemInfo "FileList1" "C:\Test\Photo1.jpg" "Time" "h:nn ampm" "[Info4]"

fmGetItemInfo "FileList1" "C:\Test\Photo1.jpg" "Attributes" "" "[Info5]"

AlertBox "" "Size: [Info1]|Type: [Info2]|Date: [Info3]|Time: [Info4]|Attributes: [Info5]"

Purpose:

Set the date, time, attributes or permissions for a specific file or folder. (To modify multiple items at the same time use fmSetSelectedInfo.)

Category:

Advanced File Processing

Syntax:

fmSetItemInfo "connection id" "file" "info type" "date format" "new value"

connection id

The name assigned to the connection. The connection must have already been opened with fmConnectLocal or fmConnectRemote.

file

The name (including path) of the file or folder. Only one file name may be specified at a time.

info type

The type of information you want to set. Use one of the following types:

DateTime

Set the item's date and/or time stamp.

Note: Many FTP servers do not support setting of the file date or time.

Attributes

Set the item's attributes or permissions. The types of attributes that can be modified are different depending the type of connection. For local connections the available attributes are Archive (A), Read-Only (R), System (S) and Hidden (H). For FTP connections, the attributes correspond to the standard file permissions used by the Unix CHMOD command.

date format

The formatting to be used when setting the item's date stamp. This is the format of the date passed in the value parameter. The date format may be one of the following:

m/d/y	Month/Day/Year
d/m/y	Day/Month/Year
y/m/d	Year/Month/Day
Default	Use the system’s default short date format.

This parameter is ignored when setting attributes or permissions.

new value

The new date/time or attributes/permissions to be applied to the item. The value depends of the info type selected above.

info type

value

DateTime

The date and/or time to apply to the file.

The date must match that specified by the date format parameter. Year values between 0 and 99 are assumed to be in the current century. For example:

"1/15/11"

is the same as

"1/15/2011"

The date may be omitted to leave the file's existing date unchanged.

The time can be specified in either 12 or 24 hour format. For example:

"3:45pm"

or

"15:45"

The time may be omitted to leave the file's existing time unchanged.

If both a data and time are specified then the date must be first followed by the time. For example:

"1/15/2011 3:45pm"

Attributes

The new attributes or permissions to apply to the file.

For local connections, you can use any combination of the following Windows/DOS file attributes:

A	Sets the Archive file attribute.
R	Sets the Read-Only file attribute.
S	Sets the System file attribute.
H	Sets the Hidden file attribute.

For example, to set the selected files to archive and read-only use the following:

"AR"

For remote/FTP connections, you can use either numeric or string permissions (CHMOD). For example, the permissions for a common HTML file on a Unix server could be set like this:

"644"

or

"-rw-r--r--"

NeoFM/FTP provides two helpful actions called fmCHMODNumToPermStr and fmPermStrToCHMODNum to convert between these two permission formats.

Example:

fmSetItemInfo "FileList1" "C:\Test\Photo1.jpg" "DateTime" "m/d/yy" "1/15/2011 3:45pm"

Purpose:	Retrieve a thumbnail image for a specific file or folder and save the image to a file in PNG or BMP format. Thumbnails are generated by Windows and are not provided for all types of files. When thumbnails are not available, Windows usually substitutes the file's associated extra large icon. Thumbnails and extra large icons are only available for local files in Windows XP and higher. For older versions of Windows, or when viewing remote FTP sites, large icons will be substituted.
Category:	Advanced File Processing
Syntax:	fmGetItemThumbnail "connection id" "source file" "width" "height" "output file" connection id The name assigned to the connection containing the selected files or folders. The connection must have already been opened with fmConnectLocal or fmConnectRemote. source file The name (including path) of a local file or folder. Only one file name may be specified at a time. width The desired maximum width for the thumbnail image. height The desired maximum height for the thumbnail image. Note: The actual dimensions of the generated thumbnail image may be smaller than the width and height specified. The image will be scaled if the original is larger than the requested width and height. However, the image's original aspect ratio will be maintained. output file The name and location of the external file where the thumbnail file will be saved. The thumbnail can be saved in BMP or PNG format. To save the thumbnail in PNG format the output file must end with ".png". Using any other file extension will result in the thumbnail being saved in BMP format. If the output file already exists, it will be overwritten.
Example:	The following example generates and displays a thumbnail image for the currently selected file or folder. (The first line insures that only one item is selected): If "[FileList1.SelCount]" "=" "1" fmFileListToVar "FileList1" "FullPath=Yes;IncludeFiles=Yes; IncludeFolders=Yes;SelectedOnly=Yes" "[FName]" fmGetItemThumbnail "FileList1" "[FName]" "96" "96" "[PubDir]thumb.bmp" If "[FMFTP.Error]" "=" "" ImageWindow "Thumbnail" "-1" "-1" "[PubDir]Thumb.bmp" EndIf Else AlertBox "Error" "Make sure only one item is selected." EndIf

Purpose:	Display the standard Windows properties dialog for a local file or folder. Note: This action cannot be used for files or folders located on a remote/FTP connection.
Category:	Advanced File Processing
Syntax:	fmShowFilePropertiesDlg "file" file The name (including path) of a local file or folder. Only one file name may be specified at a time.
Example:	The following example displays the properties dialog for the currently selected file or folder. (The first line insures that only one item is selected): If "[FileList1.SelCount]" "=" "1" fmFileListToVar "FileList1" "FullPath=Yes;IncludeFiles=Yes; IncludeFolders=Yes;SelectedOnly=Yes" "[FName]" fmShowFilePropertiesDlg "[FName]" Else AlertBox "Error" "Make sure only one item is selected." EndIf