File Content Functions

cla140

You can use the File Content functions on any platform.

CloseFile - Close the File

Valid on NetWare, Symbian OS, UNIX, Windows and Windows CE

The CloseFile function closes the file that is associated with a file handle. The file handle is obtained from a call to OpenFile or CreateFile.

Function format:

CloseFile(handle as Integer) as Boolean

handle

This parameter specifies the file handle obtained from a call of OpenFile or CreateFile.

On successful completion, the function returns TRUE (non zero). If the function fails the function returns FALSE. For example, when the handle is not the handle of a valid open file.

Example:

This example creates a backup of the CONFIG.SYS file.

Dim fIn, fOut as integer   ' Declare file handles
Dim OneLine as string     ' String to hold one line

' First open the Input file...


fIn=OpenFile("C:\CONFIG.SYS",O_READ)
if fIn<0 then
	MessageBox("Unable to open input file","Error")
	Goto End
End if

' ...Then create the output file...


fOut=CreateFile("C:\CONFIG.BAK")
if fOut<0 then
	MessageBox("Unable to create output file","Error")
	Goto End

End if

' ...Copy lines until none left...


while Not(Eof(fIn))
	if ReadFile(fIn,OneLine) then WriteFile(fOut,OneLine)
wend

' ...Close Files, and signal success.


CloseFile(fIn)
CloseFile(fOut)
MessageBox("A backup of the CONFIG.SYS file was created","MyScript")

end:

CreatePipe - Create a Pipe

Valid on UNIX and Windows

This function is new in

CA Client Automation

and does not work with older versions of the Script Interpreter.

The CreatePipe function creates a named pipe for reading or writing in server role.

Function format:

CreatePipe(pipename as String, access as Integer) as Integer

pipename

This parameter specifies the name of the pipe to be created. On UNIX, pipename is a valid pathname.

On Windows it has the form:

\\.\pipe\xxx

Where xxx can contain any characters except '\.

access

This parameter specifies in what direction the pipe is used.

O_READ

(value 0) Opened for reading.

O_WRITE

(value 1) Opened for writing.

The function returns a file handle that you can use with functions ReadFile, WriteFile, and CloseFile.

CreatePipe is used in the process that acts as a pipe server. A pipe client uses the OpenPipe function.

The pipe works in blocking mode. The read or write functions following CreatePipe wait until a client uses the inverse function.

The function is not available on Windows 95/98/ME.

On successful completion, the function returns a non-negative integer, which is the file handle. If the function fails, it returns -1.

Example:

This example assumes that the example of OpenPipe is stored as file p0cl.dms.

rem example named pipe server
rem create two pipes
rem start client process
rem write command to one pipe
rem read response from second pipe

dim rc, h0, h1 as integer
dim pnam0, pnam1 as string
dim stopstring as string
dim s, cmd as string
dim iswin as boolean

if left(osstring, 3) = "Win" then
    pnam0 = "\\.\pipe\p0rsp"
    pnam1 = "\\.\pipe\p0cmd"
	iswin = 1
else
    pnam0 = "/tmp/p0rsp"
    pnam1 = "/tmp/p0cmd"
	iswin = 0
endif
stopstring = "---END---"

h0 = CreatePipe(pnam0, O_READ)	  'read response form client
h1 = CreatePipe(pnam1, O_WRITE)	  'send command to client
if h0 < 0 or h1	< 0 then
    print "create pipe failure. h0: " + str(h0) + "  h1: " + str(h1)
	exit
end if 

if iswin then
	cmd = "dmscript p0cl.dms -o_dms: p0clout.txt -script "	+ pnam1 + " " + pnam0
	rc = Exec(cmd, 0) 
else
	cmd = "dmscript p0cl.dms -o_dms: p0clout.txt -script " + pnam1 + " " + pnam0 + " &"
	rc = Exec(cmd) 
end if
print "exec rc: " + str(rc) + " cmd: " + cmd

rc = WriteFile(h1, "command")
if not(rc) then
	print "write command failed"
else    
	while rc
		rc = ReadFile(h0, s)
		print "read response rc: " + str(rc) + " " + s
		if s = stopstring then
			rc = 0
			print "test successful"
		end if
	wend
end if

CloseFile(h0)
CloseFile(h1)

CreateFile - Create a New File

Valid on NetWare, Symbian OS, UNIX, Windows, and Windows CE

On Windows 9x, do not use this function to create an .ini file. Windows OS creates the specified .ini file of a WriteIniSection() or WriteIniEntry().

The CreateFile function creates a file for writing.

Function format:

CreateFile(filename as String, mode as Integer) as Integer
CreateFile(filename as String) as Integer

filename

This parameter specifies the name of the file.

mode

This parameter specifies the mode in which to create the file. The value is one of the following predefined constants:

O_TEXT

(value 0, default) Text mode

O_BINARY

(value 1) Binary mode

If the mode parameter is omitted, text mode is assumed.

If the function succeeds, the return value is a non-negative integer, the file handle. If the function fails, it returns -1.

Example:

This example Creates a backup of the CONFIG.SYS file.

Dim fIn, fOut as integer   ' Declare file handles
Dim OneLine as string     ' String to hold one line

' First open the Input file...

fIn=OpenFile("C:\CONFIG.SYS",O_READ)
if fIn<0 then
	MessageBox("Unable to open input file","Error")
	Goto End
End if

' ...Then create the output file...


fOut=CreateFile("C:\CONFIG.BAK")
if fOut<0 then
	MessageBox("Unable to create output file","Error")
	Goto End

End if

' ...Copy lines until none left...


while Not(Eof(fIn))
	if ReadFile(fIn,OneLine) then WriteFile(fOut,OneLine)
wend

' ...Close Files, and signal success.

CloseFile(fIn)
CloseFile(fOut)
MessageBox("A backup of the CONFIG.SYS file was created","MyScript")

end:

EOF - Check for the End-of-File

Valid on NetWare, Symbian OS, UNIX, Windows and Windows CE

The EOF function determines whether the end of the file has been reached.

Function format:

Eof(handle as Integer) as Boolean

handle

This parameter specifies a file handle.

The function returns TRUE if the end of file has been reached; otherwise, it returns false.

EOF returns TRUE when the last read operation has reached the end of file. The function does not check in advance to see whether a subsequent read command reached the end of a file.

Example:

This example creates a backup of the CONFIG.SYS file.

Dim fIn, fOut as integer   ' Declare file handles
Dim OneLine as string     ' String to hold one line

Rem First open the Input file...

fIn=OpenFile("C:\CONFIG.SYS",O_READ)
if fIn<0 then
	MessageBox("Unable to open input file","Error")
	Goto End
End if

Rem ...Then create the output file...

fOut=CreateFile("C:\CONFIG.BAK")
if fOut<0 then
	MessageBox("Unable to create output file","Error")

CloseFile(fIn)
	Goto End
End if

Rem ...Copy lines until none left...

while Not(Eof(fIn))
	if ReadFile(fIn,OneLine) then WriteFile(fOut,OneLine)
wend

Rem ...Close Files, and signal success.

CloseFile(fIn)
CloseFile(fOut)
MsgBox("A backup of the CONFIG.SYS file was created","MyScript",MB_OK)

end:

OpenFile - Open a File

Valid on NetWare, Symbian OS, UNIX, Windows, and Windows CE

The OpenFile function opens a file for reading or writing.

Function format:

OpenFile(filename as String, access as Integer, mode as Integer) as Integer
OpenFile(filename as String, access as Integer) as Integer

filename

This parameter specifies the name of the file to open.

access

This parameter specifies how to open the file. The access parameter can be any of the following predefined constants:

O_READ

(value 0) Opened for reading.

O_WRITE

(value 1) Created for writing

The file is overwritten if it exists.

O_APPEND

(value 2) Opened for writing at end of file.

A file is craeted if it does not exist.

O_UPDATE

(value 3) Opened for reading and writing.

mode

This parameter specifies an optional parameter to specify binary mode. The mode parameter can be one of the following predefined constants:

O_TEXT

Value 0; text mode

O_BINARY

Value 1; binary mode

If the mode parameter is omitted, text mode is assumed.

If the function succeeds, the return value is a non-negative integer, the file handle. If the function fails, it returns -1.

Example:

This example creates a backup of the CONFIG.SYS file.

Dim fIn, fOut as integer   ' Declare file handles
Dim OneLine as string     ' String to hold one line

' First open the Input file...
fIn=OpenFile("C:\CONFIG.SYS",O_READ)
if fIn<0 then
	MessageBox("Unable to open input file","Error")
	Goto End
End if

' ...Then create the output file...
fOut=CreateFile("C:\CONFIG.BAK")
if fOut<0 then
	MessageBox("Unable to create output file","Error")
	Goto End

End if

' ...Copy lines until none left...

while Not(Eof(fIn))
	if ReadFile(fIn,OneLine) then WriteFile(fOut,OneLine)
wend

' ...Close Files, and signal success.

CloseFile(fIn)
CloseFile(fOut)
MessageBox("A backup of the CONFIG.SYS file was created","MyScript")

end:

OpenPipe - Open a Pipe

Valid on UNIX and Windows

This function is new in

CA Client Automation

and does not work with older versions of the Script Interpreter.

The OpenPipe function opens a named pipe for reading or writing a client role.

Function format:

OpenPipe(pipename as String, access as Integer) as Integer

pipename

This parameter specifies the name of the pipe to be opened.

On UNIX, the pipename is a valid pathname.

On Windows, it has the form \\.\pipe\xxx
where xxx
can contain any characters except '\'

access

This parameter specifies in what direction the pipe is used.

O_READ

(value 0) Opened for reading.

O_WRITE

(value 1) Opened for writing.

You can use the returned file handle with the functions ReadFile, WriteFile, and CloseFile. OpenPipe is used in the process that acts as a pipe client. Before you call OpenPipe, call the CreatePipe.

The pipe works in blocking mode. The read or write functions following OpenPipe wait until the server uses the inverse function.

On successful completion, the function returns a non-negative integer, which is the file handle. If the function fails, it returns -1.

Example:

This example shows a named pipe client.

dim rc, h0, h1, i as integer
dim pnam0, pnam1 as string
dim stopstring as string
dim s, s1 as string
dim iswin as boolean

pnam0 = argv(1)
pnam1 = argv(2)
stopstring = "---END---"

h0 = OpenPipe(pnam0, O_READ)	  
h1 = OpenPipe(pnam1, O_WRITE)	  
if h0 < 0 or h1	< 0 then
    print "open pipe failure. h0: " + str(h0) + "  h1: " + str(h1)
    print "pnam0: " + pnam0 + "  pnam1: " + pnam1
	exit
end if 

rc = ReadFile(h0, s)
print "read command rc: " + str(rc) + " " + s
if rc then
	for i = 1 to 5
		s1 = "RSP " + s + " line " + str(i) 
		rc = WriteFile(h1, s1)
		if not(rc) then
			print "write failed: " + s1
			exit for
		end if
	next i
	if rc then
		rc = WriteFile(h1, stopstring)
		if rc then
		    print "test successful"
		end if 
	end if
end if

CloseFile(h0)
CloseFile(h1)

ReadFile - Read Data from a File

Valid on NetWare, Symbian OS, UNIX, Windows and Windows CE

The ReadFile function reads data from a file.

The file content function has one
of the following formats:

ReadFile (handle as Integer, buffer as String) as Boolean
ReadFile (handle as Integer, buffer as String, buflen as Integer) as Boolean
ReadFile (handle as Integer, buffer as Void) as Boolean
ReadFile (handle as Integer, buffer as Void, buflen as Integer) as Boolean

handle

This parameter specifies a file handle that is returned by a previous call of OpenFile or CreateFile.

buffer

This parameter specifies a variable of any type.

Buffers of type arrays of char are treated as strings.

If the argument buffer is a string type variable, the function reads from the current file position. The function stops reading when a newline character is present or the maximum number of characters are reached. If the argument buffer is any other type, the function reads from the current file position and stops when the buffer is full or the file pointer reaches end of file.

Void means that the type of object can be any valid type except for string and arrays of char.

buflen

This parameter specifies the number of bytes to be read from the file into the buffer. If the file has insufficient bytes, all the bytes remaining are transmitted into the buffer.

On successful completion, the function returns TRUE; otherwise, it returns FALSE.

Do not mix the different formats of the ReadFile() function which can lead to unexpected results.

Unlike the other formats, the first format reads the string as a text line that a newline sign or end of file terminates. The information is stored to the buffer without the newline sign. The interpreter maps this function to a different system read function than the other three formats. The other ReadFile formats are mapped to a common system read function.

The different systems read functions use different cache and read pointers to retrieve the data. If you mix the formats, the data is not read in sequence in which it was stored on the disk.

In the case of the first format, the string read is a text line. A newline sign or end of file terminates the string. The information is stored to the buffer without this newline. This is not true for the other ReadFile functions.

The interpreter maps this function to a different system read function than the other three formats, which are mapped to a common system read function. These different systems read functions also use different caches and read pointers to retrieve the data. If the formats are mixed, the data might not be read in the sequence in it was stored on the disk.

Example:

Dim fIn, fOut as integer   ' Declare file handles
Dim OneLine as string     ' String to hold one line

Rem First open the Input file...

fIn=OpenFile("C:\CONFIG.SYS",O_READ)
if fIn<0 then
	MessageBox("Unable to open input file","Error")
	Goto End
End if

Rem ...Then create the output file...

fOut=CreateFile("C:\CONFIG.BAK")
if fOut<0 then
	MessageBox("Unable to create output file","Error")

CloseFile(fIn)
	Goto End
End if

Rem ...Copy lines until none left...

while Not(Eof(fIn))
	if ReadFile(fIn,OneLine) then WriteFile(fOut,OneLine)
wend

Rem ...Close Files, and signal success.

CloseFile(fIn)
CloseFile(fOut)
MsgBox("A backup of the CONFIG.SYS file was created","MyScript",MB_OK)

end:

SeekFile - Reposition the Current Position in an Open File

Valid on NetWare, Symbian OS, UNIX, Windows and Windows CE

The SeekFile function repositions the current position in an open file.

Function format:

Seekfile(handle as integer, position as integer) as Boolean

handle

This parameter specifies a handle that is returned by a previous call.

position

This parameter specifies the new position in the file. A position of 0 sets the position to the beginning of the file

The next read or write will be at the new position in the file.

On successful completion, the function returns TRUE; otherwise, it returns FALSE.

Example:

'	Update a file at the 4th double word. set it to 0.
Dim fHandle as integer

fHandle = OpenFile("out5.a", O_UPDATE)
if (fHandle = -1) then
	Print("OpenFile(""out5.a"", O_UPDATE) failed.")
	exit
endif
if Not(SeekFile(fHandle, 16)) then
	Print("SeekFile(fHandle, 16) failed.")
	exit
endif
if Not(WriteFile(fHandle, 0)) then
	Print("WriteFile(fHandle, 0) failed.")
	exit
endif
CloseFile(fHandle)

WriteFile - Write Data to a File

Valid on NetWare, Symbian OS, UNIX, Windows and Windows CE

The WriteFile function writes data to a file.

Function formats:

WriteFile(handle as Integer, buffer as String) as Boolean
WriteFile(handle as Integer, buffer as String, buflen as Integer) as Boolean
WriteFile(handle as Integer, buffer as Void) as Boolean
WriteFile(handle as Integer, buffer as Void, buflen as Integer) as Boolean

handle

This parameter specifies a file handle that is returned by OpenFile or CreateFile.

buffer

This parameter specifies a variable of any type.

buflen

This parameter specifies the number of characters to be stored in the file. If the number of char exceeds buflen, only the first buflen characters are stored in the file. If the number of chars does not exceed buflen, the whole buffer is stored.

On successful completion, the function returns TRUE; otherwise, returns FALSE.

Do not mix the different formats of the WriteFile() function formats. Mixing the formats leads to unexpected results.

The interpreter handles the first format differently. When the string is written to disk, the interpreter always adds a newline sign.

The interpreter maps the first format to a different system write function than the other three formats, which are mapped to a common system write function. The different systems write functions use different caches to store the data that are written. At close time, the caches are written to disk one after another. If you mix the formats, the data does not appear in the correct sequence.

The interpreter handles the following formats in a different way:

WriteFile(handle as Integer, buffer as String) as Boolean

When the string is written to disk, a newline is always added. This is not true for the other types of formats. The interpreter maps this function to a different system write function than the other three formats which were mapped to a common system write function. These different systems write functions may also use different caches to store the data written. At close time, the caches are written to disk one after another. If the formats are mixed, the data may not appear in the sequence - in which it was written. Therefore, do not mix this format with the other formats.

Example:

Dim fIn, fOut as integer   ' Declare file handles
Dim OneLine as string     ' String to hold one line

Rem First open the Input file...

fIn=OpenFile("C:\CONFIG.SYS",O_READ)
if fIn<0 then
	MessageBox("Unable to open input file","Error")
	Goto End
End if

Rem ...Then create the output file...

fOut=CreateFile("C:\CONFIG.BAK")
if fOut<0 then
	MessageBox("Unable to create output file","Error")

CloseFile(fIn)
	Goto End
End if

Rem ...Copy lines until none left...

while Not(Eof(fIn))
	if ReadFile(fIn,OneLine) then WriteFile(fOut,OneLine)
wend

Rem ...Close Files, and signal success.

CloseFile(fIn)
CloseFile(fOut)
MsgBox("A backup of the CONFIG.SYS file was created","MyScript",MB_OK)

end:

Functions

CA Client Automation - 14.0

File Content Functions