MPE/iX System Utilities Reference Manual > Chapter 22 SOMPATCH

SOMPATCH Operation

	MPE documents
	Complete PDF
	Table of Contents
	Index

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"
  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
         {invoke program, giving primary file}
  sp>log {a log command is required before the first modify}
  username>junie moon from august skies {program is prompting}
  patchid>163
  srnumber>4700241760
  comment>fixes system crash on listf ,5
  comment>    {a Return signifies end of comment}
  sp>modify iobuf+20, 2
  12345678|22222222 33333333|FFFFFFFF {application of the patch}
  sp>exit {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          ]
             [ @                 ]
             [ 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
  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
  sp> log  jim gann(by Kate T.), 19, 4700-192066

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

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:

The current patch is written.
A new patch is generated, with the same information as the last one (user, patchid, srnumber), but with comments truncated.
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
                              {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 in this chapter 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
  Sompatch Version A.00.00
  sp>

Chapter 22 SOMPATCH

Chapter 23 SORT-MERGE/XL

SOMPATCH Operation

MPE documents

Interactive patching

; (semicolon)

BACKOUT

Error Messages

DISPLAY

Error Messages

EXIT

FIND

HELP

LIST

LOG

Error Messages

MODIFY

Error Messages

OFFSET

OPEN

PATCHFILE

QUIT

SAVE

SHOW

Error Messages

SOM

SYMBOL

Error Message

USE

VERSION