Writing script files
====================



You can simplify the task of scanning things which you scan a lot (eg. the
'Temp' directory on your hard drive) by using a script file. VEnd implements
script files by providing an OS ('star') command which performs a scan. This
means that you can use ordinary Obey files as scripts.

The syntax of the OS command is:

  *VEnd_StartScan [<options>] [<path>]

The options are: (defaults in {} brackets)
  -arcfs       Scan archives using ArcFS         {off}
  -close       Close status window after scan    {off}
  -errors      Report errors in log              {off}
  -kill        Kill viruses                      {off} *
  -load        Just load VEnd                    {off}
  -log         Show log window                   {off}
  -prompt      Prompt user if virus found        {off} *
  -quit        Quit VEnd after scanning          {off}
  -report      Report errors                     {off}
  -save        Save log to disc                  {off}
  -skip        Skip viruses                      {on}  *
  -slow        Slow and pointless scanning       {off}
  -suspicious  Include suspicions in log file    {off}
  -wait        Wait for VEnd to finish scanning  {off}

Options marked * are mutually exclusive and the result is undefined if more
than one of them are specified. The options are scanned used OS_ReadArgs so
all the usual rules of this SWI apply.

The '-load' option ensures that VEnd is loaded, and ignores all the other
parameters. If you don't have any other VEnd_StartScan commands before a
VEnd_Prompt command then it's a good idea to do '*VEnd_StartScan -load'
before it - otherwise the VEnd_Prompt command might fail due to VEnd not
being loaded.

Once the VEnd application has been 'seen' by the filer (even if you don't
load it) the VEnd_StartScan command is available for use. VEnd will set up
aliases so that if you issue VEnd_StartScan and VEnd isn't loaded and running
then VEnd will be loaded and/or run before the command is executed.

The command will return immediately (unless -wait is specified), setting a
flag to tell VEnd to start scanning when it receives the next null event. The
command will produce an error if VEnd is already scanning, or if VEnd is
waiting to perform a scan.

If -wait is specified then the command won't return until VEnd finishes
scanning (or someone clicks 'Abort' or quits VEnd).

Remember that if you don't specify -log or -save then there will be no log
file generated, and hence no record of the scan.

You can make script files from Obey files by using this command. If you want
to do several scans and then quit VEnd, for example, you could try:

  VEnd_StartScan -wait ...
  VEnd_StartScan -wait ...
  VEnd_StartScan -quit ...

which would perform several scans in a row, keeping VEnd loaded until the end
of the last scan, when it will be quitted.

You can also have automatic timed scans by using the 'Task alarms' feature
of Rough Time or Alarm. To do a task alarm from Rough Time (version 4.19
or later) simply make an ordinary alarm, but put the OS command you want in
the 'Message' section, prefixed with a '' (that's SHIFT-). eg:

  VEnd_StartScan -skip -close -save scsi::HardDisc.$

Or you could make the task alarm start an Obey file:

  Run scsi::HardDisc.$.!VEnd.Scripts.ScanHD

Remember that if you want to have unattended scans then you shouldn't
specify the '-prompt' or '-report' as these could cause the scanning to stop
and wait for user response.

Because the script files are Obey files, you can include all the other
commands that you can normally put in Obey files. eg. Error, Run, etc.

If you use the '-arcfs' option, then you may like to include a line in your
script to check that ArcFS is loaded. This would be something like:

  RMEnsure ArcFS 0 RMLoad scsi::HardDisc.$.!ArcFS.ArcFS

where you obviously have to replace 'scsi::HardDisc...' with the location of
ArcFS on your disc.

So that you can pause the script file and prompt the user to do things, there
is a command '*VEnd_Prompt [<message>]'. This pauses multitasking and opens a
requester window containing the message. Multitasking resumes when the user
clicks 'OK'. If no parameters are given then a default message is used.

An example script file called 'Example' is included in this directory.
