In order to avoid the confusion of having multiple users all trying to modify the same astrod.conf file to request their observations, we've established a ``scheduler'' account to which you can log in for the purpose of account management. Within the home directory of that guest account, you should create a directory for yourself, to avoid confusion with other guest users. Each guest user should be assigned a user number from 1 to 50 by the host institution; you may wish to use this in your directory name. It will become critical later on.
All of your interaction with the scheduler files should be through the Perl script user_sched.pl, which will be in the path for the guest account. Call it without any options to get a simple description of its usage. In order to schedule ROTSE-III observations, you will write your own local schedule file containing triggers and schedules (as defined above), and you must get this script to agree that there are no mistakes or problems within your list. The script cannot, of course, confirm that your schedule will perform the observations you have in mind, if you have misunderstood the command formatting, but it will ensure that you can't crash the system or confuse your observations with others'.
This is what you will see if you run the script with no options:
Welcome to the ROTSE-III scheduler script.
Options may be in any order.
Use -e to extract your schedule to your local directory.
Then modify that file to match what you want to schedule.
Then use -s to submit your modified file.
If you do not specify a file name, local_user_file.txt is assumed.
Make sure the first line of this file is your user_cap.
Use -t with -s to test submission but not to modify lsched.
For a test submission, output is written to local_test_file.txt in the working directory.
Syntax: user_sched.pl -u <Your user ID number> [-s|e] [optional file name] [-t]
To get more than the usage instruction from the script, you must use the -u option to give it your user number. The script can then perform two operations: it will extract all triggers and schedules from the standard configuration file astrod_lsched.conf into a local file in your directory, or it can insert your local file into astrod_lsched.conf to be used in planning the night's observations. You distinguish between these two operating modes by using either the -s or -e command line options. One of these two options must be present. You may include a file name after this option call, if you wish. If not, the script will assume a default file name of ``local_user_file.txt''. There is a final option that you can use, -t, which runs in conjunction with option -s. It will check your local file for submission, but instead of replacing the official configuration file with your updated version, it will write the updated version of astrod_lsched.conf to your local directory under the name ``local_test_file.txt''. Use this option if you want to test your schedule file for errors, but don't want to actually put your instructions to the telescope yet.
You should always begin your session by running in extract mode, even if you have never used it before. The returned file will always start with a line called ``user_cap''. This line establishes what percent of the nightly observing time has been allocated to you. The first number on the line will be your user number. The second number should be your percentage (a number between 0 and 30), and you can put any information you like after a number sign. Your real name would be a useful thing to put in this comment area. The ``user_cap'' line should always come first in your schedule file.
If you run ``user_sched.pl -u 5 -e'', your first local schedule file
will have the single line:
user_cap 5 [your allowed percentage] # [comments, like your name]
Once you have a user_cap line in place, you can define as many triggers and schedules as you want. When you run user_sched.pl in extract mode, it reports a list of all the triggers that have already been defined by other people. You may not use any of these trigger names or three-letter-acronyms. Construct your trigger types and schedules as described above in Sections 4.4.1 and 4.4.2. The only difference is that your trigger type definitions must include ``userNN'' (where ``NN'' is your user ID number) in the comment field. If you omit this, the Perl script will insert it for you, and remind you to include it in the future. Also make sure you include your user number (-L NN) and schedule priority (-p #) in the options for your schedule items. The trigger name given in your schedule item must match one of the trigger names given earlier in this file. In general, the order of your line items in this file is irrelevant, except that a trigger item definition must come earlier than the use of that trigger name in a schedule item.
When you are satisfied with your schedule file, you may check it for errors by running user_sched.pl in test submit mode (-s [file name] -t). The script will print to standard error a running description of its progress as it evaluates your file. Please keep a close eye on these output lines for errors. Any errors discovered should (we hope) be clearly reported for easy fixing. If the script finds no errors, it will write a complete local schedule file (local_test_file.txt) to your local directory for your perusal. If everything looks in order, run user_sched.pl one last time without the -t option, and you are done.
A sample local user schedule file might look like this:
user_cap 5 25 # I am Simon, my ID number is 5, and I get 25% of the time
trigger simons_kvars skv 0 2jm,4js # user5 - I want 2 20 s exposures and 4 5 s
trigger supnovae sne 0 2jl # user5 - I want 2 60 s exposures
sched simons_kvars "-r 23,12 -d -12,25 -e 2000.0 -p 2 -L 5 -i 1000 -m 45"
sched simons_kvars "-r 10.5 -d 10,2 -e 2000.0 -p 1 -L 5 -i 1000 -m 45"
sched supnovae "-r 1 -d 56 -e 2000.0 -p 1 -L 5 -i 1000 -m 45"
If you were to submit such a file, using the command ``user_sched.pl -u 5 -s -t'', you would see the following output:
Submit mode: Sched file local_user_file.txt will be submitted.
Reading file user5file.txt
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Checking: "user_cap 5 25 # I am Simon, my ID number is 5, and I get 25% of the time"
Line clears successfully.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Checking: "trigger simons_kvars skv 0 2jm,4js # user5 - I want 2 20 s exposures and 4 5 s"
-----------
Parsing trigger type : "trigger simons_kvars skv 0 2jm,4js "
This trigger first will take 2 jiggled medium exposures.
And then it will take 4 jiggled short exposures.
-----------
Line clears successfully.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Checking: "trigger supnovae sne 0 2jl # user5 - I want 2 60 s exposures"
-----------
Parsing trigger type : "trigger supnovae sne 0 2jl "
This trigger first will take 2 jiggled long exposures.
-----------
Line clears successfully.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Checking: "sched simons_kvars "-r 23,12 -d -12,25 -e 2000.0 -p 2 -L 5 -i 1000 -m 45""
***********************
Parsing schedule options "-r 23,12 -d -12,25 -e 2000.0 -p 2 -L 5 -i 1000 -m 45"
Parse successful.
***********************
Line clears successfully.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Checking: "sched simons_kvars "-r 10.5 -d 10,2 -e 2000.0 -p 1 -L 5 -i 1000 -m 45""
***********************
Parsing schedule options "-r 10.5 -d 10,2 -e 2000.0 -p 1 -L 5 -i 1000 -m 45"
Parse successful.
***********************
Line clears successfully.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Checking: "sched supnovae "-r 1 -d 56 -e 2000.0 -p 1 -L 5 -i 1000 -m 45""
***********************
Parsing schedule options "-r 1 -d 56 -e 2000.0 -p 1 -L 5 -i 1000 -m 45"
Parse successful.
***********************
Line clears successfully.
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Congratulations! I could find no errors in your submitted file.
Writing submission to local_test_file.txt
Please note that this final submission must be completed before the sun
falls to 5
above the horizon at the telescope site, or your schedule
will not be read into the DAQ for the evening's observing procedures.
Also be aware that it's quite possible for someone to submit their file after
you have extracted, but before you have resubmitted, yours. If that person
happens to use a trigger name or TLA that you are adding to your schedule, you
will get an error when you resubmit, despite the fact that when you checked
out, the trigger was free.