1  PATCH



   On Alpha and Integrity servers, invokes PATCH/ABSOLUTE, by
   default, which patches a file at absolute virtual addresses.

   For more information, see the online help inside the Patch
   Utility.

   Format

     PATCH  filespec
 

2  Parameter
 

filespec

   Specifies the image file to be patched or a command procedure
   that contains both the name of the image file to be patched and
   PATCH commands.

   If the file specification denotes an image file, the file
   specification must contain the file name. If you omit the
   remaining fields (device, directory, file type, and version
   number), PATCH uses your default device and directory, assumes
   a file type of EXE, and uses the highest version of the image
   file.

   If the file specification denotes a command procedure, the
   filespec parameter must be preceded by an at sign (@). Only
   the file name is required. If you omit the remaining fields
   (device, directory, file type, and version number), PATCH uses
   your default device and directory, assumes a file type of COM,
   and locates the highest version of the command procedure.

   The asterisk (*) and the percent sign (%) wildcard characters are
   not allowed in the file specification.
 

2  Qualifiers
 

/ABSOLUTE

   Patches a file at absolute virtual addresses. This is the
   default for Alpha and Integrity server systems. The /ABSOLUTE
   function allows a user to patch any file (not just image files)
   at absolute virtual addresses relative to the beginning of the
   file. This feature allows replacement of existing data with new
   data of the same length. If the data is smaller than that of
   the original data, PATCH uses the appropriate fill character for
   the mode in use. For example, if the current mode is instruction
   mode, a NOP is used for fill; if it is data (numeric or ASCII)
   mode, a NULL is used for fill. Any PATCH operation that results
   in a data replacement longer than the length of the original
   data generates an error message and terminates the command in
   progress; either the PATCH or DCL prompt is then displayed,
   whichever is appropriate.

   Also, note that there is no default patch area, and none will be
   created, because of the tendency to corrupt a file. Patch area is
   meaningless in other than an image file.

   If you patch a file in absolute mode, remember that there are no
   symbols available to assist you in locating data locations. You
   must exercise great care to ascertain that the correct locations
   are modified.

   Most PATCH commands will work in their normal fashion. However,
   only REPLACE and DEPOSIT should be used for write operations;
   other commands are acceptable for read operations. Commands that
   attempt to expand the file, such as ALIGN and INSERT, should
   be avoided because they will probably corrupt the file. (These
   commands will be trapped by PATCH and an error message will be
   issued indicating that the replacement data must not exceed the
   length of the original data.)

   File attributes are propagated from the original input file to
   the output file. These include ALQ, TYPE, MRS, RAT, RFM, and RAC.
 

/JOURNAL

      /JOURNAL[=filespec]

   Indicates an alternate journal file specification. By default,
   PATCH creates a journal file with a file specification that
   consists of the current defaults. Use the /JOURNAL qualifier when
   you want to specify an alternate file specification. If you omit
   fields in the file specification, PATCH supplies the following
   default values:

   Filespec Field              Default Value

   device and directory        defaults of current process
   file name                   name of input image file
   file type                   JNL
   version                     1

   Subsequent PATCH sessions append information to the journal file,
   rather than create a new version of this file.

   The asterisk (*) and the percent sign (%) wildcard characters are
   not allowed in the file specification.
 

/NEW_VERSION

      /NEW_VERSION (default)
      /NONEW_VERSION

   Controls whether a new version of the patched file is created
   or the contents of the existing file are modified in place. The
   /NEW_VERSION qualifier is used in conjunction with the /ABSOLUTE
   qualifier to control whether a new version of the patched file
   is created or the contents of the existing file are modified
   in place. /NEW_VERSION is the default. If /NONEW_VERSION is
   selected, the PATCH command UPDATE will act as a checkpoint
   operation, that is, all modifications made to the file are
   written back to the file instead of waiting until image exit.
   If /ABSOLUTE is not specified with /NONEW_VERSION, /NONEW_VERSION
   is ignored, that is, a new version of the file will be created.
   /NONEW_VERSION will need to be used when patching large data
   files when there is not enough disk space to create a new version
   of the patched file.

                                  NOTE

      If /NEW_VERSION is specified, the file will be overwritten.
      No attempt on the part of the user, including pressing
      Ctrl/Y, will prevent this result. Therefore, you should
      have a back up copy of the file before making any attempt to
      patch it.

      PATCH will always issue an informational message at image
      exit, indicating that the file is being overwritten.
 

/OUTPUT

      /OUTPUT[=filespec]

   Indicates the output image file specification. By default, PATCH
   creates an output file with a file specification that consists of
   the current defaults. Use the /OUTPUT qualifier when you want to
   specify an alternate file specification.

   If you omit fields in the file specification, PATCH supplies the
   following default values:

   Field                       Default Value

   device and directory        defaults of current process

   file name                   name of input image file

   file type                   .EXE

   version                     one greater than the most recent copy
                               of the input image file

   The output image file is created only when you issue the PATCH
   command UPDATE at the end of the PATCH session. You can issue
   multiple UPDATE commands in a single session. The first UPDATE
   command creates the output image file; subsequent UPDATE commands
   overwrite this file.

   The asterisk (*)  and the percent sign (%) wildcard characters
   are not allowed in the file specification.
 

/VOLUME

      /VOLUME[=n]

   Requests that the output file be placed on a specified relative
   volume number of a multivolume set. If you specify /VOLUME
   without a number, the number defaults to the relative volume
   number of the input image file.

   If the /VOLUME qualifier is not specified, the file is placed in
   an arbitrary position within the multivolume set.
 

2  Examples

   1.$ PATCH/ABSOLUTE IMAGE.EXE
     PATCH>EX/INS 604
     00000604:  BBSS    #07,R1,00000608
     PATCH>REPLACE/INS 604='BBSS #07,R1,0608'
     NEW>  'BBSS #07,R1,0608'
     NEW>  'CLRL R0'
     NEW>  EXIT
     old: 00000604:  BBSS    #07,R1,00000608
     %PATCH-E-DATTOOLNG, length of new data may not exceed length of
     old data
     PATCH>EX/INS 684
     00000684:  MOVB    #01,(R5)+
     PATCH>REPLACE/INS 684='MOVB #01,(R5)+'
     NEW>  'MOVB #02,(R5)+'
     NEW>  EXIT
     old: 00000684:  MOVB    #01,(R5)+
     new: 00000684:  MOVB    #02,(R5)+
     PATCH>EX/INS 687
     00000687:  MOVB    #00,(R5)+
     PATCH>DEPOSIT/INS 687
     NEW>  'CLRB (R5)+'
     NEW>  EXIT
     old: 00000687:  MOVB    #00,(R5)+
     new: 00000687:  CLRB    (R5)+
     PATCH>INSERT/INS 68D
     OLD>  'MOVB #10,(R5)+'
     NEW>  'MOVB #20,(R5)+'
     NEW>  EXIT
     old: 0000068D:  MOVB    #10,(R5)+
     %PATCH-E-DATTOOLNG, length of new data may not exceed length of
     old data
     PATCH>UPDATE
     %PATCH-I-WRTFIL, updating image file
     DISK$STARWORK01:[NASR.PATCH]IMAGE.EXE;2
     PATCH>EXIT

     Example of the /ABSOLUTE qualifier with /NEW_VERSION as the
     default. Note the error messages returned when the command
     tries to expand the file.
 


   2.$ PATCH/ABSOLUTE/NONEW_VERSION  LOGIN.COM
     PATCH>EX/ASCII 57
     00000057:  'MANA'
     PATCH>REPLACE/ASCII 57='MANA'
     NEW>  'mana'
     NEW>  'test'
     NEW>  exit
     old: 00000057:  'MANA'
     %PATCH-E-REPLACEERR, replacement value too large for location
     PATCH>replace/ascii 57='MANA'
     NEW>  'mana'
     NEW>  exit
     old: 00000057:  'MANA'
     new: 00000057:  'mana'
     PATCH>EX/ASCII 24
     00000024:  'F$MO'
     PATCH>INSERT/ASCII 24='F$MO'
     NEW>  'test'
     NEW>  exit
     %PATCH-E-INVCMD, invalid command
     PATCH>UPDATE
     %PATCH-I-OVERLAY, DISK$STARWORK01:[NASR.PATCH]LOGIN.COM;1 being
     overwritten
     PATCH>EX 68:75
     00000068:  4349544F
     0000006C:  58542E45
     00000070:  00010054
     00000074:  00100024
     PATCH>REPLACE 68
     OLD>  4349544F
     OLD>  58542E45
     OLD>  00010054
     OLD>  EXIT
     NEW>  6369746F
     NEW>  68642E65
     NEW>  00010074
     NEW>  EXIT
     old: 00000068:  4349544F
     old: 0000006C:  58542E45
     old: 00000070:  00010054
     new: 00000068:  6369746F
     new: 0000006C:  68642E65
     new: 00000070:  00010074
     PATCH>EX/ASCII 68
     00000068:  'otic'
     PATCH>UPDATE
     %PATCH-I-OVERLAY, DISK$STARWORK01:[NASR.PATCH]LOGIN.COM;1 being
     overwritten
     PATCH>EXIT
     %PATCH-I-OVERLAY, DISK$STARWORK01:[NASR.PATCH]LOGIN.COM;1 being
     overwritten
     $

     Example of a PATCH/ABSOLUTE/NONEW_VERSION command. Note the
     error messages that are returned when the command tries to
     expand the file, and when the commands UPDATE and EXIT are
     performed, that is, (file) "being overwritten."

   3.$ PATCH AVERAGE /JOURNAL=TEST /OUTPUT=TEST

     This command invokes PATCH for an interactive PATCH session
     with the image file AVERAGE.EXE. The journal file and output
     image file created by this session are both named TEST and
     reside in the default device and directory. The journal file
     has a file type of JNL, and the output image file has a file
     type of .EXE.

   4.$ PATCH /UPDATE=(100,102) @ORION
     $

     This PATCH command executes the command procedure ORION.COM.
     The /UPDATE qualifier requests that only the patches identified
     by the ECO levels 100 and 102, contained in ORION.COM, be
     processed. The first record in ORION.COM must specify the
     input image file. The second DCL prompt ($) indicates that
     the patches were successfully applied.
 

