--------------------------------------------------------------------------------
MODULE    IMEND

-------------------------------------------------------------------------------- REPLACES DAMP modules MIF and IFT

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

FUNCTION

IMEND is used to recover IFF files which have been improperly closed as a result of system failure or operator error.

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

FORMAT

$ IMEND file-spec Command qualifiers Defaults /[NO]RANGE /NORANGE /[NO]TRUNCATE Truncate file after last complete feature.

_IFF file: IFF-file-spec

PARAMETER

IFF-file-spec

- specifies the IFF file to be mended. Any part of the file-spec which is not supplied will be taken from the default specification 'LSL$IF:IFF.IFF'.

COMMAND QUALIFIERS

/RANGE
/NORANGE (default)

- by default IMEND does not update the RA (RAnge) entry after mending the file. The /RANGE qualifier causes IMEND to do a second pass through the IFF file after successful mending. The string (ST,ZS,CB) entries are read and the file (x,y) coordinate range is calculated. The range entry is then updated.

/TRUNCATE

- by default IMEND truncates the IFF file after the last complete map, layer, or feature (EM, EO, or EF entry) found. It then adds EF, EO, EM, and EJ entries as required to correctly terminate the file.

If /NOTRUNCATE is specified (or the file contains no complete map, layer, or feature) then the file is ended after the last complete entry and no extra entries are added.

DESCRIPTION

If an IFF file has been opened for write (or update) and the IFF library is unable to properly close the file then the file may be corrupt. Unclosed files may be caused by system crash, operator error (using for instance), or program failure. To check for this kind of error, the IFF library sets a flag in the forepart of the file when it is opened, and only clears the flag just before the file is closed. If an attempt is made to open a file which has this flag set, the IFF error 'MEND' will occur, and the IFF library will not allow access to the file. Use of IMEND is the only way to regain access to such a file, but IMEND may also be used on files which have been properly closed, but for some reason contain corrupt data, or end part way through a feature.

The particular problems which may occur when a file has been improperly closed (and which IMEND attempts to rectify) are as follows:

• The forepart will not have been written back to the file. If the file had actually been written to since it was opened, this will mean that the IFF library may be unable to access the data which had been added.
• The end-of-file pointer may not have been set correctly. An indication of this is that the number of disk blocks used is zero or much less than the number of disk blocks allocated to the file. The DCL 'DIRECTORY/SIZE=ALL' command will supply information about blocks used versus allocated. In this case, the file may not be copied before IMEND is used, as COPY will only copy up to the (incorrect) end of file block.
• Blocks of data may not have been written to the IFF file. If the file was being written at the end, then the data will probably just be lost, but if the file was being written in the middle, then there is a chance that the file will be corrupted, and that all following data will be lost.

The action taken by IMEND in attempting to repair an IFF file is as follows:

• The file is opened for updating, and its end of file pointer is set to the end of the last allocated block, allowing the filing system to access all the blocks. (This is effectively a SET FILE/END_OF_FILE operation.)
• The IFF end of file pointer (LPOSE) is also set to the end of the file, allowing IFFLIB to access all the data.
• The entries in the file are the scanned until either an IFF error occurs, an unexpected entry is found, or the EJ entry is found. The structure is not checked very rigorously. Files may contain maps (delimited by MH/EM), containing layers (delimited by NO/EO), containing features (delimited by NF/EF), containing those entries which are valid within features. The map level is optional. Any EO pointers in NO entries which are incorrect are corrected at this stage.
• If the file contained no entries at all, then the user is informed that the file is empty.
• If /NOTRUNCATE was used, or the file contained no complete maps, layers, or features, then the IFF end of file is set after the last complete entry.
• If the file did contain complete maps, layers, or features, and /TRUNCATE (the default) was used, then the file is truncated after the last complete map, layer, or feature, and appropriate EF, EO, EM, and EJ entries are added to terminate the file correctly.
• If the /RANGE qualifier is specified, IMEND does a second pass through the IFF file after successful mending. The string (ST,ZS,CB) entries are read and the file (x,y) coordinate range is calculated. The range entry is then updated.
• The file is closed.

After running IMEND the IFF data may subsequently be accessed as usual (but note that some features at the end of the file may have been lost). In particular digitising may be resumed with LASERTRAK using the Laseraid OLD option.

However, note that the recovery of a corrupt IFF file cannot be guaranteed and any file mended with IMEND should be treated with caution.

EXAMPLES

$ IMEND TST<CR>
%LSLLIB-I-IFFOPENED, IFF file DUA3:[BUREAU.TRIALS]TST.IFF;0 opened for mend
%IMEND-I-ENDLAY, end of layer 2
%IMEND-I-ENDLAY, end of layer 32
%IFF-E-IFFERR, IFF error BW   on LUN 1
%IMEND-I-CORRUPT, file corrupt in map 1
%IMEND-I-LSTFTR, last complete feature FSN 9996 (9970) layer 32 map 1
%IMEND-S-IFILREP, IFF file successfully mended
 ELAPSED:    0 00:00:02.33  CPU: 0:00:00.71  BUFIO: 7  DIRIO: 37  FAULTS: 88 
$

In this example a corrupt, improperly closed IFF file, TST.IFF, has been mended. The diagnostic output shows that the file was opened successfully and that it contained 2 sound layers. The data structure had been corrupted after the feature with FSN (Feature Serial Number) 9666, internal sequence number 9970. The first map was incomplete (no EM entry was found) when the corruption occurred, but no other layers had been commenced.

The IFF error BW is produced by the IFF library, and is one of the IFF errors possible when IMEND reaches the end of sound data and attempts to read corrupted data. It is quite normal for IMEND to produce error messages such as this. IMEND will have truncated the IFF file after feature FSN 9996 (9970) and will have terminated the file with an EO, EM, EJ sequence of IFF entries. All data in the file which was located after feature FSN 9996 (9970) will have been lost. The file should now be available for use, but there can be no guarantee that it is completely sanitary. $STATUS will be set to SS$_NORMAL.

$ IMEND<CR> _IFF file: GHASTLY.MER/RANGE<CR> %LSLLIB-I-IFFOPENED, IFF file DUA0:[LSL.IFF]GHASTLY.MER;0 opened for mend %IMEND-I-ENDLAY, end of layer 0 %IMEND-I-ENDLAY, end of layer 1 %IMEND-I-ENDMAP, end of map 1 %IMEND-I-LSTFTR, last complete feature FSN 1956 (1956), layer 1, map 1 %IMEND-S-IFILREP, IFF file successfully mended %IMEND-I-UPRANGE, updating range entry %IMEND-I-NEWRANGE, new range entry - XMIN 230.300, XMAX 450.874, YMIN 0.003, YMAX 597.839 ELAPSED: 0 00:00:30.52 CPU: 0:00:00.73 BUFIO: 7 DIRIO: 28 FAULTS: 74 $

In this example an improperly terminated IFF file, GHASTLY.MER, has been mended. The diagnostic output shows that the file was opened successfully and that it contained 2 sound layers within one completely sound map. No other maps or layers were commenced (an IFF file corrupt in _... message would have been output). In the absence of any IFF errors, the file was probably intact anyway and correctly terminated with an EJ. The end of file occurred after the feature with FSN (Feature Serial Number) 1962 and internal sequence number 1956. Any entries after the EM for map 1 will have been discarded (but there wouldn't be any expected anyway).

As the /RANGE qualifier was specified, IMEND has performed a second pass through the IFF file to calculate the (x,y) coordinate range. This is patched into the file RA (RAnge) entry. The calculated range is indicated.

The file should now be available for use, but there can be no guarantee that it is completely sanitary. $STATUS will be set to SS$_NORMAL.

$ IMEND PERDU.IFF<CR> %LSLLIB-E-IFFMODIFY, error opening IFF file DUA3:[BUREAU.TRIALS]PERDU.IFF;0 for update %IFF-E-IFFERR, IFF error USER on LUN 0 -RMS-E-FNF, file not found ELAPSED: 0 00:00:18.39 CPU: 0:00:00.34 BUFIO: 4 DIRIO: 9 FAULTS: 42 $

The file does not exist. Even if the VMS DIRECTORY utility tells you that the file contains zero used blocks, IMEND will still open the file and attempt to mend it. You have either mistyped the file-spec or you have not set logical name LSL$IF: to point to the correct directory. The error 'USER' is a consequence of the routine used by IMEND to fix the end of file pointers failing to find the file - normal programs would give error 'OPEN' under these circumstances.

$ IMEND RUINED.IFF<CR> %LSLLIB-E-IFFMODIFY, error opening IFF file DUA3:[BUREAU.TRIALS]RUINED.IFF;0 for update %IFF-E-IFFERR, IFF error READ on LUN 0 -RMS-E-EOF, end of file detected ELAPSED: 0 00:00:01.39 CPU: 0:00:00.12 BUFIO: 4 DIRIO: 9 FAULTS: 11 $

The RMS (Record Management Services) error message "end of file detected" indicates that the file is completely empty. It does not even contain an IFF "forepart" in the first disk block. There is no hope for the recovery of this file. All data contained in the file has been lost.

$ IMEND SADNESS.IFF<CR> %LSLLIB-I-IFFOPNED, IFF file DUA0:[LSL.IFF]SADNESS.IFF; opened for mend %IMEND-I-IFFEMPTY, IFF file is empty ELAPSED: 0 00:00:01.39 CPU: 0:00:00.12 BUFIO: 4 DIRIO: 9 FAULTS: 11 $

Compare this example with the one above. This file did contain a forepart, and was successfully opened, but it did not contain any entries. As in the previous example there is no hope for the recovery of this file.

$ IMEND DEMO/NOTRUNCATE<CR> %LSLLIB-I-IFFOPENED, IFF file DUA3:[BUREAU.TRIALS]DEMO.IFF;0 opened for mend %IMEND-I-ENALAY, end of layer 1 %IMEND-I-CORRUPT, file corrupt in feature with FSN 7 (7), layer 2, map 1 %IMEND-I-LSTFTR, last complete feature FSN 1 (1), Layer 2, Map 1 %IMEND-I-TERM, file has been terminated after the last complete entry %IMEND-I-IFILREP, IFF file successfully mended ELAPSED: 0 00:00:05.32 CPU: 0:00:00.54 BUFIO: 8 DIRIO: 17 FAULTS: 104 $

In this example the /NOTRUNCATE option has been used to preserve all entries in the file. After scanning layer 1, IMEND has detected an error somewhere in the feature with FSN (Feature Serial Number) 7 in layer 2. The last complete feature was feature 1, also in layer 2. Because /NOTRUNCATE has been used, the file will still contain the incomplete feature 7. After examining the file, IMEND may be used again without the /NOTRUNCATE option to remove the part feature if required. $STATUS is set to SS$_NORMAL.

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

MESSAGES (INFORMATIONAL)

These messages give information only, and require no immediate action by the user.

CORRUPT, file corrupt in feature WITH FSN 'integer' ('integer'), layer 'integer', map 'integer'

Explanation: Corruption of the IFF file structure has been detected within a map, layer, or feature. The file will be terminated at the last complete map, layer, or feature (or entry if /NOTRUNCATE was used). If this message does not occur, then it is likely that no data has been lost.

User action: None.


ENDMAP, end of map 'integer'
ENDLAY, end of layer 'integer'

Explanation: The end of the given map or layer has been reached. It is safe to assume that the data before this point is safe (but note that the same layer may occur several times if the layer has become fragmented).

User action: None.


FIXEOP, EO pointer amended in layer 'integer'

Explanation: The pointer to the end of this layer contained within the NO entry has been found to be incorrect. It has been corrected.

User action: None. But if this happens repeatedly, then the program responsible may have a bug which requires fixing.


IFILREP, IFF file successfully mended

Explanation: All is well. IMEND has recovered at least some, if not all of the IFF file.

User action: The IFF file may be used with caution.


IFFEMPTY, IFF file is empty

Explanation: There is no hope for the recovery of this file, it contains no entries at all.

User action: None.


LSTFTR, last complete feature FSN 'integer' ('integer'), layer 'integer', map 'integer'

Explanation: This is the last complete feature in the mended file. If this message is not output, then there were no complete features.

User action: None.


NEWRANGE, new range entry - XMIN 'real', XMAX 'real', YMIN 'real', YMAX 'real'

Explanation: IMEND indicates the new range values calculated from the string (ST,ZS,CB) entries present in the file after mending.

User action: Check that the calculated range is what you expected to have in the file.


NOSTS, file contains no ST entries - range entry will not be changed

Explanation: After mending, the file contains no ST entries. The RA (RAnge) entry will not be changed.

User action: None.


TERM, file has been terminated after last complete entry

Explanation: Either /NOTRUNCATE was used, or the file contained no complete maps, layers, or features. The file now ends after the last complete entry. No attempt has been made to add EF, EO, EM, or EJ entries.

User action: None.


UPRANGE, updating range entry

Explanation: You have specified the /RANGE qualifier. This causes IMEND to do a second pass through the IFF file after successful mending. The string (ST,ZS,CB) entries are read and the file (x,y) coordinate range is calculated. The range entry is then updated.

User action: None.

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

MESSAGES (ERROR)

These messages indicate an error in processing which has caused the program to terminate. The most likely causes are a corrupt or otherwise invalid input IFF file, or an error related to command line processing and file manipulation.

NORANGE, file has no range entry

Explanation: IMEND has failed to find the RA (RAnge) entry at the start of the IFF file. It is therefore unable to patch in the calculated (x,y) coordinate range.

User action: Without a range entry, the file is useless. Use ITOTEXT to convert the file into a textual representation. Use a text editor (like VMS EDIT or TPU) to add a range entry. Use IFROMTEXT to convert the text back to an IFF file. Re-run IMEND/RANGE to correctly update the range entry that you created.

MESSAGES (OTHER)

In addition to the above messages which are generated by IMEND itself, other 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. These are introduced by '%IFF' and are documented in the IFF library users' guide. It is quite normal for IMEND to produce an IFF error message when corrupt data is encountered - it will terminate the file at this point. If the cause of an error cannot be traced by the user and Laser-Scan are consulted, then the input file should be preserved to facilitate diagnosis.