STIS Calibration Proposal Procedures

1. Createpro (usually run for you).

Generally, one of the members of the STIS group at STScI requests a particular calibration program. If it has been (or will be) approved by the TTRB, then the calibration manager, (currently Tony Roman), assigns a proposal number and creates the skeleton phase II. Tony informs the PC that a STIS/CAL proposal number has been assigned. You should see a submission of a proposal within a "reasonable" amount of time.

What is "reasonable?" If a proposal has not been submitted within a week of the assignment of the proposal number, contact the PI and ask when he or she intends to submit the proposal.

2. Check the Phase II into PLIB and review the syntax diagnostics

Some of the calibration proposals will generate errors about illegal combinations of detector/aperture/filter. The PC should always check with the PI and the commanding group about these errors.

3. SPEC COMmanding exposure lines.

Review all STIS/CAL proposals for the SPECial COMmanding exposure special requirement. This special requirement is used whenever standard processing through Transformation does not support the instrument commanding required by a calibration proposal. The PI should have inserted comments describing what he or she would like to do with the instrument in the exposures that need special commanding.

The PC should contact one of the members of the commanding group (usually Vicki Balzano) and give them a formatted copy of the proposal having special commanding requirements. The commanding group will tell you if any changes need to be made to the proposal and if any additional comments need to be inserted into the exposure comments. These comments describe any "special" processing of the proposal after it is loaded into the PMDB.

3.1. Flavors of special commanding.

For STIS calibrations the SPECial COMmanding special requirement comes in two flavors:

(a) When the "normal" commanding instructions cannot be used, the special commanding requirement is placed in a separate S/C (SpaceCraft) exposure line with the appropriate special processing comments. (Note: Special processing of the PMDB is accomplished using isql command files described in Section 14)

(b) The normal commanding instructions can be used, but the transformation does not populate the PMDB correctly in order to meet the special commanding requirements. One example of this is when the PI wants to use more than one TUNGSTEN calibration lamp in an exposure. This also requires special processing of the PMDB using isql command files (Section 14).

3.2. Using the SAME ALIGNMENT Special Requirement.

All S/C lines with the SPEC COM requirement should be forced into the same alignment as the following (or preceding) instrument exposure line using the SAME ALIGNMENT <list> DONT SPLIT special requirement. If there are more than two special commanding S/C lines within a visit, it's probably best (well ... simpler is better, isn't it?) to force the entire exposure sequence within the visit into the same alignment. There may be cases where the entire visit should not be forced into the same alignment, in which case each S/C exposure line must be dealt with separately. See proposals 7944 and 7969 for examples.

4. Review the output of PIP.

You should review the trans diagnostics and ask the PI and the commanding group about any errors you do not understand.

4.1. Merging Rule Violations and DEAD Visits.

In some cases, forcing a S/C exposure line into the same alignment as a STIS exposure line can result in transformation merging rule errors. The following merging rule errors are usually OK and can be waived:

• - BREAK STIS EXPOSURES USING CALIBRATION LAMPS
• - BREAK STIS ACQ EXPOSURES
• - BREAK EXPOSURE AFTER END-ORBIT SPECIAL REQUIREMENT

The errors will make the visit dead and you will have to UNDEAD them using the Update button in the PC toolbox. If you are unsure that a trans merging rule violation is OK, check with one of the commandos (Vicki Balzano, Ron Pitts or Dean Zak).

4.2. Internal Visits Longer than 1800 seconds.

Transformation issues a warning if an internal is longer than 1800 seconds. Usually these warnings can be ignored, although it might make it more difficult to schedule the visit on a calendar.

5. Set the LRP State.

Verification of calibration proposals is unnecessary. After checking in the initial submission, set the LRP state to "ready" using the Update Tool; otherwise, the LRP state will remain "not_ready." The TTRB will allocate the number of orbits for the calibration proposals, and the PC needs to check that the proposal is within this allocation.

6. CS reviews.

CS reviews are not done for calibration proposals.

If a STIS Calibration proposal generates a Bright Object Alert (you can check by using the command line version of gs_request with the -status option), it requires a Phase B review by the Contact Scientist. Since the PI is the CS for calibration proposals, contact the PI and he or she will get someone (else) to conduct the phase B review.

7. Plan Windows

Proposals with external and internal targets are picked up and assigned plan windows by the LRP software beast. It will also adjust or add plan windows if necessary. As long as the internal visits have constraints, like links or betweens, you will get reasonable windows. Otherwise you should find out when the visits are suppose to execute and add either betweens or USCs.

You can use the LRP GUI to run the scheduler on internal or external visits if you can't wait for the next released LRP. You should write out your windows to the current released LRP.

8. Creation and Review of isql to implement SPECial COMmanding requirements:

After the proposal has been loaded into the PMDB, the PMDB must be modified for the special commanding requirements. This is accomplished through the execution of isql (Interactive Structured Query Language) files. This is the same language that Transformation assignment files use to populate the PMDB.

After the PC has consulted the commanding group about the special commanding requirements, the PC should create a file with the extension .isql in the UNIX directory: /data/operational1/trans/####/.

8.1. Writing isql Command Files

The following remarks about isql command files are from a particular user's point view. So, caveat emptor :

The isql you are writing and using should always begin with some comments about the proposal being modified, the PC's name, and the date the file was last modified. All isql should start with "begin transaction" statement and "go" statements, and end with "commit" and "go" statements.

Modification of the PMDB is accomplished with either an "update <relation>" statement (to change the value of a field that already exists in a database relation), or an "insert into <relation>" statement (for new fields such as a new input parameter for a special instruction). All "insert" and "update into" statements include the name of the database relation, the name of the field being modified, and the appropriate programmatic numbers (proposal, obset, alignment, exposure, and version numbers). Although it's not required, these statements should end with a "go" statement. The go statement in isql serves as a command line terminator.

You can copy the isql code from another proposal doing similar things, but make sure that the proposal number, visit numbers, alignment numbers, command names, spectral elements, etc. are correct for your proposal. You can edit the files you create in the UNIX directory with your favorite editor. These files will be read-only by default for everyone but the person who created the file.

You may find that using the Printpro button on the tool box to print a formatted version of the proposal, and copies of the ####-catalog.rpt (printed in landscape) and ####.summ files from the trans directory helpful in editing the isql files. See for example 7673-catalog.rpt and 7673.summ and compare these with the isql file, 7673_special_may8.isql .

8.2. What isql is needed?

The special commanding comments in the proposal should note what relations need to be modified in the database. Usually these changes affect the relations qgactinst (the instruction used to generate SMS statements) and qesiparm (instrument parameters passed into the instructions).

Sometimes, the saa_avoid contour in qalignment must be reset if a special commanding S/C line is in a separate alignment from all other exposures (see proposal 7965 for an example). Using the SAME ALIGNMENT DONT SPLIT special requirement with other exposures in the visit should eliminate the need for resetting this flag.

Occasionally, the flags affecting the scheduling of an internal as an unattached parallel need to be reset (see proposal 7965). These flags are in qscheduling (parallel_su and par_attach) and qbs_obset (parallel_can). Normally this will not be necessary.

8.3. Review of isql command files.

After the isql has been written, give copies of the isql, the formatted proposal, the catalog file, and the summary file to Merle Reinhart (SPST) and Vicki Balzano or Ron Pitts (CMD) for their review.

Leave the paper copies with Merle. When Merle has finished reviewing the files and returned them, (and you have made any needed changes) you need to make an appointment to review them with Vicki. She will want to keep a copy of the three documents listed above as well as the isql files, so make an extra copy for your own files.

Make any changes requested by commanding.

9. Execution of the isql.

To execute an isql file on the UNIX side:

report <isql_file> -isql -output=/dev/tty

During the execution of the command file, you should see messages scrolling on your screen indicating that PMDB records are being changed. Make sure that no errors occur, and that the correct number of records are reported as having been affected. A message of "0 records affected " is a sure sign of a problem -- usually the result of trying to modify a record that does not exist.

10. SPSS Processing.

Normal SPSS processing is done for proposals with external targets. For proposals with internal targets, run only an Obset Update (now an option in Guide Star Processing), Visit Update and Prep Done (now in the Update tool).