x

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')

x

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. true. If the current version and the prior version are the same, no generation is pushed. false. The new generation is always pushed (created).

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.

x

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: absolute. The full, absolute path of the file. A relative path will be converted to an absolute path. exists. Returns true if the file exists, else false. isdir. Returns true if the file is a directory, else false if it does not exist or is a file. isfile. Returns true if the file is a file, else false if it does not exist or is a directory. length. Returns the (approximate) length in bytes of the file. locked. Returns true if the operating system reports that the file is locked. name. Returns the file name portion of a full file path specification. owner. ACL owner for the file, if available in the operating system. path. Returns the path portion of a full file path specification. moddate. Returns a Unix date value for the modification date of the file. The _fmtdate() function uses a pattern to convert the Unix time/date to a readable value. For more information on returning timestamps, see _timer(): Return Unix Epoch Time.
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

x

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: standard. Name is a file name. dos. Name is a DOS/Windows wildcard specification.

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.