FileObject Interface

The File object (IFileObject) is returned by the CreateFileObject function of the ComScript connection. Through this object, the functionality of the FileObject utility can be used in programs that are written in any COM supporting development environment.

File Access

Access to files is possible to files with Open... and Create... functions to three types of files:

TextStream: access the file as a normal textfile.
RecordStream: access the file as a file containing records with fixed length
BinaryStream: access the file containing any sort of data

File Cycles

The File Object also supports File Cycles for both OS2200 File Cycles and IBM CICS File Cycles. File Cycles can be created and maintained through a special set of methods in the section File Cycle Functions below. The usage of File Cycles and the difference between IBM CICS and OS2200 File Cycles are described in the help page File Cycles.

File Object Functionality

The following functionality is provided:

Properties

Name	Return type	Access	Description
Connected	Boolean	Readonly	True when the File Object is connected to a running File Controller Service.
ErrorCode	Integer	Readonly	Returns the error code of the File object. Zero if no error occurred.
ErrorDescription	String	Readonly	Returns the error description of the File object. If no error occurred there will be returned an empty string.

Functions

Function Name	Return type	Parameters		Description
Function Name	Return type	Name	Type	Description
AddIndexKey	Void	IndexName	String	Adds an index key to a record stream file before the file gets created or opened. When calling CreateRecordFile or OpenRecordFile after this function, the file is created/opened with the specified index. The description of the parameters together with the allowed values can be found in the AddIndexKey parameters table below.
		Startpos	Integer
		Length	Integer
		Type	String
		Order	String
AsciiToEbcdic	Boolean	FileName	String	Converts the specified ASCII file to EBCDIC file. Returns True when successful. Application Kind is optional when the conversion behavior is based on the kind of the connected application. For the application kinds see the list below. When skipLineFeeds it set to True, line feeds will not be converted. When maxWait is set to a non zero value the conversion will wait the set value in seconds before an error is returned.
		[ApplicationKind]	Integer
		SkipLineFeeds	Boolean
		MaxWait	Integer

Assign	FileInfo Object	FileName	String	Locks the file specified in filename with the specified ShareMode. Unicode should be set to true when the file is a Unicode file. False for ASCII. When existingFile is set to True the lock is applied to an existing file. maxWaitTimeInSec sets a time out on the creation of the file. For a list of Share Modes see below.
		ShareMode	Integer
		Unicode	Boolean
		ExistingFile	Boolean
		MaxWaitTimeInSec	Integer
CloseAllFiles	Boolean	---		Closes all open files and returns True on success.
Concat	Boolean	SourceFileNames	Array of Strings	Concatenate files. Concatenates files from a string array into a specified file. MaxWaitTimeInSec sets a time out on the creation of the file.
		DestinationFileName	String
		MaxWaitTimeInSec	Integer
CopyFile	Boolean	SourceFileName	String	Copies a file specified in SourceFileName to a file specified in DestinationFileName. Both file names should be specified with the full path. Any non existent folder will be created. On success True is returned and False on failure. When Overwrite is set to True an existing file with the name specified in Destination will be overwritten. MaxWaitTimeInSec specifies the maximum wait time in seconds.
		DestinationFileName	String
		Overwrite	Boolean
		MaxWaitTimeInSec	Integer

CopyFolder	Boolean	SourcePath	String	Copies a folder with contents specified in SourcePath to a folder specified in DestinationPath. Both folder names should be specified with the full path. Any non existent folder will be created. When Overwrite is set to True, an existing file with the name specified in Destination will be overwritten. MaxWaitTimeInSec specifies the maximum wait time in seconds.
		DestinationPath	String
		Overwrite	Boolean
		MaxWaitTimeInSec	Integer

CopyRecords	Boolean	SourceFileName	String	Copies all the records present in the source file and appends them an existing file. Using this function will leave the structure of the destination file intact, making it useful to copy records to an SQLite file for example. Both file names should be specified with the full path. On success, True is returned and False on failure. MaxWaitTimeInSec specifies the maximum wait time in seconds.
		DestinationFileName	String
		MaxWaitTimeInSec	Integer
CreateBinaryFile	Binary Stream Object	FileName	String	Creates the file specified by FileName and opens it as a Binary Stream. Returned is an Object of type Binary Stream. When a file with the file name specified already exists and Overwrite is set to True, this file will be overwritten. Otherwise the creation of the Binary Stream Object will fail and properties ErrorCode and ErrorDescription will be set accordingly. With ShareMode the mode for possible sharing can be specified. For an explanation of the share modes see below.
		ShareMode	Integer
		Overwrite	Boolean
CreateFolder	Boolean	Path	String	Creates a folder or folder tree specified in Path. The name of the folder should contain the full path. Returns True on success and False on Failure.
CreateRecordFile	Record Stream Object	FileName	String	Creates the file specified by FileName and opens it as a Record Stream. Returned is an object of type Record Stream. When a file with the file name specified already exists and Overwrite is set to True, this file will be overwritten. Otherwise the creation of the Record Stream Object will fail and properties ErrorCode and ErrorDescription will be set accordingly. With ShareMode the mode for possible sharing can be specified. For an explanation of the share modes see below. When Unicode is set to True the file will be created as a Unicode file, otherwise as an ASCII file. RecordSize must be set to the record size used in the file. ContainsComp should be set to True when the file will contain computational values. MaxWaitTimeInSec specifies the maximum wait time in seconds before the create will fail. FileRecordEnding will set the type of record ending used in the file, where: 0 Default, 1 CR/LF, 2 CR, 3 LF, 4 None. An index can be added to the file with the AddIndexKey function.
		ShareMode	Integer
		Unicode	Boolean
		RecordSize	Integer
		ContainsComp	Boolean
		Overwrite	Boolean
		MaxWaitTimeInSec	Integer
		FileRecordEnding	Integer

CreateTextFile	Text Stream Object	FileName	String	Creates the file specified by FileName and opens it as a Text Stream. Returned is an object of type Text Stream. When a file with the name specified already exists and Overwrite is set to true, this file will be overwritten. Otherwise the creation of the Text Stream Object will fail and the properties ErrorCode and ErrorDescription will be set. When Unicode is set to true, the created text file will be a Unicode text file, otherwise an ASCII text file. With ShareMode the mode for possible sharing can be specified. For an explanation of the share modes see below.
		ShareMode	Integer
		Unicode	Boolean
		Overwrite	Boolean

DeleteFile	Boolean	FileName	String	Deletes the file specified by FileName. The name of the file should contain the full path. Returns True on success and False on failure. With MaxWaitTimeInSec a maximum wait time in seconds can be specified in case the file to delete is either open by a process or not yet existent.
		MaxWaitTimeInSec	Integer

DeleteFolder	Boolean	Path	String	Deletes the folder specified by Path. The name of the folder should contain the full path. Files and subfolders will be deleted. Returns True on success and False on failure. Note: this function will only fail when there is a file open in the folder or in one of its subfolders.
		MaxWaitTimeInSec	Integer

EbcdicToAscii	Boolean	fileName	String	Converts the specified EBCDIC file to ASCII file. Returns True when successful. Application Kind is optional when the conversion behavior is based on the kind of the connected application. For application kinds see the list below. When skipLineFeeds it set to True, line feeds will not be converted. MaxWaitTimeInSec specifies the maximum wait time in seconds.
		[ApplicationKind]	Integer
		skipLineFeeds	Boolean
		MaxWaitTimeInSec	Integer

FileExists	Boolean	FileName	String	Returns True when specified file in FileName exists. The name of the file should contain the full path.
FileInUse	Boolean	FileName	String	Returns True when the specified file is in use by a process. The name of the file should contain the full path.
FolderExists	Boolean	Path	String	Returns True when the specified folder exists. The name of the folder should contain the full path to the folder.
Free	FileInfo Object	FileId	String	Frees the lock, set by assign, of the file identified by the FileId of the file. The FileId is the string present in the FileId property of the FileInfo Object.
GetDirectories	String	Path	String	Returns a comma separated list of folders in the folder specified by Path. The name of the folder should contain the full path. When Recursive is set to True also sub-folders will be listed.
		Recursive	Boolean

GetFiles	String	Path	String	Returns a comma separated list of files in the folder specified by Path. The name of the folder should contain the full path. When Recursive is set to True, the files in sub-folders will also be listed. The optional Max parameter limits the number of files which are searched (and returned). The default value of Max is -1 which will disable the limit.
		Recursive	Boolean
		Max	Integer
GetFileInfo	FileInfo Object	FileName	String	Returns an object containing information about the file specified in FileName. The name of the file should contain the full path. MaxWaitTimeInSec specifies the maximum wait time in seconds. For information about the returned FileInfo object see FileInfo Interface.
		MaxWaitTimeInSec	Integer

GetIndexKeyInfo	String	FileName	String	Returns the index key geometry of an existing file, read from its meta data. Each key is encoded as "indexName,offset,length" and keys are separated by ';'. Returns an empty string when the file has no indexes or no meta data is available. The name of the file should contain the full path. MaxWaitTimeInSec specifies the maximum wait time in seconds.
		MaxWaitTimeInSec	Integer

GetIndexKeyInfo	String	FileName	String	Returns the index key geometry of an existing file, read from its meta data. Each key is encoded as "indexName,offset,length" and keys are separated by ';'. Returns an empty string when the file has no indexes or no meta data is available. The name of the file should contain the full path. MaxWaitTimeInSec specifies the maximum wait time in seconds.
		MaxWaitTimeInSec	Integer

GetOpenFiles	String	---		Returns a list of opened files by a client in the AMT FileController.
MergeFiles	Boolean	SourceFiles	Array of Strings	Merge one or more files specified in the Array of Strings SourceFiles into a target file specified by TargetFileName. If the target file already exist, it will append. OutputRecordSize sets the record size to use when merging. When set to 0 record size of the SourceFiles used. MaxWaitTimeInSec specifies the maximum wait time in seconds for the merge.
		TargetFileName	String
		OutputRecordSize	Integer
		MaxWaitTimeInSec	Integer

OpenBinaryFile	Binary Stream Object	FileName	String	Opens the file specified by FileName as Binary Stream. Returns an Object of type Binary Stream. When the open fails, the properties ErrorCode and ErrorDescription will be set accordingly. With ShareMode the mode for possible sharing can be specified. For an explanation of the share modes, see below.
		ShareMode	Integer

OpenRecordFile	Record Stream Object	FileName	String	Opens the file specified by FileName as a Record Stream. Returned is an object of type Record Stream. With ShareMode the mode for possible sharing can be specified. For an explanation of the share modes, see below. When Unicode is set to True the file will be opened as a Unicode file, otherwise as an ASCII file. RecordSize must be set to the record size used in the file. ContainsComp should be set to True when the file contains computational values. With MaxWaitTimeInSec a maximum wait time can be specified before the open will fail, e.g. when the file is locked or has not yet been created. FileRecordEnding will set the type of record ending used in the file, where: 0 Default, 1 CR/LF, 2 CR, 3 LF, 4 None. An index can be added to the file with the AddIndexKey function.
		ShareMode	Integer
		Unicode	Boolean
		RecordSize	Integer
		ContainsComp	Boolean
		MaxWaitTimeInSec	Integer
		FileRecordEnding	Integer
OpenTextFile	Text Stream Object	FileName	String	Opens the file specified by FileName as Text Stream. Returns an object of type Text Stream. FileEncoding can be 1 for an ASCII file, 2 for a Unicode file and 0 for autodetect. When Append is set to True the file will be opened for appending and the open will fail when the specified file does not exist. When Append is set to False, a new empty file will be created thereby overwriting any existing file with the same name. With ShareMode the mode for possible sharing can be specified. For an explanation of the share modes see below.
		ShareMode	Integer
		FileEncoding	Integer
		Append	Boolean

RenameFile	Boolean	OldFileName	String	Renames a file specified in OldFileName to the name specified in NewFileName. Both file names should contain the full path. Any non existent folder in the NewFileName will be created. If the NewFileName already exists, it will be overwritten. Returns True on success and False on failure. With MaxWaitTimeInSec a maximum wait time can be specified.
		NewFileName	String
		MaxWaitTimeInSec	Integer
RenameFolder	Boolean	OldPath	String	Renames a folder specified on OldPath to the name specified in NewPath. Both folder names should contain the full path. Returns True on success and false on failure. New folders in the path of NewPath will NOT be created. With Timeout a maximum wait time in seconds can be specified.
		NewPath	String
		MaxWaitTimeInSec	Integer
SetAttributes	Boolean	FileName	String	Set file attributes to the file specified in FileName. The supported attributes can be found the System.IO.FileAttributes enum.
		Attributes	System IO FileAttributes

SetModifiedDate	Boolean	FileName	String	Sets the Modified Date/Time of the file specified by FileName. The name of the file should contain the full path. On success True is returned, otherwise False. DateTime should be presented in the format 'YYYYMMDDHHMMSSsss', where SS stands for seconds and sss for milliseconds. Dates before the first of January 1970 are not allowed.
		DateTime	String

WaitForFile	Boolean	FileName	String	Will wait for a non existent or open file specified in FileName to be created or closed for the number of seconds specified in MaxWaitTimeInSec. Returns True when the file is already existent and closed, once it is created and closed or closed when already existent and open.
WaitForFile	Boolean	MaxWaitTimeInSec	Integer

File Cycle Functions


The file cycle functions in the FileObject Interface are mainly to be used by the Script Libraries. It is strongly discouraged to use these functions directly in scripts. When however these functions are to be used directly more information on the usage can be found in the help page File Cycles.


The FileObject functions Assign and Free are NOT to be confused with the OS2200 ECL commands ASSIGN and FREE which control Catalogued files. The FileObject functions Assign and Free simply control locks on files as described above.

Function Name	Return type	Parameters		Description
Function Name	Return type	Name	Type	Description
CreateFileCycle	FileInfo Object	FileName	String	Create a file, in text mode, in a file cycle using the specified file name and return the FileInfo Object of the created file. When the file cycle is not yet present it will be created. The cycle limit to use when creating the file. Maximum value is 32 for a OS2200 file cycle and 255 for a IBM file cycle. When Unicode is set to True, the text file will be created as Unicode file. When Overwrite is set to true, an existing file will be overwritten (when using an absolute file number). When Overwrite is set to false and the file with the absolute file number already exists the ErrorCode will be set to a nonzero value and the ErrorDescription will be set. MaxWaitTimeInSec specifies the maximum wait time in seconds.
		CycleLimit	Integer
		ShareMode	Integer
		Unicode	Boolean
		Overwrite	Boolean
		MaxWaitTimeInSec	Integer

ChangeCycle	Boolean	FileName	String	Changes the cycle limit of the file cycle specified by FileName to the value specified in CycleLimit. The maximum value is 32 for a OS2200 file cycle and 255 for a IBM file cycle. MaxWaitTimeInSec specifies the maximum wait time in seconds for the change of the cycle limit.
		CycleLimit	Integer
		MaxWaitTimeInSec	Integer
CloseFileCycle	Boolean	FileId	String	Closes the file cycle specified by FileId. When DeleteFile is set to True, the file will also be deleted. MaxWaitTimeInSec specifies the maximum wait time in seconds for the delete of the file cycle.
		DeleteFile	Boolean
		MaxWaitTimeInSec	Integer

AddIndexKey Parameters

Parameter

Allowed Values

Description

IndexName

Any characters

The name of the index, this may be a new index or an existing index.

StartPos

Any integer

The starting position of the key.

Length

Any integer

The length of the key.

Type

A	1
N	2
S	7
O	0
E	9
=

The type of the key. Some types are restricted by the application origin.

A is Alpha, N is Numeric, S is Signed,

O is Numeric computational, E is Financial computational,

1 is Numeric bit9 (OS2200 only), 2 is Financial bit9 (OS2200 only),

7 is Numeric binary (IBM & Microfocus), 0 is Financial binary (IBM & Microfocus),

9 is Numeric comp 9 (OS2200 only), = is Financial comp 9 (OS2200 only)

Order

ASC
DSC

Index order, either ascending or descending.

Share Modes

Mode	Name	Description
1	Exclusive	The file is opened exclusive, no other process can access the file.
2	Exclusive Batch	The file is opened exclusive for this batch. I.e. the file is shared with processes started by the same batch.
3	Shared Read/Write	The opened file can be accessed both for read and write by other processes.
4	Shared Read	The opened file can be accessed for read by other processes.

Application Kind

Number	Application Kind
1	LionASeries
4	LionOS2200
256	LionUNIX
1024	CobolASeries
2048	CobolIbm
4096	CobolOS2200
262144	CobolMiFoUnix
524288	CobolMiFoWindows

Example

PowerShell

# See ComScript Connection Interface
# ...

$ComScr.Connect()

#Create an object of the FileObject Interface to be able to handle files.
$AmtFile = $ComScr.CreateFileObject()

[void]$AmtFile.CopyFile("D:\Files\Ebcdic.txt", "D:\Temp\Mainframe.txt", $true, 5)
$success = $AmtFile.EbcdicToAscii("D:\Temp\Mainframe.txt", $false, 5)
[void]$AmtFile.RenameFile("D:\Temp\Mainframe.txt", "D:\Files\Ascii.txt", 5)

if ($success) {
  Write-Host "File converted to Ascii"
} else {
  Write-Host "Error, file not converted: $($AmtFile.ErrorCode) $($AmtFile.ErrorDescription)"
}

# Finally release the variables and clean up the session.
$ComScr.Dispose()