PATCH
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help PATCH *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
On VAX, invokes the Patch utility, which patches an executable
image, a shareable image, or a device driver image.
For more information about the Patch utility, refer to the
OpenVMS VAX Patch Utility Manual (available on the Documentation
CD-ROM) or online help.
Format
PATCH filespec
| 1 - Parameters |
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 |
2.1 - /ABSOLUTE
Patches a file at absolute virtual addresses. 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.
2.2 - /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.
2.3 - /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.
2.4 - /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.
2.5 - /UPDATE
/UPDATE[=(eco-level[,...])]
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.
2.6 - /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.
| 3 - 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
An 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.
|
|
