[This is preliminary documentation and subject to change]

Writing the Metabase to Disk

The metabase configuration is written to disk either when the MetaBase.xml file is edited directly using a text editor and manually saved to disk or when the in-memory metabase is saved to disk.

Important    The MetaBase.xml file can be edited and saved to disk only when Editing the MetaBase.XML File While IIS Is Running is enabled or when the IIS service is stopped before the MetaBase.xml file is edited and saved.

Further, the in-memory metabase is written to disk only under the following circumstances:

• When the IIS service is stopped and there are changes pending in the in-memory metabase.
• After a predetermined number of changes have been made to the in-memory metabase within a 5-minute interval or, regardless of whether changes have been made, after a maximum interval of every 4 hours.
• Programmatically, as when using a resource such as ADSI.

How the In-Memory Metabase Is Written to Disk

The following illustration and discussion describe how the in-memory metabase configuration is written to disk. The verification checks can influence how IIS saves the in-memory metabase to disk, as illustrated by the possible scenarios shown in the illustration. The in-memory schema is written to disk in a similar way and will be discussed later in this topic.

Writing the In-Memory Metabase Configuration to Disk

Step 1:  Are there changes pending in the in-memory metabase?
When a write-to-disk event occurs, IIS first checks for pending changes in the in-memory metabase. Changes that are written to the MetaBase.xml file while edit-while-running is enabled are counted as pending changes in the in-memory metabase. If there are no pending changes within the in-memory metabase, no further action is taken and the in-memory metabase is written to disk. Otherwise, IIS proceeds to step 2.

Step 2:  IIS locks the in-memory metabase to prevent external writes.
The in-memory metabase is locked to prevent writes while the in-memory metabase is written to disk. This ensures that a valid copy of the in-memory metabase is used.

Step 3:  IIS determines the major version number.

1. IIS reads the value of the HistoryMajorVersionNumber property within the in-memory metabase and increments the value by 1.
2. IIS then checks to determine whether a file within the history folder is named with the same major version number. If a file using the same major version number exists in the history folder, IIS checks the history folder to determine whether the next highest version number is available. This process is repeated until an available major version number is found.

This method of determining the major version number prevents the possibility of overwriting a file within the history folder. Although unlikely under normal circumstances, the possibility exists that a file within the history folder could have a nonsequential version number for the following reasons:

• An administrator changes the value of the HistoryMajorVersionNumber property, which causes the value of the HistoryMajorVersionNumber property to roll over to 1 or to the lowest available major version number. For more information about this scenario, see Metabase History Scenario 3.
• An administrator copies an old history file into the history folder. For more information about this scenario, see Metabase History Scenario 4.

Step 4:  IIS creates a temporary file containing the in-memory metabase configuration.
When the major version number is determined, a temporary file named MetaBase.bak is created within the same folder as MetaBase.xml. The major version number that was determined in step 3 is written within the temporary file.

Step 5:  IIS unlocks the in-memory metabase to allow writes.
After the temporary file is created, the in-memory metabase is unlocked to allow writes through Admin Base Objects.

Step 6:  IIS copies the temporary file to the history folder and renames the history file using the major and minor version numbers.
The temporary file is copied to the history folder and renamed in the following format, where HistoryMajorVersionNumber is the major version number that was determined in step 3 and the minor version number is reset to 0:

MetaBase_HistoryMajorVersionNumber_minor version number.xml

For more information about how history files are versioned, see Naming the Metabase History Files.

Step 7:  Is MetaBase.xml write-locked?
The MetaBase.xml file can become write-locked by an application if the administrator opens the MetaBase.xml file for editing and the editing application enforces a write-lock. An application that enforces a write-lock releases the lock when the file is closed. However, in most circumstances, the MetaBase.xml file is not write-locked. How IIS works when the in-memory metabase is written to disk and the MetaBase.xml file is not write-locked is outlined in Metabase History Scenario 1.

If MetaBase.xml is write-locked by an application, IIS cannot write changes to the MetaBase.xml file. Instead, a history file is created and an error is sent to the event log as outlined in Metabase History Scenario 2.

Step 8:  Is MetaBase.xml read-only?
The administrator has full control access of the MetaBase.xml file by default. Therefore, under most circumstances, the MetaBase.xml file is not read-only. If MetaBase.xml is read-only when the in-memory metabase is written to disk, IIS behaves the same as if MetaBase.xml were write-locked, as described in step 7.

Step 9:  Is MetaBase.xml newer than the temporary file?
IIS checks to determine whether the MetaBase.xml file is newer than the temporary file. The MetaBase.xml file can be newer than the temporary file when the in-memory metabase is written to disk at about the same time that an administrator saves changes to the MetaBase.xml file when Editing the MetaBase.XML File While IIS Is Running is enabled.

If the MetaBase.xml file is newer than the temporary file, the MetaBase.xml file is not overwritten with the temporary file. Instead, an error is sent to the event log as outlined in Edit-While-Running Scenario 4.

Step 10:  The temporary file is copied over MetaBase.xml, and then the temporary file is deleted.
If all verification tests pass, the MetaBase.xml file is overwritten with the temporary file and the temporary file is deleted.

Step 11:  Delete oldest history file?
IIS checks to determine whether the number of history file pairs contained in the history folder exceeds the value of the MaxHistoryFiles property. (A history file pair is a MetaBase.xml and MBSchema.xml history file versioned with the same major and minor version numbers.) If the number of history file pairs exceed the MaxHistoryFiles value, the oldest history file pair, based on the timestamp value, is deleted.

Writing the In-Memory Schema to Disk

IIS can distinguish changes that were made to the in-memory metabase schema separately from changes made to the in-memory metabase configuration. The process of writing the in-memory metabase schema to disk is similar to writing the in-memory metabase configuration to disk, as follows:

• If there are no pending changes within the in-memory metabase schema when a write-to-disk event occurs, the in-memory metabase schema node is not written to disk. Instead, the MBSchema.xml file is copied to the history folder and renamed with the same major and minor version numbers that were used to version and name the metabase configuration history file in step 6 above.
• Otherwise, if changes were made to the in-memory metabase schema, the following happens:
  • The MBSchema.xml file is renamed to a temporary file.
  • The in-memory schema is written to MBSchema.xml.
  • The MBSchema_00000000h.bin file is recompiled with the contents from the new MBSchema.xml file.
  • The temporary schema file is copied to the history folder and renamed with the same major and minor version numbers that were used in step 6 above.

© 1997-2001 Microsoft Corporation. All rights reserved.