Mr. Cluey : How To ...? : Creating Files on the Target Machine

How do I create a file on the target machine?

Frequently when running distributed tests, you will want to manipulate a file on the target machine directly from your script. For instance, you might want to put some data into a file so that your application can open the file, or you might want to directly read the file that was output by your application.

Intuitively, you might expect that this code would create a file on the client machine:

main ()
{
      HFILE hFile;

      Connect ("client1");   //  connect to target machine.
      Current machine = client1 ;

      // anything does here applies to Client1
      hFile = FileOpen ("C:\mytest.txt", FM_WRITE)
      FileWriteLine (hFile, "This file should show up in the Client1.");
      FileClose (hFile);
} // automatically disconnect target machine

But it doesn't - and the reason is perfectly straight forward - but not necessarily clearly documented.

The Connect() command specified which Agent partner will receive the "application commands". The User's Guide (p. 283) describes this correctly; the description of the Connect() function in the Language Reference is misleading.

Not every command is an application command. To determine if a command is an application command, try running the command locally with the "Print Agent Calls" option selected in the Runtime Dialog. Here is a quick example

main()
{
	//This is the runtime equivalent to selecting Print Agent
	//Calls in the Runtime Dialog.
	boolean bTrace = SetAgentTrace(true) ;

	// this is an application (Agent) call - it will appear in the results file.
	Desktop.Exists () ;

	// this is NOT an application call - it will always run locally.
	HFILE hfile = FileOpen( "C:\mytest.txt", FM_READ ) ;

	//Restoring the previous Trace setting
	SetAgentTrace(bTrace) ;
}

That FileOpen() is not reported as an Agent call serves as good evidence that it will always run locally. It sure would be nice if there were a list of which commands go through the Agent, and which do not. All I can find in the documentation is that system functions [SYS_???()] execute in the Agent process; intuitively, anything that directly manipulates a window also has to be in the Agent process. As for the rest; try them and find out!

So to create a file on the target machine, we have to do something else. There are three alternatives which leap to mind.

The easiest, conceptually, is to create the file locally using a network file path. For example, working in the world of Win32, you could open a handle to the file \\TargetMachine\Share\Subdir\myfile.txt; then treat that file just as if you had opened it locally. Alternatively, on your server, map a drive letter to the client machine, and use a file path based on that ("F:\Subdir\myfile.txt"). In the Unix world, you can do the same sort of thing - specifying full paths, or creating symbolic links, or whatever.

Of course, with multiple clients, you need to suddenly worry about which path to use. I would deal with this by creating records for each of the clients, with a field for the name and a field for the path to use. Your scripts use calls like Connect( MyClient.Name ) and theDocument = MyClient.Path + "mytest.txt" - and you set MyClient to the appropriate record using your favorite method [ compiler.html discusses how you might do it with compiler constants ].

Option number two is to run an application on the client to manipulate the file. For instance, you might open a copy of Notepad on the client, load the file, change the text, save it, etc. This is clumsy, and involves some extra work (you have to worry about getting your editor closed up correctly and so forth) but it does preserve the local file paths for you - which may be an advantage. This method is especially important if you can't be sure what the path to the file will be.

Option number three is to manipulate the file locally, but use FTP or some similar protocol to move the file back and forth between the client and the server. I don't see any advantage that this has over the first method, and the work involved in configuring your machines for the transfer is likely to be far more than writing a correct frame for the editor suggests in option two. It did leap to mind though - this probably says more about my convoluted thinking that the practicality of the suggestion.