AUTO 9.1 User Guide

AUTO User Guide

Release 9.1

OSI logo Copyright (c) 1993-2016, Steve J. Martin.
MIT License applies.

Table of Contents

  1. Introduction.
    1. License and Warranty.
    2. Acknowledgements.
    3. How to Contact AUTO's developer.

  2. Installation Guide.
    1. Quickstart Guide to Installing AUTO.
    2. Upgrading AUTO.
    3. Contents of the AUTO file.
      1. ASSERT (absolute)
      2. ASSERT/ADD
      3. AUTO
      4. AUTO (absolute)
      5. AUTO/ADD
      6. AUTO/HTM
      7. AUTO/SKEL
      8. CALENDAR
      9. CALENDAR/SKEL
      10. CHECK-ERRCNT
      11. CONFIG
      12. COPYRIGHT
      13. DAY-OF-WEEK
      14. DENY (absolute)
      15. DENY/ADD
      16. DICTIONARY
      17. EDIT-NUMBER
      18. EXIT/SKEL
      19. FACT/SKEL
      20. FILE-SPEC
      21. GENERIC
      22. GET-EXT-DATE
      23. INIT/SKEL
      24. LICENSE
      25. MAIN/SKEL
      26. PIPELINE
      27. PIPELINE (relocatable)
      28. PREREQ (absolute)
      29. PREREQ/ADD
      30. PROCESSORS/COMPILE
      31. QUERY/SKEL
      32. QWMODE
      33. READ-THIS
      34. RELEASE/HISTORY
      35. RESREG
      36. SAVREG
      37. SCHEDULE
      38. SCRIPT/AMS
      39. SETUP-FIELDS
      40. SET-DEST
      41. SHOW-ID-LINE
      42. SOLAR$SGS
      43. TWMODE
      44. UPDATE-FACTS
    4. Customizing AUTO.
      1. Configuration.
        1. SLEEPTIME
        2. CONTROLFILE
        3. FACTFILE
        4. PREREQFILE
        5. SHOWEXPIRY
        6. ACTIVEFILE
        7. PAGELINES
        8. SITE_DATE_FORMAT
        9. SITE_DATE_SEP_CHAR
        10. SYSID
        11. KEYIN_OK
        12. MAXDELAY
        13. HOST
        14. STARTMAX
        15. STARTWAIT
        16. STARTWARN
        17. COUNTWIDTH
        18. IIKEYIN
      2. Background run.
    5. AUTO Files.
      1. Control File.
      2. Fact File.
      3. Prerequisite File.
    6. Installing AUTO.
      1. Notes for Sites Lacking SSG 23R1.
      2. SSG Release Levels.

  3. User's Guide.
    1. AUTO's Calendar.
    2. AUTO's task list.
      1. The WHEN SGS.
        1. Field #1 -- scheduled time.
          1. Subfields #1 and 2 -- repetitive scheduling.
        2. Field #2 -- task name.
        3. Field #3 -- expiry time.
        4. Field #4 -- expiry replacement task.
        5. Field #5, #6, etc.
          1. Prerequisites: FACT and FILE.
          2. Restriction on Field Lengths.
        6. Examples of WHEN SGSs.
      2. The TASK SGS.
        1. Field #1 -- task name.
        2. Field #2 -- action type.
        3. Field #3 -- action contents.
        4. Field #4 -- delay.
        5. Examples of TASK SGSs.
      3. The TASKID SGS.
    3. Administration Functions in @AUTO.
      1. Simulation (S option).
      2. Database query (Q option).
      3. AUTO Background Run Termination (X option).
      4. AUTO Background Run Refresh (R option).
      5. II Keyins.
      6. Pointing @AUTO at Alternate Software.

1. Introduction.

This documentation is for AUTO version 9.1 released on 2016-03-25.

AUTO is an automated scheduling utility for Unisys 1100/2200 (aka IX-series) computers. AUTO was designed and written by Steve J. Martin.

AUTO allows you to direct that certain tasks be performed at given local times on given days. It is written in Symbolic Stream Generator (SSG) and requires SSG level 23R1B for basic functioning and 24R2 or above for all features:

See the important discussion below on
SSG release levels.

Please note that AUTO works with local time, not UTC.

Writing AUTO in SSG provides several advantages: development time is minimized; considerable functionality can be provided in few lines of code; all Unisys 1100/2200 sites have SSG, as it's part of the Operating System Group of products. SSG also has a disadvantage: since it's an interpreter, it requires more system resources than does compiled code. I don't think you will find this a problem unless you have a very large schedule or a very small or overworked 2200.

You don't have to understand SSG programming in order to use AUTO, but you do have to know how to create Stream Generation Statements (SGSs) using a text editor. If this is new to you, see section 3.1.1 of the SSG Programming Reference Manual (7831 1784-nnn).

AUTO was written in response to the high cost of automated scheduling products such as THE SCHEDULER and DAILY PLANIT. There are things these products do that AUTO does not and they may use fewer system resources. AUTO is designed to encourage "lights out" operation and so doesn't provide much in the way of manual override capability for computer operators. But AUTO has some features that other scheduling packages lack and AUTO does not require you to license products such as ACOB or DMS from Unisys. And AUTO is free, thereby allowing you to experiment with automated scheduling without committing any cash. Which scheduler is best for you will depend on your site's requirements.

With AUTO, you get the level of support and warranty that you've paid for. That is, you're entitled to no support and the product is not warranted in any way! Please carefully read the license and warranty information (see next section). Your use of AUTO means that you accept the terms and conditions described there.

Having said that, I encourage you to forward your bug reports and New Feature Suggestions (NFS). AUTO has shown itself to be highly reliable and future enhancements are anticipated.

1.1. License and Warranty.

This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.

This program is free software. You can use, redistribute and/or modify it under the terms of the MIT License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the symbolic LICENSE element for more details.

1.2. Acknowledgements.

Over the years several people have greatly contributed to AUTO by helping with testing, supplying bug reports and fixes, creating new feature suggestions, critiquing designs, etc. These include Arnold Cameron, Tom Nelson, Erich Staubringer, Bill Toner, and Andrew Williams. I thank them.

1.3. How to Contact AUTO's developer.

   
     Steve J. Martin
     Web site:  http://www.superiorbeing.ca 

2. Installation Guide.

2.1. Quickstart Guide to Installing AUTO.

To get the most from AUTO, you should eventually study this entire manual carefully. Those sites with SSG 23R1B (or above) that are prepared to accept all of AUTO's defaults can quickly get started using AUTO by:

  1. Catalog AUTO*AUTO on disk and copy the AUTO release to it. 500 tracks is sufficient.
  2. Fire up SOLAR and select the "Local Products" option under the "Software Installation" heading. Then enter the file and element name containing AUTO's SOLAR Product Descriptor SGSs: AUTO*AUTO.SOLAR$SGS
  3. Start the SOLAR-generated batch ECL to install AUTO from AUTO*AUTO into SYS$LIB$*AUTO.
  4. Ensure that the @RUN card in SYS$LIB$*RUN$.AUTO is acceptable. (Correct the account and user-id.)
  5. Start AUTO from the console with condition code of 7 to create and initialize its database files: ST AUTO,7
AUTO's default tasks direct it to send a message to the console at various times during the day. These messages show that AUTO is properly installed.

2.2. Upgrading AUTO.

If you've already got AUTO installed and wish to upgrade to a new level, you should perform two tasks before installing the new release.
  1. Save your CALENDAR and SCHEDULE elements. These are unique to your site and installing a new version of AUTO will overwrite them. If you're using a non-default CONFIG element, save that too. After the installation, you can copy these elements back to SYS$LIB$*AUTO.
  2. Read elements READ-THIS and RELEASE/HISTORY to determine if there are any incompatibilities between the old and new releases. Since AUTO has a small user base, correcting dubious design decisions has taken priority over backward compatibility. You may need do some work to convert your calendar, schedule or configuration to a new format.

2.3. Contents of the AUTO file.

AUTO is distributed as a single file. You should copy this file to a catalogued disk file (normally AUTO*AUTO).

Elements described here expect that AUTO will be copied from the release tape to a file called AUTO*AUTO and then installed into a file called SYS$LIB$*AUTO. If this is not what you want, please edit these elements accordingly. I strongly suggest that you use SOLAR to install AUTO into SYS$LIB$*AUTO as a local product.

The following sections describe each element in the AUTO release file.

2.3.1. ASSERT (absolute)

This is a processor that you can place in batch jobs to record some fact in AUTO's fact database. Its most common use is to allow you to place "@ASSERT,R" in a batch run to record when the run finishes successfully. An AUTO task can have successful completion of one or more jobs as a prerequisite for performing some task. This processor is a 'generic processor'. See also DENY, PREREQ, GENERIC.

Note that when you assert a fact it remains asserted until you deny it (via @DENY or by initializing AUTO's fact database). This is because a fact in the database represents a condition in the real world and AUTO can't automatically know when this changes.

When you start AUTO with a condition code indicating that the fact database should be re-created, the background run does this command:

   
      @ASSERT,I  FACTFILE/CREATED   
If you wish to initialize the fact database while AUTO continues to run, I suggest that you also use this command. By always doing it this way, you can use the FACTFILE/CREATED fact to determine the date and time that the fact database was most recently initialized.

2.3.2. ASSERT/ADD

This ECL is @ADDed by the @ASSERT generic processor. It uses FACT/SKEL to add a fact to AUTO's fact database.

2.3.3. AUTO

This is the AUTO background run. You'll need to modify it for your site. See
below.

2.3.4. AUTO (absolute)

This is the main auto processor.

2.3.5. AUTO/ADD

This ECL is @ADDed by the @AUTO generic processor. It uses AUTO/SKEL to generate ECL to perform various AUTO utility functions.

2.3.6. AUTO/HTM

This is the source element of this documentation. It can be downloaded to a PC disk drive or web server and then viewed with a web browser.

2.3.7. AUTO/SKEL

This skeleton is part of the @AUTO processor.

2.3.8. CALENDAR

This is a sample calendar containing DAY SGSs. Note that your calendar must extend at least 33 days into the past and future. You use @AUTO,C to create these SGSs, which will be placed into TPF$.CALENDAR. The version included with release contains a calendar for the year of release and the following two years with no statutory holidays defined.

2.3.9. CALENDAR/SKEL

This SSG skeleton is used by @AUTO,C to generate a calendar. It asks you for the year and puts the year's calendar in symbolic element TPF$.CALENDAR, from where you may then edit it. CALENDAR/SKEL makes no assumptions about statutory (or other company-wide) holidays, so after you've generated a calendar you should edit it to set these. Please note that AUTO requires at least 33 days before and after today's date. Also note that you need never use CALENDAR/SKEL: its purpose is merely to save you the time (and boredom) necessary to create a lot of SGSs manually (which you may do if you wish).

2.3.10. CHECK-ERRCNT

This *COPY proc ensures that global SSG variable ERRCNT$ is clear. SSG does not do ER ERR$ on some syntax errors, but it always updates ERRCNT$.

2.3.11. CONFIG

This element contains AUTO configuration parameters that may be modified to suit your site's needs. See
below.

2.3.12. COPYRIGHT

This element contains a description of AUTO's copyright. It is documentation.

2.3.13. DAY-OF-WEEK

This is *COPYd by CALENDAR/SKEL to determine the day of the week on which January 1 falls. This element is a modified version of the one found on the SSG release tape and documented in Appendix C of the SSG P.R.M. This version (which uses an eight-digit date) will work until 2099.

2.3.14. DENY (absolute)

This is a processor that you can place in batch jobs to remove a fact from AUTO's fact database. It is the inverse of @ASSERT. The most common use of this is to remove facts that were asserted for an earlier time period or processing cycle, and that no longer apply. This is a 'generic processor'. See also ASSERT, PREREQ, GENERIC.

2.3.15. DENY/ADD

This ECL is @ADDed by the @DENY generic processor. It uses FACT/SKEL to remove a fact from AUTO's fact database.

2.3.16. DICTIONARY

These SGSs serve as AUTO's 'relational catalog'. They describe other AUTO SGSs, as well as the values that various SGS fields may take. None of these SGSs are site-configurable--do NOT modify them.

2.3.17. EDIT-NUMBER

This is *COPYd by MAIN/SKEL to return a right-justified edited number in form 999,999,999. The number is given as string input and the number of character positions is also needed.

2.3.18. EXIT/SKEL

This SSG skeleton is used by AUTO,X to tell the AUTO background run to exit the next time it wakes up.

2.3.19. FACT/SKEL

This skeleton is used by @ASSERT, @DENY and @PREREQ to manipulate AUTO's fact database. The fact database is just a file containing facts that describe the current operating environment. The name of this file is defined by the FACTFILE SGS in CONFIG (default is AUTO*FACTS). This file can be created and initialized by starting the AUTO background run (AUTO) with a condition code of 2. This file is in SSG *SAVE format.

@ASSERT adds facts to the file, @DENY removes facts from the file, and @PREREQ allows a batch job to make decisions based on the contents of the fact database. In addition, AUTO uses the fact database to check whether prerequisites specified by the 'FACT' keyword (on WHEN SGSs) are satisfied.

Setting the 'H' option on any of the processors that use FACT/SKEL will cause FACT/SKEL to display help in using that processor. Example: @ASSERT,H

2.3.20. FILE-SPEC

This SSG *COPY procedure is used by @AUTO to interpret file specifications on the processor call.

2.3.21. GENERIC

This is MASM source code for the @AUTO, @ASSERT, @DENY and @PREREQ standalone processors. Yes, all four processors share the same source code and absolute. Assembling and collecting these via the PROCESSORS/COMPILE element creates four absolutes--ASSERT, AUTO, DENY, PREREQ. There is no absolute called GENERIC. When you call any of these processors, it decodes the ELT$ table and pipes it into a temporary file with @USE name PL$$ (via the PIPELINE subroutine). Then the processor figures out its own absolute name (via ER INFO$) and does "@ADD SYS$LIB$*AUTO.xxxxxx/ADD", where xxxxxx is its absolute name. Three of the @ADD elements (ASSERT/ADD, DENY/ADD, PREREQ/ADD) each fire up SSG skeleton FACT/SKEL; the fourth @ADD element (AUTO/ADD) fires up SSG skeleton AUTO/SKEL. The generic processor is a method by which you can write processors in SSG. If you want the generic processor to @ADD from a file other than SYS$LIB$*AUTO, then change the tag ADDFILE in GENERIC and re-create the absolutes via PROCESSORS/COMPILE.

2.3.22. GET-EXT-DATE

This SSG *COPY procedure converts an ISO 8601 internal date (format YYYYMMDD) to a site-standard external format date as specified by the SITE_DATE_FORMAT and SITE_DATE_SEP_CHAR configuration parameters (examples: YYYY-MM-DD, MM/DD/YYYY).

2.3.23. INIT/SKEL

This generates AUTO intialization ECL for the AUTO background run (@AUTO,B).

2.3.24. LICENSE

This contains the MIT License under which this software is distributed.

2.3.25. MAIN/SKEL

This is AUTO's main SSG skeleton, which runs continuously in the AUTO background run. It wakes up periodically to perform scheduling tasks. MAIN/SKEL exits only in response to the HALT action type on the TASK SGS or in response to the @AUTO,X processor call submitted by another run. @AUTO,B generates the call to MAIN/SKEL.

2.3.26. PIPELINE

This is a MASM subroutine that assigns, opens, writes and closes the pipeline file. It's called by GENERIC. The pipeline file is a temporary (@ASG,T) file called PL$$xxxxxx (where xxxxxx is the processor name); an @USE name of PL$$ is also attached. For more information on pipelining, see "Simulating UNIX Pipelines" in Unisphere, March 1993, and "Techniques for Implementing UNIX-style Pipelines on the 1100/2200" in UNITE 1100/2200 Proceedings Journal, Fall 1994.

2.3.27. PIPELINE (relocatble)

This is a relocatable produced by assembling the PIPELINE symbolic.

2.3.28. PREREQ (absolute)

This is a processor that you can place in your batch jobs to force them to wait until some fact(s) is true (i.e., @ASSERTed) in AUTO's database. The most common use of this is to make an active job wait until prerequisite condition(s) obtain. You can also use this processor to @JUMP rather than wait if the prerequisite(s) are not met (see the 'I' option). Note that this is a standalone prerequisite enforcer. The AUTO background run will also enforce prerequisites via the 'FACT' and 'FILE' keywords on the WHEN SGS. Thus, you may choose never to use @PREREQ. It's included just in case you find it useful to enforce some prerequisite checking by jobs other than AUTO. This is a 'generic processor'. See also ASSERT, DENY, GENERIC.

2.3.29. PREREQ/ADD

This ECL is @ADDed by the @PREREQ generic processor. It uses FACT/SKEL to check AUTO's fact database and wait (or @JUMP) if the prerequisites specified on the @PREREQ call are not all met.

2.3.30. PROCESSORS/COMPILE

This assembles and collects AUTO's four processors (@ASSERT, @AUTO, @DENY, @PREREQ), as well as the procs and subroutines they require. This ECL assumes that the AUTO release file has been copied to AUTO*AUTO. If not, change the 'AUTO$' @USE name.

2.3.31. QUERY/SKEL

You call this SSG skeleton via @AUTO,Q. It will show what facts have been asserted (via @ASSERT) and any tasks that are waiting on the completion of which other tasks (or on the existence of files). This is useful for troubleshooting.

2.3.32. QWMODE

This is a MASM proc used by PIPELINE.

2.3.33. READ-THIS

This is the first element you should read from the AUTO release.

2.3.34. RELEASE/HISTORY

This documents the changes made with each release of AUTO.

2.3.35. RESREG

This is a MASM proc used by PIPELINE.

2.3.36. SAVREG

This is a MASM proc used by PIPELINE.

2.3.37. SCHEDULE

This contains the WHEN and TASK SGSs, which define AUTO's schedule. Thus, it's unique to each site. The version included with the release is a trivial version that you can use to prove that AUTO is functioning; it should work for any site and does no harm. You must create your own version tailored to your site's needs.

2.3.38. SCRIPT/AMS

This is two AMS scripts that support the AMS action type on the TASK SGS. The scripts are identical, except that AUTO#1 handles the primary instance and AUTO#2 handles the secondary instance. If you have only one console running AMS, then you don't need AUTO#2. Note that these scripts are looking for "privileged Exec" messages from a run called AUTO, AUTOA, etc. This is to ensure that unauthorized users don't take advantage of the primary script's willingness to submit any keyin! If you don't have Smart Console (or SP-AMS), then you can't use these scripts and so you should not use the 'AMS' action type on your TASK SGSs.

2.3.39. SETUP-FIELDS

This is *COPYd by AUTO's SSG skeletons to create global variables from RELATION SGSs (see DICTIONARY). My December 1992 Unisphere article, "A Relational Approach to SSG", describes this along with the RELATION SGSs.

2.3.40. SET-DEST

This is *COPYd by AUTO's SSG skeletons. It sets global variable DEST to 'Z' or 'O' depending on whether the skeleton is running in demand or batch, respectively. This enables *ACCEPT and *DISPLAY statements to be directed to the demand terminal or system console.

2.3.41. SHOW-ID-LINE

This is *COPYd by FACT/SKEL (used to implement the @ASSERT, @DENY and @PREREQ processors) and AUTO/SKEL (used to implement @AUTO). It prints a processor identification line.

2.3.42. SOLAR$SGS

These SGSs direct SOLAR to install AUTO as a local product.

2.3.43. TWMODE

This is a MASM proc used by PIPELINE.

2.3.44. UPDATE-FACTS

This SSG *COPY procedure updates the fact database (normally AUTO*FACTS). It's used by MAIN/SKEL and FACT/SKEL.

2.4. Customizing AUTO.

2.4.1. Configuration.

AUTO's configuration is maintained in CONFIG. It contains seven site-configurable SGSs. You may modify these if you wish.

2.4.1.1. SLEEPTIME

This SGS tells AUTO how many seconds to sleep between checks of its schedule. Setting this to a high value means that the delay between the scheduled time of a task and its actual performance may be too long. Setting this to a low value means that AUTO uses more system resources (because it checks more often). The default is 120 seconds. Find the tradeoff that's best for your site.

2.4.1.2. CONTROLFILE

This SGS describes the file that the AUTO background run uses to record the last date and time it checked the schedule. The first field describes the file name. The second field describes the placement attributes used to catalog the file.

2.4.1.3. FACTFILE

This SGS names the file that AUTO, @ASSERT, @DENY and @PREREQ to store facts that you assert about your operating environment. The first field describes the file name. The second field describes the placement attributes used to catalog the file.

2.4.1.4. PREREQFILE

This SGS names the file that AUTO uses to store currently unsatisfied prerequisites. The first field describes the file name. The second field describes the placement attributes used to catalog the file.

2.4.1.5. SHOWEXPIRY

This SGS tells AUTO whether to display a console message whenever a task expires. Allowable values are YES or NO. The default is YES.

2.4.1.6. ACTIVEFILE

This SGS specifies the name of a file that the AUTO background run will @ASG,CP to ensure that only one copy of AUTO is active at a time. (The Exec allows only one run to have a particular file in the to-be-catalogued state at any time.) AUTO deletes this file (@FREE,D) when it terminates. The default file name is AUTO*AUTO-ACTIVE, but you may use any file name that is not normally catalogued on your system.

2.4.1.7. PAGELINES

This SGS specifies the number of lines on a printed page. It's used by the detailed simulation. You should set this to a suitable value for the printer to which you'll sym detailed simulation reports.

2.4.1.8. SITE_DATE_FORMAT

This SGS specifies the external date format. Allowable values are 'ISO' (YYYY MM DD), 'USA' (MM DD YYYY), and 'GBR' (DD MM YYYY). The default is ISO.

2.4.1.9. SITE_DATE_SEP_CHAR

This SGS specifies the site-standard date separator character. In combination with SITE_DATE_FORMAT, it determines the external date display format. The default is minus sign (-).

2.4.1.10. SYSID

This optional SGS specifies the system name (1 to 6 characters). If omitted, the Exec's configued system-id ([SYSTEM$,1,1,2]) is used.

2.4.1.10. KEYIN_OK

This optional SGS specifies an acceptable keyin for AMS action on TASK SGSs. Multiple KEYIN_OK SGSs may be included. If omitted, all keyins are acceptable.

2.4.1.12. MAXDELAY

This optional SGS specifies the maximum delay in seconds that may be used on TASK SGSs. This value must be between 1 and 999. The default is 10 seconds.

2.4.1.13. HOST

These optional SGSs specify the host-ids that participate in a Multi-Host File Sharing (MHFS) system. If use you the MULTI_HOST, MULTI_HOST_ID or MULTI_HOST_STAT scheduling attributes, you should add HOST SGSs to your configuration. The default configuration contains commented-out HOST SGSs. This parameter may be overridden on the TASK . . . STRT SGS.

2.4.1.14. STARTMAX

This optional SGS specifies the default number of attempts when @START gets error 2 (file access denied). It must be between 1 and 999. If this parameter is omitted, it defaults to 1 (i.e., no retry). This parameter may be overridden on individual TASK . . . STRT SGSs.

2.4.1.15. STARTWAIT

This optional SGS specifies the default number of seconds to wait between @START attempts when error 2 (file access denied) is received. It must be between 1 and 999. If this parameter is omitted, it defaults to 10. This parameter is ignored if STARTMAX is 1. This parameter may be overridden on individual TASK . . . STRT SGSs.

2.4.1.16. STARTWARN

This optional SGS specifies whether to show a warning message on the console when @START gets error 2 (file access denied) but more attempts are allowed. (AUTO always displays an error message on the console if an @START fails and that failure is final.) It must be YES or NO. If this parameter is omitted, it defaults to NO. This parameter is ignored if STARTMAX is 1. This parameter may be overridden on individual TASK . . . STRT SGSs.

2.4.1.18. COUNTWIDTH

This optional SGS tells AUTO how many character positions to use when displaying operational counters in long format on the console or printer. The minimum value is 5 and the maximum and default values are 14. Here is the maximum counter value that can be displayed for the various reasonable values of COUNTWIDTH:

COUNTWIDTH Max Value
59,999
699,999
7999,999
99,999,999
1099,999,999
11999,999,999
139,999,999,999
1434,359,738,367

Although it is allowed, it does not make much sense to specify a value of 8 or 12 here. These reserve space for a leading comma, but this will never occur.

2.4.1.19. IIKEYIN

This optional SGS tells AUTO whether to enable II keyins. Allowable values are YES or NO. The default is NO. If set to YES and SSG level is below 24R2, AUTO will issue a warning message and ignore this.

2.4.2. Background run.

AUTO is active only when its background run is up. (Exceptions: @ASSERT, @DENY, and @PREREQ do not require that the background run be up; nor does the simulate function.) The background run, normally called AUTO, continuously executes an SSG skeleton called MAIN/SKEL. MAIN/SKEL wakes up periodically and checks whether any tasks have "come due" since it went to sleep. If so, MAIN/SKEL executes these tasks. Then MAIN/SKEL sleeps again. The length of AUTO's sleep, and how to change it, is described above (SLEEPTIME SGS).

The AUTO background run is an element called AUTO, which you copy to a file from where it can be started. Normally this would be SYS$LIB$*RUN$ (the SOLAR$SGS element tells SOLAR to copy it to this file).

Notice that the ECL in AUTO is simply '@AUTO,B' to generate the background run ECL and '@ADD TPF$.AUTOSAVE' to execute it. If you need to change background run ECL, look at AUTO/SKEL and INIT/SKEL.

You may wish to make the following changes to the AUTO run:

The first time you start AUTO you must force creation of all files via:

   
      ST AUTO,7 
Subsequent starts of AUTO should normally be without any condition code setting:
   
      ST AUTO   
To terminate AUTO, call the @AUTO processor with the X option:
   
      @AUTO,X   
Or if you have II keyins turned on, you may use II grunid HALT (or II grunid TERM) to accomplish the same thing.

You may also instruct AUTO to terminate itself at a given future time by using the HALT action type.

Normally, each time the background run starts it considers tasks whose times fall between the time it previously terminated and its start-up time. This ensures that tasks are not missed because AUTO or the system was down for a short period of time. (Restriction: AUTO assumes that its down-time will never be more than 24 hours.) If you do not want this re-consideration of missed tasks, then start the background run with any condition code that will intialize the control file (e.g., 4).

If you change AUTO's schedule, calendar or configuration, you can force AUTO to read the new elements without terminating the background run via:

   
      @AUTO,R   
Such a 'refresh' will also re-read all other elements used by the background run (MAIN/SKEL, DICTIONARY, SSG absolute, etc.). Or if you have II keyins turned on, you may use II grunid REFR to accomplish the same thing.

You may also instruct AUTO to refresh itself at a given future time by using the REFRESH action type.

2.5. AUTO Files.

AUTO uses three files to maintain status information. These are reused each time the background run is started unless a condition code value specifies that one or more of them be re-catalogued (see previous section).

All three files are data files in SSG *SAVE format.

2.5.1. Control File.

AUTO uses this file to keep track of the last time it checked the schedule. This allows it to pick up where it left off after being down. @AUTO,X will write an SGS to this file to tell the background run to terminate normally while @AUTO,R will write an SGS to this file to tell the background run to refresh itself.

The CONTROLFILE configuation SGS specifies file name and placement for this file. The default file name is AUTO*CONTROL.

2.5.2. Fact File.

AUTO uses this file to keep track of facts that you wish to assert about your operating environment. This supports the FACT keyword on WHEN SGSs. This file is updated by @ASSERT, @DENY, and the ASSERT and DENY action types on TASK SGSs.

The FACTFILE configuation SGS specifies file name and placement for this file. The default file name is AUTO*FACTS.

2.5.3. Prerequisite File.

AUTO uses this file to keep track of unsatisfied prerequisites.

The PREREQFILE configuation SGS specifies file name and placement for this file. The default file name is AUTO*PREREQS.

2.6. Installing AUTO.

To install AUTO, you must install four types of components--the background run, the SSG skeletons and ECL, the processors, and your SGSs that instruct AUTO when and how to perform tasks (CALENDAR and SCHEDULE). The SOLAR$SGS element provides SGSs which you can use to install AUTO as a local product into SYS$LIB$*AUTO. I strongly suggest that you do this.

The SOLAR$SGS element specifies that the four processors (@AUTO, @ASSERT, @DENY and @PREREQ) are not accelerated. This allows you to update and pack the file without having to reinstall it afterwards. You will sometimes wish to update this file because it contains your calendar (CALENDAR) and task list (SCHEDULE), and these will undoubtedly change from time to time. With acceleration the product must be re-installed if the start address of an absolute changes and this will usually happen if the file is @PACKed. So I avoid acceleration.

The SOLAR$SGS element specifies that the background run be copied to SYS$LIB$*RUN$. It also updates AUTO$START so that AUTO will be started automatically after a boot.

In addition, if you have Smart Console (or SP-AMS) you may install AUTO's AMS (Autoaction Message System) scripts. Merge the script element into your AMS source database, use BADB to create a new AMS object database, and then install and activate it on your PC Console or SPO Console. AUTO was designed for use with AMS, so it is highly recommended that you use them together.

All AUTO SSG skeletons, and runstreams with version name of ADD, are normally placed into a file called SYS$LIB$*AUTO. This serves as the "product file" for AUTO. I suggest that you use the SOLAR local install process and the SOLAR SGSs provided (SOLAR$SGS). Locally installing SYS$LIB$*AUTO means it will be saved by the library save and so can be made available very quickly after an initial boot.

If this file name is unacceptable, you may change it but great care must be taken. You must find and modify every occurence in these symbolic elements:

Then you must re-create the four processors (@AUTO, @ASSERT, @DENY, and @PREREQ) via the PROCESSORS/COMPILE element.

2.6.1. Notes for Sites Lacking SSG 23R1B.

This version of AUTO requires SSG 23R1B (or above), because it uses the DATE$ SGS. If your site is on a lower level of SSG, the only way you can run this is to obtain and install SSG level 23R1B (or above). If you don't wish to install it over top of your current version, then local install it to a different location and follow the directions in Pointing @AUTO at Alternate Software below.

2.6.2. SSG Release Levels.

For maximum reliability, I strongly recommend that you use a recent SSG release (24R2 or above) with AUTO. This release of AUTO was developed and tested with SSG 24R3.

Please note that scheduling based on Manufacturing Control Number (MCN) requires SSG level 24R2 or above.

Please note that the II keyin feature is available only if your are running SSG level 24R2 or above.

Please note that scheduling based on Multi-Host File Sharing (MHFS) attributes requires SSG level 23R8 or above. If using any SSG below 23R8, the MULTI_HOST clause will always equal NO and any MULTI_HOST_ID and MULTI_HOST_STAT clauses will evalaute to FALSE.

Please note that SSG levels 23R1 and 23R1A had year 2000 problems, and AUTO will not work with them.

3. User's Guide.

Using AUTO requires that you customize two symbolic elements--your calendar and your schedule of tasks. You use a text editor (such as @ED or @IPF) to create the elements in a form that SSG can read as Stream Generation Statements (SGSs).

When the AUTO background run starts, MAIN/SKEL extensively edits your input SGSs, particularly the DAY, WHEN, TASK and TASKID SGSs. If errors are found, AUTO terminates. You can use the simulator (@AUTO,S) to test a new set of SGSs while the AUTO background run continues to work with your production set.

Since AUTO copies the SGSs to TPF$ when the background run starts or refreshes, you must either terminate and re-start AUTO (@AUTO,X and ST AUTO) or refresh AUTO (@AUTO,R) if you want it to pick up a new version of its SGSs.

3.1. AUTO's Calendar.

AUTO uses the DAY SGS, located in a symbolic element called CALENDAR, to learn about today, yesterday and tomorrow. These SGSs must describe today and at least 33 past and future days. Dates must be in ascending order. I suggest that you create a calendar that describes one or two years, so you won't have to update it very often. The AUTO background run warns you when you are within 10 days of having fewer than 33 future days remaining in your calendar. So AUTO's calendar will never unexpectedly "run out" of days. The DAY SGSs record various attributes about each day:

The four types of days (work, bank, batch, online) allow you to group together days with similar characteristics. Then you can instruct AUTO to perform certain tasks only on certain types of day. For example, you might run a batch cycle every night Monday to Friday. So by setting all but Saturdays and Sundays as batch days in the calendar, you can cause AUTO to perform some tasks only on those days.

When you generate a calendar with @AUTO,C and CALENDAR/SKEL, certain assumptions are made about which days of the week are which type of day:

These defaults may not be appropriate for your site. To change them edit the CONFIG element, setting the WEEKDAY SGSs field values to YES or NO, as appropriate. Then re-create CALENDAR.

Fortunately, you don't have to create the calendar manually. To create a calendar, type in demand:

   
      @AUTO,C   
@AUTO,C runs the SSG skeleton CALENDAR/SKEL, which will solicit a four-digit year and then will generate a calendar for that year. The output calendar is placed in TPF$.CALENDAR, from where you copy it to AUTO's product file (normally SYS$LIB$*AUTO).

Before copying the output calendar, you may wish to edit it to change the settings for work, bank, batch and online days for exceptional days (such as statutory holidays). CALENDAR/SKEL cannot be smart enough to know that your company doesn't work on December 25, so you must edit the calendar for such dates. Then you can copy it to AUTO's product file.

Note that in order to force AUTO to pick up your new calendar, you must terminate and re-start the background run.

3.2. AUTO's task list.

In order for AUTO to do something useful, you must tell it what you want done. You do this by creating WHEN and TASK SGSs (and optionally TASKID SGSs) in element SCHEDULE. The WHEN SGSs tell AUTO when to perform tasks. The TASK SGSs tell AUTO how to perform tasks. The optional TASKID SGSs document the purpose of the tasks given on TASK SGSs.

The advantage of distinguishing between when and how to perform a task is that you are likely to have some tasks that must be done at many different times. Although you may specify numerous conditions for performing the task (i.e., many WHEN SGSs with the same task name), you only have to define the contents of the task in one place (its TASK SGSs). This makes maintenance simpler should the content of the task change in the future.

3.2.1. The WHEN SGS.

Each WHEN SGS consists of at least five fields, described in the following sections. You may include as many WHEN SGSs as you need, but they must be in ascending order by scheduled time (field #1).

Please note that AUTO works with local time, not UTC.

Note that time fields on WHEN SGSs can be expressed with or without the seconds portion (which will be assumed to be zero when omitted). Thus, these four SGSs are equivalent:

   
      WHEN  13:00:00  TASK1  13:15:00  \  DAY=ALL   
      WHEN  13:00     TASK1  13:15     \  DAY=ALL   
      WHEN  13:00:00  TASK1  13:15     \  DAY=ALL   
      WHEN  13:00     TASK1  13:15:00  \  DAY=ALL   

3.2.1.1. Field #1 -- scheduled time.

The first field describes the local time at which AUTO is to schedule the task. You supply this in format 'hh:mm:ss' using a 24-hour clock. Example: 13:47:02

Note that because AUTO wakes periodically from its sleep to check for tasks, a task will be performed somewhat later than its scheduled time (how much later depends on the setting of the AUTO configuration parameter SLEEPTIME and "the luck of the draw").

3.2.1.1.1 Subfields #2 and 3 -- repetitive scheduling
This field has two optional subfields that allow tasks to be schedule repetitvely. Subfield 2 specifies that the task is to be repeated every N minutes. Subfield 3 specifies a cessation time for the repetition. For example:
   
      WHEN  08:00:00,30,17:00:00  TASK1   +10  \  DAY=ALL   
TASK1 is executed every 30 minutes between 8 a.m. and 5 p.m. (and expires at 8:10 to 5:10, respectively).

If subfield 2 is omitted, then it defaults to zero, which means no repetition. If supplied, it must be an integer between 1 and 1440.

Subfield 3 is meaningful only if subfield 2 is specified. If subfield 2 is specified but subfield 3 is omitted, then it defaults to the subfield 1 time (i.e., repeat around the clock). Subfield 3 can be expressed in any of the supported time formats (HH:MM, HH:MM:SS or +MIN).

Use of this feature requires that an internal sort be done to order the items by ascending schedule time. This sort uses the original WHEN occurrence number as a tiebreaker when multiple WHENs have the same scheduled time. This preserves the input order of user-created WHEN SGSs. It also controls the order of scheduling internally-created items for repetition: The occurrence number of the WHEN SGS that specified the repetition will be used. This means that, when multiple WHENs specify the same schedule time, items generated for repetition will be scheduled before user-submitted items if the time is later than the original WHEN time; otherwise, they will be scheduled after. You are strongly advised not to count on any specific behavior as to the order that repetitive items will be scheduled when several items are to be scheduled at the same time. All that is guaranteed is that repetitive items will be scheduled at the specified time.

3.2.1.2. Field #2 -- task name.

The second field on the WHEN SGS specifies the name of the task. This may be a character string (letters, numbers, underscores) of up to 16 characters in length. This name is used to relate WHEN SGSs to TASK SGSs. That is, every task name on a WHEN SGS requires at least one TASK SGS with that task name; it may optionally also have at most one TASKID SGS that describes what the task does. AUTO is case-insensitive, so 'JK4BOOT' is the same task as 'jk4boot', 'JK4Boot', etc.

The task name field may also be a backslash (\), indicating that the field is null. In this case, there is no task to be performed. This is useful when you only wish to do something only upon task expiry.

3.2.1.3. Field #3 -- expiry time.

The third field describes the local time at which the task expires. A task that is waiting on one or more prerequisite conditions (see below) might wait forever unless there is some method of stopping it. The expiry time provides this.

You enter expiry time in either an absolute format using a 24-hour clock ('hh:mm:ss' or 'hh:mm') or as a forward relative time in minutes ('+minutes'). A relative time is relative to the task's scheduled time and must be an integer from 0 (immediate expiry) to 1440. These two WHEN SGSs are equivalent:

   
      WHEN  13:00:00  TASK1  13:15:00  \  DAY=ALL   
      WHEN  13:00:00  TASK1  +15       \  DAY=ALL   

Since there is no expiry date, the expiry time will always be within 24 hours. If the expiry time is exactly equal to the scheduled time, then the task expires immediately if its prerequisites are not all met.

If you wish the task never to expire, then enter it as null ('\').

Please note that expiry time affects tasks that may wait on one or more prerequisite conditions. These are tasks that use the 'FACT' and 'FILE' keywords on the fifth and following fields on the WHEN SGS. If no prerequisites are specified, the task is immediately performed, assuming that it meets the other criteria specified on the fifth and following fields.

Also note that when AUTO starts up it enforces the expiry time when scheduling tasks that were missed because AUTO had been down; this is done irrespective of whether or not the missed task has prerequisites. Thus, use of a forward relative expiry time is recommended for repetitvely scheduled tasks:

   
      WHEN  08:00,30,17:00  FASCPY  +20  \  DAY=ALL 
In this example, task FASCPY is performed every 30 minutes between 8 a.m. and 5 p.m. But it expires 20 minutes after it's scheduled. This ensures that if AUTO is down during the day, it won't run it multiple times when it is brought back up.

3.2.1.4. Field #4 -- expiry replacement task.

The fourth field specifies the name of a task to be performed if this WHEN SGS expires. This allows you to specify an alternate course of action to be taken in case of expiry. This field is meaningful only if an expiry time applies to the WHEN SGS (see previous section). The task name given must be found on at least one TASK SGS.

If you don't wish any task to be performed upon expiry or if the expiry time is null, then set this field to null ('\').

3.2.1.5. Field #5, #6, etc.

The fifth field, and all other fields after it, allow you to specify conditions under which the task will be performed. If you specify more than one condition, then all must be met (i.e., their truth values are logically ANDed together). If all conditions are not met, then the task is skipped.

Conditions are specified via a "<keyword><operator><value>" syntax with no imbedded spaces. Examples:

   
      DAY=MON   
      YYYYMMDD>19990901 

The fifth and subsequent fields can have subfields that specify alternate ways (OR conditions) of satisfying the conditions. Examples:

   
      WHEN  22:45:00  TASK1  \  \         DAY=MON,DAY=TUE   
      . 
      WHEN  22:45:00  TASK2   \ 23:45:00  ONLINE=YES  ; 
                                          BATCH=NO,FILE=SJM*F1  
TASK1 will be performed if and only if it's Monday or Tuesday. TASK2 will be performed if and only if it's an on-line day and (either it's a non-batch day or SJM*F1 arrives before 23:45). Note that on non-batch days, TASK2 will not wait for SJM*F1 because there is no need: BATCH=NO is true and so it can proceed immediately.

If there are no conditions (i.e., if it's to be done at a fixed time every day), then code field #5 as 'DAY=ALL'.

Most of the conditions you can specify use the calendar to decide whether to perform the task. The following table describes the legal combinations of keywords, operators and values.

Legal Combinations of keyword/operator/value
   
                       Yesterday      Legal              Legal  
      Keyword         & Tomorrow?   Operators            Values 

      DAY                 Yes          = ~         MON to SUN or ALL
      DATE                Yes        < = ~ >       01 - 31 or LAST  
      JULIAN              Yes        < = ~ >       001 - 366
      MONTH               Yes        < = ~ >       01 - 12  
      YYYYMMDD            Yes        < = ~ >       date in YYYYMMDD format  
      WEEK                Yes          = ~         int/int  
      WORK                Yes          = ~         YES or NO
      BANK                Yes          = ~         YES or NO
      BATCH               Yes          = ~         YES or NO
      ONLINE              Yes          = ~         YES or NO
      WEEK_WORK_DAY       Yes        < = ~ >       1 to 7  or LAST  
      WEEK_BANK_DAY       Yes        < = ~ >       1 to 7  or LAST  
      WEEK_BATCH_DAY      Yes        < = ~ >       1 to 7  or LAST  
      WEEK_ONLINE_DAY     Yes        < = ~ >       1 to 7  or LAST  
      MONTH_WORK_DAY      Yes        < = ~ >       1 to 31 or LAST  
      MONTH_BANK_DAY      Yes        < = ~ >       1 to 31 or LAST  
      MONTH_BATCH_DAY     Yes        < = ~ >       1 to 31 or LAST  
      MONTH_ONLINE_DAY    Yes        < = ~ >       1 to 31 or LAST  
      SINCE_WORK          Yes        < = ~ >       1 or higher  
      SINCE_BANK          Yes        < = ~ >       1 or higher  
      SINCE_BATCH         Yes        < = ~ >       1 or higher  
      SINCE_ONLINE        Yes        < = ~ >       1 or higher  
      SINCE_NON_WORK      Yes        < = ~ >       1 or higher  
      SINCE_NON_BANK      Yes        < = ~ >       1 or higher  
      SINCE_NON_BATCH     Yes        < = ~ >       1 or higher  
      SINCE_NON_ONLINE    Yes        < = ~ >       1 or higher  
      PROB                No           =           1 to 99  
      FACT                No           = ~         subj/pred
      FILE                No           =           q*f(c)   
      MCN                 No           = ~         alphanumeric string  
      SYSID               No           = ~         sysid
      NOW_FACT            No           = ~         subj/pred
      NOW_FILE            No           =           q*f(c)   
      MULTI_HOST          No           = ~         YES or NO
      MULTI_HOST_ID       No           = ~         single-letter host-id
      MULTI_HOST_STAT     No           = ~         UP, DN, RV, NC   

Keywords that specify calendar attributes may optionally be prefixed with 'YES_' or 'TOM_' to indicate yesterday or tomorrow, respectively. If you supply neither of these prefixes, then today is indicated.

All keywords may use the EQUALS ('=') operator. As well, some may use the NOT EQUALS ('~'), LESS THAN ('<'), or GREATER THAN ('>') operators. For other keywords, these operators make no sense. Please note that the NOT EQUALS operator is a tilde ('~'), which may not be a printable character on some printers.

Keywords ending in the suffix '_DAY' mean "the n'th ... day of the ...". For example, 'MONTH_BATCH_DAY=2' means the "second batch day of the month." The value is undefined if the day is not that type of day. Thus, the following WHEN SGS clauses are equivalent though the first is preferable because it's more direct):

   
      BANK=YES  
      WEEK_BANK_DAY>0   
      MONTH_BANK_DAY>0  

These types of keywords may also specify LAST: the expression 'WEEK_BANK_DAY=LAST' means "the last banking day of the week." AUTO considers a week to begin on Monday. You can use '~LAST' to specify all days except the last day of the week or month.

Restriction: you may not use the value LAST with the LESS THAN ('<') or GREATER THAN ('>') operators.

Keywords beginning with the prefix 'SINCE_' provide schedule control based on the number of days since the last day of the given type. Values will be GE 1 (e.g., if the day immediately preceding the day in question was a batch day, then SINCE_BATCH_YES will be 1). These counters can be used with yesterday ("YES_") and tomorrow ("TOM_") prefixes and with all AUTO relational operators (=,~,>,<).

The WEEK parameter allows you to specify that the task is to be performed every x'th week of a y-week cycle. For example:

   
      WEEK=1/2  
This says to perform the task only during the first week of a two-week cycle (i.e., during odd-numbered weeks). Weeks are numbered sequentially beginning with week #1 on January 6, 1964 (the week beginning January 1, 1996 is week #1670). The specification 'WEEK=x/y' (where x and y are non-zero whole numbers, with y not less than x) is true if and only if:

x = ( current_week_number modulo y ) + 1

You should try to choose the simplest form of WHEN SGSs that will cause your tasks to be scheduled when and only when you want. Consider these three WHEN SGS clauses:

   
      DAY=TUE   
      YES_DAY=MON   
      TOM_DAY=WED   

Each clause accomplishes the same thing--the task is restricted to Tuesday only, but the first form is preferable because it's simpler.

Examples of Legal Calendar Conditions
   

DAY=ALL . all days DATE=07 . if today is 7th calendar day of month WEEK=2/3 . if today is in week 2 of a 3-week cycle YYYYMMDD~20000101 . if today is not January 1, 2000 ONLINE=YES . if today is an online day WORK=NO . if today is a non-work day WEEK_WORK_DAY=1 . if today is the first work day of week MONTH_BATCH_DAY=LAST . if today is the last batch day of month YES_DAY=MON . if yesterday was Monday TOM_WEEK_BANK_DAY=LAST . if tomorrow is last bank day of week MONTH<03 . during January and February MCN=G2XQZ12 . if Manufacuting Control Number is G2XQZ12 SYSID=PROD01 . if system-id is PROD01 SINCE_ONLINE>2 . if more than two days since most recent on-line day NOW_FACT=JOB1/FIN . if fact JOB1/FIN is now asserted NOW_FACT~JOB2/FIN . if fact JOB2/FIN is not now asserted NOW_FILE=SJM*FILE1 . if file SJM*FILE1 currently exists MULTI_HOST=YES . if multi-host feature is configured MULTI_HOST_STAT~NC . synonym for MULTI_HOST=YES MULTI_HOST=NO . if multi-host feature is not configured MULTI_HOST_STAT=NC . synonym for MULTI_HOST=NO MULTI_HOST_STAT=UP . if MHFS is UP MULTI_HOST_STAT~DN . if MHFS is not DN MULTI_HOST_ID=A . if multi-host-id is A MULTI_HOST_ID~B . if multi-host-id is not B

Three keywords represent non-calendar conditions. The 'PROB=n' condition specifies that AUTO is to perform the task n% of the time. This allows performing some tasks at random. The FACT and FILE keywords are discussed in the next section.

3.2.1.5.1. Prerequisites: FACT and FILE.
The FILE and FACT keywords are the only two that can cause AUTO to wait before performing the task. They are analogous to the NOW_FACT and NOW_FILE keywords, except that AUTO can wait for FACT or FILE clauses to become true.

Normally, AUTO either rejects the task (because at least one of its conditions is false) or performs it immediately. But the FACT and FILE keywords can cause AUTO to wait until the prerequisite condition specified is met. Of course, if some immediate condition is not met, then AUTO will not wait on prerequisites. And AUTO will only wait until the expiry time is reached.

The FILE keyword causes AUTO to wait until the specified file exists. For AUTO's purposes, a file exists when it's catalogued and not assigned to anyone else. For example, the condition

   
      FILE=SJM*CARDFILE(1)  

will cause AUTO to wait until absolute cycle 1 of SJM*CARDFILE exists.

The FACT keyword causes AUTO to wait until the specified fact has been asserted or denied in AUTO's database. 'FACT=' tells AUTO to wait until the fact has been asserted. 'FACT~' tells AUTO to wait until the fact has been denied.

A fact consists of a subject and predicate seperated by a slash ('/') which acts as the copula. For example, you might code the fact "the database save is finished" as 'DBSAVE/DONE'. Subject and predicate must each be one to twelve characters long and contain only letters, numbers, dash ('-') and dollar sign ('$').

You use @ASSERT to record facts in AUTO's database, and @DENY to remove them. When the database save finishes, you (or the batch job) could assert this fact via:

   
      @ASSERT  DBSAVE/DONE  

If an AUTO task was waiting on 'FACT=DBSAVE/DONE', then this prerequisite would now be satisfied and AUTO would perform the task, unless of course the task was also waiting on other still unsatisfied prerequisites.

On the other hand, if an AUTO task specifies 'FACT~DBSAVE/DONE', it will be satisfied only when DBSAVE/DONE is not asserted in AUTO's database. If DBSAVE/DONE is not now asserted, then the prerequisite is immediately satisfied. If DBSAVE/DONE is now asserted, then the prerequisite will be satisfied only when you (or a batch job):

   
      @DENY  DBSAVE/DONE

A special form of @ASSERT or @DENY is to call it with the 'R' option. This indicates that a run wishes to assert (or deny) that it has finished successfully. For example, '@ASSERT,R' is equivalent to '@ASSERT orunid/FIN' (where orunid is the original run-id from the Program Control Table).

The R option can also be used in conjunction with the Y and Z options:

Please note that when a task is waiting on more than one prerequisite and one of them becomes satisfied, it's removed from AUTO's list of unsatisfied prerequisites. Thus, AUTO does not attempt to re-satisfy previously satisfied prerequisites when the final prerequisite is met. This means that a previously satisfied prerequisite need no longer be true when a task's last prerequisite is met.
3.2.1.5.2. Restriction on Field Lengths.
Due to SSG's restriction that internally generated SGSs must not exceed 132 characters in length, AUTO must restrict the size of some fields when using FACT or FILE keywords. The sum of the lengths of these 3 fields must not exceed 50 characters:

3.2.1.6. Examples of WHEN SGSs.

Sample WHEN SGSs
   
     WHEN  17:00:00  TGIF     \         \   DAY=FRI 
     .  
     WHEN  20:00:00  DAILY    02:00:00  DAILY_EXP               ;   
                                            WEEK_WORK_DAY~LAST  ;   
                                            FACT=DBSAVE/DONE
     .  
     WHEN  21:00:00  PAYDAY   \         \   DAY=WED  WEEK=1/2   ;   
                                            NOW_FACT=PAYROLL/APPROVED   
     .  
     WHEN  22:30:00  CLEANUP  \         \   MONTH=01  DAY=FRI   ;   
                                            FACT=CLEAN/FIN      ;   
                                            FILE=CLEANUP*MESS(1)
     .  
     WHEN  23:00:00  VERIFY   \         \   DAY=MON  DATE<08 
     WHEN  23:00:00  VERIFY   \         \   DAY=TUE  DATE<08 
     .  
     WHEN  23:10:00  USELESS  \         \   DAY=TUE   DAY=THU  ;
                                            MONTH>06  WORK=YES  

AUTO will perform the task TGIF on Fridays at 5 p.m.

AUTO will perform the task DAILY on all but the last working day of the week after the database save is done. You would modify the database save job to @ASSERT its successful completion. AUTO begins considering this task at 8 p.m., and will wait only until 2 a.m. (the next morning) for the database save to finish. When 2 a.m. arrives, AUTO will reject this task if the database save is still not done; instead it will perform task DAILY_EXP.

AUTO will perform the task PAYDAY at 9 p.m. on Wednesday of odd-numbered weeks (i.e., during week #1 of a two-week cycle) if fact PAYDAY/APPROVED is asserted. Unlike FACT keyword, NOW_FACT will not wait for a fact to be asserted.

AUTO will perform the task CLEANUP on Fridays during January. AUTO begins trying to satisfy the two prerequisites at 10:30 p.m. and will wait forever, if necessary.

AUTO will perform the task VERIFY on the first Monday or Tuesday of each month at 11 p.m. Notice how including two otherwise identical WHEN SGSs implement a logical OR on the day of the week.

AUTO will never perform the task USELESS because no day can be both a Tuesday and a Thursday. AUTO's edits don't catch such syntactically legal, but contradictory, specifications.

3.2.2. The TASK SGS.

Now that we've specified WHEN to perform a task, we must specify HOW to perform it. The TASK SGS describes this.

3.2.2.1. Field #1 -- task name.

The first field on the TASK SGS describes the task name. Every task specified on a WHEN SGS must be defined on one or more TASK SGSs; otherwise, AUTO will report an error when the background run starts (or when you use the simulator). If you define a task on TASK SGSs and don't use it on a WHEN SGS, AUTO will issue a warning. This is not an error condition because you may wish to define tasks now which you plan to add to the schedule (WHEN SGSs) in the future.

The same task name may be specified on multiple TASK SGSs (in effect a task may have subtasks). When you do this, AUTO performs the specified actions in the order given. Restriction: all TASK SGSs with the same task name must be specified consecutively in the input SGSs.

3.2.2.2. Field #2 -- action type.

AUTO can perform six types of actions: display messages on the console; send console messages to be intercepted by AUTO's Smart Console AMS script (thereby allowing keyins to be entered); start batch jobs via the SSG *CSF command; assert a fact in AUTO's database; deny a fact in AUTO's database; terminate the AUTO background run. The allowable action types are:

You must install AUTO's AMS scripts (element SCRIPT/AMS) in Smart Console if you plan to use the AMS action type. This feature allows AUTO to perform console keyins by asking AMS to enter them. Notice that the AMS scripts require that the message from AUTO be a "privileged Exec" message. This prevents unauthorized users from exploiting them.

The ASSERT and DENY action types work exactly like @ASSERT and @DENY (respectively) except that they're internal to MAIN/SKEL. That is, the ASSERT and DENY action types cause the background run internally to perform the equivalent of the @ASSERT and @DENY processor calls, respectively.

The STRT action type can have optional parameters:

STRT,max,wait,warn

3.2.2.3. Field #3 -- action contents.

The third field contains the contents of the action. This is placed within two single quotes so that SSG will allow imbedded spaces. This is where you tell AUTO what to do. The format of this field will depend on the action type and, of course, on what you want it to do.

This field is required for all action types except HALT and REFRESH, where it is meaningless. If you are including field #4 (delay) on HALT or REFRESH, you must encode field #3 as a backslash (\).

3.2.2.4. Field #4 -- delay.

The fourth field contains a delay in seconds before performing the given action. Within a TASK set, delays are cumulative. That is, if you wait 1 second before performing the first action and then 2 seconds before performing the second action, then the second action will be performed three seconds after the start of performing the task.

3.2.2.5. Examples of TASK SGSs.

Here are TASK SGSs that might go with the sample WHEN SGSs given in the previous section.

Sample TASK SGSs
   
     TASK  TGIF       AMS          ''TB TGIF!!!''   
     .  
     TASK  DAILY      AMS          ''CS A'' 
     TASK  DAILY      AMS          ''ST DAILY'' 
     .  
     TASK  DAILY_EXP  DENY         ''DAILY-JOBS/OK''
     TASK  DAILY_EXP  MSG          ''Insufficient time to run daily jobs!'' 
     .  
     TASK  PAYDAY     AMS          ''ST PAYROL,1''  
     .  
     TASK  CLEANUP    MSG          ''File clean-up is about to start''  
     TASK  CLEANUP    AMS          ''ST FILCLN''
     TASK  CLEANUP    ASSERT       ''CLEANUP/STARTED''  
     .  
     TASK  VERIFY     STRT         ''PROD*ECL.RUN1''
     TASK  VERIFY     STRT,,,YES   '',/U  PROD*ECL.RUN2''   
     .  
     TASK  USELESS    MSG          ''Internal error!  Halting ...'' 
     TASK  USELESS    HALT         \  30
     .  
     TASK  KEYINS     AMS          SS   
     TASK  KEYINS     AMS          BL    1  
     TASK  KEYINS     AMS          T     1  

The TGIF task causes AUTO to ask the AMS script to enter a TB console keyin.

The DAILY task causes AUTO to ask the AMS script to enter two keyins.

The DAILY_EXP task causes AUTO to deny DAILY-JOBS/OK and to send a message to the system console.

The PAYDAY task causes AUTO to ask the AMS script to start a job via an ST keyin.

The CLEANUP task causes AUTO to send a message to the console, then ask AMS to start a batch job, and to assert CLEANUP/STARTED in AUTO's fact file.

The VERIFY task causes AUTO to @START two batch jobs using the SSG *CSF command. Notice that the second @START will have the 'U' option ("@START,/U PROD*ECL.RUN2") and will display warning message on the console if this gets @START error 2 and will be re-tried. If an @START fails and the failure is final, AUTO will always display the error status on the console.

The USELESS task would cause AUTO to display a message and terminate 30 seconds later.

The KEYINS tasks would cause AUTO to submit SS keyin, wait a second and submit BL keyin, and wait another second and submit T keyin.

When using AUTO to start batch jobs, choose the most efficient action type available. If you have Smart Console, the AMS action type is recommended; otherwise, use the STRT action type.

3.2.3. The TASKID SGS.

The optional TASKID SGS allows you to describe the purpose of a task. Its format is:
   
      TASKID  taskname  ''description of the task'' 
Each task defined on TASK SGSs is associated with at most one TASKID SGS. Each task mentioned on a TASKID SGS must also be mentioned on at least one TASK SGS.

If configuration parameter SHOWEXPIRY is YES, AUTO will display the description (if available) of any task that expires, as well as the description of the replacement task (if available). The description displayed will be truncated to 60 characters.

3.3. Administration Functions in @AUTO.

In addition to generating calendars and background run ECL, @AUTO provides several AUTO administration functions. These functions are specified by the option letter on the processor call. You can see all available options by using the help option: @AUTO,H

3.3.1. Simulation (S option).

This invokes MAIN/SKEL in a mode where no tasks will ever actually be performed. It's used to see what AUTO would do were the specified WHEN SGSs actually being used in production on given dates. The simulator can be used to test new or changed WHEN SGSs to ensure that they will perform as intended.

In simulation mode, rather than use the current date MAIN/SKEL will ask you to specify the date. This allows you to test any past or future date covered by the calendar. You can optionally specify a starting time of day if you wish to simulate only the latter part of each day.

The simulator can be used while a production version of AUTO is running; neither will affect the other.

There are two types of simulation. The default, or short, simulation summarizes what tasks will be performed. This summary fits on an 80-column screen. @AUTO,S requests a default (short) simulation.

By calling AUTO with both the S and L options set, you can request a detailed simulation. This prints a report that needs a 132 column form. The report is more detailed in two ways. First, instead of simply summarizing the number of prerequisites on which a task will wait, it lists them. Second, after listing the schedule of tasks, it reports on what the scheduled tasks do.

You may also use the N (no edit) option to suppress the edit of WHEN, TASK, and TASKID SGSs during simulation. This is useful when performing simulations of a schedule you know is syntactically correct because the edit can take a while. However, be careful with this if you're not 100% sure the schedule is correct.

3.3.2. Database query (Q option).

@AUTO,Q displays the contents of AUTO's fact database (normally AUTO*FACTS) or unsatisfied prerequisite file (normally AUTO*PREREQS). It has a simple menu-driven interface and can be used whether the AUTO background run is active or inactive.

3.3.3. AUTO Background Run Termination (X option).

@AUTO,X requests that the AUTO background run terminate the next time it wakes up. @AUTO,X does this by writing an SGS to the AUTO control file (normally AUTO*CONTROL). AUTO checks this file each time it wakes.

3.3.4. AUTO Background Run Refresh (R option).

@AUTO,R requests that the AUTO background run refresh itself the next time it wakes up. @AUTO,R does this by writing an SGS to the AUTO control file (normally AUTO*CONTROL). AUTO checks this file each time it wakes.

3.3.5. II Keyins

II keyins are available if all of the following conditions are met:

The following II keyins are available (where grunid is AUTO's generated run-id):

Keyin Function
II grunid HALT
II grunid TERM
Terminate AUTO
II grunid REFRRefresh AUTO
II grunid BRKPTBreakpoint PRINT$ and print counters (long format)
II grunid RESETPrint counters (long format) and then zero them
II grunid STATShow config highlights and counters (short format)
II grunid STATUSShow config highlights and counters (long format)
II grunid HELPShow list of II keyins

SSG does not fork a separate activity to handle II keyins. AUTO checks for an II keyin each time it awakes. Therefore, it can take up to SLEEPTIME seconds before AUTO is aware of your II keyin. Also note a second II keyin is not accepted until the first is processed. Patience is a virtue.

If AUTO awakes to both @AUTO,X or @AUTO,R and an II keyin, the II keyin will not be performed. @AUTO commands that terminate the main skeleton take precedence.

3.3.6. Pointing @AUTO at Alternate Software.

By supplying file names on field 1 and 2 of the @AUTO call, you can specify use of a different version of AUTO or SSG, respectively. This is useful for testing new schedules, changes to AUTO software, or new releases of SSG.

You may wish to create an AUTO test file for developing new calendars and schedules. This would contain all elements from SYS$LIB$*AUTO along with test versions of CALENDAR and SCHEDULE. If you call your test file AUTO*TEST, then you can point the AUTO simulator at it via:

   
      @AUTO,S   AUTO*TEST.  

If you have new release of SSG you'd like to test, you could use (for example):

   
      @AUTO,S   ,NEW*SSG.         . field #1 defaults   

AUTO always assumes that the SSG absolute name is "SSG".

*EOF*