MIT License applies.
|
|
Copyright (c) 1993-2023 Steve J. Martin. MIT License applies. |
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 24R3 or above for all features:
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. AUTO will consume less IP when its sleep time is longer.
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.
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:
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.
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 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
This parameter can be changed dynamically by "TASK taskname SLEEP"
or by "II grunid SLEEP+", "II grunid SLEEP-",
"II grunid SLPMIN" or "II grunid SLPMAX" keyins. It
can be restored by the "II grunid SLPDEF" keyin. And this
always reverts to its configured default (SLEEPTIME) value after an
AUTO refresh.
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.
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:
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:
You may also instruct AUTO to refresh itself at a given future time
by using the REFRESH action type.
All three files are data files in SSG *SAVE format.
The CONTROLFILE configuation SGS specifies file name and
placement for this file. The default file name is AUTO*CONTROL.
The FACTFILE configuation SGS specifies file name and
placement for this file. The default file name is AUTO*FACTS.
The PREREQFILE configuation SGS specifies file name and
placement for this file. The default file name is AUTO*PREREQS.
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.
Please note that scheduling based on UTC time requires SSG level
24R3 or above.
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 evaluate to FALSE.
Please note that SSG levels 23R1 and 23R1A had year 2000 problems,
and AUTO will not work with them.
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.
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:
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.
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.
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:
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").
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.
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.
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:
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:
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 ('\').
Conditions are specified via a "<keyword><operator><value>"
syntax with no imbedded spaces. Examples:
The fifth and subsequent fields can have subfields that specify
alternate ways (OR conditions) of satisfying the conditions. Examples:
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.
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):
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:
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:
Each clause accomplishes the same thing--the task is restricted to
Tuesday only, but the first form is preferable because it's simpler.
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.
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
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:
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):
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:
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.
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.
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
The SLEEP action type makes a temporary change that is not remembered
across AUTO refreshes. If the change would cause the SLEEPTIME value
to be less than SLEEPMIN or greater than SLEEPMAX, the appropriate
minimum or maximum will be used.
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 (\).
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.
The SLEEPIER task changes AUTO's sleep time to 240 seconds.
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.
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.
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.
The following II keyins are available (where grunid is AUTO's
generated run-id):
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.
Changes made by "II grunid SLEEP-" and "II grunid SLEEP+"
keyins are not remembered across AUTO refreshes.
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:
If you have new release of SSG you'd like to test, you could
use (for example):
AUTO always assumes that the SSG absolute name is "SSG".
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.
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.
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).
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.
@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.
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. This must be greater than or equal to SLEEPMIN parameter and
less than or equal to SLEEPMAX parameter. 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 AUTO
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.11. 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.17. 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
5 9,999 6 99,999 7 999,999 9 9,999,999 10 99,999,999 11 999,999,999 13 9,999,999,999 14 34,359,738,367 2.4.1.18. 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.1.19. MCN
This optional SGS tells AUTO what to use as the system's Manufacturing
Control Number. It can be useful if you are running a pre-24R2 SSG,
where MCN is not available on the SYSTEM$ SGS.
2.4.1.20. UTC
This optional SGS tells AUTO whether to schedule in UTC ("UTC YES") or
local time ("UTC NO"). UTC scheduling is available only on SSG 24R3
or higher. Default is "UTC NO".
Caution: If you change the value of this parameter, you must
re-create AUTO's control, fact and prerequisite files (that is, start
AUTO comma 7). Otherwise, AUTO might have a mixture of local and UTC
times, and so results could be unpredictable.
2.4.1.21. SLEEPMIN
This optional SGS specifies the minimum number of seconds to which
AUTO's SLEEPTIME parameter (see above) may be set. This applies to
the SLEEPTIME configuration SGS, the SLEEP action on TASK SGSs, and the
"II grunid SLEEP-" and "II grunid SLPMIN" keyins.
Its value must be between 1 and 86400 and must be less than or equal
to the value of SLEEPMAX.
2.4.1.22. SLEEPMAX
This optional SGS specifies the maximum number of seconds to which
AUTO's SLEEPTIME parameter (see above) may be set. This applies to
the SLEEPTIME configuration SGS, the SLEEP action on TASK SGSs, and the
"II grunid SLEEP+" and "II grunid SLPMAX" keyins.
Its value must be between 1 and 86400 and must be greater than or equal
to the value of SLEEPMIN.
2.4.1.23. SCREENLINES
This optional SGS specifies the number of lines on the screen for
non-breakpointed demand users. Allowable values are 24, 36 and 48.
If omitted, default is 24. This applies to @AUTO,Q and @AUTO,S.
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).
1 = re-create prerequisite file.
2 = re-create fact file.
3 = re-create fact and prerequisite files.
4 = re-create control file.
5 = re-create prerequisite and control file.
6 = re-create fact and control file.
7 = re-create prerequisite, fact and control file.
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.
@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.
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).
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.
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.
2.5.3. Prerequisite File.
AUTO uses this file to keep track of unsatisfied prerequisites.
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.
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 (24R3 or above) with AUTO. This release of AUTO was
developed and tested with SSG 24R4A.
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).
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:
@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).
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.
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).
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
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).
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.
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.
WHEN 13:00:00 TASK1 13:15:00 \ DAY=ALL
WHEN 13:00:00 TASK1 +15 \ DAY=ALL
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.
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.
DAY=MON
YYYYMMDD>19990901
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.
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
BANK=YES
WEEK_BANK_DAY>0
MONTH_BANK_DAY>0
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:
DAY=TUE
YES_DAY=MON
TOM_DAY=WED
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.
FILE=SJM*CARDFILE(1)
@ASSERT DBSAVE/DONE
@DENY DBSAVE/DONE
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.
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
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.
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:
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.
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.
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
.
TASK SLEEPIER SLEEP 240
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.
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.
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:
Keyin
Function
II grunid HALT
II grunid TERMTerminate AUTO II grunid REFR Refresh AUTO II grunid BRKPT Breakpoint PRINT$ and print counters
(long format) II grunid RESET Print counters (long format) and then
zero them II grunid STAT Show config highlights and counters
(short format) II grunid STATUS Show config highlights and counters
(long format) II grunid SLEEP- Halve the number of seconds that
AUTO sleeps II grunid SLEEP+ Double the number of seconds that
AUTO sleeps II grunid SLPDEF Set AUTO sleep time to default
(SLEEPTIME) value II grunid SLPMAX Set AUTO sleep time to maximum
(SLEEPMAX) value II grunid SLPMIN Set AUTO sleep time to minimum
(SLEEPMIN) value II grunid HELP Show list of II keyins 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.
@AUTO,S AUTO*TEST.
@AUTO,S ,NEW*SSG. . field #1 defaults