PROCEDURE create_catalog_backup, crecb, backup_catalogs, bacc (
  vsn_prefix, vsnp, vp: any of
      name 1..5
      string 1..5
      integer 1..99999
    anyend = $optional
  vsn_count, vsnc, vc: integer 1..11881376 = 9
  increment_scheme, is: key
      (alphabetic, a)
      (decimal, d)
    keyend = decimal
  vsn_list, vsnl: list of any of
      name 1..6
      string 1..6
    anyend = $optional
  file_label_type, flt: key
      (labeled, labelled, l)
      (unlabeled, unlabelled, u)
    keyend = labeled
  type, t: key
      mt9$800, mt9$1600, mt9$6250, mt18$38000
    keyend = mt9$6250
  backup_file, bf: file = $optional
  output_disposition, odi: any of
      key
        (discard_all_output, dao),(discard_standard_output, dso),
        (printer, p),(wait_queue, wt, wq)
      keyend
      file
    anyend = puv$create_catalog_backup, printer
  status)

"  The purpose of this procedure is to create a batch job to backup all
"  catalogs on the system to a set of backup tapes or to a permanent backup
"  file.  The catalogs are backed up in alphabetic order sorted by family and
"  user.  This procedure may be run while there are currently active users.
"
"  The backup tapes or the backup file produced by this procedure may be used
"  as input to the RESTORE_UNRECONCILED_CATALOGS and RESTORE_CATALOGED_FILES
"  procs.  If this backup set or the backup file is used as input to the
"  RESTORE_CATALOGED_FILES proc, the set of partial tapes or the permanent
"  backup file containing the partial backups, if any, need to be
"  restored next, to restore the most recent catalog information.
"
"  To support the use of labelled backup tapes the list of VSN's for the
"  backup tapes are generated by the procedure. The value of the VSN's
"  depends on the values for vsn_prefix, vsn_count and increment_scheme.
"
"  PARAMETERS:
"    vsn_prefix, vsnp: Specify a one to five character name, string or integer
"      that will become the leftmost characters in the list of VSN's generated
"      by the procedure.
"
"    vsn_count, vsnc: The number of backup tapes in the set. The number of
"      tapes actually required for a backup will be unknown until the
"      backup is complete; however, this parameter must be specified to
"      provide enough information to generate a list of VSN's for labelled
"      tapes. The value specified should be larger than the actual amount
"      required. The backup will stop after all the data has been backed up
"      and use only the number of tapes required to hold the data.
"
"    increment_scheme, is: This parameter determines the format for the
"      rightmost characters of the VSN's generated by this procedure.
"      Decimal mode is the default. Alphabetic mode is for situations
"      where a decimal increment scheme does not allow enough tapes.
"
"    vsn_list, vsnl: A list of magnetic tape external VSNs generated by
"      a calling procedure such as SELECT_OPERATOR_MENU.  This parameter
"      value overrides the vsn_prefix, vsn_count, and increment_scheme VSN
"      generation parameters.
"
"    file_label_type, flt: This parameter specifies the type of label
"      on the backup tapes you are using. If this parameter is not specified,
"      then LABELED is used.
"
"    backup_file: This parameter is used to create a permanent backup
"      file, which can be either a permanent mass storage file or a permanent
"      tape file.  If this parameter is specified, the following parameters
"      will be ignored.
"
"          file_label_type
"          increment_scheme
"          type
"          vsn_count
"          vsn_list
"          vsn_prefix
"
"    type, t: This parameter specifies the density of the backup tapes
"      you are using.
"
"    output_disposition, odi: This parameter specifies the destination of the
"      output generated.  The default for this parameter is 'PRINTER'
"
"    help, h: This parameter causes documentation for this procedure to
"      be written to the specified file. The procedure will not be run
"      in this case.
"
" VSN Generation Examples:
"   vsn_prefix=part vsn_count=12 increment_scheme=decimal    ==>part01-part12
"   vsn_prefix=part vsn_count=12 increment_scheme=alphabetic ==>partaa-partal
"
"   vsn_prefix=A1 vsn_count=27 increment_scheme=decimal    ==>A10001-A10027
"   vsn_prefix=A1 vsn_count=27 increment_scheme=alphabetic ==>A1AAAA-A1AABA

  VAR
    backup_file_created: boolean = FALSE
    job_file: file = $unique(:$local)
    volume_list: list 1 .. $max_list of string 6
  VAREND

  IF $specified(backup_file) THEN
    IF $string($file_attributes(backup_file, lifetime)) <> 'UNLIMITED'  THEN
      EXIT procedure WITH $status(false, 'PU', 3330, 'The file specified '//..
'by the BACKUP_FILE parameter must be a permanent mass storage file or a permanent tape file.')
    ELSE
      IF NOT $string($file_attributes(backup_file, registered))='YES' THEN
        create_file f=backup_file
        detach_file f=backup_file
        backup_file_created = TRUE
      IFEND
    IFEND
  ELSE
    IF $specified(vsn_list) THEN
      delete_variable volume_list
      volume_list = $apply(vsn_list, $string(x))
    ELSE
      pup$construct_volume_list vsn_count=vsn_count vsn_prefix=vsn_prefix increment_scheme=increment_scheme ..
            volume_list=volume_list
    IFEND
  IFEND

  IF $specified(backup_file) THEN
    attach_or_request_command = 'attach_file am=write local_file_name=backup_file file= '//$string(backup_file)
  ELSE
    attach_or_request_command = 'request_magnetic_tape file=$local.backup_file ring=yes type='//$string(type)// ..
          ' external_vsn='//$string(volume_list, source)// ..
          '; set_file_attributes file=$local.backup_file file_label_type='//$string(file_label_type)
  IFEND

"Create a file containing a batch job to do the actual backup.
COLLECT_TEXT output=job_file sm='?' until='**END_COLLECT**'
  JOB job_name=create_catalog_backup job_class=system magnetic_tape_limit=unlimited output_disposition=?output_disposition?
    ?attach_or_request_command?

    WHEN any_fault DO
     detach_file file=$local.backup_file
     display_value osv$status
     send_operator_message ' CREATE_CATALOG_BACKUP aborting -check listing '
    WHENEND

    SYSTEM_OPERATOR_UTILITY capability=system_administration
      backup_permanent_files backup_file=$local.backup_file
        VAR
          ignore_status: status
        VAREND
        set_list_options display_excluded_items=false
        set_backup_options include_archive_information=TRUE
        exclude_highest_cycles number_of_cycles=all
        exclude_catalog  $system.$df$client_mainframes  status=ignore_status
        backup_all_files
      QUIT
    END_SYSTEM_OPERATOR_UTILITY
    detach_file file=$local.backup_file
  JOBEND
**END_COLLECT**

  include_file file=job_file
  detach_file file=job_file

PROCEND create_catalog_backup
