In this section: |
File functions operate on the file system of iWay Service Manager (iSM). File operations depend on the specifics of the operating system.
The _file() function uses the following format:
_file(path, [,default[,encoding]])
path | string | Path to the desired file. |
default | string | Value to be returned if the file does not exist. |
encoding | string | IANA encoding. |
The specified file is loaded and returned. If encoding is specified, the file is considered to be encoded in the specified IANA encoding. If omitted, the default file system encoding is assumed.
The special encoding of base64 will return the contents of the file encoded in base64. This is especially useful when contents of files, such as PDFs, are to be included as XML values. Placing an _file() function in the XML document and then using the Tree Evaluator Service (com.ibi.agents.EvalWalk) will perform the inclusion.
For example:
_file('/mydoc.pdf',,'base64')
The _filegdg function pushes down versions of a file as new versions are created. It is designed to assist in situations in which only a few generations (versions) of a file are required. The _filegdg function uses the following format:
_filegdg(sourcefile , generations [,generationpath] [,compare])
sourcefile | string | The path to the file to be preserved. |
generations | integer | The number of generations to exist. |
generation path | string | Path of a directory in which pushed generations will be preserved. The default is the directory in which the source file is found. |
compare | keyword | Determines whether the source file should be compared to the prior last generation. The default is true.
|
Generation Data Groups (GDG) keep identified generations of a file. Frequently this is used to assist during debugging. For example, to keep a limited number of versions of a file to represent the last few changes to the data. The GDG is the reverse of the unique file naming facility of iSM in which versions count up to the modulus of the unique characters in the name.
For unique naming, a file named abc####.txt would create 10000 files and then restart at abc00001. In contrast, the GDG with three versions:
_filegdg('Abc.txt',3)
might create:
Abc.txt
Abc0.txt (last version)
Abc1.txt (prior version)
When the next Abc.txt is written (assuming compress is true), the contents of the existing Abc.txt will be compared to Abc0.txt. If the contents match, then no change will be made. If they do not match, then the existing Abc1.txt will be deleted, Abc0.txt will be renamed to Abc1.txt, Abc.txt will be renamed to Abc0.txt, and a new Abc.txt will be created.
The function returns the source file value, so that your file write component can write into Abc.txt.
The compare option when set to true prevents the creation of identical generations, ensuring that only changes are represented. For a debug run in which you need to see the actual results of the specific list runs, you may want to set this option to false.
A reasonable use case would be to write the input file using a File Emit service or a QA service, using the _filegdg() as the file name to be written. Thus at a failure (ending the iteration or stopping the channel with a control agent), the output of the debugging service would hold the last three records, given the above example.
Note: The number of generations and the compare option are consistent over all executions. The source file (and backup directory if used) vary by instance execution.
The _fileinfo function returns information about a specified file. The information returned depends on the operating system. The _fileinfo function uses the following format:
_fileinfo(type , file)
type | keyword | The desired information about the file to be returned. Specify one of the following types:
|
file | string | The specified file for which information is to be returned. |
As an example, a file called filedata.txt is located in the c:\mydir\ directory. The following _fileinfo() function is executed:
_fileinfo(type,' c:\mydir\filedata.txt')
The following table lists the returned values for several supported types.
Type | Sample Returned Value |
---|---|
absolute | c:/mydir/filedata.txt |
length | 55 |
isdir | false |
isfile | true |
owner | pc1/pcuser Note: The owner information ID is dependent on the operating system. |
Time/date values can be converted to more readable formats by use of the _fmtdate() function. For example:
_fmtdate('mm/dd/yyyy HH:mm:ss',_fileinfo('moddate','c:/docs/a.xml'))
returns:
07/20/2015 07:23:44
The _fileexists() function determines whether a file exists on a specified path. It uses the following format:
_fileexists(path [,nametype])
path | string | Path to file. |
nametype | Keyword | Determines how the file name is being expressed. Specify one of the following types:
|
If the file name is a literal or is resolved as a literal, such as the contents of a Special Register (SREG), then that file name is used. If the parameter is a _file() function, then the file name as resolved for the _file() function is used, not the contents of the file. To test for a name in a file, use the _eval() function to evaluate the file operation.
For example, if a SREG called fname holds a file name, then the following function is returned as true:
_fileexists(sreg(fname))
Otherwise, this function is returned as false.
If the nametype property is set to dos, then the file name may contain DOS-type wildcard characters (for example, ? and *). Wildcard characters cannot be used in the path specification itself, only in the file portion (the file name).
For example, the following function returns true if any files on the path meet the specification:
_fileexists('/lookhere/any*.txt',dos)
Otherwise, this function is returned as false.
iWay Software |