MappFileOperation

See also

User Guide:

Preparing computers for Distributed MIL Working with files

Reference:

MfuncAlloc

Availability

Available in MIL-Lite

Available in MIL

Available on Windows with restrictions

Available on Linux with restrictions

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

Function Map

Table:

For specifying the application context on Computer 1

- Comp1FileName

Table:

For specifying the file on Computer 1 or the file name search pattern to find files on Computer 1

Parameter Associations

Table:	For specifying the file operation
Table:	For specifying to perform a file search
+ combination:	For getting the string size

Compilation information

Synopsis

Perform a file operation or file search on a local or a remote computer.

Syntax

void MappFileOperation(

MIL_ID Comp1ContextAppId,	//in
MIL_CONST_TEXT_PTR Comp1FileName,	//in
MIL_ID Comp2ContextAppId,	//in
MIL_CONST_TEXT_PTR Comp2FileName,	//in
MIL_INT64 Operation,	//in
MIL_INT64 OperationFlag,	//in
void *OperationDataPtr	//out

)

Description

This function can copy or move a file from one computer to another, including your local computer as either source or destination. This function can also remotely delete a file, create or delete a directory, search a directory for files with a specific file name (wildcards are supported), or execute a program on another computer. When executing a program, you can choose to wait for the remotely-run program to finish before proceeding with the local program, or start the remote program and immediately continue with the local program.

This function is typically used to perform operations on remote computers, but also works on the local computer.

When using this function to manipulate files (for example, moving, copying, or executing them), you must set the Comp1FileName parameter (and optionally the Comp2FileName parameter) to a file name or full file path. If you specify only a file name or partial file path (without drive letter), the working directory of the application is assumed as the location of the file (or as the prefix of the partial file path).

When using this function to search for files (M_FILE_NAME_FIND and M_FILE_NAME_FIND_COUNT), you must specify a file name search pattern. The search might find more than one matching file. You must specify which file name to return by setting the OperationFlag parameter to the file's index in the search results. You can retrieve the total number of search results using M_FILE_NAME_FIND_COUNT.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

Comp1ContextAppId

Specifies the identifier of the application context to use. The computer on which this application context has been allocated is referred to as either computer 1, or the source computer.

For specifying the application context on Computer 1
Value	Description
M_DEFAULT	Specifies the current (local) application context.
Application Context Identifier	Specifies the application context identifier. Typically specifying an application context identifier is used to specify a remote application on a remote computer. However, it can be used for a remote application on the local computer, or the current application. When you explicitly specify the current application, it is equivalent to specifying M_DEFAULT. (summarize) Specifies the application context identifier. (more details...)

Comp1FileName

Specifies the file on the target or source computer to use for the file operation, or the file name search pattern to use.

For specifying the file on Computer 1 or the file name search pattern to find files on Computer 1
Value	Description
MIL_TEXT("FileName") ¹	Specifies the file name, and optionally the full file path drive and directory, of the file on the target or source computer to use for the operation. If you specify only the file name, MIL assumes that the file is in the working directory of the application. If the file is elsewhere on the computer, a path is required. For example, "myFile" or "C:\myDirectory\myFile". To specify a file on a remote computer (under Distributed MIL), prefix the specified file name string with "remote:///" (for example, "remote:///C:\myDirectory\myFile"). Optionally, the file name and/or path can be followed by executable arguments (command-line parameters) for the M_FILE_EXECUTE and M_FILE_DISPATCH operations. For example, "C:\myDirectory\myProgram -c -r". (summarize) Specifies the file name, and optionally the full file path drive and directory, of the file on the target or source computer to use for the operation. (more details...)
MIL_TEXT("FileNameSearchPattern") ¹	Specifies the file name search pattern to use. This must include the path to the root folder of the search, and can also include the asterisk () and question mark (?) wildcard characters. An asterisk () matches 0 or more characters, while a question mark (?) matches exactly 1 character. For example, the search string "C:\DirectoryToSearch\Year_188?\Night.bmp" specifies to search only the immediate subdirectories of C:\DirectoryToSearch\ that have the name Year188 plus exactly one additional character. Examples of files that would be found with this string include: C:\DirectoryToSearch\Year_1889\The_Starry_Night.bmp. C:\DirectoryToSearch\Year_1888\Starry_Night_Over_the_Rhone.bmp. C:\DirectoryToSearch\Year_188W\Night.bmp. The string must not end in a backslash (\). To find all file names in a directory, follow the path with an asterisk () (for example, "C:\DirectoryToSearch\"). The file name search pattern is always local to computer 1. (summarize) Specifies the file name search pattern to use. (more details...)

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

Comp2ContextAppId

Specifies the identifier of the application context that determines where to copy or move the file specified using Comp1FileName, during a M_FILE_COPY, M_FILE_COPY_MIL_DLL, M_FILE_COPY_MIL_USER_DLL, or M_FILE_MOVE operation. The computer on which this application context has been allocated is referred to as either computer 2, or the destination computer.

Note that computer 2 can be the same as computer 1. In other words, the source and destination of the copied file can be different paths on the same computer.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Comp2FileName

Specifies the directory (and optionally a new file name) on computer 2 to which to copy the file specified using Comp1FileName. If this parameter is set to a file name and not a full path, the file is copied or moved to the working directory of the destination application.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Operation

Specifies the operation to perform on the specified file, or the type of information to return from the search.

See the Parameter associations section for possible values that can be specified.

OperationFlag

Specifies additional settings for the operation or search. Set this parameter to M_DEFAULT if not used.

OperationDataPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_TEXT_CHAR [optionally, in C++: a reference to a MIL_STRING]
M_NULL
MIL_INT

Specifies the address of the user data that is used by some operations. Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be returned.

Parameter associations

The tables below list possible values for the Comp2ContextAppId, Comp2FileName, and Operation parameters and possible values returned to the OperationDataPtr parameter.

For specifying the file operation
For specifying to perform a file search

The following Operation and corresponding Comp2ContextAppId and Comp2FileName parameter settings can be specified to perform a file operation. For these settings, you must set Comp1FileName to an explicit file name, partial path, or full path.

Set unused parameters to M_NULL, except for OperationFlag which must be set to M_DEFAULT.

For specifying the file operation
Operation			Description
	Comp2ContextAppId
	Comp2FileName
	OperationDataPtr - Possible values returned
M_FILE_COPY			Specifies to copy the file from the source computer to the destination computer. (summarize) Specifies to copy the file from the source computer to the destination computer. (more details...)
	Comp2ContextAppId		Specifies the application context that determines where to copy the file specified using Comp1FileName. The computer that will receive the copied file is referred to as the destination computer. (summarize) Specifies the application context that determines where to copy the file specified using Comp1FileName. (more details...)
		M_DEFAULT	Specifies the current (local) application context.
		Application Context Identifier	Specifies the application context identifier.
	Comp2FileName		Specifies the directory, and optionally a new file name, in the destination computer in which to copy the file specified using Comp1FileName. (summarize) Specifies the directory, and optionally a new file name, in the destination computer in which to copy the file specified using Comp1FileName. (more details...)
		MIL_TEXT("Drive\Path\[FileName]") ¹	Specifies the drive, directory, and optionally the new file name, in the destination computer in which the file specified using Comp1FileName will be copied. For example, "C:\myDirectory\" or "C:\myDirectory\myNewFileName". To specify a file on a remote computer (under Distributed MIL), prefix the specified file name string with "remote:///" (for example, "remote:///C:\myDirectory\myFile"). If no destination file name is specified, the source file name is used. (summarize) Specifies the drive, directory, and optionally the new file name, in the destination computer in which the file specified using Comp1FileName will be copied. (more details...)
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_COPY_MIL_DLL			Specifies to attempt to copy a file from the source computer to the runtime library subfolder of the MIL installation folder on the destination computer; the specified MIL application might not have write-access to this folder (in which case the operation fails). This is primarily useful for copying a compiled library that contains custom MIL functions, created using the Function Development module (Mfunc...()). You can check whether the file already exists in this folder using M_FILE_EXISTS_MIL_DLL. (summarize) Specifies to attempt to copy a file from the source computer to the runtime library subfolder of the MIL installation folder on the destination computer; the specified MIL application might not have write-access to this folder (in which case the operation fails). (more details...)
				Operating system specific
				[This is only applicable to Windows] This is the DLL subfolder of your MIL installation folder (for example, C:\Program Files\Matrox Imaging\MIL\DLL). This folder might not be write-accessible if the destination MIL application, specified by the Comp2ContextAppId parameter, was launched without administrative privileges. To copy the DLL to a folder that does not require administrative privileges (but where it can still be loaded by the MIL application), use M_FILE_COPY_MIL_USER_DLL instead.
				[This is only applicable to Linux] This is the lib subfolder of your MIL installation folder (for example, /opt/matrox_imaging/mil/lib). This folder might not be write-accessible if the destination MIL application, specified by the Comp2ContextAppId parameter, was launched by a user who is not part of the mil permissions group. Before accessing the copied DSO, you must update the runtime library bindings using ldconfig.
	Comp2ContextAppId		Specifies the application context that determines where to copy the file specified using Comp1FileName. The computer that will receive the copied file is referred to as the destination computer. (summarize) Specifies the application context that determines where to copy the file specified using Comp1FileName. (more details...)
		M_DEFAULT	Specifies the current (local) application context.
		Application Context Identifier	Specifies the application context identifier.
	Comp2FileName		Specifies to rename the DLL copied to Computer 2. The drive and path are determined based on the location of the MIL DLLs on Computer 2. To keep the file name specified in Comp1FileName, set this parameter to M_NULL. (summarize) Specifies to rename the DLL copied to Computer 2. (more details...)
		MIL_TEXT("FileName") ¹	Specifies a new file name for the copied DLL.
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_COPY_MIL_USER_DLL			Specifies to copy a file from the source computer to the user runtime library folder on the destination computer; the specified MIL application typically has write-access to this folder (under Windows). This is primarily useful for copying a compiled library that contains custom MIL functions, created using the Function Development module (Mfunc...()). You can check whether the file already exists in this folder using M_FILE_EXISTS_MIL_USER_DLL. (summarize) Specifies to copy a file from the source computer to the user runtime library folder on the destination computer; the specified MIL application typically has write-access to this folder (under Windows). (more details...)
				Operating system specific
				[This is only applicable to Windows] The path to this folder is C:\Users\Public\Documents\Matrox Imaging\Mil\UserDLL.
				[This is only applicable to Linux] This setting is the same as M_FILE_COPY_MIL_DLL. The folder is not guaranteed to be write-accessible. Before accessing the copied DSO, you must update the runtime library bindings using ldconfig.
	Comp2ContextAppId		Specifies the application context that determines where to copy the file specified using Comp1FileName. The computer that will receive the copied file is referred to as the destination computer. (summarize) Specifies the application context that determines where to copy the file specified using Comp1FileName. (more details...)
		M_DEFAULT	Specifies the current (local) application context.
		Application Context Identifier	Specifies the application context identifier.
	Comp2FileName		Specifies to rename the DLL copied to Computer 2. The drive and path are determined based on the location of the MIL DLLs on Computer 2. To keep the file name specified in Comp1FileName, set this parameter to M_NULL. (summarize) Specifies to rename the DLL copied to Computer 2. (more details...)
		MIL_TEXT("FileName") ¹	Specifies a new file name for the copied DLL.
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_DELETE			Specifies to delete the specified file on Computer 1. (summarize) Specifies to delete the specified file on Computer 1. (more details...)
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_DELETE_DIR			Specifies to delete a directory on Computer 1. The directory must already be empty, unless OperationFlag is set to M_RECURSIVE. (summarize) Specifies to delete a directory on Computer 1. (more details...)
	OperationFlag		Specifies one of the following. (summarize) Specifies one of the following. (more details...)
		M_DEFAULT	Specifies the default behavior. The directory is only deleted if it is empty. (summarize) Specifies the default behavior. (more details...)
		M_RECURSIVE	Specifies to delete the directory and its contents.
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_DISPATCH			Specifies to execute the specified program on Computer 1 without waiting for the specified program to terminate on the source computer. When set to M_FILE_DISPATCH, Computer 1 cannot return an exit code. Note that when set to M_FILE_DISPATCH, the Comp1FileName parameter can include executable arguments (command-line parameters). The capability to execute programs on a remote computer has security implications. You are responsible for ensuring that the program executed by the remote DMIL application is in fact the program that you requested. MappFileOperation() cannot execute a program on a remote computer unless that computer is running a connected DMIL application. (summarize) Specifies to execute the specified program on Computer 1 without waiting for the specified program to terminate on the source computer. (more details...)
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_EXECUTE			Specifies to execute the specified program on Computer 1. The computer initiating the operation will wait for the program to terminate. Optionally, you can retrieve the exit code of the program using OperationDataPtr. Note that when set to M_FILE_EXECUTE, the Comp1FileName parameter can include executable arguments (command-line parameters). The capability to execute programs on a remote computer has security implications. You are responsible for ensuring that the program executed by the remote DMIL application is in fact the program that you requested. MappFileOperation() cannot execute a program on a remote computer unless that computer is running a connected DMIL application. (summarize) Specifies to execute the specified program on Computer 1. (more details...)
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_EXISTS			Specifies to determine whether the file specified by Comp1FileName exists on computer 1. (summarize) Specifies to determine whether the file specified by Comp1FileName exists on computer 1. (more details...)
	OperationDataPtr		Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Returns one of the following. (summarize) Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Returns one of the following. (more details...)
		M_NO	Specifies that the file does not exist.
		M_YES	Specifies that the file does exist.
M_FILE_EXISTS_MIL_DLL			Specifies to determine whether the file specified by Comp1FileName exists in the runtime library subfolder of the MIL installation folder on computer 1; the specified MIL application might not have write-access to this folder. (summarize) Specifies to determine whether the file specified by Comp1FileName exists in the runtime library subfolder of the MIL installation folder on computer 1; the specified MIL application might not have write-access to this folder. (more details...)
				Operating system specific
				[This is only applicable to Windows] This is the DLL subfolder of your MIL installation folder (for example, C:\Program Files\Matrox Imaging\MIL\DLL).
				[This is only applicable to Linux] This is the lib subfolder of your MIL installation folder (for example, /opt/matrox_imaging/mil/lib).
	OperationDataPtr		Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Returns one of the following. (summarize) Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Returns one of the following. (more details...)
		M_NO	Specifies that the file does not exist.
		M_YES	Specifies that the file does exist.
M_FILE_EXISTS_MIL_USER_DLL			Specifies to determine whether the file specified by Comp1FileName exists in the user runtime library folder on computer 1; the specified MIL application typically has write-access to this folder (under Windows). (summarize) Specifies to determine whether the file specified by Comp1FileName exists in the user runtime library folder on computer 1; the specified MIL application typically has write-access to this folder (under Windows). (more details...)
				Operating system specific
				[This is only applicable to Windows] The path to this folder is C:\Users\Public\Documents\Matrox Imaging\Mil\UserDLL.
				[This is only applicable to Linux] This is the same as M_FILE_EXISTS_MIL_DLL.
	OperationDataPtr		Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Returns one of the following. (summarize) Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Returns one of the following. (more details...)
		M_NO	Specifies that the file does not exist.
		M_YES	Specifies that the file does exist.
M_FILE_MAKE_DIR			Specifies to create a directory on Computer 1. (summarize) Specifies to create a directory on Computer 1. (more details...)
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL
M_FILE_MOVE			Specifies to move the file from the source computer to the destination computer. The file is only deleted from the source computer after it is successfully copied to the destination computer. (summarize) Specifies to move the file from the source computer to the destination computer. (more details...)
	Comp2ContextAppId		Specifies the application context that determines where to move the file specified using Comp1FileName. The computer that will receive the moved file is referred to as the destination computer. (summarize) Specifies the application context that determines where to move the file specified using Comp1FileName. (more details...)
		M_DEFAULT	Specifies the current (local) application context.
		Application Context Identifier	Specifies the application context identifier.
	Comp2FileName		Specifies the directory, and optionally a new file name, on the destination computer in which to move the file specified using Comp1FileName. (summarize) Specifies the directory, and optionally a new file name, on the destination computer in which to move the file specified using Comp1FileName. (more details...)
		MIL_TEXT("Drive\Path\[FileName]") ¹	Specifies the drive, directory, and optionally the new file name, on the destination computer in which the file specified using Comp1FileName will be moved. For example, "C:\myDirectory\" or "C:\myDirectory\myNewFileName". To specify a file on a remote computer (under Distributed MIL), prefix the specified file name string with "remote:///" (for example, "remote:///C:\myDirectory\myFile"). If no destination file name is specified, the source file name is used. (summarize) Specifies the drive, directory, and optionally the new file name, on the destination computer in which the file specified using Comp1FileName will be moved. (more details...)
	OperationDataPtr		Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL Data type info: Data type: Set this parameter to M_NULL Data type: Set this parameter to M_NULL

¹ If you are passing the value in a variable, don't enclose it in MIL_TEXT().

The following Operation parameter settings can be specified to perform a file search. For these settings, you must set Comp1FileName to a file name search pattern.

Set unused parameters to M_NULL, except for OperationFlag which must be set to M_DEFAULT.

For specifying to perform a file search
Operation			Description
	Comp2ContextAppId
	Comp2FileName
	OperationDataPtr - Possible values returned
M_FILE_NAME_FIND +			Specifies to determine the name of a file found with the search pattern specified by the Comp1FileName parameter. Since the search might find more than one file, you must specify which file name to return by setting the OperationFlag parameter to the file's index in the search results. You can determine the total number of files that match the search pattern using M_FILE_NAME_FIND_COUNT. The search is not recursive, and does not include the names of folders that match the search pattern. Only the file name is output, and not the full path. MIL does not cache the results of a search. If a file is added or deleted between calls to MappFileOperation(), the indexing of the search results might change. Therefore, if you want to iterate through the files found by a search and delete some of them, you should first iteratively call MappFileOperation() with M_FILE_NAME_FIND to store all of the search results in an array (or other data structure), and then delete the files by iterating through the stored results. (summarize) Specifies to determine the name of a file found with the search pattern specified by the Comp1FileName parameter. (more details...)
	OperationFlag		Specifies the following. (summarize) Specifies the following. (more details...)
		0 < Value < M_FILE_NAME_FIND_COUNT	Specifies which file name to return, by index in the search results.
	OperationDataPtr		Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] Required array size: MappFileOperation ( M_FILE_NAME_FIND + M_STRING_SIZE ) Note: When using C++, you can pass a reference to a MIL_STRING instead. In this case, the function will automatically determine the correct string size. Data type info: Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] MORE Data type: array of type MIL_TEXT_CHAR [optionally, in C++: MIL_STRING ] Required array size: MappFileOperation ( M_FILE_NAME_FIND + M_STRING_SIZE ) Note: When using C++, you can pass a reference to a MIL_STRING instead. In this case, the function will automatically determine the correct string size.
M_FILE_NAME_FIND_COUNT			Specifies to determine the number of files found with the search pattern specified by the Comp1FileName parameter. The search is not recursive, and does not include the names of folders that match the search pattern. (summarize) Specifies to determine the number of files found with the search pattern specified by the Comp1FileName parameter. (more details...)
	OperationDataPtr		Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT

Combination value for M_FILE_NAME_FIND.

You can add the following value to the above-mentioned value to get the string's length.

For getting the string size
Operation		Description
	Comp2ContextAppId
	Comp2FileName
	OperationDataPtr - Possible values returned
M_STRING_SIZE		Retrieves the length of the string, including the terminating null character ("\0"). (summarize) Retrieves the length of the string, including the terminating null character ("\0"). (more details...)
	OperationDataPtr	Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT Data type info: Data type: address of a MIL_INT Data type: address of a MIL_INT

Compilation information

Header	Include mil.h.
Library	Use mil.lib.
DLL	Requires mil.dll.