 |
» |
|
|
|
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. Never emit blank lines. All output lines must
have one of these forms: In each case, the keyword, if there is one, must
begin in column 1, and the text must begin
in column 10 (indented nine blanks). 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. 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. |
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.
|
Printable version
