HP OpenVMS Systems Documentation
Content starts here

HP OpenVMS DCL Dictionary

Previous Contents Index

PATCH

On VAX, invokes the Patch utility which patches an executable image, a shareable image, or a device driver image.

On Alpha and I64, 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

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.

Qualifiers

/ABSOLUTE

Patches a file at absolute virtual addresses. This is the default for Alpha and I64 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[=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 (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[=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.

/UPDATE[=(eco-level[,...])] (VAX only)

Requests that only the patches associated with the specified ECO levels be processed. If you specify more than one ECO level, you must separate the ECO levels with commas and enclose the list in parentheses.

When you specify the /UPDATE qualifier, the PATCH command file specification denotes either a command procedure that contains the patches to be processed or an image file to which certain patches are to be applied. When the file specification denotes a command procedure, the /UPDATE qualifier must precede the file specification on the command line. When the file specification denotes an image file, the /UPDATE qualifier can precede or follow the file specification. In either case, the file specification is required.

If PATCH encounters an ECO level in a command procedure that does not match the ECO level specified on the /UPDATE qualifier, PATCH ignores the ensuing patch but displays a message. Whenever you omit the optional ECO levels, PATCH responds by processing all patches submitted.

/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.

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.

Previous Next Contents Index