FileAgent: Wood from the trees

Day 10

So last post we were about to start the FileAgent and test our FileAgent rule and associated C:D process.  First check that your Connect:Direct server is up and running.   You can do this on Windows by using the "CD Admin Tool" that you will find in the start menu for Connect:Direct.  It will show you whether or not the Connect:Direct server is started by showing a green traffic light for up and running and a red traffic light for stopped.  You can start the Connect:Direct server by right clicking the traffic light for your node and selecting "Start".  You can alternatively use the "services" control panel to check/start/stop the Connect:Direct service.

 Start the C:D Requester as we will be using that to monitor the activity of Connect:Direct, and also looking at the statistics files for any possible errors.  Double click the "Process Monitor" in the left hand pane of the requester and fill in the form as follows.

Here you can see that I have set it to update the display of what's happening with Connect:Direct every second.  Also double click the "Select Statistics" in the left hand pane of the Requester and fill in the following way:

Here I'm saying that I want the last 5 minutes worth of statistics and I want that list of statistics updated every minute.  So if anything fails while I'm trying to get the FileAgent rule or process working I can find out what happened quickly.  I find it also convenient to tile the "Process Monitor" & "Select Statistics" windows which you can do by using one of the toolbar buttons on the right in the Requester window.

I also open a file explorer on the directory to be watched by the FileAgent.  In our FileAgent rule the source file should be deleted from the watch directory only after successful transmission of the source file to its destination.  I usually create a test file in the directory above the watch directory and update the contents and save the file before dropping it in the watch directory for FileAgent to see.

Above you can see I'm in the directory above with the candidate test file before dropping it into the watch directory "DataABC".

FileAgent looks at the watch directory every minute depending on the configuration and if it finds a candidate that matches one of its rules it records the fact and decides to come back in another minute to see if the file is still growing in size.  If so it waits again until it believes the file has been finished writing to by either a local application or if it was a file being received by Connect:Direct from a remote node.

So you should start FileAgent and then leave it a minute or so to settle before dropping the updated file in the watch directory.  Then you have to be patient and wait a couple of minutes more before you might see some activity in Connect:Direct.

Open a command prompt and navigate to the FileAgent install directory. In my case that is "C:\Program Files\FileAgent".  Although on Windows the FileAgent is installed as a Windows service with manual startup.  However for testing it is often easier to run the FileAgent from the command line in verbose mode and re-directing the output to a log file.

I waited for a minute or so and then updated the data file using my favourite editor and then copied the file into the watch directory. I then watched the "Process Monitor" window and saw the following indicating that the C:D process was being run:

When the "Select Statisics" window refreshed I found the following:

Here I have highlighted the statistic row of interest showing a record type of "CTRC" which stands for Copy Termination ReCord and a condition code "CC" of 0 indicating that the transfer was a success.  Double clicking on that row will give a more detailed view of the statistic record:

So there you can see a successful transfer of the file to the remote node.

You can stop the FileAgent that you started from the command line either by pressing the CTRL+C keys if you are in a hurry and not worried about properly shutting down the FileAgent.  If you were more concerned about that you would create a file in the installation directory of FileAgent called "shut" which signals to FileAgent it should shutdown.  I consider myself working in a test environment so I use CTRL+C as I am the only one using this particular environment.

If you were to look in the FileAgent.log file that the FileAgent created you will see why the option that created the information was called "verbose".  It is sometimes very difficult to see the wood for the trees when looking at this kind of output. I myself use an editor with syntax highlighting to help me more easily see the things I'm looking for.

 Here I have highlighted in green the fact that the C:D process was submited, and in the next few lines you see that submit command was accepted.  You can also see in the lines above that one that the FileAgent variables get substituted before the C:D process is submitted to Connect:Direct.

So that's FileAgent in a flash.  It can be a bit tricky to set-up initially, but it can save you from having to write batch/wsh/shell scripts and makes it easy for applications to send/recieve data without being too tightly coupled with Connect:Direct.  What could be easier than just moving a file into a directory for it to be sent on its way?  

In many cases you can just use the single Connect:Direct process template you saw earlier for any additional FileAgent rules you might add for Windows/UNIX destinations.  At a later date I will show you how you can use FileAgent together with a script to generate dynamically specialised C:D processes for a variety of platforms while keeping the FileAgent configuration simple.

FileAgent: Rules of the game

Day 9

On Windows you can configure FileAgent by selecting the shortcut on the desktop or using the Start menu "Configure Connect Direct FileAgent".  You should see something like the following:

The FileAgent comes with a default configuration file which is what it is showing above.  You select the configuration you want to work with in the left pane of the application.  In the right pane you have two tabs.  The tab that is showing above is the "FileAgent" tab where we configure it to connect via the API with the Connect:Direct.

We also list the directories we want to FileAgent to watch.  There should be no reason to change the default values that you see above that were already in the configuration, unless they clash with some other software already using those values.  

You can have multiple instances of FileAgent running which would need you to have separate "Gate Keeper" ports for each.  In most cases that would not be necessary. 

By default when FileAgent is running it will use this "Default_Config.ser" configuration file unless overridden by options on the command line if running FileAgent from the command prompt, or by editing the appropriate .lax file to override the arguments that get passed to FileAgent.  If running as a Windows service then that would be the "cdfa$.lax", or the "cdfa.lax" if runing from the command prompt or shortcut on Windows or on UNIX.

If you just use the "Default_Config.ser" then you will not need to override anything.

On the "Rules" tab you can see a "Submit Process Rules" tab within it.  This is where we define our rules to automatically submit C:D processes for the new file detected in the directory that was specified to watch.  If there are any problems with submitting a process from FileAgent the first things to check will be the "Enabled" check-box on this tab and also within the definition of the matching file pattern as can be seen on the next screenshot.

In this rule I have defined a match for all the .dat files within the watch directory.  On detecting a new file that matches this pattern FileAgent will submit the C:D process specified in the "Process Name" field with the arguments to be passed to the C:D process on in the next field.

In my C:D process I have some variables that take their values from the "Process arguments" field within this FileAgent rule.  The C:D process variables are &NODE which is assigned to CD.REMOTE, &FILESPEC and &NAME .  They take their values from some built in FileAgent variables "%FA_FILE_FOUND." and "%FA_NOT_PATH." respectively.  It is important to note that these special FileAgent variable names start with a "%" and end with a "." . Miss off the period at the end of the name and they will not work.

Above you can see the C:D process that is used by the FileAgent rule.  Previously when we sent a test file using the C:D Requester we used the "Send/Receive File" function in the left hand pane of the Requester which presented you with a form which we filled out.  Behind the scenes that form constructed a textual C:D process like the one you see above.

I will go into C:D processes in more detail at a later date.  For now hopefully you see some sort of script with a COPY command where the source of the copy is specified by &FILESPEC and the destination by &NAME .  Also note that the destination node or secondary node (SNODE) is specified by the C:D process variable &NODE .

This means that potentially we could use this single C:D process template for all our FileAgent rules.

If the transfer is successful then the source file is removed as it has been safely received at the destination.

Next post I will explain how to run the FileAgent and test that this rule is working.