HP 3000 Manuals HP 3000 Manuals
Operation
The MPE/iX command interpreter includes the implied RUN concept, which
allows the user to invoke a program merely by naming it. For the
SOMPATCH utility, type sompatch[.group[.account]] and then specify a
string of parameters (enclosed in quotes) before typing Return. The
program file is searched according to the CI variable HPPATH. Currently,
the SOMPATCH utility is stored in PUB.SYS.
You may specify the following parameters on the command line:
* name of file to be patched
* name of script file
* name of output list file
The last two files can be specified in one of two ways. To use the
C-shell indirection syntax, enter:
sompatch mainfile patchfil> listfile
Or, to specify the files either positionally or by using the key words
USE and LIST, respectively, enter:
sompatch "nl.abuild, patchfil, patchlst"
sompatch "nl.abuild,,patchlst"
sompatch "nl.abuild use:patchfil list:patchlst"
If you use a patch file as is shown in the example, SOMPATCH executes all
commands in the patch file and returns you to the MPE prompt.
The following example shows how to patch a file that has been linked with
a ypatch file.
Using a text editor, create a patch file that has the following four
lines:
log junie moon from august skies, 163, 4700741260
; fixes system crash on listf ,5
modify iobuf+20, 2, 12345678 | 22222222 33333333|FFFFFFFF
exit
In this command:
Junie moon is the integrator,
August skies supplied the patch,
163 is the number of the patch, and
listf ,5 is the system command that needs to be fixed.
; A semicolon signifies that the rest of the line is
a comment.
SR 4700741260 is the STARS SR where the breakdown is documented.
iobuf+20 is the location to modify with an offset of 20
bytes.
2 indicates that two 32-bit words need to be changed.
222222222 and FFFFFFFF are the new values.
12345678 and 33333333 are the old values.
The file to be patched is nl.abuild00.official.
When using a patch file, specify a list file, so that if the JCW is FATAL
after the SOMPATCH utility executes, the list file can be examined to
determine the problem.
In the following examples, the patch file is pat0511 and the list file is
lpat0511.
sompatch "nl.abuild00.official <pat0511 >lpat0511"
OR
sompatch "nl.abuild00.official,use:pat0511,list:lpat0511"
Interactive patching
Normally, the LOG command is used with all of the required parameters
specified, just as in the example above; however, the SOMPATCH utility
also provides user prompting for the log command.
: { at colon prompt, type }
sompatch nl.abuild00.official Return
{invoke program, giving primary file}
sp>log Return {a log command is required before the first modify}
username>junie moon from august skies Return{program is prompting}
patchid>163 Return
srnumber>4700241760 Return
comment>fixes system crash on listf ,5 Return
comment> Return {a Return signifies end of comment}
sp>modify iobuf+20, 2
12345678|22222222 33333333|FFFFFFFF Return {application of the patch}
sp>exit Return {exit program, saving patched nl.abuild00.official}
: {the colon prompt returns}
; (semicolon)
This command describes the reason that a patch is being applied. It
indicates problem symptoms and a fix description. A minimum of one line
of comment text is required for each set of modify instructions composing
a patch. You should describe the symptoms of the problem in detail, with
an explanation when you anticipate a fix in source.
Syntax
; text
Parameters
text The ASCII text describing the problem and why the
patch fixes it.
Example
;no_op call to check_for_overflow to prevent system error
;#2099 on bootup.
;source fix anticipated in SEL CORE release C.06
BACKOUT
This command returns a file previously patched to an unmodified state.
It is possible to undo a patch if the patch ID given in the LOG command
used to apply the patch is known. This number can be seen in the output
of the SHOW [BACKOUTS] command. The patch file name also can be used to
back out the set of patches applied with the patch file.
Backout commands are preserved in the ypatch information area. They can
be also seen when using the [BACKOUTS] option on the SHOW command.
All backouts are displayed as they are done (at program exit).
NOTE This command is not available unless the file being patched has
been linked with a ypatch file.
Syntax
BA[CKOUT] [ :patchid ]`lb`
[ @ ]`lb`
[ file=patchfilename]
Parameters
patchid The patch to be backed out by its identification
number (as given with the LOG command).
@ Causes all applied patches to be backed out.
file= Causes the SOMPATCH utility to look for all patches
applied under patchfilename and to back them all
out. If there is no reference to patchfilename in
the audit history, an error message is issued.
patchfilename The name of a patch file that was used to make
modifications to the primary input file. Group and
account default to the logon if not specified.
Example
backout :12
This example shows 12 as the patch ID specified with the LOG command.
backout file=patchfle.pub
This example shows that all patches applied under patchfle.pub are to be
removed.
Error Messages
No patchfile as given.
CAUSE The FILE= option specified a script file that was
not used on this file. The FILES option on the
SHOW command indicates what files have been used.
ACTION Specify the correct file.
No patchid as given.
CAUSE An attempt was made to back out a patch that the
Sompatch utility does not have recorded. The JCWs
will be set to their respective FATAL conditions.
ACTION Use the SHOW command to find out what patches are
recorded.
NOTE If more than one patch under the same patch ID has been entered, or
if patches were applied under the same file name more than once,
everything specified is backed out. If in doubt, use the SHOW
command to see the buffer's contents for a given patch ID or file
name.
DISPLAY
This command displays the value(s) at a location.
Syntax
DI[SPLAY] symbolname [+/-offset][,count][mode]
Parameters
symbolname Symbolname is the string name of an external symbol
given in the link map for the file being patched.
offset Offset is the offset (in bytes) from the start of
the symbol. It can be specified as a simple
numeric expression. The default value is 0.
count Count is the word count (32-bit words) for the
command. The default value is 1.
mode Mode is the display mode.
The values for mode are:
?X Hex (default)
?D Decimal
?O Octal (two 6-digit octal numbers)
?C Characters
The display is sent to $STDLIST. The parameter symbolname may be entered
in uppercase or lowercase or mixed case, unless it is defined in a C
procedure, in which case it must be entered in the specific case in which
it is listed out from the linker. If the symbol starts with an underbar,
that should be entered as the first character.
If the values to be displayed are the result of modifications made
earlier in the SOMPATCH utility session, then the oldvalue|newvalue
convention of the MODIFY command is used to indicate it. In the example
below, only the word at iobuf+10 has been modified since the user invoked
the SOMPATCH utility. (It is currently 1234ABCD in the file and will be
200 if the program is terminated with an EXIT command or a SAVE command.)
sp> display iobuf+2,3,?X Return
22222222 FFFFFFFF 1234ABCD200|
Error Messages
Symbol symbolname not found.
CAUSE The JCWs are set to their respective WARN status.
ACTION Use the FIND command to search for the symbol.
EXIT
This command is used to exit the program and save the modifications made
to the primary input file. To obtain a backup copy, make one before
running the SOMPATCH utility.
If the SOMPATCH utility is being run interactively and patch xx had an
error, the following message is printed:
Error(s) in patch xx but valid modifies will be applied upon exit.
Syntax
EX[IT]
Parameters
None
FIND
This command displays the following information about a symbol:
* residency status (that is, memory resident, initially resident or
neither)
* index of SOM (that is, for a multi-SOM library, which SOM contains
the symbol)
* symbol type (CODE, DATA, PRIMARY PROGRAM,...)
This command can also be used to look for a symbol when its name is not
known.
Syntax
F[IND] symbolspec
Parameters
symbolspec The string name of an external symbol as given in
the link map for the file being patched. All
symbols are case-sensitive.
The "at" symbol (@) may be used as a leading or trailing mask, as shown
in the example below.
Example
The following example displays `trap_handler$248$set_up_user_trap
:find @set_up_user_trap
HELP
This command displays a summary of commands, including syntax and
options.
Syntax
HE[LP]
Parameters
None
LIST
This command causes the SOMPATCH utility to open an output list file.
Syntax
LI[ST] filename
Parameters
filename The output list file name. If you omit the group
and account, SOMPATCHcreates the file in the logon
group and account.
SOMPATCH uses the output list file to record all commands it encountered,
all old values that were modified, and any errors that occurred.
Example
To append output to an existing file, use the C-shell redirection
feature. For example:
sompatch "mainfile <cmdfile >>listfile"
If for some reason the file cannot be opened, an error message is
generated and the JCWs are set to WARN status. Reissue the LIST command
and enter a legal output file name.
LOG
This command records important information about the specified patch.
Syntax
LO[G ] username ,patchid [,srnumber]
Parameters
username An ASCII string that gives the name of the person
installing the patch and the name of the patch
creator, if it is not the same person. The string
is terminated by a comma, but can include other
non-alpha characters.
patchid The identification code from the patch management
system. It is parsed as a string and is terminated
by a comma. Blanks are ignored.
srnumber The SR number that this patch is fixing.
Every patch made on a shared file should have associated with it, at a
minimum, the patch ID. The other parameters to this command are also
important, but they may not be known at the time that the patch is
applied. Always build the file with one of the ypatch files so that this
information is saved.
Use the LOG command before the first MODIFY command and before each
subsequent patch, where each patch is composed of a set of one or more
functionally connected modify commands.
If you do not enter any parameters, LOG will prompt you for them. Refer
to the "Operation" section.
Example
sp> log STEVE THOMPSON, 155 Return
sp> log jim gann(by Kate T.), 19, 4700-192066 Return
Error Messages
No username given.
CAUSE The first parameter (username) is missing.
ACTION Supply username.
No patchid given.
CAUSE The second parameter (patchid) is missing.
ACTION Supply patchid.
File not built with ypatch.
CAUSE The file being patched has not been linked with a
buffer ypatch file.
ACTION Refer to the "Preparation for Use" information on
how to do this. JCWs are set to their respective
FATAL conditions.
MODIFY
This command modifies the value(s) at a specified location.
Syntax
MO[DIFY] [symbol][+/-off][,count] [?mode] [oval] nval ...`lb`
Parameters
symbol Specifies the name of the associated level 1
symbol. This is normally a CODE type symbol, but
SOMPATCH accepts a DATA symbol. If the symbol has
duplicates (that is, the same name is used more
than once in a multi-SOM library), the SOM command
must be used to tell SOMPATCH which SOM to look in
for the desired symbol. If the symbol is not
specified, absolute addressing from 0 is assumed.
off The offset (in bytes) from the start of the symbol.
It can be specified as a simple numeric expression.
The default is 0. If no symbol is specified, the
offset must be positive.
count The word count (32-bit words) for the command. The
default is 1. It is not needed for character mode.
mode Indicates how the values are coming in, which can
be one of hex, decimal, character, or octal. The
default is hex. Refer to the DISPLAY command for
syntax.
oval The current value of specified location. Oval
should be given whenever possible so that SOMPATCH
can verify that the modification instruction does
indeed reference the correct area in the file.
Mode specification is the same as given under the
nval entry.
nval The new value for a specified location. The
default base specification mode is hex.
NOTE To specify verify on only part of the word, use a "#" character to
specify each digit to be ignored.
All modifications are made in a buffer. However, if you issue a DISPLAY
command following a MODIFY command and reference the same location, you
will see the oldvalue|newvalue pair.
Multi-SOM patches
If a MODIFY command belongs to a symbol in a different SOM from the last
symbol encountered, and there is no new LOG command, and the relevant
SOMs have been built with a ypatch file, then the following action is
taken:
1. The current patch is written.
2. A new patch is generated, with the same information as the last
one (user, patchid, srnumber), but with comments truncated.
3. An informational message is displayed.
Error handling
If there is an error in a MODIFY command, the SOMPATCH utility takes one
of the following actions, depending on its state:
* When running the program interactively, the current MODIFY command
is not applied, but all previous good MODIFY commands are applied.
* If the input to the SOMPATCH utility is coming from a patch file,
and the SOM being patched has not been built with a ypatch file,
then the current MODIFY command is not applied, but all previous
good MODIFY commands are applied.
* If the input to the SOMPATCH utility is coming from a patch file,
and the SOM being patched has been built with a ypatch file, then
none of the current patch (as specified by the last LOG command)
is applied.
Example
sp>modify iobuf+10 2154#### FFFFFFFF Return
{only check upper 16 bits}
Also refer to the "Operation" section for an example of this command.
Error Messages
Symbol symbolname not found.
CAUSE PATCHJCW is set to the FATAL condition.
ACTION Change the PATCHJCW setting.
Old value is not as specified.
CAUSE The old value is displayed, and PATCHJCW is set to
the FATAL condition.
ACTION Specify the old value.
Illegal syntax--use help.
CAUSE PATCHJCW is set to the FATAL condition.
ACTION Use the help facility, and supply the legal syntax.
OFFSET
This command searches for a set of numbers in a range around a specified
symbol.
Syntax
OFFSET symbolname number0 [number1 number 2 ... numbern]
Parameters
symbolname Symbolname is an entry from the library symbol
table or current SOM dictionary.
numbern Number0..numbern is a sequence of numbers that the
user is looking for. The maximum is 10 numbers.
This command is used mainly in relocating a patch. When an NL is
relinked, all those patches that were not bound to their own entry-level
procedure (refer to the SYMBOL command) move around. The OFFSET command
can be used to find their new location.
OPEN
This command causes a patch to open a new file for patching or query. It
specifies the input file to be patched. If a file is already open and
patches have been made to it, the SOMPATCH utility reminds the user that
a SAVE command is necessary to save changes before opening the new file.
If the file you specified cannot be opened for read/write, an error
message is generated, and the JCWs are set to their respective FATAL
conditions.
Syntax
OP[EN] filename
Parameters
filename The name of the file to be opened.
PATCHFILE
This command causes the SOMPATCH utility to generate a patch file from
the patches in the main input file. It generates a patch file from the
patch information in the ypatch areas in the SOM(s) in the main input
file. If there are no patches, a file containing a few lines of header
is generated.
If there are no ypatch areas, an error message is generated.
Syntax
PA[TCHFILE] filename
Parameters
filename Filename is the file to be generated.
QUIT
This command quits the program without changing the input file.
If no modifications were made to the primary input file, the program
exits and returns the user to the colon prompt.
If you have made modifications, you will see following prompt:
Do you really what to throw away your patches?
If the user returns an uppercase or lowercase "y" or "yes," there is an
immediate exit to the MPE colon prompt, with no changes made to the file
to be patched; otherwise, the sp> prompt is displayed, and the SOMPATCH
utility continues to operate.
In either case, if there is a list file open, it is closed and saved.
Syntax
qu[it]
Parameters
None
SAVE
Use this command to save the modifications made to the primary input file
without exiting the program.
The section entitled "Input Files" in the "Overview" section on page 9-1
explains how to recover from a system malfunction in the middle of a SAVE
command.
Syntax
SA[VE]
Parameters
None
SHOW
Function
This command shows information about any patches that have been applied
to the input file.
If only SHOW is typed, the most recent patch applied is displayed.
In pre-releases of MPE XL, the installation procedures may not clearly
define the proper use of the CLKUTIL utility. In this case, the system
clock may not be correctly set, and the time of patch shown may be the
Greenwich Mean Time, rather than the local time.
Syntax
SH[OW][since[=datespec] ]
[ [=yesterday] ]
[:patchid ]
[work ]
[@ ]
[srs ]
[multi ]
[backouts ]
[history ] [,long]
[files ]
[symbol+/-off ]
Parameters
since Specifies a sort backwards by date of the
modifications made to the file.
datespec Specifies the AFTER window to view patch
modifications. (The BEFORE window is always the
current day). Enter a 1 to 6 digit integer in the
form ddmmyy, where either or both mm and yy default
to current. If no datespec is given at all, the
current day is assumed. (Month starts with January
= 01.)
yesterday A quick way to show all patches since yesterday.
patchid The string (usually a number) given as the first
parameter to the LOG command. The SOMPATCH utility
searches its patches to see if that patch has been
applied.
work Shows all patches in the working buffer of an
interactive session (that is, the material to be
saved by an EXIT command).
@ Provides information on all current patches to be
displayed; that is, multiple writes to the same
symbol+offset aren't shown. The last write is the
only one shown.
srs Shows all SRs fixed by patches.
multi Shows all multi-SOM patches.
backouts Shows all backed-out patches.
history Shows all modifications made to the symbol
specified. It is useful for checking the reworks
of a patch.
long Specifies the long format display. The default is
short format, which is patch ID, user name, SR
number, and time applied. The long format gives
this information, plus the old values, new values,
and any other information connected with the patch,
such as the name of the source file, the SR number
connected with this patch, and the patch applier.
files Prints out names of all patch files applied and the
time that they were applied.
symbol+/-offset Refer to the MODIFY or DISPLAY commands for an
explanation of this parameter.
Error Messages
No query available--file not linked with ypatch.
CAUSE The SOMPATCH utility cannot show anything because
the file was not linked with a buffer area for
history tracking. PATCHJCW is set to the WARN
condition.
ACTION Link the ypatch.
Illegal date specified--syntax YYMMDD.
CAUSE The date as specified, with defaults, is not a
legal date.
ACTION Supply a date with the correct syntax.
Symbol not found.
CAUSE The symbol given in symbolspec was not in the
symbol table for the file being queried.
ACTION Use a correct symbol.
SOM
This command causes the SOMPATCH utility to look only in the specified
SOM for symbols. There are no SOM errors when parameters are entered as
specified. Remember to start indexing from zero.
If a name is given, it is a SOM not in the file. Try SOM @ to see what
SOMs are in the file.
Syntax
SOM [somindex ]
[somname ]
[@ ]
[? ]
Parameters
somindex Specifies an index (starting at 0) of the desired
SOM.
somname Indicates the name of the SOM (as shown by the
LISTXL command in linker, or by SOM @.)
@ Shows all SOMs in the current file.
? Shows which SOM is current for patching.
SYMBOL
This command finds the next level 1 procedure after the symbol+offset
specified.
Syntax
SYMBOL symbolname +- offset
Parameters
symbolname The LST symbol name.
offset The byte offset of the patch from symbolname.
This command is used in generating level 1 patches for multi-SOM
libraries.
For a very large file, such as the native mode system library, there may
be a five-second to ten-second delay for symbol lookup. In this case,
the message searching... is displayed every 15,000 symbols.
For Pascal level 2 procedures, the code being patched is represented as a
positive offset from the last level 1 procedure; however, this level 1
procedure is often in a different relocatable object file from the level
2 procedure being patched. This is because of the way that Pascal code
is generated:
------------------------
| Proc A's Level 2 code|
| |
ProcA + 0000-->------------------------
| Proc A -- Level 1 |
| |
------------------------
ProcA + 00xx-->| Proc B's Level 2 code| <-- code being patched
| |
ProcB + 0000-->------------------------
| |
| Proc B -- Level 1 |
------------------------
The patch instruction may have the following syntax, but the
second represents the preferred method:
1) Modify ProcA + 00xx
OR
2) Modify ProcB - 00yy (Where ProcA + xx + yy = ProcB)
When the multi-SOM NL is linked, the two relocatable object files are
sometimes no longer congruent. If they are not congruent, the positive
offset from the first level 1 procedure is no longer valid.
There are different ways of dealing with this problem. The easiest way
is to specify a patch as a negative offset from the level 1 procedure
that owns the level 2 procedure being patched ( 2) in the example above).
The SOMPATCH utility contains the SYMBOL command, which determines the
procedure name of the level 1 procedure that owns the level 2 procedure
containing the patched instruction, plus the negative offset of the patch
from the level 1 procedure entry point.
Error Message
No such symbol
CAUSE A symbol was given that is not in the library
symbol table.
ACTION Try the FIND command, and use the @ feature.
USE
This command causes a patch to read an input file of patch instructions,
and to implement the instructions.
If there is an error such as an undefined symbol in a MODIFY command, an
error message is generated, and the program continues to execute.
If the file specified is not present, an error message is generated, and
the JCWs are set to their respective FATAL status.
When the end of the patch file is reached, the program returns to the
MPE/iX CI.
Syntax
US[E ] filename
Parameters
filename Filename is the name of the script file to be used.
The group and account default to logon if not
specified.
VERSION
This command gives the current SOMPATCH utility version. It is used to
show the version of the SOMPATCH utility that is being run. The version
is also printed on the list file and as part of each patch written to the
ypatch area.
Syntax
VE[RSION]
Parameters
None
Example
sp> VERSION Return
Sompatch Version A.00.00
sp>