The behavior of the backup_dump does not match documentation w.r.t. '-nohold'

[anonymous]

The backup utilities are documented as unloading tapes by default, but do not.

complete_dump.info, backup_dump.info, catchup_dump.info:

-nohold
   rewinds and unloads the hierarchy dump tape or tapes at the end of
   the current dump pass.  This is the default.

start_dump.info:

-nohold
   rewinds and unloads the hierarchy dump tape or tapes at the end of
   the current dump pass.  This is the default for all hierarchy dump
   modes except incremental.

bk_ss_.cds:       2 holdsw bit (1),				/* ON => do not unmount tape when done */
bk_ss_.cds:	bk_static.holdsw = "0"b;

bk_arg_reader_:

               else if op = "hold" then bk_ss_$holdsw = "1"b; /* do not dismount */
               else if op = "nohold" then bk_ss_$holdsw = ""b; /* dismount, default */

then in start_dump.pl1, after 'examine_arguments:' (the "join" for complete_dump, catchup_dump, start_dump):

          bk_ss_$holdsw = "1"b;

"-nohold" is also the documented behavior for 'retreive' and 'reload', but I have not tested the actual behavior.

retrieve.info, reload.info:

The following defaults are in effect for the reloader and retriever
before any backup commands are given; they are not, however, reset to
these values at the start of each backup command, except as noted
below.

      -all                    -noquota
      -error_of               -primary
      -map                    -reload
      -nodebug                -setlvid
      -nohold                 -trim

[Eric Swenson]

This needs a decision before any further progress. Should we change the
documentation to match the code, or change the code to match the
documentation.

What the documentation says

• backup_dump, complete_dump, catchup_dump: -nohold "rewinds and unloads the hierarchy dump tape or tapes at the end of the current dump pass. This is the default."
• start_dump: the same, but nohold "is the default for all hierarchy dump modes except incremental".
• reload and retrieve: -nohold is among the defaults "in effect for the reloader and retriever before any backup commands are given".

What the code does

Sources: bound_dumper_.s.archive (start_dump.pl1, backup_dump.pl1,
bk_output.pl1) and bound_reloader_.s.archive (bk_ss_.cds,
bk_arg_reader_.pl1, bk_input.pl1).

How the hold switch works

• The switch: bk_ss_$holdsw. It starts "0"b (nohold) in bk_ss_.cds, and bk_arg_reader_ sets it for -hold/-nohold.
• It persists within a process. It is a per-process static that no dump command resets, so it carries over from one backup command to the next.
• Each call to backup_dump mounts and unmounts the tape. It calls bk_output$output_init (mount, if not mounted) at its start and bk_output$output_finish at its end. output_finish unmounts the tape unless holdsw is on.

start_dump, catchup_dump, complete_dump

• They force hold at the start. All three set bk_ss_$holdsw = "1"b at examine_arguments, before reading their arguments. They call backup_dump$abort_on_tape_errors once for each pathname in the dump control file, so forcing hold is what keeps the tape mounted from one pathname to the next, and from one incremental pass to the next.
• At the end, the code unloads the tape itself:
  • complete_dump: at the end of the dump (label ended) it sets holdsw off and calls output_finish. The tape is always unloaded, even if -hold was given.
  • catchup_dump: at the end of the catchup pass it does the same, then sets hold again and carries on as start_dump.
  • start_dump: the tape stays mounted between incremental passes until end_dump, which unloads it.
• An explicit -nohold behaves differently from the documentation. It leaves holdsw off, so output_finish unloads the tape after *each pathname* in the dump control file, not "at the end of the current dump pass".

So for these three commands:

• The behavior you get without -nohold matches the documentation in effect: complete_dump and catchup_dump unload at the end of the pass, and start_dump holds between incremental passes.
• -nohold itself does not do what is documented.
• -hold is ignored at the end of complete_dump and catchup_dump.

backup_dump (the command)

• It honours -hold/-nohold. With nohold it unloads at the end of the command, as documented.
• But it inherits holdsw from an earlier command in the same process. After start_dump (which leaves hold on until end_dump), a backup_dump with no -nohold holds the tape. This may be what the ticket's reporter saw ("documented as unloading tapes by default, but do not").

reload and retrieve

• These match their documentation. bk_input unmounts unless holdsw is on, the default is off, and the info segments already say the switches are not reset between commands.

Options

1. Document the actual behavior (recommended; no code risk).
   • complete_dump.info and catchup_dump.info: the tape is unloaded at the end of the dump pass whether or not -hold is given; -nohold unloads it after each pathname in the dump control file.
   • start_dump.info: the tape is held between passes until end_dump; -nohold unloads it after each pathname.
   • backup_dump.info: -hold/-nohold remain in effect for later backup commands in the same process, as reload.info and retrieve.info already say.
2. Make -nohold mean "at the end of the pass" in the dump commands.
   • How: start_dump would remember the user's -hold/-nohold separately, keep holdsw on during a pass, and at the end of each pass unload only if -nohold was given (and, for complete_dump, keep the tape if -hold was given).
   • Cost: this changes operator-visible behavior in the dumper daemon, and existing operating procedures may depend on it. It would need testing with real tape drives in a dumper process.
3. Also reset holdsw (and perhaps the other dump switches) at the start of each backup_dump command, so that it does not inherit start_dump's hold.

Option 1 can be done with info-segment changes only. Options 2 and 3 change
bound_dumper_.