--------------------------------------------------------------------------------
MODULE IPATCH

--------------------------------------------------------------------------------
REPLACES DAMP module IED

--------------------------------------------------------------------------------

FUNCTION

--------------------------------------------------------------------------------

FORMAT

--------------------------------------------------------------------------------

PROMPTS

--------------------------------------------------------------------------------

PARAMETER

--------------------------------------------------------------------------------

QUALIFIERS

--------------------------------------------------------------------------------

DESCRIPTION

--------------------------------------------------------------------------------

HOW THE PREVIOUS COMMAND WORKS

<------------scanned-area---------->
RA..........NF..........NF..........NF..........NF..........NF..........NF..
                             _^%|
                      current position
<------------scanned-area---------->
RA..........NF..........NF..........NF..........NF..........NF..........NF..
                                                      _^%|
                                               current position
<----------------------scanned-area------------------------>
RA..........NF..........NF..........NF..........NF..........NF..........NF..
                                                      _^%|
                                               current position

--------------------------------------------------------------------------------

WILDCARDING

--------------------------------------------------------------------------------

COMMENTS

--------------------------------------------------------------------------------

SEARCHING

IPATCH COMMANDS

* COMMAND

--------------------------------------------------------------------------------
*

--------------------------------------------------------------------------------
FORMAT: *

--------------------------------------------------------------------------------
DESCRIPTION:

The * command moves the current position back to the start of the IFF file, before the first entry.

This command is the only command which may be followed by another command on the same line. This second command will be obeyed after moving to the start of the file - for instance *NEXT would move to the first entry in the file. Note that it is not necessary to separate the * and the succeeding command with spaces.

--------------------------------------------------------------------------------
Examples:

IPATCH> *<CR>
00000000: Start of file
IPATCH>

IPATCH> *NEXT 5<CR>
000011D6: NS "created by IFROMTEXT at 15:39:49 on 30-OCT-85"
IPATCH>

_? COMMAND

--------------------------------------------------------------------------------
_?

--------------------------------------------------------------------------------
FORMAT: _?

--------------------------------------------------------------------------------
DESCRIPTION:

The _? command prints the current entry out again, in the same format as produced by NEXT. It does not change the current entry.

--------------------------------------------------------------------------------
Examples:

0000123B: NF 170 1
IPATCH> ?<CR>
0000123B: NF 170 1
IPATCH>

_/ COMMAND

--------------------------------------------------------------------------------
_/

--------------------------------------------------------------------------------
FORMAT: _/
_/ values
_/ command value

--------------------------------------------------------------------------------
DESCRIPTION:

The _/ command introduces edit mode.

There are three forms of edit mode:

Note that it is only possible to edit an entry when the IFF file has been opened /WRITE.

--------------------------------------------------------------------------------
Prompt mode

_/

If the _/ command is given on a line by itself, then prompt mode is entered. A prompt is given for each field of the current entry, and a new value may be given as reply. A reply of <CR> is taken to mean that the original value should be used. <CTRL/Z> is treated as <CR>

Prompt mode is not supported for the CP, CC, ST, ZS, or CB entries.

--------------------------------------------------------------------------------
Line mode

_/ values

If the _/ command is immediately followed by appropriate values on the command line, then those values will be used to replace the fields of the current entry, in the relevant order. The wildcard character (*) may be used as a position holder for a field which is not to be changed.

Line mode is not supported for the CP, CC, ST, ZS, or CB entries.

--------------------------------------------------------------------------------
Command mode

_/ command value

Almost all entries may be edited in command mode. For each such entry, a series of command mnemonics are supplied to allow individual fields (or parts of fields) to be altered. For instance, the FS entry edit command /FC 5 sets the feature code to 5.

See the documentation for each IFF entry for a definition of the edit commands available.

--------------------------------------------------------------------------------
Examples:

00001236: NO 1 0000 00000000
IPATCH> / LAYER 2<CR>
00001236: NO 2 0000 00000000
IPATCH> / * * 1714<CR>
00001236: NO 1 0000 00001714
IPATCH> NEXT<CR>
0000123B: NF 170 1
IPATCH> /<CR>
FSN:
ISN: 170
0000123B: NF 170 170
IPATCH> NEXT<CR>
0000123E: FS 123 0000 0000 0000
IPATCH> / TEXT<CR>
0000123E: FS 123 0000 8000 0000
IPATCH> / POSITION 3<CR>
0000123E: FS 123 0000 8003 0000
IPATCH> NEXT<CR>
00001243: AC Height (3) = 67.9 "This text belongs to a type 3 AC.."
IPATCH> / Contour 70 "This text belongs to a type 2 AC.."<CR>
00001243: AC Contour (2) = 70 "This text belongs to a type 2 AC.."
IPATCH>

DELETE COMMAND

--------------------------------------------------------------------------------
DELETE

--------------------------------------------------------------------------------
FORMAT: DELETE

--------------------------------------------------------------------------------
DESCRIPTION:

The DELETE command deletes the current entry, replacing it by a void (VO) entry of the appropriate size. This command does not do anything if the file is not opened for write.

Note that if there is a current mark (see the MARK command), the DELETE command will have removed it.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the DELETE command:

--------------------------------------------------------------------------------
Examples:

DELETE MARK COMMAND

--------------------------------------------------------------------------------
DELETE MARK

--------------------------------------------------------------------------------
FORMAT: DELETE MARK

--------------------------------------------------------------------------------
DESCRIPTION:

The DELETE MARK command deletes all entries from (and including) the marked entry to the previous entry. The deleted entries are replaced by a void (VO) entry of the appropriate size. The current entry is not deleted.

The marked entry (at which deletion starts) is indicated with the MARK command. Note that after DELETE MARK, there is no longer any mark on the (now voided) entry.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the DELETE MARK command:

--------------------------------------------------------------------------------
Examples:

0000123B: NF 170 1
IPATCH> DELETE MARK<CR>
0000123B: NF 170 1
IPATCH> PREVIOUS<CR>
00001224: VO 22
IPATCH>

DISPLAY OFF COMMAND

--------------------------------------------------------------------------------
DISPLAY OFF

--------------------------------------------------------------------------------
FORMAT: DISPLAY OFF

--------------------------------------------------------------------------------
DESCRIPTION:

After this command, NEXT will only print out the destination entry. Thus the command NEXT 5 would not print out the intermediate entries (entries 1 to 4), but only the 5th entry, which becomes current.

This is the default state.

--------------------------------------------------------------------------------
Information messages:

The following information messages are specific to the DISPLAY OFF command:

--------------------------------------------------------------------------------
Examples:

IPATCH> DISPLAY OFF<CR>
%IPATCH-I-DISPLAYOFF, NEXT will now only display the destination entry
IPATCH> NEXT 5<CR>
0000126B: EF
IPATCH>

DISPLAY ON COMMAND

--------------------------------------------------------------------------------
DISPLAY ON

--------------------------------------------------------------------------------
FORMAT: DISPLAY ON

--------------------------------------------------------------------------------
DESCRIPTION:

After this command, NEXT will print out all entries that it passes over. Thus the command NEXT 5 would print out the intermediate entries (entries 1 to 4), as well as the 5th entry, which becomes current.

--------------------------------------------------------------------------------
Information messages:

The following information messages are specific to the DISPLAY ON command:

--------------------------------------------------------------------------------
Examples:

IPATCH> DISPLAY ON<CR>
%IPATCH-I-DISPLAYON, NEXT will now display intermediate entries
IPATCH> NEXT 5<CR>
0000126C: NF 170 2
0000126F: FS 123 0000 0000 0000
00001274: AC Height (3) = 67.9 "This text belongs to a type 3 AC.."
00001289: TH 30
0000128B: ST 4 0000
IPATCH>

EOF COMMAND

--------------------------------------------------------------------------------
EOF

--------------------------------------------------------------------------------
FORMAT: EOF

--------------------------------------------------------------------------------
DESCRIPTION:

The EOF command moves the current position to the end of the IFF file, after the last entry. Note that the first attempt to PREVIOUS from the end of file will cause IPATCH to scan up to the end, which can take a while for a large file.

--------------------------------------------------------------------------------
Examples:

0000128B: ST 4 0000
IPATCH> EOF<CR>
00006199: End of file
IPATCH>

EXIT COMMAND

--------------------------------------------------------------------------------
EXIT CTRL/Z> > see EXIT command

--------------------------------------------------------------------------------
FORMAT: EXIT

--------------------------------------------------------------------------------
DESCRIPTION:

The EXIT command causes IPATCH to exit. Note that any editing performed by IPATCH was done at the time it was requested, not at the time of EXIT.

<CTRL/Z> (pressing the Ctrl and Z keys together) may also be used to exit the program.

--------------------------------------------------------------------------------
Examples:

IPATCH> EXIT<CR>
ELAPSED: 00:05:25.84 CPU: 0:00:05.71 BUFIO: 281 DIRIO: 46 FAULTS: 263
_$

EXPLAIN COMMAND

--------------------------------------------------------------------------------
EXPLAIN

--------------------------------------------------------------------------------
FORMAT: E
EXPLAIN

--------------------------------------------------------------------------------
DESCRIPTION:

The EXPLAIN command causes IPATCH to explain the meaning of the current entry. The fields of the entry will be named, and any bit-set fields will be explained.

--------------------------------------------------------------------------------
Examples:

0000128B: ST 4 0000
IPATCH> EXPLAIN<CR>
0000128B: ST 4 0000
2-dimensional point string entry
- size of entry = 16 words
- number of points = 4
- flag bits = 0000 - ie pen UP to first point
IPATCH> FS<CR>
000012A0: FS 123 0000 0000 0000
IPATCH> EXPLAIN<CR>
000012A0: FS 123 0000 0000 0000
Feature Status entry
- size of entry = 4 words
- FC (feature code) 123
- word 2 = 0000 hex
CLOSED = 0 (feature is open)
NOTEDGE = 0 (feature is an edge, not a line)
REVERSE = 0 (feature is not reversed)
TWOPART = 0 (feature is not two-part)
PAINTOUT = 0 (feature is not paintout - keep it)
SQUARE = 0 (squaring flag clear)
INVERSE = 0 (normal polarity)
SUPPRESS = 0 (no paintout suppress)
- word 3 = 0000 hex
text/symbol bits = 0 (linear feature)
PC = 0 (process code)
- word 4 = 0000 hex - user specific data
IPATCH>

FIND COMMAND

--------------------------------------------------------------------------------
FIND

--------------------------------------------------------------------------------
FORMAT: F address
FIND address

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The FIND command changes the current position to the given hexadecimal address in the IFF file, and takes in hand any entry there.

If the program has scanned past that address (for instance by using NEXT to move past it), then IPATCH will report if it does not believe that the entry that you have positioned to is 'real' - that is, reachable by a sequence of NEXT commands from the start of file.

The FIND command is mainly intended to allow inspection of an IFF file after a corrupted area, which may stop the NEXT command from working over that area. It can also be useful for finding a problem reported by a utility program, when the error message contained an IFF file address.

You should realize, however, that using a series of NEXT entries from a random position in the file can sometimes provide a superficially sensible set of entries, even though they are only due to the accidental bit patterns caused by the real entries in that area.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the FIND command:

--------------------------------------------------------------------------------
Examples:

IPATCH> FIND 128B<CR>
0000128B: ST 4 0000
IPATCH> FIND 123<CR>
%IFF-E-IFFERR, IFF error BINC on LUN 1
%IFF-E-IFFERR, IFF error BINC on LUN 1
%IPATCH-W-NOTENTRY, entry XX at 00000123 is not simply reachable
00000123: XX 249
IPATCH>

FRT COMMAND

--------------------------------------------------------------------------------
FRT

--------------------------------------------------------------------------------
FORMAT: FRT file-spec

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The FRT command causes an FRT file to be read, possibly as a replacement for one specified on the IPATCH command line. The FRT library may produce messages concerning any errors in the FRT file.

Only the ACD (Attribute Code Definition) part of the FRT is relevant to IPATCH.

HELP COMMAND

--------------------------------------------------------------------------------
HELP

--------------------------------------------------------------------------------
FORMAT: H subject
HELP subject

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The HELP command looks the rest of the line up in the IPATCH HELP library. This library contains a brief summary of the operation of each command, and examples of the operation of each.

The information is looked up in the IPATCH section of the IMP help library, LSL$HELP:IMP.HLB.

LINE COMMAND

--------------------------------------------------------------------------------
LINE

--------------------------------------------------------------------------------
FORMAT: LINE

--------------------------------------------------------------------------------
DESCRIPTION:

The LINE command performs a search for the next FS entry with the text and symbol bits both unset in the third word. See the FS entry documentation for further details.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the LINE command:

--------------------------------------------------------------------------------
Examples:

IPATCH> LINE<CR>
000001F1: FS 1 0000 0000 0000
IPATCH>

LIST COMMAND

--------------------------------------------------------------------------------
LIST

--------------------------------------------------------------------------------
FORMAT: L [from [to]]
LIST [from [to]]

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The LIST command types the specified points from the current ST, ZS, or CB entry.

If no parameters are specified, then all of the points will be listed. If only one parameter is specified, then all the points starting with the from'th will be listed. If both parameters are specified, then the from'th to to'th points will be listed.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the LIST command:

--------------------------------------------------------------------------------
Examples:

0000125A: ST 4 0000
IPATCH> LIST 2 3<CR>
0000125A: ST 4 0000
2: 0.8506, 16.8394
3: 2.2290, 18.8454
IPATCH>

MARK COMMAND

--------------------------------------------------------------------------------
MARK

--------------------------------------------------------------------------------
FORMAT: M
MARK

--------------------------------------------------------------------------------
DESCRIPTION:

The MARK command is used to mark the current entry.

The RETURN command can then be used at any time to reposition to the marked entry, and the DELETE MARK command can be used to delete from it.

The DELETE and DELETE MARK commands both remove the mark from the marked entry.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the MARK command:

Information messages:

The following information messages are specific to the MARK command:

--------------------------------------------------------------------------------
Examples:

0000126C: NF 170 2
IPATCH> MARK<CR>
%IPATCH-I-MARKED, current entry now marked
0000126C: NF 170 2
IPATCH>

NEXT COMMAND

--------------------------------------------------------------------------------
NEXT

--------------------------------------------------------------------------------
FORMAT: N [count]
NEXT [count]
NEXT *

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The NEXT command is used to move to the next entry in the IFF file, and make it current. If an integer argument is given, then the effect is as of repeating the NEXT command that number of times. If NEXT * is used, then the effect is as of repeating the NEXT command until the end of file is reached (and made current).

If the DISPLAY ON command has been given, then the intermediate entries will be displayed. Otherwise only the final entry (the one which is made current) will be displayed.

Note that the NEXT * command is only obeyed when DISPLAY is ON - otherwise an error message is given and the command ignored. If you just want to move to the end of file, use the EOF command.

See also the discussion of IFF file scanning.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the NEXT command:

--------------------------------------------------------------------------------
Examples:

IPATCH> NEXT 5<CR>
00001243: AC Height (3) = 67.9 "This text belongs to a type 3 AC.."
00001258: TH 30
0000125A: ST 4 0000
0000126B: EF
0000126C: NF 170 2
IPATCH>

PREVIOUS COMMAND

--------------------------------------------------------------------------------
PREVIOUS

--------------------------------------------------------------------------------
FORMAT: P [count]
PREVIOUS [count]

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The PREVIOUS command is used to move to the previous entry in the IFF file, and make it current. If an argument is given, then the effect is as of repeating the PREVIOUS command that number of times, although without displaying the intermediate entries.

See also the discussion of IFF file scanning.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the PREVIOUS command:

--------------------------------------------------------------------------------
Examples:

IPATCH> NEXT 5<CR>
00001243: AC Height (3) = 67.9 "This text belongs to a type 3 AC.."
00001258: TH 30
0000125A: ST 4 0000
0000126B: EF
0000126C: NF 170 2
IPATCH> PREVIOUS<CR>
0000126B: EF
IPATCH> PREVIOUS 2<CR>
00001258: TH 30
IPATCH>

RETURN COMMAND

--------------------------------------------------------------------------------
RETURN

--------------------------------------------------------------------------------
FORMAT: RETURN

--------------------------------------------------------------------------------
DESCRIPTION:

The RETURN command makes the marked entry the current entry again.

The MARK command is used to mark an entry.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the RETURN command:

--------------------------------------------------------------------------------
Examples:

00001307: AC Height (3) = 67.9 "This text belongs to a type 3 AC.."
IPATCH> RETURN<CR>
0000126C: NF 170 2
IPATCH>

REVISION_LEVEL COMMAND

--------------------------------------------------------------------------------
REVISION_LEVEL

--------------------------------------------------------------------------------
FORMAT: REVISION_LEVEL level

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The REVISION_LEVEL command is used to alter the IFF input revision level used for reading the file. The original level used defaults to -1, but may be set using the /REVISION_LEVEL command qualifier. The default of -1 causes all entries to be displayed exactly as they are in the file, but 0 may be used to force CB entries to be displayed as ST or ZS entries, while 1 may be used to force ST or ZS entries to be displayed as CB entries.

After a REVISION_LEVEL command, the current entry is displayed.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the REVISION_LEVEL command:

--------------------------------------------------------------------------------
Examples:

IPATCH> NEXT<CR>
0000029E: ZS 5 0001
IPATCH> REVISION_LEVEL 1<CR>
0000029E: CB 5 01 1 7 5
IPATCH>

STATUS COMMAND

--------------------------------------------------------------------------------
STATUS

--------------------------------------------------------------------------------
FORMAT: STATUS

--------------------------------------------------------------------------------
DESCRIPTION:

The STATUS command prints a summary of the current file status. This is the same information as would be output in the status area if the STATUS ON command had been given.

--------------------------------------------------------------------------------
Examples:

IPATCH> STATUS<CR>
Reading file DUA0:[LSL.IFF]WINNIE_THE_POOH.IFF;2
current 0000126C NF 170, 2 at 0000126C mark at 0000126C
eof 00006199 revision levels: input -1 output 1
5 features scanned (below 00001330)
NEXT will not display intermediate entries
IPATCH> DISPLAY ON<CR>
%IPATCH-I-DISPLAYON, NEXT will now display intermediate entries
IPATCH> FS 123<CR>
00001368: FS 123 0000 0000 0000
IPATCH> STATUS<CR>
Reading file DUA0:[LSL.IFF]WINNIE_THE_POOH.IFF;2
current 00001368 no previous known NF mark at 0000126C
eof 00006199 revision levels: input -1 output 1
5 features scanned (below 00001330) - PREVIOUS will have to scan
NEXT will display intermediate entries
IPATCH>

STATUS OFF COMMAND

--------------------------------------------------------------------------------
STATUS OFF

--------------------------------------------------------------------------------
FORMAT: STATUS OFF

--------------------------------------------------------------------------------
DESCRIPTION:

The STATUS OFF command switches off the status area at the top of the screen, and clears the screen. The default is to have a status area.

STATUS ON COMMAND

--------------------------------------------------------------------------------
STATUS ON

--------------------------------------------------------------------------------
FORMAT: STATUS ON

--------------------------------------------------------------------------------
DESCRIPTION:

The STATUS ON command causes IPATCH to write and maintain a status area at the top of the screen.

The status area is only supported on ANSI terminals (ie VT100 and VT200 series).

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the STATUS ON command:

SYMBOL COMMAND

--------------------------------------------------------------------------------
SYMBOL

--------------------------------------------------------------------------------
FORMAT: SYMBOL

--------------------------------------------------------------------------------
DESCRIPTION:

The SYMBOL command performs a search for the next FS entry with the symbol bit set and the text bit unset in the third word. See the FS entry documentation for further details.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the SYMBOL command:

--------------------------------------------------------------------------------
Examples:

IPATCH> SYMBOL<CR>
00000221: FS 54 0000 4000 0000
IPATCH>

TEXT COMMAND

--------------------------------------------------------------------------------
TEXT

--------------------------------------------------------------------------------
FORMAT: TEXT

--------------------------------------------------------------------------------
DESCRIPTION:

The TEXT command performs a search for the next FS entry with the text bit set and the symbol bit unset in the third word. See the FS entry documentation for further details.

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the TEXT command:

--------------------------------------------------------------------------------
Examples:

IPATCH> TEXT<CR>
00000209: FS 28 0000 8083 0000
IPATCH>

TO DECIMAL COMMAND

--------------------------------------------------------------------------------
TO DECIMAL

--------------------------------------------------------------------------------
FORMAT: TO DECIMAL hex-number

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The TO DECIMAL command translates the given integer value from hexadecimal to decimal, and prints it out.

--------------------------------------------------------------------------------
Examples:

IPATCH> TO DECIMAL 123B<CR>
123B hexadecimal is 4667 decimal
IPATCH>

TO DEGREES COMMAND

--------------------------------------------------------------------------------
TO DEGREES

--------------------------------------------------------------------------------
FORMAT: TO DEGREES radians

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The TO DEGREES command translates the given angle from radians to degrees, and prints it out.

--------------------------------------------------------------------------------
Examples:

IPATCH> TO DEGREES 3.1415<CR>
3.141 radians is 179.995 degrees
IPATCH>

TO HEXADECIMAL COMMAND

--------------------------------------------------------------------------------
TO HEXADECIMAL

--------------------------------------------------------------------------------
FORMAT: TO HEXADECIMAL integer

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The TO HEXADECIMAL command translates the given integer value from decimal to hexadecimal, and prints it out.

--------------------------------------------------------------------------------
Examples:

IPATCH> TO HEX 1234<CR>
1234 decimal is 4D2 hexadecimal
IPATCH>

TO RADIANS COMMAND

--------------------------------------------------------------------------------
TO RADIANS

--------------------------------------------------------------------------------
FORMAT: TO RADIANS degrees

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The TO RADIANS command translates the given angle from degrees to radians, and prints it out.

--------------------------------------------------------------------------------
Examples:

IPATCH> TO RADIANS 89.0<CR>
89.000 degrees is 1.553 radians
IPATCH>

TYPE COMMAND

--------------------------------------------------------------------------------
TYPE

--------------------------------------------------------------------------------
FORMAT: T [count]
TYPE [count]
TYPE *

--------------------------------------------------------------------------------
Command parameters:

--------------------------------------------------------------------------------
DESCRIPTION:

The TYPE command types out the contents of an entry.

If no argument is given, then the effect is as of TYPE 0, and the current entry is typed out. If an integer argument greater than zero is given, then each of the next count entries (but not the current entry) is typed out, and the last one is left current. If TYPE * is used, then the effect is as of specifying an argument great enough to TYPE to the end of file, which is left current.

The typed information is as follows:

--------------------------------------------------------------------------------
Warning messages:

The following warning messages are specific to the TYPE command:

IFF ENTRIES

Descriptions, searching and editing

AC ENTRY

--------------------------------------------------------------------------------
AC - Ancillary code entry

address: AC name (type) = value ["text"]

--------------------------------------------------------------------------------
DESCRIPTION

AC entries are used to hold miscellaneous information. They are composed of a word (integer*2) type, a longword (integer*4, real, date, time, or character) value and an optional text.

The type of information held in an AC is determined by the AC type. Names and data types are associated with the numerical AC type by means of an FRT file (though some default types are always present). For a list of currently default AC types, and the method for adding user defined types via and FRT file, see the IFF and FRT User guides.

AC types may take values in the range 0-32767. Negative ACs are not allowed in normal use of IFF files, although IPATCH does not enforce this. The name of an AC (if defined in the FRT file) may be used in place of the numerical AC type. If the type is not present in the FRT file, then the name is displayed as ?, and the datatype is assumed to be integer.

AC values are printed in the format defined by the FRT file. A value may be 'absent'. The absent value is printed as ? (or "" for a text value). Values should be entered in the same format as that in which they are printed (including the absent value).

AC texts may be up to 255 characters in length. However, note that IPATCH itself can never change the length of a text.

--------------------------------------------------------------------------------
SEARCHING

AC [values required]

If the search is to be qualified by the contents of the AC, then the relevant values may be specified. Any values not required may be wildcarded if necessary. The AC type may be specified either as an integer, or by using the associated name.

If the AC type is wildcarded, and the AC value is specified, then IPATCH has to decide the data type of the desired AC. Only real or integer values are allowed, and if a real is intended, then it must be unambiguous - it should contain a decimal point or be in E notation. For instance, AC * 100 will search for an integer value, but AC * 100.0 will search for a real. If a date, time, or character value is required, then the AC type may not be wildcarded.

If a specific text is being searched for, IPATCH will stop at the first AC entry which contains the requested text as a sub-string. Note that the case of the letters must match exactly. For instance, AC * * "UP _& down" would match the AC

AC ? (1234) = 27 "This text goes UP _& down"

--------------------------------------------------------------------------------
EDITING

The AC type, value and text (if present) may all be changed independently or together. If the AC type is changed such that the data-type of the value (integer, real, date, time, character) should also change, but a new value is not requested, then in the case of conversion between integer and real, IPATCH will convert the value. In other cases, IPATCH leaves the value unchanged (i.e. keeps the same bit pattern), but checks whether the value is in the valid range for the new AC type. If not the value is changed to 'absent'. For instance:

00001243: AC Height (3) = 67.9 "This text belongs to a type 3 AC.."
IPATCH> / TYPE 2<CR>
%IPATCH-I-ACNOWINT, value has been converted from real to integer
00001243: AC Contour (2) = 68 "This text belongs to a type 3 AC.."
IPATCH> / TYPE 3<CR>
%IPATCH-I-ACNOWREAL, value has been converted from integer to real

00001243: AC Height (3) = 68.0 "This text belongs to a type 3 AC.."

Since IPATCH cannot add new data to the file, it is not possible to add text data to an AC that does not already contain it.

If a new text is specified, then if it is too long IPATCH will truncate it before using it, and if it is too short IPATCH will pad it to the right with spaces. For instance:

00001243: AC Height (3) = 68.0 "This text belongs to a type 3 AC.."
IPATCH> / TEXT "This text has been changed to a longer string"<CR>
%LSLLIB-E-STRTOOLONG, string is too long - truncated

00001243: AC Height (3) = 68.0 "This text has been changed to a lo"
IPATCH> / TEXT "This text is too short"<CR>

00001243: AC Height (3) = 68.0 "This text is too short "

--------------------------------------------------------------------------------
Prompt mode

The following prompts will be made:

where <data-type> is either "integer", "real", "date", "time", or "character", depending on the AC type.

If a text is specified, it should not be enclosed in quotation marks. Note that this means that it is not possible to define a text of all spaces in prompt mode, as the 'trailing' spaces on a response are ignored. Use line mode or command mode for this purpose.

A reply of <CR> will leave the relevant value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new values to be inserted into the AC. Wildcards may be used as placeholders - for instance

IPATCH> / 2<CR>

will change the AC type, and

IPATCH> / * 80.0 "This is a new text"<CR>

changes the value and text field.

--------------------------------------------------------------------------------
Command mode

CB ENTRY

--------------------------------------------------------------------------------
CB - Coordinate block entry

address: CB nrow flags gtype ncol natt

--------------------------------------------------------------------------------
DESCRIPTION

The CB entry contains the point data defining the feature. There may be more than one CB entry in a feature. The CB entry supercedes the ST and ZS entries. In addition to X and Y coordinates, it may contain other attributes (ncol in total) on a per-point basis, and also attributes (natt of them) considered fixed for the entire CB. Attributes may contain a value indicating 'absent' (equivalent to not present at all) and this is represented by a question mark '?', or for a character value "".

Note that the pen is always considered to be up for the first CB in a feature - that is the pen is always kept up to move to the start of a new feature.

--------------------------------------------------------------------------------
SEARCHING

CB [values required]

If the search is to be qualified by the contents of the CB, then the relevant values may be specified (in the order in which they are printed above). Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

Prompt mode is not supported for the CB entry.

--------------------------------------------------------------------------------
Line mode

Line mode is not supported for the CB entry.

--------------------------------------------------------------------------------
Command mode

CC ENTRY

--------------------------------------------------------------------------------
CC - Cubic coefficients entry

address: CC

--------------------------------------------------------------------------------
DESCRIPTION

The CC entry occurs once per section, and is a matrix of size (10_,2) real numbers (indexed as for Fortran). It defines a transformation between two coordinate systems to be used by a post-processing program to transform all points in the file into the same coordinate space. This is necessary when (for instance) data has been digitised on a Lasertrak.

The matrix may be represented as


			a	k
			b	l
			c	m
			d	n
			e	o
			f	p
			g	q
			h	r
			i	s
			j	t

which represents the transformation

X' = a + bX + cY + dXX + eXY + fYY + gXXX + hXXY + iXYY + jYYY Y' = k + lX + mY + nXX + oXY + pYY + qXXX + rXXY + sXYY + tYYY

The unit matrix specifies a unit transformation - ie no transformation is necessary. The unit matrix has all terms 0.0, except for those at (2_,1) and (3_,2) which are 1.0. In the convention adopted by IPATCH these are the b and m terms.

--------------------------------------------------------------------------------
SEARCHING

CC

It is not possible to modify the search by the CC contents.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

Prompt mode is not supported for the CC entry.

--------------------------------------------------------------------------------
Line mode

Line mode is not supported for the CC entry.

--------------------------------------------------------------------------------
Command mode

CH ENTRY

--------------------------------------------------------------------------------
CH - Literal character entry

address: CH "text"

--------------------------------------------------------------------------------
DESCRIPTION

This entry is obsolete, and should not be used in new IFF files.

Its only current use is for storing the data in Laseraid patch files.

Note that CH entries must be outside features, and may also be outside layers (Laseraid patch files do not contain layers or features).

--------------------------------------------------------------------------------
SEARCHING

CH ["text"]

If a specific text is being searched for, IPATCH will stop at the first CH entry which contains the requested text as a sub-string. Note that the case of the letters must match exactly. For instance, CH "UP _& down" would match the CH

CH "This text goes UP _& down"

--------------------------------------------------------------------------------
EDITING

If a new text is specified, then if it is too long IPATCH will truncate it before using it, and if it is too short IPATCH will pad it to the right with spaces. For instance:

00001243: CH "This text belongs to a CH entry"
IPATCH> / TEXT "This text has been changed to a longer string"<CR>
%LSLLIB-E-STRTOOLONG, string is too long - truncated
00001243: CH "This text has been changed to a"
IPATCH> / TEXT "This text is too short"<CR>
00001243: CH "This text is too short "

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

If a text is specified, it should not be enclosed in quotation marks. Note that this means that it is not possible to define a text of all spaces in prompt mode, as the 'trailing' spaces on a response are ignored. Use line mode or command mode for this purpose.

A reply of <CR> will leave the text unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new text to be inserted into the CH - for instance

IPATCH> / "This is a new text"<CR>

--------------------------------------------------------------------------------
Command mode

CP ENTRY

--------------------------------------------------------------------------------
CP - Control points entry

address: CP

--------------------------------------------------------------------------------
DESCRIPTION

The CP entry occurs once for each section. It defines the control points for the section, in both original (input) and destination (output) space.

--------------------------------------------------------------------------------
SEARCHING

CP

It is not possible to modify the search by the CP contents.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

Prompt mode is not supported for the CP entry.

--------------------------------------------------------------------------------
Line mode

Line mode is not supported for the CP entry.

--------------------------------------------------------------------------------
Command mode

CS ENTRY

--------------------------------------------------------------------------------
CS - Character size entry

address: CS height spacing

--------------------------------------------------------------------------------
DESCRIPTION

This entry is obsolete, and should not be used in new IFF files.

--------------------------------------------------------------------------------
SEARCHING

CS [values required]

If the search is to be qualified by the contents of the CS, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompts will be made:

Note that a reply of <CR> will leave the relevant value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new values to be inserted into the CS. Wildcards may be used as placeholders - thus

IPATCH> / 2 4<CR>

will change both the height and the spacing, but

IPATCH> / * 8<CR>

changes only the spacing.

--------------------------------------------------------------------------------
Command mode

Command mode is not supported for the CS entry.

EF ENTRY

--------------------------------------------------------------------------------
EF - End of feature entry

address: EF

--------------------------------------------------------------------------------
DESCRIPTION

The EF entry flags the end of a feature, and balances the NF entry at the start of the feature.

--------------------------------------------------------------------------------
SEARCHING

EF

The EF entry does not have any contents, so has no search modifiers.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit the EF entry.

EJ ENTRY

--------------------------------------------------------------------------------
EJ - End of job (data) entry

address: EJ

--------------------------------------------------------------------------------
DESCRIPTION

The EJ entry should always be the last entry in the IFF file. It signifies the end of data, and is used to provide a tidy end to the file, rather than requiring programs to detect the end-of-file explicitly.

--------------------------------------------------------------------------------
SEARCHING

EJ

The EJ entry does not have any contents, so has no search modifiers.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit the EJ entry.

EM ENTRY

--------------------------------------------------------------------------------
EM - End of map entry

address: EM

--------------------------------------------------------------------------------
DESCRIPTION

The EM entry is the last entry of a map or sheet, and flags its end. It should be the last entry before the EJ entry.

Historically, IFF files were permitted to contain several maps, and the EM entry was then required to mark the end of each.

--------------------------------------------------------------------------------
SEARCHING

EM

The EM entry does not have any contents, so has no search modifiers.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit the EM entry.

EO ENTRY

--------------------------------------------------------------------------------
EO - End of layer (overlay) entry

address: EO

--------------------------------------------------------------------------------
DESCRIPTION

The EO entry flags the end of a layer, and balances the matching NO entry at the start of the layer. That NO entry should contain a pointer field which holds the address of this EO - this allows fast chaining through a file when particular layers are being ignored.

Note that some entries are legal between an EO and an NO - particularly the new section entries (NS,CC,CP) and also the (obsolete) CH entry.

--------------------------------------------------------------------------------
SEARCHING

EO

The EO entry does not have any contents, so has no search modifiers.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit the EO entry.

FS ENTRY

--------------------------------------------------------------------------------
FS - Feature status entry

address: FS fc status pc/text user-word

--------------------------------------------------------------------------------
DESCRIPTION

The FS entry contains data which describes the feature containing it. It should be the first entry after the NF entry.

The FS entry includes the feature code in word 1, which is the primary descriptive code for a feature. The second word contains flag data used by Laseraid and its post-processing programs. The third word states whether this feature is text, symbol or line, and also holds either a process code or a description of the type of text. The fourth word is reserved for use by users, although beware that not all processing programs will preserve this word from input to output.

--------------------------------------------------------------------------------
SEARCHING

FS [values required]

If the search is to be qualified by the contents of the FS, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

See also the TEXT, SYMBOL and LINE commands, which can be used to search for an FS entry with the relevant bit set in word 3.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompts will be made:

A reply of <CR> will leave the relevant value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new values to be inserted into the FS. Wildcards may be used as placeholders - for instance

IPATCH> / 2<CR>

will change the feature code, and

IPATCH> / * * 8012 1234<CR>

changes the text/symbol/PC word and the user specific word.

--------------------------------------------------------------------------------
Command mode

HI ENTRY

--------------------------------------------------------------------------------
HI - History entry

address: HI

--------------------------------------------------------------------------------
DESCRIPTION

The HI record contains a history of which programs have been run on the current data, when they were run, and whether they succeeded. It thus provides a history of how the current file was produced, which can be very useful in trying to track down problems.

The HI entry occurs once at the beginning of the file, after the RA entry.

--------------------------------------------------------------------------------
SEARCHING

HI

It is not possible to modify the search by the HI contents.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit the HI entry. The entry is intended as a record of a file's lifetime, so editing it to change the record of that lifetime is not allowed.

JB ENTRY

--------------------------------------------------------------------------------
JB - Junction block entry

address: JB

--------------------------------------------------------------------------------
DESCRIPTION

The JB entry defines a series of junctions.

Within each sector of the IFF file, a chain of JB entries is maintained to hold the details of all junctions within that sector.

Each JB entry contains the number of the sector that it is in, a pointer to the next JB entry in this JB chain, and details of each junction.

For each junction, the JB contains

See also the JP (Junction Pointer) and SH (Sector Header) entries.

--------------------------------------------------------------------------------
SEARCHING

JB

It is not currently possible to modify the search by the JB contents.

--------------------------------------------------------------------------------
EDITING

Editing of junction entries is not currently supported.

JP ENTRY

--------------------------------------------------------------------------------
JP - Junction pointer entry

address: JP

--------------------------------------------------------------------------------
DESCRIPTION

The JP entry is a pointer back to a JB entry. A JP entry is inserted before or after (as appropriate) each ST that starts or ends at a junction.

The point in the ST corresponding to the junction is either the first (in which case the JP occurs before the ST) or the last (the JP occurs after the ST).

Each JP entry contains the address of the relevant JB entry, and the sequence number of the junction within that JB.

--------------------------------------------------------------------------------
SEARCHING

JP

It is not currently possible to modify the search by the JP contents.

--------------------------------------------------------------------------------
EDITING

Editing of junction entries is not currently supported.

MD ENTRY

--------------------------------------------------------------------------------
MD - Map descriptor entry

address: MD version size

--------------------------------------------------------------------------------
DESCRIPTION

The MD entry contains data describing the origin, projection and coordinate system of the IFF file. It occurs once at the beginning of the file, after the MH entry.

An unset map descriptor has its first word set to -1 (or FFFF in hex).

--------------------------------------------------------------------------------
SEARCHING

MD

It is not possible to modify the search by the MD contents.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit the MD entry using IPATCH. The map descriptor describes the current origin, projection and units of the IFF file, and a change to the map descriptor must thus be accompanied by the appropriate changes to all point data in the file. The IMP utility ITRANS is provided to perform such transformations, and it will modify the map descriptor correctly.

MH ENTRY

--------------------------------------------------------------------------------
MH - Map header entry

address: MH customer size

--------------------------------------------------------------------------------
DESCRIPTION

The MH entry contains customer specific data about the IFF file. The customer number determines which format of data is present.

--------------------------------------------------------------------------------
SEARCHING

MH

It is not possible to modify the search by the MH contents.

--------------------------------------------------------------------------------
EDITING

IPATCH supports editing of the map header's customer number. For editing the actual value within the map header itself, use the relevant customer specific map header editing program - that is:

MCEHED is a utility supplied with the customer-specific package MCE. OSMHED is a utility in the IFFOSTF module of the CONVERT package.

Type 3 and 4 OS map headers are intended for use by Ordnance Survey (Great Britain) only and will be edited using OS developed header editors.

The map header occurs once in the file, after the HI entry. Note that historically IFF files could contain more than one map, and such maps each started with a separate map header, and ended with an EM entry.

--------------------------------------------------------------------------------
Prompt mode

Prompt mode is not supported for the MH entry.

--------------------------------------------------------------------------------
Line mode

Line mode is not supported for the MH entry.

--------------------------------------------------------------------------------
Command mode

NF ENTRY

--------------------------------------------------------------------------------
NF - New feature entry

address: NF fsn isn

--------------------------------------------------------------------------------
DESCRIPTION

The NF entry starts a new feature. It contains two identifying numbers, both in the range 0-65535.

The feature serial number (FSN) is generally used as the 'name' of the feature. There are three main conventions about when or whether FSNs are unique:

Note that historically FSN 0 was considered special by many programs. It was used to flag an empty feature used as a place-holder in the IFF file, generally to hold TCs which applied to the entire layer. Thus it was possible to come across multiple FSN 0s even when FSNs are notionally unique within a file. In modern IFF files, the trailing TCs are no longer used.

The internal sequence number (ISN) is unique within the IFF file, and can be used as a single unique identifier for a feature. It may, but need not, be the same as the FSN. The ISN is generally assigned starting at 1 and incremented as a file is digitised.

--------------------------------------------------------------------------------
SEARCHING

NF [values required]

If the search is to be qualified by the contents of the NF, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompts will be made:

A reply of <CR> will leave the relevant value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new values to be inserted into the NF. A wildcard may be used as a placeholder - for instance

IPATCH> / 2 2<CR>

will change the feature serial number and the internal sequence number, but

IPATCH> / * 80<CR>

just changes the internal sequence number

--------------------------------------------------------------------------------
Command mode

NO ENTRY

--------------------------------------------------------------------------------
NO - New layer (overlay) entry

address: NO layer status EO-address

--------------------------------------------------------------------------------
DESCRIPTION

The NO entry starts a layer. It contains the number identifying this layer, and a status word. It may also contain the address of the corresponding EO entry.

IFF files are generally divided up into multiple layers, where data of a common sort or source is grouped in the same layer. Note that a layer may be split into several parts, identified by all having the same layer number.

Layer 0 is conventionally reserved for 'non-essential' data - for instance a grid, symbols at control points, or MCE DFAD accuracy polygons. The assumption is that the IFF file would not be significantly degraded in terms of information content by throwing layer 0 away. If layer 0 is present, some programs expect it to be the first layer in the file.

Historically, layers 11 and 32 were also used for the same sort of purpose as layer 0.

The status flag is not currently used, and should be set to zero.

If the EO pointer field is present, it should contain the hexadecimal address of the EO entry which matches this NO. This is used by programs which must ignore layers to 'jump' from the NO to the EO. Thus take great care when editing the EO pointer field, as an incorrect value could cause a processing program to abort.

--------------------------------------------------------------------------------
SEARCHING

NO [values required]

If the search is to be qualified by the contents of the NO, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompts will be made:

and if the NO entry contains an EO address field, then

A reply of <CR> will leave the relevant value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new values to be inserted into the NO. Wildcards may be used as placeholders - for instance

IPATCH> / 2<CR>

will change the layer, and

IPATCH> / 5 * 8013<CR>

changes the layer and the EO pointer field.

--------------------------------------------------------------------------------
Command mode

NS ENTRY

--------------------------------------------------------------------------------
NS - New section entry

address: NS "text"

--------------------------------------------------------------------------------
DESCRIPTION

The NS entry is used to flag the start of a new digitising session. The text written in it conventionally contains the initials of the digitising operator, the program being used and the date and time at which digitising was started.

The entry is necessary because IFF files are often digitised in several sessions. The NS entry will be followed by a CC and a CP entry, defining the transformations and control points applying from now on. Post-processing programs used to transform all data into the same coordinate system will normally also reduce the whole IFF file down to one section.

The NS entry will follow either an MD entry (for the first section) or an EO entry (for later sections).

The maximum number of characters in the text is 255, but note that IPATCH cannot itself change the length of the text string.

--------------------------------------------------------------------------------
SEARCHING

NS ["text"]

If a specific text is being searched for, IPATCH will stop at the first NS entry which contains the requested text as a sub-string. Note that the case of the letters must match exactly. For instance, NS "UP _& down" would match the NS

NS "This text goes UP _& down"

--------------------------------------------------------------------------------
EDITING

If a new text is specified, then if it is too long IPATCH will truncate it before using it, and if it is too short IPATCH will pad it to the right with spaces. For instance:

00001243: NS "This text belongs to an NS entry"
IPATCH> / TEXT "This text has been changed to a longer string"<CR>
%LSLLIB-E-STRTOOLONG, string is too long - truncated
00001243: NS "This text has been changed to a "
IPATCH> / TEXT "This text is too short"<CR>
00001243: NS "This text is too short "

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

If a text is specified, it should not be enclosed in quotation marks. Note that this means that it is not possible to define a text of all spaces in prompt mode, as the 'trailing' spaces on a response are ignored. Use line mode or command mode for this purpose.

A reply of <CR> will leave the text unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new text to be inserted into the NS - for instance

IPATCH> / "This is a new text"<CR>

--------------------------------------------------------------------------------
Command mode

RA ENTRY

--------------------------------------------------------------------------------
RA - Range entry

address: RA minX maxX minY maxY

--------------------------------------------------------------------------------
DESCRIPTION

The RA entry records the maximum extent of the data in the IFF file. It is used by plot and display programs to work out whether to clip the file, and what scale it can be displayed at.

The range entry is always the first entry in the IFF file.

--------------------------------------------------------------------------------
SEARCHING

RA [values required]

If the search is to be qualified by the contents of the RA, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompts will be made:

A reply of <CR> will leave the relevant value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new values to be inserted into the RA. Wildcards may be used as placeholders - thus

IPATCH> / 200.0 0.0 300.0 0.0<CR>

will change the entire RA, but

IPATCH> / * 80.0<CR>

just changes the minimum X value.

--------------------------------------------------------------------------------
Command mode

RO ENTRY

--------------------------------------------------------------------------------
RO - Rotation entry

address: RO angle

--------------------------------------------------------------------------------
DESCRIPTION

The RO entry defines the angle at which an oriented symbol or a text is to be drawn. The angle is in radians, measured counterclockwise from the positive horizontal axis.

--------------------------------------------------------------------------------
SEARCHING

RO [angle]

If the search is to be qualified by the contents of the RO, then the angle may be specified.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

A reply of <CR> will leave the angle unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new angle to be inserted into the RO - for instance

IPATCH> / 2.0<CR>

--------------------------------------------------------------------------------
Command mode

SH ENTRY

--------------------------------------------------------------------------------
SH - Sector header entry

address: SH

--------------------------------------------------------------------------------
DESCRIPTION

The SH entry contains the addresses of the start of the JB chain for each sector in the IFF file.

When an IFF file contains junction structure, the map is divided into rectangular sectors. A chain of JB entries is maintained for each sector, containing the junction information. The SH entry provides the address of the start of each of these chains.

--------------------------------------------------------------------------------
SEARCHING

SH

It is not currently possible to modify the search by the SH contents.

--------------------------------------------------------------------------------
EDITING

Editing of junction entries is not currently supported.

SL ENTRY

--------------------------------------------------------------------------------
SL - Select symbol library entry

address: SL symbol-library

--------------------------------------------------------------------------------
DESCRIPTION

This entry is obsolete, and should not be used in new IFF files.

--------------------------------------------------------------------------------
SEARCHING

SL [symbol-library]

If the search is to be qualified by the contents of the SL, then the symbol library may be specified.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

A reply of <CR> will leave the value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new value to be inserted into the SL - for instance

IPATCH> / 2<CR>

--------------------------------------------------------------------------------
Command mode

Command mode is not supported for the SL entry.

SS ENTRY

--------------------------------------------------------------------------------
SS - Symbol select entry

address: SS symbol

--------------------------------------------------------------------------------
DESCRIPTION

This entry is obsolete, and should not be used in new IFF files.

--------------------------------------------------------------------------------
SEARCHING

SS [values required]

If the search is to be qualified by the contents of the SS, then the symbol may be specified.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

A reply of <CR> will leave the value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new value to be inserted into the SS - for instance

IPATCH> / 2<CR>

--------------------------------------------------------------------------------
Command mode

Command mode is not supported for the SS entry.

ST ENTRY

--------------------------------------------------------------------------------
ST - 2-dimensional point string entry

address: ST npts pen

--------------------------------------------------------------------------------
DESCRIPTION

The ST entry contains the point data defining the feature. There may be more than one ST entry in a feature.

Note that the pen flag is always considered to be 0 for the first ST in a feature - that is the pen is always kept up to move to the start of a new feature.

--------------------------------------------------------------------------------
SEARCHING

ST [values required]

If the search is to be qualified by the number of points or pen code of the ST, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

Prompt mode is not supported for the ST entry.

--------------------------------------------------------------------------------
Line mode

Line mode is not supported for the ST entry.

--------------------------------------------------------------------------------
Command mode

TC ENTRY

--------------------------------------------------------------------------------
TC - Transmitted comment entry

address: TC "text"

--------------------------------------------------------------------------------
DESCRIPTION

A TC entry is used to label the following feature. It is used by MCE to hold specialised plotting instructions.

Interpretation of a TC requires the IFF file to be regarded as a sequential file, since the TC applies either to the following feature, or to the layer as a whole (in which case it appears after the last feature - in old format IFF files before a special empty feature with FSN 0).

The TC entry is not allowed inside a feature, but must be inside a layer.

The maximum number of characters in a TC is 255, but note that IPATCH cannot itself change the length of that text.

--------------------------------------------------------------------------------
SEARCHING

TC ["text"]

If a specific text is being searched for, IPATCH will stop at the first TC entry which contains the requested text as a sub-string. Note that the case of the letters must match exactly. For instance, TC "UP _& down" would match the TC

TC "This text goes UP _& down"

--------------------------------------------------------------------------------
EDITING

If a new text is specified, then if it is too long IPATCH will truncate it before using it, and if it is too short IPATCH will pad it to the right with spaces. For instance:

00001243: TC "This text belongs to a TC entry"
IPATCH> / TEXT "This text has been changed to a longer string"<CR>
%LSLLIB-E-STRTOOLONG, string is too long - truncated
00001243: TC "This text has been changed to a"
IPATCH> / TEXT "This text is too short"<CR>
00001243: TC "This text is too short "

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

If a text is specified, it should not be enclosed in quotation marks. Note that this means that it is not possible to define a text of all spaces in prompt mode, as the 'trailing' spaces on a response are ignored. Use line mode or command mode for this purpose.

A reply of <CR> will leave the text unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new text to be inserted into the TC - for instance

IPATCH> / "This is a new text"<CR>

--------------------------------------------------------------------------------
Command mode

TH ENTRY

--------------------------------------------------------------------------------
TH - Text height / line thickness entry

address: TH integer

--------------------------------------------------------------------------------
DESCRIPTION

The TH entry is used

--------------------------------------------------------------------------------
SEARCHING

TH [height/thickness]

If the search is to be qualified by the contents of the TH, then the relevant value may be specified.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

A reply of <CR> will leave the value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new value to be inserted into the TH - for instance

IPATCH> / 20<CR>

--------------------------------------------------------------------------------
Command mode

TS ENTRY

--------------------------------------------------------------------------------
TS - Text status entry

address: TS tcc reserved textcode reserved

--------------------------------------------------------------------------------
DESCRIPTION

The TS entry introduces a text component, and contains data which describes the text component following it.

Text features may contain one text string, with associated location and descriptive data, or they may be composite - that is composed of several sub-texts or text components, which may be manipulated independently or as a single entity.

Each text component starts with a TS entry, and ends with the next TS entry, or the final EF of the feature. The first TS entry occurs immediately after the FS entry and any AC entries. Text components may not include FS or AC entries, but may contain any other entries that are legal within a normal text feature.

Word 1 of the TS entry is the text component code (TCC), which is the primary descriptive code for a text component - it is effectively the feature code for this component of the composite text, and is used in the same manner.

Word 3 of the TS entry is the text word, and is identical in form to word 3 of a text's FS entry - it holds a description of the type of text component. Note that the top two bits (what would be the text/symbol bits in an FS) should always be set to '10' binary, as they would in an FS entry. These bits are referred to as redundancy bits, since they are not strictly necessary.

The second and fourth words are reserved for later definition, and should always be zero.

--------------------------------------------------------------------------------
SEARCHING

TS [values required]

If the search is to be qualified by the contents of the TS, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

The following prompts will be made:

A reply of <CR> will leave the relevant value unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new values to be inserted into the TS. Wildcards may be used as placeholders - for instance

IPATCH> / 2<CR>

will change the text component code, and

IPATCH> / * * 8012<CR>

changes the text word.

--------------------------------------------------------------------------------
Command mode

TX ENTRY

--------------------------------------------------------------------------------
TX - Text entry

address: TX "text"

--------------------------------------------------------------------------------
DESCRIPTION

The TX entry holds the text for a text feature. It should be the last entry before the EF entry.

The maximum number of characters in a TX is 255, but note that IPATCH cannot itself change the length of a text.

--------------------------------------------------------------------------------
SEARCHING

If a specific text is being searched for, IPATCH will stop at the first TX entry which contains the requested text as a sub-string. Note that the case of the letters must match exactly. For instance, TX "UP _& down" would match the TX

TX "This text goes UP _& down"

--------------------------------------------------------------------------------
EDITING

If a new text is specified, then if it is too long IPATCH will truncate it before using it, and if it is too short IPATCH will pad it to the right with spaces. For instance:

00001243: TX "This text belongs to a TX entry"
IPATCH> / TEXT "This text has been changed to a longer string"<CR>
%LSLLIB-E-STRTOOLONG, string is too long - truncated
00001243: TX "This text has been changed to a"
IPATCH> / TEXT "This text is too short"<CR>
00001243: TX "This text is too short "

--------------------------------------------------------------------------------
Prompt mode

The following prompt will be made:

If a text is specified, it should not be enclosed in quotation marks. Note that this means that it is not possible to define a text of all spaces in prompt mode, as the 'trailing' spaces on a response are ignored. Use line mode or command mode for this purpose.

A reply of <CR> will leave the text unaltered.

--------------------------------------------------------------------------------
Line mode

The / may also be followed immediately by the new text to be inserted into the TX - for instance

IPATCH> / "This is a new text"<CR>

--------------------------------------------------------------------------------
Command mode

VO ENTRY

--------------------------------------------------------------------------------
VO - Void entry

address: VO size

--------------------------------------------------------------------------------
DESCRIPTION

The VO entry is used to replace a series of deleted IFF entries. Since it is not possible to 'compress' an IFF file, a deleted entry or series of entries is overwritten with a void area or the requisite size.

--------------------------------------------------------------------------------
SEARCHING

VO [size]

The search may optionally be qualified by the size of the VO entry required, as it would be reported by IPATCH.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit a VO entry.

XX ENTRY

--------------------------------------------------------------------------------
XX - Invalid entry

address: XX size

--------------------------------------------------------------------------------
DESCRIPTION

IFFLIB returns the entry mnemonic XX when it has found an entry that it cannot identify as a valid IFF entry. This generally occurs because either the IFF file is corrupt in some manner, or because the FIND command has been used to position to an address which does not appear to contain an entry.

--------------------------------------------------------------------------------
SEARCHING

It is not possible to search for an XX entry.

--------------------------------------------------------------------------------
EDITING

It is not possible to edit an XX entry.

ZS ENTRY

--------------------------------------------------------------------------------
ZS - 3-dimensional point string entry

address: ZS npts pen

--------------------------------------------------------------------------------
DESCRIPTION

The ZS entry contains the three-dimensional point data defining the feature. There may be more than one ZS entry in a feature:

Note that the pen flag is always considered to be 0 for the first ZS in a feature - that is the pen is always kept up to move to the start of a new feature.

--------------------------------------------------------------------------------
SEARCHING

ZS [values required]

If the search is to be qualified by the number of points or pen code of the ZS, then the relevant values may be specified. Any values not required may be wildcarded if necessary.

--------------------------------------------------------------------------------
EDITING

--------------------------------------------------------------------------------
Prompt mode

Prompt mode is not supported for the ZS entry.

--------------------------------------------------------------------------------
Line mode

Line mode is not supported for the ZS entry.

--------------------------------------------------------------------------------
Command mode

EXAMPLE EDITING SESSION

--------------------------------------------------------------------------------

EXAMPLE EDITING SESSION

EXAMPLE EDITING SESSION

$ ipatch winnie_the_pooh/write/nostatus
00000000: Start of file
IPATCH> NEXT<CR>
00000001: RA -225.114 9241.125 -0.145 9081.765
IPATCH> /MINX 200.01<CR>
00000001: RA 200.010 9241.125 -0.145 9081.765
IPATCH> TYPE 1<CR>
0000000A: HI
History entry
- size of entry = 4001 words
Date Time Username Program Function Elapsed CPU STATUS
18-JUL-1986 17:16 TIM IFROMTEXT Create 00:01:41 00:00:47 00000001
25-JUL-1986 17:28 TONY IPATCH Patch 00:09:45 00:00:11 00000001
IPATCH> NEXT 2<CR>
0000110D: MD 2 200
IPATCH> /<CR>
%IPATCH-W-NOEDIT, MD entries cannot be edited
0000110D: MD 2 200
IPATCH> EXPLAIN<CR>
0000110D: MD 2 200
Map descriptor entry
- size is 200 words
- map descriptor version 2
- Local origin: 0.0000, 90.0000
- Map scale: 1000.0000
- Projection: 100 (Geographic (ie Lat and Long))
- Spheroid: 0 (Clarke 1866)
- Units: 5 (radians)
* use the TYPE command to type the contents of the map descriptor in *
* hexadecimal, or use the ITRANS utility to edit the map descriptor *
IPATCH> NEXT<CR>
000011D6: NS "created by IFROMTEXT at 15:39:49 on 30-OCT-85"
IPATCH> /<CR>
Text: This NS has been edited<CR>
000011D6: NS "This NS has been edited "
IPATCH> /TEXT "Fred"<CR>
000011D6: NS "Fred "
IPATCH> NEXT<CR>
000011EC: CC
IPATCH> /<CR>
%IPATCH-W-EDITCC, use the form 'letter' 'value' to change CC entries
000011EC: CC
IPATCH> EXPLAIN<CR>
000011EC: CC
Cubic coefficients entry
- size of entry = 40 words
- matrix of the form:
a = .000000E 000 k = .000000E 000
b = .100000E 001 l = .000000E 000
c = .000000E 000 m = .100000E 001
d = .000000E 000 n = .000000E 000
e = .000000E 000 o = .000000E 000
f = .000000E 000 p = .000000E 000
g = .000000E 000 q = .000000E 000
h = .000000E 000 r = .000000E 000
i = .000000E 000 s = .000000E 000
j = .000000E 000 t = .000000E 000
IPATCH> /A 10.0<CR>
000011EC: CC
IPATCH> TYPE<CR>
000011EC: CC
Cubic coefficients entry
- size of entry = 40 words
- matrix of the form:
a = .100000E 002 k = .000000E 000
b = .100000E 001 l = .000000E 000
c = .000000E 000 m = .100000E 001
d = .000000E 000 n = .000000E 000
e = .000000E 000 o = .000000E 000
f = .000000E 000 p = .000000E 000
g = .000000E 000 q = .000000E 000
h = .000000E 000 r = .000000E 000
i = .000000E 000 s = .000000E 000
j = .000000E 000 t = .000000E 000
IPATCH> NEXT<CR>
00001215: CP
IPATCH> /<CR>
%IPATCH-W-CPEDIT, to edit a CP use /TARGET, /BOTH, /ROTATE or /REPEAT
00001215: CP
IPATCH> EXPLAIN<CR>
00001215: CP
Control point entry
- size of entry = 32 words
corner original target
NW 400.000, 0.000 400.000, 0.000
SW 400.000, 400.000 400.000, 400.000
SE 0.000, 400.000 0.000, 400.000
NE 0.000, 0.000 0.000, 0.000
IPATCH> /ROTATE SE<CR>
00001215: CP
IPATCH> TYPE<CR>
00001215: CP
Control point entry
- size of entry = 32 words
corner original target
NW 0.000, 400.000 0.000, 400.000
SW 0.000, 0.000 0.000, 0.000
SE 400.000, 0.000 400.000, 0.000
NE 400.000, 400.000 400.000, 400.000
IPATCH> /TARGET<CR>
Now give a new value for each of the target control points
NW corner (was 0.0000, 400.0000) : 800, 0 <CR>
SW corner (was 0.0000, 0.0000) : 800, 800<CR>
SE corner (was 400.0000, 0.0000) : 0, 800<CR>
NE corner (was 400.0000, 400.0000) : 0, 0 <CR>
IPATCH> TYPE<CR>
00001215: CP
Control point entry
- size of entry = 32 words
corner original target
NW 0.000, 400.000 800.000, 0.000
SW 0.000, 0.000 800.000, 800.000
SE 400.000, 0.000 0.000, 800.000
NE 400.000, 400.000 0.000, 0.000
IPATCH> NEXT<CR>
00001236: NO 1 0000 00FFFFFF
IPATCH> EO<CR>
00001714: EO
IPATCH> FIND 1236<CR>
00001236: NO 1 0000 00FFFFFF
IPATCH> / * * 1714<CR>
00001236: NO 1 0000 00001714
IPATCH> NEXT<CR>
0000123B: NF 170 1
IPATCH> /<CR>
FSN: 171<CR>
ISN: 171<CR>
0000123B: NF 171 171
IPATCH> NEXT<CR>
0000123E: FS 123 0001 4000 0000
IPATCH> /TEXT<CR>
0000123E: FS 123 0001 8000 0000
IPATCH> /CATEGORY 4<CR>
0000123E: FS 123 0001 8100 0000
IPATCH> /POSITION 3<CR>
0000123E: FS 123 0001 8103 0000
IPATCH> /STATUS 0<CR>
0000123E: FS 123 0000 8103 0000
IPATCH> /WORD 4 512<CR>
0000123E: FS 123 0000 8103 0512
IPATCH> NEXT<CR>
00001243: AC Height (3) = 67.9 "This text belongs to a type 3 AC.."
IPATCH> /TYPE 2<CR>
%IPATCH-I-ACNOWINT, value has been converted from real to integer
00001243: AC Contour (2) = 68 "This text belongs to a type 3 AC.."
IPATCH> /TYPE 3<CR>
%IPATCH-I-ACNOWREAL, value has been converted from integer to real
00001243: AC Height (3) = 68.0 "This text belongs to a type 3 AC.."
IPATCH> NEXT<CR>
00001258: TH 30
IPATCH> / 25<CR>
00001258: TH 25
IPATCH> NEXT<CR>
0000125A: ST 4 0000
IPATCH> TYPE<CR>
0000125A: ST 4 0000
1: -0.5344, 14.8308
2: 0.8506, 16.8394
3: 2.2290, 18.8454
4: 3.4641, 23.9534
IPATCH> NEXT 2<CR>
0000126B: EF
IPATCH> /<CR>
%IPATCH-W-NOEDIT, EF entries cannot be edited
0000126B: EF
IPATCH> NEXT<CR>
0000126C: NF 170 2
IPATCH> RO<CR>
00001F38: RO 0.000
IPATCH> /ANGLE 0.8<CR>
00001F38: RO 0.800
IPATCH> TO DEGREES 12.0<CR>
0.800 radians is 45.837 degrees
IPATCH> NEXT 3<CR>
00001F56: TC "This TC is outside a feature.."
IPATCH> NEXT<CR>
00001F66: NF 330 44
IPATCH> PREVIOUS<CR>
Scanning file to establish where we are
00001F56: TC ""This TC is outside a feature""
IPATCH> /"Hello there"<CR>
00001F56: TC "Hello there "
IPATCH> DISPLAY ON<CR>
%IPATCH-I-DISPLAYON, NEXT will now display intermediate entries
IPATCH> NEXT 15<CR>
00001F66: NF 330 44
00001F69: FS 123 0000 8080 0000
00001F6E: TH 30
00001F70: ST 1 0000
00001F75: EF
00001F76: TC ""This is a pointless line of text .....""
00001F8B: NF 422 45
00001F8E: FS 0 0000 0000 0000
00001F93: ST 4 0000
00001FA4: EF
00001FA5: NF 190 46
00001FA8: FS 5 0000 0000 0000
00001FAD: ST 1 0000
00001FB2: EF
00001FB3: CH ""This text came from a CH entry""
IPATCH> /<CR>
Text: <CR>
00001FB3: CH ""This text came from a CH entry""
IPATCH> /TEXT "fredddy"<CR>
00001FB3: CH "fredddy "
IPATCH> EIT<CR>
%LSLLIB-E-UNEXPCMD, unexpected 'EIT' found instead of command
IPATCH> EXIT<CR>
ELAPSED: 00:05:25.84 CPU: 0:00:05.71 BUFIO: 281 DIRIO: 46 FAULTS: 263
$

IPATCH messages

--------------------------------------------------------------------------------

MESSAGES (INFORMATIONAL)

These messages provide information on the current state of the program, or follow from a more serious message to help explain it.

--------------------------------------------------------------------------------

MESSAGES (WARNING)

These messages indicate that something has gone wrong, or that the operation requested is not possible.

--------------------------------------------------------------------------------

MESSAGES (FATAL)

These messages reflect a problem with the program itself, and should be reported to Laser-Scan.

--------------------------------------------------------------------------------

MESSAGES (OTHER)

In addition to those which are generated by IPATCH itself, messages may be produced by the command line interpreter (CLI) and by Laser-Scan libraries.

In particular, messages may be generated by the IFF library and by the Laser-Scan I/O library, LSLLIB.

IFF library messages are introduced by '%IFF' and are documented in the IFF library user's guide. In most cases IFF errors will be due to a corrupt input file, and this should be the first area of investigation. If the cause of the error cannot be traced by the user, and Laser-Scan are consulted, then the input file should be preserved to facilitate diagnosis.

LSLLIB messages are introduced by '%LSLLIB' and are generally self-explanatory. They are used to explain the details of program generated errors.