[ Procedures ]

Building State Files #

Description #

To build a new state file for a month.

Conditions #

Write access.

Operator Level #

Basic Entry.

Some reasons for needing to build the state file for a month can only be caused by actions which need higher operator levels.

Usage #

Reasons for building #

The state file for a month can be rebuilt at any time. It needs to be built if it does not exist or if it may be invalid either because of changes in a previous month or changes to the transactions in the current month which have, for one reason or another, not been applied fully to the state file.

One reason for a transaction not being applied fully to the state file might be the entry of a start-of-month transaction after daily transactions for the month have already been entered. The effect of the new start-of-month transaction might be to change the way in which subsequent daily transactions should be processed so that, in effect, the daily transactions have not now been correctly applied.

An example of this would be the addition or removal of a property on an account which results in changes to the way subsequent flight transactions are charged.

Another reason for rebuilding the state file is changes to the Max2 software which change the format of the data stored in the state file, for example, the addition of a new field in the account record.

Max2 is designed to detect all cases where the state file needs to be rebuilt except for new software versions. In some cases Max2 is conservative in that it assumes that the state file needs to be rebuilt even if this is not actually the case. For example, adding a property to an account does not necessarily affect the charging of subsequent flights but Max2 will always assume that a rebuild is required.

In order to ensure that closed months are left in a valid state a state file rebuild is performed when the month is closed (see Month End Processing).

Forcing a rebuild #

If there is any doubt about the validity of the state file or if there is a need to view any errors detected during a state file build then it is possible to force a rebuild by deleting the current state file. This requires Full Entry operator level. Choose Manager | Month | Delete State File in the main window's menu.

Note that this will force a rebuild for any following months as well as the currently selected month.

Rebuilding all of the state files #

To rebuild all of the state files (e.g., for a new software version or after restoring backed-up transaction files), first select the month before the first transaction file in the database. For Booker the first transaction file month is 1993-August so 1993-July should be selected.

If there's an existing state file then it should be deleted, as described above. Then rebuild the month files for all of the following months up to and including the present month, as described below.

Rebuild process #

Whenever a month is selected in the main window a check is made to see if the state file exists or is marked as invalid. If there is not a valid state file then the action taken depends on whether the database is open for write.

If the database is open for read then the appropriate message ("State file invalid" or "No state file") is shown in the month state field (at the bottom right hand corner of the main window) and no further action is taken.

If the database is open for write then the preceding month's state file is checked. If there is no valid state file for the preceding month then the message "There is no state file previous month. Select the previous month to build its state file." is displayed. If you want to build the state file then select the previous month as suggested.

If the month before the previous does not have a valid state file either then the message is repeated until you get back to either the very first month of the database or a valid state file is found. If you know which month is the last month with a valid state file then you can select the month following it immediately and save some tedious message boxes and month selection.

Once a month with no valid state file but with a valid state file for the preceding state is selected it is possible to do a state file build. The State File Creation window is displayed.

Rebuild options #

This has two buttons, Yes and No to choose whether or not to rebuild the state file. It is always safe to rebuild the state file so selecting Yes will do no harm other than cause a few minutes delay.

The State File Creation window also has a few other controls to determine how the state file creation process is to operate.

The Build state file for all following months? check box indicates whether all months up to the month following the present month month are to be rebuilt as well. For example, if the present month is October and the month selected is August then checking this box will cause not just August's state file to be rebuilt but also September, October and November's.

This feature is particularly useful if a large number of months need to be rebuilt, e.g., as a result of a new version of the Max2 software requiring all of the state files to be rebuilt.

This check box will be disabled if the rebuild is being performed as part of closing a month and also if the month for which the rebuild is being done is the one after the present month (as there are no further month's accessible to Max).

The Skip sorting transaction files? check box controls whether the contents of the daily transaction file for the month is sorted before the state file is rebuilt.

Sorting the daily transaction file puts the transactions in order of day in month. It also ensures that sale transactions (e.g., membership or course sales) for a day come before flight transactions. Aerotow credits on a day come before flight transactions but debits come after.

Normally the transaction file should be sorted as this ensures that daily transactions are stored in the correct order. For example, if a course sale is entered after a course flight has been made the course flight might not be accounted properly. As long as the sale and flight transactions have been entered for the correct dates sorting will correct this problem.

Irrespective of the setting of this check box, sorting will only happen for July 1998 or later (for Booker) and will only happen if the month in question is currently open.

This check box is disabled if the state file is being rebuilt as part of the process of closing the month (see Month End Processing).

There are two option buttons. Stop state file build on error and Log errors to window and continue build. These determine the action taken if an error is detected in any of the transactions processed during the build.

There should not be any errors in the transaction file as transactions are validated as they are posted. However, there are various ways in which a transaction which was valid at the time at which it was posted could have become invalid by the time the state file is rebuilt. In general, this can happen because of retrospective actions: changes in previous months, deletion or undeletion of transactions in the current month or addition of start-of-month transactions to the current month.

For example, if a transaction in September references an account but later a transaction is added in August to delete the account then when the September state file is rebuilt the transaction will have been found to be "orphaned".

It is also possible that a transaction can become invalid as a result of software changes. For example, the code could be changed to validate transactions more carefully, so a transaction which originally passed the checks now does not. In the Booker database there are quite a few transactions for the mid-1990s which are now considered to be in error.

The normal option to select would be Stop state file build on error. This ensures that only state files built without errors are allowed. However, if errors are encountered it may be desirable to build a state file anyway, either if the errors are known not to be important or to help with their solution.

Error log window #

When the Log errors to window and continue build option is selected the State File Build - Error Log window is displayed. Any errors encountered are displayed in this window.

When multiple months are rebuilt (Build state file for all following months? checked) then the error log can contain messages from more than one month. To make diagnosing the errors easier the first line of the message indicates the month of the transaction.

During the build process the only button enabled in this window is Cancel. Choosing this button causes the rebuild process to be terminated, leaving the state file invalid.

If the state file build is completed without error the error log window is removed. If any errors are detected, however, the window is left displayed.

The Print button prints the text of the error log.

The transaction which caused an error can be displayed by selecting one of the lines of text in the error message and choosing View Transaction. A short cut for this is to double click on the error message.

When multiple months have been rebuilt error messages may not be for transactions in the current month. In this case Max2 automatically switches to the month of the transaction to view it.

When all of the errors have been considered the Close button discards the window.

See Also #

Displaying Transactions
Month End Processing