2.1.1 Invoking Cogsys

Part of this information was given in 1.3 Running Cogsys and is reproduced here with more detail.

This is the full syntax of the Cogsys program:

cogsys [-v | testlist [outfile] | -l labelfile ]

The `-v' option simply returns the version of the program and quits.

Cogsys needs to know four important things whenever it starts up:

1. Where to get its testlist (testlist name)
2. What to call its testlist (testlist label)
3. Where to write its outfile (outfile name)
4. What to call its outfile (outfile label)

At the top of the outfile, before any data is written, Cogsys will write the testlist label and outfile label. These labels may be simply the name of the file, but they need not be. In a networked installation, labels are the only way to distinguish the real, data-host names of the file from the local client names (particularly since the local client is most likely running some variant of MS-DOS and limited by the 8.3 filename restrictions, which the data host won't be).

For clarity, the search path for all four items are enumerated below. The phrase "filename ok" implies that the file exists, is readable to Cogsys, and has a non-null contents. If Cogsys can open the file but can not find a valid name in it (for example, the file is empty), it stops with a runtime error (and does not attempt to check the next option on the search path). This ensures that files are not quietly labelled with incorrect names.

1. Testlist Name
   1. first command line argument
   2. environment variable COGIN
   3. default filename `COGSYS.IN'

2. Outfile Name
   1. second command line argument
   2. environment variable COGOUT
   3. default filename `COGSYS.OUT'

3. Testlist Label
   1. if `-l labelfile' given, labelfile ok, then first line of labelfile
   2. environment variable COGINLABEL
   3. if `KEEPFILE.TMP' ok, then first line of `KEEPFILE.TMP'
   4. name of testlist

4. Outfile Label
   1. if `-l labelfile' given, labelfile ok, then first line of labelfile
   2. environment variable COGINLABEL
   3. if `KEEPFILE.TMP' ok, then first line of `KEEPFILE.TMP'
   4. name of testlist

The environment variables and labelfiles allow control programs to invoke Cogsys without arguments but still have Cogsys label outfiles properly.

For example, here our Pibterm scripts create the default labelfile, `KEEPFILE.TMP' with the names of the data as they appear on the data host. The testlist is copied from the data host to the client system with the name `COGSYS.IN'. Cogsys is then invoked without arguments, and so writes its output to `COGSYS.OUT' and labels the file using the names in `KEEPFILE.TMP'. To use a label file other than `KEEPFILE.TMP', you would use the `-l labelfile' option.

An alternative possibility would be to use environment names. This speeds up processing by removing the need for temporary files.

C:\COGSYS> set COGINLABEL=mytestlist C:\COGSYS> set COGOUTLABEL=myoutfile C:\COGSYS> cogsys

Here, Cogsys uses the default `COGSYS.IN' and `COGSYS.OUT' files, but labels them with the contents of the environment variables COGINLABEL and COGOUTLABEL.