Command Prompt for Windows




Using a TextStream

Automation includes the COM object called "Scripting.FileSystemObject" which implements many file system operations, including a comprehensive implementation of a TextStream. A TextStream can be used from a batch file to work easily with text files.

The following example demonstrates the use of a TextStream to write sequentially to and from a text file from with in a batch file :-

SET file=C:\text.txt
SET forreading=1
SET forwriting=2

COM obj=CreateObject("Scripting.FileSystemObject")
COM ts=obj.CreateTextFile(file,@true,@false)
COM ts.WriteLine("Hello world!")
COM ts.WriteLine("The quick brown fox...")
COM ts.Close()

COM ts=obj.OpenTextFile(file,forreading)

COG ret=ts.AtEndOfStream
WHILE (ret != -1) DO {

   COM line=ts.ReadLine()
   ECHO %line%

   COG ret=ts.AtEndOfStream
}
COM ts.Close()
COM obj.Release()

Firstly, three environment variables are set up and used as constants, to make understanding the batch file a little earlier :-

SET file=C:\text.txt
SET forreading=1
SET forwriting=2

Then the COM object called "Scripting.FileSystemObject" is created and the handle for the object is placed into the environment variable called obj :-

COM obj=CreateObject("Scripting.FileSystemObject")

Next, the COM objects method .CreateTextFile() is called, passing three parameters :-

  1. the file environment variable which specifies the file C:\text.txt to create,
  2. the bool value for true which tells this method to create the file if it does not exit and
  3. the bool value for false which tells the method to use ANSI text instead of UNICODE text

The TextStream handle returned by the COM object is stored in the environment variable ts. The environment variable ts is really just another COM object that is used to call other methods in order to perform various tasks on the TextStream that has been created :-

COM ts=obj.CreateTextFile(file,@true,@false)

Note: when this line is executed on Windows Vista and above, the WinOne® Command Prompt will need to be run with Administrator Privileges in order to create a file located in the folder C:\.

Then the COM object method .WriteLine() is called, to simply write a few lines of text to the file :-

COM ts.WriteLine("Hello world!")
COM ts.WriteLine("The quick brown fox...")

and the .Close() method is called to close the file :-

COM ts.Close()

The next part of the batch file calls the COM object method .OpenTextFile() passing two parameters, the file environment variable and the forreading environment variable, which opens the file for reading :-

COM ts=obj.OpenTextFile(file,forreading)

The following lines of code then gets the COM object property .AtEndOfStream and set the environment variable ret with the value and implements a WHILE loop, testing the environment variable ret to see if it is equal to -1, which is the bool value for true. If ret is not equal to -1 (ie. not at the end of the stream) then the next two lines reads a line of text out of the file using the COM object method .ReadLine() and the ECHO command displays what was read from the file.

The environment variable ret is then again set to the value of the property .AtEndOfStream and the WHILE loop starts again, testing the value of ret to see if the end of the file has been reached. When the end if the file has been reached then the batch file jumps out of the loop and starts executing commands after the closing brace character :-

COG ret=ts.AtEndOfStream
WHILE (ret != -1) DO {

   COM line=ts.ReadLine()
   ECHO %line%

   COG ret=ts.AtEndOfStream
}

It is important to note the use of braces in the loop instead of using brackets. Braces give the environment variables in the WHILE loop local scope. If brackets were used then the ECHO %ret% command line in the loop, would not display the result of the .ReadLine() call. For example:-

REM a bad while loop example using 
REM brackets instead of braces

COG ret=ts.AtEndOfStream
WHILE (ret != -1) DO (

   COM line=ts.ReadLine()
   ECHO %line%

   COG ret=ts.AtEndOfStream
)

will not work as the environment variable ret will be instantiated at the time the WHILE loop is being parsed, we want the ret environment variable to be instantiated at execution time.

Similarly, the following is also incorrect :-

REM another bad while loop example using 
REM %ret% for the WHILE loop condition

COG ret=ts.AtEndOfStream
WHILE (%ret% != -1) DO {

   COM line=ts.ReadLine()
   ECHO %line%

   COG ret=ts.AtEndOfStream
}

As we do not want the ret environment variable in the condition part of the WHILE loop instantiated at parse time, instead, we want it to be instantiated at run time internally by the WHILE command itself.

Finally, the batch file calls the COM objects .Close() method which simply closes the file as it is not needed any more and the last line in the batch file calls the COM objects .Release() method which tells the COM object that we have finished with it and if no one else is using the COM object it can be removed from memory :-

COM ts.Close()
COM obj.Release()