DEC-10-YUFA-D Software Updating Package Programmers Reference Oct73

This "SOUP (SOFTWARE UPDATING PACKAGE) PROGRAMMER'S REFERENCE MANUAL" (DEC-10-YUFA-D, Version 3, updated October 1973) describes a set of programs designed to streamline the process of updating system source files for DECsystem10 users.

Purpose: SOUP eliminates the need to redistribute entire software routines when only small portions have changed. Instead, Digital Equipment Corporation (DEC) provides "correction files" containing only the differences in a compressed editing format. SOUP then applies these changes to the user's local copies. It also supports users who maintain their own modified versions of system files, allowing them to incorporate DEC's updates while managing their custom changes. SOUP operates on ASCII files that do not have embedded line sequence numbers, using its own internal line numbering for reference.

Core Programs: The SOUP package consists of three main programs:

1. CAM (Correction Application and Merging):

   • COMPARE: Compares an updated "base file" (original DEC file) with a "user file" (user's modified version) to generate a "correction file" detailing the differences. This is also how DEC generates correction files for distribution.
   • COMERGE: Merges two existing correction files (e.g., user-generated corrections and DEC-generated corrections for the same base file) into a single, combined correction file. It detects and notes "conflicts" where both correction files refer to the same line in the base file.
   • Full CAM: Performs both COMPARE and COMERGE functions simultaneously.
   • Output is always a correction file and potentially a listing file and log file.

2. COMP10:

   • An enhanced version of CAM's COMPARE function, designed with larger buffers to compare "very dissimilar files" that might cause CAM to overflow. It's used for single-file comparisons and outputs a correction file.

3. FED (Final Edit):

   • The "final edit" program that reads a correction file (generated by CAM or COMP10) and applies the specified editing changes (insertions, deletions, replacements of lines, or insertion/deletion of entire files) to a "base file," producing an "updated file."

Workflow and Key Concepts:

• Updating DEC System Files (Unmodified by User): Users only need FED. They feed DEC's correction file to FED, which applies the changes to their base system files.

• Updating User-Modified System Files: This is more complex:

  1. The user first uses CAM (COMPARE option) to compare their current modified file against the original base file, creating a "user correction file."
  2. Then, CAM (COMERGE option) merges this user correction file with the DEC-provided correction file.
  3. CAM identifies any conflicts between the two sets of corrections, which the user must manually resolve by editing the merged correction file (often using TECO).
  4. Finally, FED applies this resolved, merged correction file to the base file to create the updated user version.

• Correction File Format: These files contain special command lines (starting with a minus sign) that instruct FED on operations like file correction headers, file insertion/deletion headers, line insertions, deletions, and replacements. They also include SYNC lines for integrity checks and can contain messages or comments.

• Command Conventions: Programs are invoked with command strings that can include filenames, device names, and various switches (e.g., /I to suppress extension incrementing, /N=n to set match line count for COMPARE, "xxx" for user identifiers in correction files).
• Output: Programs generate updated files, line-numbered listing files (indicating new or deleted lines), and log files containing operational messages.
• Equipment Requirements: Specified core memory (9K for CAM, 4K for FED, 11K for COMP10) and various input/output devices for base files, user files, correction files, and output logs/listings.

The manual provides detailed descriptions of command strings, input/output, messages, and examples for each program and operation. SOUP was originally developed at Case Western Reserve University.