save command

The save command invokes the backup procedure to save the entire file system, an individual account, or to perform an incremental save. It is the process invoked by the account-save and file-save commands.

Syntax

save {(options)}

Parameter(s)

options a Suppresses the added information (including all update stamps and binary item sizes).
  b Saves the B-tree indexes. After a full-restore, this prevents having to regenerate indexes. Note that this option is only supported for UNIX and Windows VME implementations. It is not supported from the Windows FSI.
Warning: Saved indexes are platform specific and will not be restored properly on platforms differing from the originator.
  d Prevents the clearing of dirty bits.
Note: This option should only be used when performing a save in preparation for a full restore.
  f Displays the file names as they are saved. If omitted, only the mds file and individual master dictionary (account) names are listed.
  g Displays file inconsistency errors when found, but skips the group and continues the save. Errors are logged in the dm,errors, file in attributes 14, 15, and 16 of the error item. Attribute 14 is the save date, 15 is the primary group FID, and 16 is the account > dictionary > data display information. At the end of the save, a message displays indicating the total number of file inconsistency errors encountered, if at least one was found. If used with the b option, index corruptions are also skipped.
  h Truncates any GFE's found in the save.
Warning: Care should be taken when using this option because of potential data loss.
  i Individual master dictionary save (account-save command).

The account name can only be specified at TCL if the account-save command is used. The save command does not take an account name at TCL. It always prompts when the i  option is specified.

The i option can be used with an active list to generate multiple account-saves. If a list is active and the i  option is specified, the system generates a tape that can be restored with the restore-accounts command.
  j Suppresses the dirty bit counter display.
  k Reorganizes all file of files file numbers sequentially on the tape. This option is not support from the FSI.
Warning: Care should be taken if reorganizing the file of files file using Hot-Backup, Transaction logging, or an incremental file-save.
  l Each file may have a list of value mark separated item-IDs (stored in attribute 25 of the file) to save. This option saves only that list of value mark separated item-IDs. An asterisk in attribute 25 saves all items in the file. If there is no list, only the file-defining item is saved, as if the file had a dy dictionary code. In addition, the l option does not unmark (clear dirty bits) items that have changed. These items are saved on subsequent incremental file-save commands or account-save commands. This is similar to the v option for the full file-save.
  m Same as the l option, but it additionally unmarks or clears the dirty bits.
  p Directs console listing to the printer, via the spooler.
  q Changes the terminal display from hierarchical format to indented format.
  r Same as the l and m options, except the list is also saved with the file as a separate item in the dm,file-of-files, file.
  s An item is stored in dm,file-of-files, file for each file saved. The s option generates additional statistics, which can be reviewed with list-file-stats .
  t Outputs to the tape (magnetic media), which has been previously attached to the process. If the t option is not specified, save does all the processing, but nothing is written to the media. The system prompts for the file-save tape label, which is written on the tape as part of the tape label. Omitting the t option is useful for regenerating system statistics and/or finding file inconsistency errors, and is the basis of fake or dummy saves.
  u Performs an incremental file save or account save. This saves all file items and data items that have changed since the last full file-save or account-save.
  v Performs a full file save, but does not unmark the items that have been changed. These items will continue to be saved on subsequent incremental file saves. Unless the i or u option is specified, the system does a full file save.
  x Saves files with a D-pointer type of dx.
  y Saves files with a D-pointer type of dy.

The appropriate peripheral storage device must be attached to the current process before invoking this command.

These types of saves can be performed:

  • A full file-save is a complete logical backup of the D3 file system.

  • An incremental file-save saves only those items which have changed since the last full file-save. Changed items since the last save are referred to as dirty items. If multiple incremental file-saves are done between full file-save commands, the most recent incremental file-save contains the accumulated changes since the last full file-save (see the u option).

  • A list driven file-save saves all items for a given file that are specified in the dm,file of files, files starting at attribute 25 of the item representing that file. Attribute 25 begins the select list (see l and m options).

  • An account-save saves all the files in a single account

  • An incremental account-save is like an incremental file-save, but only affects the files in a single account.

  • A dummy or fake save is a save without the t (tape) option. This is useful in cases where the D3 file system needs to be verified for integrity.

The save command can also be driven from an active list, like any other AQL command, although it is truly not an AQL command. If a list is active when save is invoked, each item in the list is treated as an account name. On a full file-save with a list active, a fully restorable tape is created. This automatically includes the dm account, even if it is not in the list. On an account-save with a list active, the prompt for account name does not appear. This type of save is not fully restorable, unless the dm account is in the list. This type of tape may be used with restore-accounts. In both of these types of saves, the dirty bits are not cleared unless the v option is used.

Note: There is a potential conflict with this function and the l and m options. If these options are used and a list is active, the active list replaces the list in the dm,file of files, file.

In any type of save process, the D-pointer to the file determines the course of action for saving or not saving files. The D-pointer type is attribute 1 of its corresponding file-defining item. Files are saved according to these rules:

  • d, dc, dl, and dp files are always saved.

  • dx files are not saved. Any files beneath a dx file are also not saved. These file can be replaced with corrected ones using the x option.

  • dy file pointers are saved, but not the data within them. After a restore, a dy file is emptied. This file can be replaced with a corrected one using the y option.

The system does not save frames which are in the overflow table (unused frames), so the amount of backup media required is related to the number of frames currently in use.

When saving to multiple reels, the system prompts with:

Load volume #n and type ’C’
label 08:00:00 16 Feb 2003 DATA "account.name" # -

The prompt accepts either the letter c, which tells it to continue after inserting the next sequential reel, or the letter q, to quit and stop the save.

Incremental FSI Save Not Supported

This version does not support the incremental save or restore of FSI accounts. Use only account saves of full saves.

Dirty Bits Item Deletion Scheme

In order for the incremental save to work properly, the system automatically marks (or dirties) any item that is changed in any way. This mark is normally cleared at the end of a complete save, and displays the message clearing dirty bits as it does so, unless the v option is specified.

If a file has a dx or dy code and an item in it is updated, that item is not marked as changed when it is filed. Therefore, even if the x or y is removed before the save, that item is not saved by an incremental file-save.

The save processor locks groups as it saves them. While the group is locked, no process can access any item in that group. Locking groups prevents spurious file inconsistency messages that would occur if another process changed an item while it was being saved.

Up to four groups may be locked at one time. These groups are the ones containing: the mds dictionary pointer, the master dictionary pointer, the file dictionary pointer, and the group for the data currently being saved.

Any changes made to the file system during the save (either a change or a deletion) are not written to the save.

If the save is being done to a SCT, an explicit EOD sequence must be written, since SCT cannot back up. Both the t-weof TCL command and the FlashBASIC weof statement write the second EOD needed to indicate the EOF. Without the EOD, account-restore or sel-restore fails to see the end of the tape.

At the end of the save, the system displays the message clearing dirty bits..., and a percent completed counter. During this time, several files are reopened and updated, renamed and cleared. All delete flags are cleared, and save# fields are reset.

Deleting Items

The rules by which D3 removes items from a file:

  • If the file is a dx-type or dy-type, the group adjusts immediately to compensate for the deleted item.

  • If the file is not a dx-type or dy-type, the item is deleted and replaced with a deleted-item/item, which includes the item-ID and the delete flag. These items are later deleted during the clearing dirty bits phase of a full save.

  • If the group has an update lock, the item delete bit is set and the last user to release the group lock compresses the group according to the previous two rules.

The reason that this was implemented has to do with incremental saves, which have to know that the item no longer exists.

The example below illustrates why this is handled this way.

  1. Suppose there is an item called materials in the file invoices, and it is saved on a full file-save.

  2. After the save, materials is deleted.

  3. An incremental save is performed.

  4. A meteorite strikes the system, necessitating a full restore (this, of course, is strictly hypothetical.)

  5. A full restore is performed, which brings back materials.

  6. At the end of the full restore, the option to perform an incremental restore is offered and accepted. It is during this process that materials is deleted.

    Note: The order in which data is saved is the opposite of the way it displays. To clarify this point, consider this display:
    1 35 > dm
    1 36 > dm > newac
    1 37 > dm > newac > newac
    This suggests that the dm file (a level 1, or master dictionary) is saved, followed immediately by dm > newac (a level 2, or dictionary), and then by dm > newac > newac (a level 3, or data section). In fact, the D-pointers to the dm and dm > newac are saved, but not the data within them. The data section is saved first. It is followed by the dictionary. The data from the master dictionary is saved last. This also provides a major clue about how these files are restored.

Example(s)

to dm
set-sct
Tape attached block size: 16384
[1082] Tape device is attached to quarter inch Streaming Cartridge Tape
save (bft)
file-save tape label = daily-backup
1 35 > dm
1 36 > dm > newac
1 37 > dm > newac > newac
.
.
Load volume #2 and type ’C’
label 08:00:00 16 Feb 2003 DATA dm daily-backup #
.
.
2 142 > lastaccount > lastfile > lastitem
Clearing dirty bits...