Control Script Input and Output

Except for request scripts, control scripts must not be interactive. This includes messages such as, Press return to continue.
Except for request scripts, all control scripts are executed by the agent on the target systems. Request scripts are executed by the controller (swinstall, swconfig, or swask).
Except for request scripts, no method of input to control scripts is supported. Request script data is input by the user through the swask command or the ask option for swinstall or swconfig.
Control scripts must write messages for error and warning conditions to stderr (echo &>2), and write all other messages to stdout. Control scripts must not write directly to /dev/console or attempt any other method of writing directly to the display.
The stdout and stderr from a control script is redirected by the agent to the log file (var/adm/sw/swagent.log) within the primary or alternate root directory in which the task is being performed.
For interactive swinstall and swremove sessions, you can display and browse this logfile.
Only minimal, essential information should be emitted by control scripts. Ideally, no output is emitted if the script successfully performs all of its actions.
In the agent logfile, the execution of each control script is prefaced by a "begin execution" message:
* Running "checkinstall" script for product "PRODUCT" * Running "checkinstall" script for fileset "PRODUCT.FILESET".
Any messages generated by the script will follow. If the script returns a value other than 0 (SUCCESS), then a concluding message such as the following, is written:
ERROR: The "unconfigure" script for "PRODUCT.FILESET" failed (exit code "1"). The script location was "/var/adm/sw/products/PRODUCT/FILESET/unconfigure". * This script had errors but the execution of this product will still proceed. Check the above output from the script for further details. WARNING: The "unconfigure" script for "PRODUCT.FILESET" failed (exit code "2"). The script location was "/var/adm/sw/products/PRODUCT/FILESET/unconfigure" * This script had warnings but the execution of this product will still proceed. Check the above output from the script for further details.
The messages written by a control script must conform to the following format conventions whenever possible.
1. Never emit blank lines.
2. All output lines must have one of these forms:
  ERROR: textWARNING:textNOTE:textblank text
  In each case, the keyword must begin in column 1, and the text must begin in column 10 (indented nine blanks).
3. Choose the keyword (ERROR, WARNING, NOTE, or blank) as follows:
  ERROR:
  Cannot proceed, may need corrective action.
  WARNING:
  Can proceed, but something went wrong and may need action.
  NOTE:
  Can proceed, but something happened that is out of the ordinary or worth special attention. (Not just a status message.)
  blank
  Generic progress and status messages (keep them to a necessary minimum).
  Do not start a line with an asterisk (*) character. This is reserved for operational messages printed by the agent so you can easily distinguish them from other messages.
4. If the message text requires more than a single 72-character line, break it into several 72-character lines. Indent all lines after the first. For example:
  NOTE: To install your new graphics package, you must turn on the lights in the next room. Please turn them off when you leave.
5. Do not use tab characters in any messages.
Scripts execute other commands which may unexpectedly fail and emit output not in the above format. Wherever you suspect a failure is possible or likely (and it is reasonable to do so) redirect the standard output or error of the executed command to /dev/null or to a temporary file. Then emit a proper-format message based on the return code or on output from the command. For example:
/bin/grep bletch /etc/bagel 2c&>/dev/null if[$?=1] then echo "ERROR: Cannot find bletch in /etc/bagel." |&>2 fi
Follow these conventions to ensure a control script's messages have a similar look and feel to the messages generated by the agent (and the commands themselves).
- Use full sentences wherever possible. Avoid terseness.
- Start sentences and phrases with capital letter and end with period.
- Put two blanks after period; one after colons, semicolons, and commas.
- Use uppercase first letters of phrases after colons. (This helps break up the message into digestible "bites" of information.)
- Surround product, fileset, directory, and file names, and other variable-valued strings with quotes. For example:
  echo "ERROR: Cannot open file \"$file\"." &>2
- Write in the present tense. Avoid "would", "will", and similar verb tenses. Also avoid past tense except where necessary.
- Use "cannot" rather than "can't", "could not", "couldn't", "unable to", "failed to", and similar phrases.
- Write messages that make sense to system administrators and users. Consider your audience.

Control Script Input and Output

Technical documentation

» Table of Contents

» Glossary

» Index