Page Numbers: Yes First Page: 27 X: 527  Y: 10.5"
Margins: Binding: 13
Odd Heading:x2qjk40(635)
Alto/Mesa Image Filesy756qck40\b21B
Even Heading: Not-on-first-pagex2qjk40
Alto/Mesa Image Filesy756qck40\b21B
Alto/Mesa Image Files
October 1980y684x12e12c\f5b22f0B
A Mesa image file contains the information necessary to start execution of a Mesa system.  In addition to image files that contain all code and data, there are also image files, called check files, that contain only data.  (Because check files know the addresses of other files on the disk they cannot be moved like other image files).  This section defines the facilities provided to make them.  See ImageDefs for further details. x2e24j\401f6b9f0B
Making Image Filesx2e24ck108\f5b18B
The standard system does not contain code to make an image file of itself and any user programs which have been loaded.  Clients must either load the ImageMaker or include it as part of their configuration.  Clients may make an image file by calling the procedure:x2e12j\150f6b10f0B
MakeImage: PROCEDURE [name: STRING, merge: BOOLEAN _ TRUE];z18697l3633d2999x2e12jk72\f6b11f7 9f6 8f7 8f6 5f7 16f6
Makes an image file on file name and returns to the Alto Executive.  When the image file is restarted, MakeImage returns to its caller. l4269x2e12j\28f6b4f0B71f6b9f0B22f1 2f0
MakeImage normally merges all the Bcds that have been loaded into one bcd and cleans up system data structures.  This results in faster loading of additional Bcds into the new image.  Those clients who do not want Bcds merged during a MakeImage because they call UnNewConfig should supply FALSE to the optional parameter merge.  The following procedure is provided for compatibly:x2e12j\f6b9f0B25f6 3f0 121f6 3f0 53f6 3f0 18f6b9f0B19f6b11f0B15f7b5f0B27f6b5f0B
MakeUnMergedImage: PROCEDURE [name: STRING] = INLINE
{MakeImage[name, FALSE]};z18697l3633d2999x2e12jk72\f6b19f7 9f6 8f7 6f6 4f7 8f6 16f7 5f6
Signals that may be generated by MakeImage or MakeUnMergedImage are:x2e12j\33f6b9f0B4f6b17f0B
InvalidImage: SIGNAL;z18697l3633d2999x2e12jk72\f6b14f7 6f6
An attempt has been made to make an image file on top of the currently executing image file. l4269x2e12j\91f1 2f0
NoRoomInImageMap: SIGNAL;z18697l3633d2999x2e12jk72\f6b18f7 6f6
The map in the ImageHeader has filled up.  This usually means that there are too many segments in memory at the time the image file is made. l4269x2e12j\4f6b3f0B8f6b11f0B113f1 2f0
ImmovableSegmentInXM: SIGNAL [seg: SegmentHandle];z18697x2e6k80(1799)\f6b20f7 8f6 21f7 1f6
MakeImage (or CheckPoint) has discovered a segment in the extended memory banks that cannot be swapped out.  (See the section on restrictions, below, for more information).l4269x2e12j\f6b9f0B5f6b10f0B147f1 1f6b
Check Filesx2e24ck80(635)\f5b11f0B
Check files differ from normal image files in that they do not contain all the code and data necessary to start the execution of the image file.  Check files only contain the data of the Mesa system, and all code and other segments remain in their original files.  As a result, check files are made and restarted very quickly.  However, care must be taken not to destroy files that are pointed to by the check file.  Check files are useful for making check points in the execution of a Mesa system.  The procedures and signals that make check files are:x2e12j
MakeCheckPoint: PROCEDURE [name: STRING] RETURNS [restart: BOOLEAN];z18697l3633d2999x2e12jk72\f6b16f7 9f6 8f7 6f6 2f7 8f6 10f7 7f6
Makes a check file on file name.  Returns to the caller when finished as if nothing happened with restart set FALSE.  If the check file is being restarted, it returns to the caller with TRUE.l4269x2e12j\27f6b4f0B67f6b7f0B4f7b6f0B71f7b4f0B1f1
NoRoomInCheckMap: SIGNAL;z18697l3633d2999x2e12jk72\f6b18f7 6f6
In MakeCheckPoint, the map in the ImageHeader has filled up.  This usually means that there are too many segments in memory at the time the check file is made. l4269x2e12j\3f6b14f0B6f6b3f0B8f6b11f0B113f1 2f0
The ability to make check files is not included in the basic system.  Clients should include the CheckPoint module in their configuration. x2e12j\97f6b10f0B
Running Image Filesx2e24ck40\f5b19f0B
Mesa programs may run another image file without returning to the Alto Executive.  The procedures and signals that implement this are:x2e12jk40
RunImage: PROCEDURE [file: SegmentDefs.FileSegmentHandle];z18697l3633d2999x2e12jk40\f6b10f7 10f6
Runs the image file specified by file where file is a segment handle for the header of the image file.  The current state of the present image file is lost, and the new image file is loaded and started.l4269x2e12jk40\33f6b4f0B7f6b4f0B154f1
Fine point: currently the header of an image file is page one (this may change in the future, and may not be constant).  Communication between the two image files must be done via disk files (like Com.cm).  See the Alto Operating System Reference Manual.l4269x2e6jk40\f1 215i38f0I
InvalidImage: SIGNAL;z18697l3633d2999x2e12jk40\f6b14f7 6f6
In RunImage, file specifies an invalid image file. l4269x2e12jk40\3f6b8f0B2f6b4f0B32f1 2f0
NoRoomForLoader: SIGNAL;z18697l3633d2999x2e12jk40\f6b17f7 6f6
In RunImage, there is no room for the bootstrap loader that loads and starts the image file. l4269x2e12jk40\3f6b8f0B80f1 2f0
Clients should include the configuration ImageRunner in their configuration.x2e12jk40\41f6b11f0B
Miscellaneousx2e24ck80\f5b13f0B
The version stamp of the currently running image file may be obtained by calling the procedure:x2e12jk40
ImageVersion: PROCEDURE RETURNS [BcdDefs.VersionStamp];z18697l3633d2999x2e9jk40\f6b14f7 9f6 1f7 8f6
The time that the currently running image file was created may be obtained by calling the procedure:x2e12jk72
ImageTime: PROCEDURE RETURNS [TimeDefs.PackedTime];z18697l3633d2999x2e9jk40\f6b11f7 9f6 1f7 8f6
The same information can be obtained about the caller's BCD from the procedures:x2e12k40\56f7b3f0B
BcdVersion: PROCEDURE RETURNS [BcdDefs.VersionStamp];z18697l3633d2999x2e9jk40\f6b12f7 9f6 1f7 8f6
BcdTime: PROCEDURE RETURNS [TimeDefs.PackedTime];z18697l3633d2999x2e9jk40\f6b9f7 9f6 1f7 8f6
A client may stop execution of a Mesa system and return to the Alto Executive by calling:x2e12jk40
StopMesa: PROCEDURE;z18697l3633d2999x2e9jk40\f6b10f7 9f6
A client may terminate execution of a Mesa system as if shift-swat had been typed and return to the Alto Executive by calling:x2e12jk40
AbortMesa: PROCEDURE;z18697l3633d2999x2e9jk40\f6b11f7 9f6
Cleanup Proceduresx2e24ck40\f5b18f0B
Client programs sometimes need to be notified when certain events occur so they can perform various cleanup functions.  Cleanup procedures provide a facility to notify client programs when image files are made or restarted, and when stopping the execution of Mesa programs.  The types and data structures involved with Cleanup procedures are:x2e12jk40
CleanupProcedure: TYPE = PROCEDURE [why: CleanupReason];z18697l3633d2999x2e12jk40\f6b18f7 4f6 3f7 9f6
CleanupItem: TYPE = RECORD [
link: POINTER TO CleanupItem,
mask: CARDINAL,
proc: CleanupProcedure];z18697l3633d2999x2e12jk40\f6b13f7 4f6 3f7 6f6 9f7 10f6 20f7 8f6
CleanupReason: TYPE = BcplOps.CleanupReason;z18697l3633d2999x2e12jk40\f6b15f7 4f6
BcplOps.CleanupReason: TYPE = {
Finish, . . . Save, Restore, CheckPoint, Restart, Continue, . . .};l3633d2999x2e12jk40\f6b23f7 4f6
CleanupReasons are copied from BcplOps.  Valid ones are:x2e12jk80\f6b13f0B18f6b7f0B
Finish:	StopMesa was called.z18697l4269x2e12j\f6b17f0B
Save:		MakeImage was called.z18697l4269x2j\f6b17f0B
Restore:	returning from MakeImage.z18697l4269x2j\f6b9f0B15f6b9f0B
Checkpoint:	Checkpoint was called.z18697l4269x2j\f6b23f0B
Restart:	returning from Checkpoint restarted by the Alto Executive.z18697l4269x2j\f6b9f0B15f6b10f0B
Continue:	returning from Checkpoint.z18697l4269x2j\f6b10f0B15f6b10f0B
The following procedures is used to add or remove cleanup procedures.  The list of CleanupItems is processed in the opposite order when returning from an image file than when making one.x2e12jk40\82f6b12f0B
AddCleanupProcedure: PROCEDURE [POINTER TO CleanupItem];z18697l3633d2999x2e12jk72\f6b21f7 9f6 2f7 10f6
RemoveCleanupProcedure: PROCEDURE [POINTER TO CleanupItem];z18697l3633d2999x2e12jk72\f6b24f7 9f6 2f7 10f6
Warning: these procedures may not be invoked from inside Cleanup procedures.x2e12jk40
CleanupMask: ARRAY CleanupReason OF CARDINAL =
[1, 2, 4, 10B, 20B, 40B, 100B, 200B, 400B, 1000B];z18697l3633d2999x2e12jk40\f6b13f7 5f6 15f7 11f6
When the Cleanup procedure mechanism is invoked, each item is examined.  If the bit corresponding to the reason is set in item.mask, item.proc is called.  Clients must set the mask field so that their procedure is invoked only for the reasons they expect.  For example, if a client needs to be notified when a normal image file is being made or started, the mask is set to:x2e12jk40\122f6b9f0B2f6b9f0B
CleanupMask[Save] + CleanupMask[Restore].l4269x2e6jk40\f6b40f0B
Warning: if the item.mask is improperly set, item.proc may be invoked at sensitive times, probably resulting in erroneous behavior.x2e6jk40\16f6b9f0B20f6b9f0B
Restrictionsx2e24ck80\f5b
MakeImagex2e12j\i9I
1.The name of the new image file may not be the same as the name of the image file running at the time MakeImage is called.   An image file can be renamed any time it is not running.  x2e12j\2g2G101f6b9f0B
2.The user program should not have handles on any files or disk streams.  Any file segments allocated by a user program will be made a part of the new image file.x2e12j\2g2G
3.This list of restrictions may not be exhaustive.  In general you should avoid doing anything other than loading modules and initializing data structures before making an image file.x2e12j\2g2G
4.MakeImage cannot preserve the contents of extended memory in the image file it constructs.  If MakeImage is invoked when useXM is TRUE, it will swap out all unlocked file segments in extended memory.  (It will also move any locked code segments to the MDS.)  If any segments then remain in extended memory, MakeImage will refuse to build the image file.  Analogous comments apply to CheckPoint.x2e12jk40(1799)\2g2f6bG9f0B86f6b9f0B17f6b5f0B4f7 4f0 173f6b9f0B67f6b10f0B
MakeCheckPointx2e12j(635)\i
1.The name of the new image file may be the same as the name of the image file running at the time MakeCheckPoint is called, only if the current image file is a check file.   A check file should not be renamed.  x2e12j\2g2G97f6b14f0B
2.The files that are pointed to by the check files should not be moved or altered.  Care must be taken with open disk streams that the pages of the current position of the stream are not moved or destroyed.x2e12j\2g2G
3.This list of restrictions may not be exhaustive and care must be taken with all files that are open at the time the check file was make.x2e12j\2g2G
CleanupProceduresx2e12j\i
1.CleanupProcedures are called with interrupts and timeouts turned off.  x2e12j\2g2f6bG16f0B
2.This list of restrictions may not be exhaustive and care must be taken when using CleanupProcedures.x2e12j\2g2G82f6b16f0B