Chapter V use of documents
Use file
%Library. The file class provides several class methods that allow various operations on files.
Copy file
To copy a file, use the CopyFile() method, which returns a Boolean value indicating success or failure.
This method takes four parameters:
- from - specifies the name of the source file.
- To to - specifies the name of the target file.
- pDeleteBeforeCopy - specifies whether to delete the target file (if any) before performing the copy. The default value is 0.
- return - output parameters. If negative, the error code returned by the operating system is included in case the method fails
The first example below takes the file old. In the directory e:\temp Txt to new txt. The second example copies the same file to new. In the default directory txt.
DHC-APP>write ##class(%File).CopyFile("e:\temp\old.txt", "e:\temp\new.txt", 0, .return)
1
DHC-APP>write ##class(%File).CopyFile("e:\temp\old.txt", "new.txt", 0, .return)
1
The last example failed with Windows error code 2 or "file not found"
DHC-APP>write ##class(%File).CopyFile("foo.txt", "new.txt", 0, .return)
0
DHC-APP>w return
-2
Delete file
To delete a file, use the delete() method, which returns 1 on success and 0 on failure. This method requires two parameters. The first parameter is the name of the file to be deleted. The second parameter is the output parameter. If negative, it contains the error code returned by the operating system in case the method fails.
In the first example below, the method succeeds. The second example fails with Windows error code 2 or file not found.
DHC-APP>write ##class(%File).Delete("e:\temp\myfile.txt", .return)
1
DHC-APP>write ##class(%File).Delete("e:\temp\myfile.txt", .return)
0
DHC-APP>w return
-2
To match wildcards when deleting files, use the ComplexDelete() method. The first parameter specifies the name of the file to delete. The second parameter is the output parameter. If negative, it contains the error code returned by the operating system in case the method fails.
The following example deletes all with. e: The out extension in the \ temp directory.
DHC-APP>write ##class(%File).ComplexDelete("e:\temp\*.out", .return)
1
truncate file
To truncate a file, use the truncate() method, which returns 1 on success and 0 on failure. This method requires two parameters. The first parameter is the name of the file to truncate. The second parameter is the output parameter. If negative, it contains the error code returned by the operating system in case the method fails.
If you truncate an existing file, the method deletes the content from the file, but does not delete the content from the file system. If you truncate a file that does not exist, the method creates a new empty file.
In the first example below, the method succeeds. The second example failed with Windows error code 5 or "access denied"
USER>write ##class(%File).Truncate("e:\temp\myfile.txt", .return)
1
USER>write ##class(%File).Truncate("e:\no access.txt", .return)
0
USER>write return
-5
rename file
To rename a file, use the rename() method, which returns 1 on success and 0 on failure. This method requires three parameters. The first parameter is the name of the file to rename, and the second parameter is the new name. The third parameter is the output parameter. If negative, it contains the error code returned by the operating system in case the method fails.
In the first example below, the method succeeds. The second example fails with error code 183, or "the file cannot be created when it already exists."
DHC-APP>write ##class(%File).Rename("e:\temp\oldname.txt", "e:\temp\newname.txt", .return)
1
DHC-APP>write ##class(%File).Rename("e:\temp\another.txt", "e:\temp\newname.txt", .return)
0
DHC-APP>write return
-2
When using this method, be careful to specify the path, because the following example will e: \ temp \ oldname Txt to the default directory, and then rename it newname txt.
DHC-APP>write ##class(%File).Rename("e:\temp\oldname.txt", "newname.txt", .return)
1
Comparison file
To compare two files, use the Compare() method. If the two files are the same, it returns a Boolean value of 1, otherwise it returns 0. The method has no output parameters to return the system error code.
In the first example below, the two files are the same, and the method returns 1. In the second example, the two files are different, so the method returns 0.
DHC-APP>write ##class(%File).Compare("e:\temp\old.txt", "e:\temp\new.txt")
1
DHC-APP>write ##class(%File).Compare("e:\temp\old.txt", "e:\temp\another.txt")
0
If one or both files do not exist, as shown in the following example, the method also returns 0.
DHC-APP>write ##class(%File).Compare("foo.txt", "bar.txt")
0
DHC-APP>write ##class(%File).Exists("foo.txt")
0
Generate temporary files
To generate a temporary file, use the TempFilename() method, which returns the name of the temporary file. This method requires three parameters. The first parameter is the file extension required for the temporary file. The second is the directory where temporary files are generated. If not provided, this method generates files in the temporary directory provided by the operating system. The third parameter is the output parameter. If negative, it contains the error code returned by the operating system in case the method fails.
Windows example:
USER>write ##class(%File).TempFilename("txt")
C:\WINDOWS\TEMP\GATqk8a6.txt
USER>write ##class(%File).TempFilename("txt","C:\temp")
C:\temp\WpSwuLlA.txt
Unix example:
USER>write ##class(%File).TempFilename("", "", .return)
/tmp/filsfHGzc
USER>write ##class(%File).TempFilename("tmp", "/InterSystems/temp", .return)
/InterSystems/temp/file0tnuh.tmp
USER>write ##class(%File).TempFilename("", "/tmp1", .return)
USER>write return
-2
In the third example above, the directory does not exist, the method fails, the system error code is 2, or "there is no such file or directory."