Google
 

Trailing-Edge - PDP-10 Archives - cuspbinsrc_2of2_bb-fp63b-sb - 10,7/soupr/soupr.man
There are no other files named soupr.man in the archive.











                         CHAPTER 1

                        INTRODUCTION



     SOUPR  (SOftware  Update  Package   Revisited)   is   a
collection of three programs: COMPAR, UPDATE, and MERGE. The
following is a brief description of  each  program.  A  more
detailed explanation can be found in the help files.

1. COMPAR

          The input to COMPAR consists of  two  ASCII  files
     known  as  the base file and the user file. COMPAR will
     compare the two files and create a correction file. The
     correction  file details how the user file differs from
     the base file. The command format is:

     .R COMPAR
     *cor-file=base-file,user-file/switches

2. UPDATE

          COMPAR and  UPDATE  are  inverse  operations.  The
     input   to  UPDATE  consists  of  a  base  file  and  a
     correction file. UPDATE will reconstruct the user file.
     The command format is:

     .R UPDATE
     *user-file=base-file,cor-file/switches

3. MERGE

          The input to MERGE consists of several  correction
     files.  MERGE  will merge them into a single correction
     file. The command format is:

     .R MERGE
     *cor-file=cor-file/switches,cor-file/switches...
INTRODUCTION                                        Page 1-2


     SOUPR is designed to fulfill two functions:

1.   Vendors very  rarely  rewrite  programs  from  scratch.
     Quite  frequently  when  a  new version of a program is
     released,  it  differs  only  slightly  from  the   old
     version.  In  such cases it is wasteful to distribute a
     complete copy of the program. A better  approach  would
     be  to  distribute  only  those portions of the program
     that have been altered. To do this the vendor would use
     COMPAR  to compare the old version with the new version
     and create a correction file. The correction file would
     be  distributed  to  the customers. The customers would
     use UPDATE to reconstruct the program from  their  copy
     of the old version.

2.   Many installations modify vendor  software.  Each  time
     the  vendor  releases  a  new version of a program, the
     installation must recode the local  features.  A  quick
     way  to  do  this  is  to  use  COMPAR  to  create  two
     correction files: one with the local features, and  one
     with  the  vendor's  new  features.  The two correction
     files can then be merged into a single correction  file
     with  MERGE.  Finally, UPDATE is used to generate a new
     source file.











                         CHAPTER 2

                 FORMAT OF THE SOURCE FILE



     Although SOUPR is normally used with assembly language,
this is not a restriction. SOUPR may be used with any source
file. In fact, SOUPR may be used with any  ASCII  file.  The
file  is  not  parsed  in any way. Binary files (such as REL
files and SAVE files) may not be used.

     Each line in the  source  file  is  identified  by  the
notation  "n/m".  Where  n  is the line number, and m is the
page number.

     A line is an arbitrary  sequence  of  ASCII  characters
terminated  by a break character. The break character itself
is considered to be  part  of  the  line.  In  the  case  of
consecutive  break  characters, each character is considered
to be a seperate line. The following are defined to be break
characters:

          12   LF   Line Feed
          13   VT   Vertical Tab
          14   FF   Form Feed
          32   ^Z   control Z
          33   ESC  ESCape


     A page is an arbitrary sequence of lines terminated  by
a  form  feed.  The form feed itself is considered to be the
last character of the last line of the previous page.  Since
form  feeds  are usually preceded by <CR><LF>, the form feed
is usually the only character in its line.

     SOUPR will ignore the line sequence  numbers  generated
by SOS.











                         CHAPTER 3

               FORMAT OF THE CORRECTION FILE



     Each line in the  correction  file  is  prefixed  by  a
special  character. This character determines which of three
categories the line falls into:

1.   Commands  to  SOUPR  (see  below).  All  commands   are
     prefixed by a space (ASCII 40).

2.   Text to be acted upon by the  commands.  Each  line  of
     text  is  prefixed  by a tab (ASCII 11). Except for its
     use as a delimiter, the tab is ignored.

3.   In the event that a line fails to be prefixed by either
     a  space  or  a  tab, the line is regarded as text. The
     first character, whatever it may be, is  considered  to
     be part of the text.



     SOUPR supports five types of commands:

1.    DELETE n/m ;comment
             text

          Delete text starting at line n of page m. The text
     to  be  deleted  follows  immediately  after the DELETE
     command, and continues until a space is encountered  in
     column  one (i.e. another command). If the text at line
     n of page m in the base file is different from the text
     in  the correction file, UPDATE will flag the condition
     as an error.

2.    INSERT n/m ;comment
             text

          Insert text just before line n of page m. The text
     to  be  inserted  follows  immediately after the INSERT
     command, and continues until a space is encountered  in
     column one.

3.    REPLACE n/m ;comment
FORMAT OF THE CORRECTION FILE                       Page 3-2


             text1
      WITH
             text2

          At line n of page  m  replace  text1  with  text2.
     Text1  follows  immediately  after the REPLACE command,
     and continues until a space is  encountered  in  column
     one.  This  line  will  be  the WITH auxiliary command.
     Text2 follows immediately after the WITH  command,  and
     continues  until  a space is encountered in column one.
     If the text at line n of page m in  the  base  file  is
     different  from  text1  in  the correction file, UPDATE
     will flag the condition as an error.

4.    SUM n ;comment

          Where n is a rotate add one checksum of  the  base
     file.  While  processing  the  base  file,  UPDATE will
     recompute this checksum. If the value  does  not  match
     that  stored  in  the correction file, UPDATE will flag
     the condition as an error. Hence a  user  is  prevented
     from  accidentally  using  the  correction file with an
     incorrect version of the base file. MERGE will type  an
     error  message  if  a user attempts to merge correction
     files with different checksums. The SUM  command  marks
     end of file.

5.    ;comment

          Ignored.


                            NOTE

               All  keywords  (e.g.   DELETE,
               INSERT,   REPLACE,  WITH,  and
               SUM) may be abbreviated to the
               smallest    unambiguous   form
               (currently one letter).



     MERGE goes to a great deal of trouble to make conflicts
easy to resolve. The begining and ending of each conflict is
clearly labeled and numbered. For example, a section of  the
correction file might appear as:

 ;***BEGINING OF CONFLICT 3***
 DEL 66/5
                 JRST    FOO
 REP 66/5
                 JRST    FOO
 WIT
         ;FALL TO ROUTINE FOO
 ;***END OF CONFLICT 3***
FORMAT OF THE CORRECTION FILE                       Page 3-3


The programmer can quickly see that both patches  attempted.
to  do the same thing, they merely did it in different ways.
The object was to remove the JRST at line 66 of page 5.  The
first  patch  tried  the straightforward approach, it merely
deleted the line. The second patch attempted to replace  the
line  with  a  comment.  But  MERGE doesn't realize that the
patches are equivalent. MERGE will type  a  warning  message
that  conflicts  exist.  The  programmer  must  type out the
correction file and study the conflicts. In  this  case,  he
merely  decides which patch he wishes to use and removes the
other. This sort of "conflict", by the way, is quite common.
It's  nice  to  know that even when conflicts do occur, they
are usually easy to resolve.











                         CHAPTER 4

                          EXAMPLES



                   Example one - Comerge

     A.MAC is a vendor program. A certain  installation  has
added  a new feature to the program. The improved version is
called B.MAC . The vendor has just released a new version of
the  program  called  C.MAC . The installation would like to
add the same feature to C.MAC . The resulting  version  will
be called D.MAC . This can be accomplished as follows:

.TYPE A.MAC
        TITLE   DECO
        T1=1
        T2=T1+1
        P=17
DECO::  IDIVI   T1,^D10
        PUSH    P,T2
        SKIPE   T1
        PUSHJ   P,.-3
        POP     P,T1
        ADDI    T1,"0"
        OUTCHR  T1
        POPJ    P,
        END

.TYPE B.MAC
        TITLE   DECO
        T1=1
        T2=T1+1
        P=17
DECO::  IDIVI   T1,^D10
        HRLM    T2,(P)
        SKIPE   T1
        PUSHJ   P,.-3
        HLRZ    T1,(P)
        ADDI    T1,"0"
        OUTCHR  T1
        POPJ    P,
        END
EXAMPLES                                            Page 4-2
comerge


.TYPE C.MAC
        TITLE   DECO
        T1=1
        T2=T1+1
        P=17
DECO::  JUMPGE  T1,.+3
        OUTCHR  ["-"]
        MOVNS   T1
        IDIVI   T1,^D10
        PUSH    P,T2
        SKIPE   T1
        PUSHJ   P,.-3
        POP     P,T1
        ADDI    T1,"0"
        OUTCHR  T1
        POPJ    P,
        END

.RUN COMPAR
*AB=A,B
AB.COR=A.MAC,B.MAC
*AC=A,C
AC.COR=A.MAC,C.MAC
*^C

.TYPE AB.COR
 REP 6/1
                PUSH P,T2
                SKIPE T1
                PUSHJ P,.-3
                POP P,T1
 WIT
                HRLM T2,(P)
                SKIPE T1
                PUSHJ P,.-3
                HLRZ T1,(P)
 SUM 179838

.TYPE AC.COR
 REP 5/1
        DECO::  IDIVI T1,^D10
 WIT
        DECO::  JUMPGE T1,.+3
                OUTCHR ["-"]
                MOVNS T1
                IDIVI T1,^D10
 SUM 179838

.RUN MERGE
*AD=AB,AC
AD.COR=AB.COR,AC.COR
*^C
EXAMPLES                                            Page 4-3
comerge


.TYPE AD.COR
 REP 5/1
        DECO::  IDIVI T1,^D10
 WIT
        DECO::  JUMPGE T1,.+3
                OUTCHR ["-"]
                MOVNS T1
                IDIVI T1,^D10
 REP 6/1
                PUSH P,T2
                SKIPE T1
                PUSHJ P,.-3
                POP P,T1
 WIT
                HRLM T2,(P)
                SKIPE T1
                PUSHJ P,.-3
                HLRZ T1,(P)
 SUM 179838

.RUN UPDATE
*D=A,AD
D.MAC=A.MAC,AD.COR
*^C

.TYPE D.MAC
        TITLE   DECO
        T1=1
        T2=T1+1
        P=17
DECO::  JUMPGE  T1,.+3
        OUTCHR  ["-"]
        MOVNS   T1
        IDIVI   T1,^D10
        HRLM    T2,(P)
        SKIPE   T1
        PUSHJ   P,.-3
        HLRZ    T1,(P)
        ADDI    T1,"0"
        OUTCHR  T1
        POPJ    P,
        END
EXAMPLES                                            Page 4-4
comerge


                  Example two - Conflicts

     A user wishes to apply two  corrections  files  (AB.COR
and  AC.COR)  to a single base file (A.MAC). But some of the
patches conflict with each other. The user may  resolve  the
conflicts as follows:

.TYPE A.MAC
        TITLE   BP
        T1=1
        C=10
        P=17
BP::    CAMN    C,[15]
        INCHWL  C
        MOVEI   T1,1
        LSH     T1,(C)
        TDNE    T1,[1400012000]
        POPJ    P,
        HALT
        END

.TYPE AB.COR
 REP 5/1
        BP::    CAMN C,[15]
 WIT
        BP::    CAIN C,15
 REP 9/1
                TDNE T1,[1400012000]
 WIT
                TDNE T1,[1400016000]
 SUM 238801

.TYPE AC.COR
 REP 9/1
                TDNE T1,[1400012000]
 WIT
                TDNE T1,[1400012200]
 REP 11/1
                HALT
 WIT
                JRST ERROR##
 SUM 238801

.R MERGE
*AD=AB,AC
AD.MAC=AB.COR,AC.COR
%MERFLT 1 CONFLICT
*^C

.TYPE AD.COR
 REP 5/1
        BP::    CAMN C,[15]
 WIT
        BP::    CAIN C,15
EXAMPLES                                            Page 4-5
conflicts


 ;***BEGINNING OF CONFLICT 1***
 REP 9/1
                TDNE T1,[1400012000]
 WIT
                TDNE T1,[1400012200]
 REP 9/1
                TDNE T1,[1400012000]
 WIT
                TDNE T1,[1400016000]
 ;***END OF CONFLICT 1***
 REP 11/1
                HALT
 WIT
                JRST ERROR##
 SUM 238801

.TECO AD.COR
*S***$0LKFS122$162$L5KEX$$

.TYPE AD.COR
 REP 5/1
        BP::    CAMN C,[15]
 WIT
        BP::    CAIN C,15
 REP 9/1
                TDNE T1,[1400012000]
 WIT
                TDNE T1,[1400016200]
 REP 11/1
                HALT
 WIT
                JRST ERROR##
 SUM 238801

.R UPDATE
*D=A,AD
D.MAC=A.MAC,AD.COR
*^C

.TYPE D.MAC
        TITLE   BP
        T1=1
        C=10
        P=17
BP::    CAIN    C,15
        INCHWL  C
        MOVEI   T1,1
        LSH     T1,(C)
        TDNE    T1,[1400016200]
        POPJ    P,
        JRST    ERROR##
        END











                         CHAPTER 5

                        CONDITIONALS



     One of the most  powerful  features  of  SOUPR  is  the
conditionals  facility. To use this facility each command in
the correction file is  labeled  with  a  sixbit  name.  The
correction  file  is  then regarded as a library of patches.
Each patch is refered to by name. The user may specify which
patches from the library are to be used.

     Labels are placed at the end of a  statement,  and  are
preceded by a semicolon. E.G.:

 INS 3/4 ;XYZBUG SPR#3141

Those of you who are familiar with MACRO will recognize  the
label  as  a  cross between a comment and a TITLE. The label
resembles a comment in that it may contain  any  information
that  the user feels would be helpful. The label resembles a
TITLE in that the first word is taken as  the  name  of  the
module.  Thus in the example above, the name of the patch is
"XYZBUG". The following is a list of  data  that  one  might
wish to include in a comment:

1. Patch name
2. SPR number
3. MCO/PCO number
4. Edit number
5. Brief description

     Labels are added to patches by using the  /NAME  switch
in COMPAR. The switch has two forms:

/NAME:"string"
/NAME:foo

The former is used to specify an entire string. The later is
used to specify just a sixbit name.

     The following is a list  of  switches  used  to  select
which  patches  from the library are to be used. Both UPDATE
and MERGE have each of the switches:
CONDITIONALS                                        Page 5-2



/NCLUDE:x           Processing includes only  those  patches
                    labeled with x. Wildcards are legal. The
                    default is * (i.e. include all patches).
/NCLUDE:(x,y,...)   Specifies  a  list  of  patches  to   be
                    included
/UNCLUD             Unlabeled patches  are  always  included
                    (default)
/UXCLUD             Unlabeled patches are always excluded
/XCLUDE:x           Processing   excludes   those    patches
                    labeled with x
/XCLUDE:(x,y,...)   Specifies  a  list  of  patches  to   be
                    excluded

Examples:
1.   To create a labeled patch:

     .R COMPAR
     *cor-file=base-file,user-file/NAME:foo

2.   To apply a single patch:

     .R UPDATE
     *user-file=base-file,cor-file/NCLUDE:foo

3.   To apply all but a single patch:

     .R UPDATE
     *user-file=base-file,cor-file/XCLUDE:foo

4.   To add a new patch to the library:

     .R MERGE
     *new-library=old-library,new-patch

5.   To remove a patch from the library:

     .R MERGE
     *new-library=old-library/XCLUDE:foo

6.   To extract a patch from the library:

     .R MERGE
     *cor-file=library/NCLUDE:foo