System Administration #

This chapter details the operations required to set up and manage Max2 databases. It is assumed that the user is familiar with the basic concepts of Max2 operation (i.e., all of the Overview chapter) and can deal with basic system administration tasks like creating directories, copying files and so on. Familiarity with the Database Organization would be very useful, too.

Conventional Directory Names #

For brevity, this chapter assumes that the core Max2 software is (or is to be) installed in the directory C:\Max2\bin and that the main database is in directory C:\Max2\livedb. This manual is assumed to be in C:\Max2\manual. Similarly, the Windows directory for 16-bit libraries is assumed to be C:\Windows\System.

There's no need to use this directory naming scheme. In particular, the software directory and database directories do not need to be in a common super-directory. The Windows directory for 16-bit libraries will vary depending on the operating system version and language. Just substitute the file names suitable to your situation consistently.

However, it's probably a good idea to put the manual, if installed, in a sibling directory of the bin directory and to call it manual. That way, it would be possible for future versions of the VB code to link to associated manual sections.

Similarly, the CD-R or other medium containing the installation materials is assumed to be mounted as D:\.

Max2 Command Line #

Max2 is started by running the MAX2.EXE program. This can be done from the command line or from a batch file but usually it is done using a Windows shortcut.

There are two modes of operation: normal program execution with access to a Max2 database or a non-interactive run which creates the max2meta.xml file (see the associated section in the Programmer's Guide).

For normal program execution the command line options are the name of the organization for which the code is to be run and the name of the database directory. The organizations recognized are booker and bggc (Bristol and Gloucester) - not case sensitive. (BGGC don't use the software anymore but the code is left in as it might be handy in future.)

Using the conventional directories mentioned above, the command line would be:

This command should be executed in a current directory which contains the Max2Dll.Dll. Since this is normally in the same C:\Max2\bin\ directory as the main executable it is easiest to simply change to that directory and execute the command there:

Basic Software Installation #

Typically, installation of the software on a new machine is done from a snapshot copy of the development directories, stored on a CD-R or similar medium. In the root directory of the snapshot should be an index.html file (e.g., D:\index.html) containing a description of the directory structure of the snapshot. Though not quite essential, this is useful background reading.

See also EMail Software Installation.

Visual Basic libraries #

Copy the files contained in D:\system to the Windows 16-bit library directory (C:\Windows\System).

These files are the vbrun300.dll which is the main support library for Visual-Basic-generated executables and various .vbx files which are dynamically loaded libraries which provide many of the Windows controls, etc, used by Max2.

Max2 Main Software #

Create the directory to contain the Max2 software (C:\Max2\bin).

Copy in to C:\Max2\bin the main Max2 executable (D:\max2\MAX2.EXE) and the associated dynamic link library (D:\max2dll\MAX2DLL.DLL).

Manual #

If required, this manual can also be installed. Copy all of the contents of D:\manual\Output to a suitable directory (e.g., C:\Max2\manual) and set up a desktop shortcut to the table-of-contents file (index.html) in that directory.

Basic Software Upgrade #

Typically, when a new version of the Max2 software is to be installed on a machine which already has a previous version installed the upgrade is simply a matter of copying the new versions of the MAX2.EXE and/or MAX2DLL.DLL files, as appropriate, into the C:\Max2\bin directory, overwriting the old copies.

Of course, it's a good idea to keep the old copies in case of a problem. The normal procedure which has been followed is to rename them to include the date of the upgrade. This keeps a rough log of the changes and allows reversion if required.

If an updated copy of the manual is to be installed then this too can be copied into the appropriate directory (C:\Max2\manual). It's probably best to delete the existing contents of this directory before copying the new version in. This shouldn't be absolutely required but will avoid the possibility of having old, unused, files left hanging around.

If the state file format has changed (or there's any doubt as to whether it might have) then the state files should be rebuilt as described in Building State Files.

Keeping two different versions of Max2 active on a machine at the same time (probably on different database copies) is a dubious thing to do. Windows might well not use the correct versions of MAX2DLL.DLL in some circumstances.

Database Creation #

It would be extremely unusual to set up a clean database from scratch. It's only required when starting operation of Max2 for a new organization.

Create Database Directory #

Create an empty directory to contain the database (e.g., C:\Max2\livedb).

Create Shortcut #

Create a method of invoking the program. E.g., to create a Windows desktop shortcut (at least, in Windows XP) right click on the desktop and choose New -> Shortcut. In the ensuing Shortcut Wizard fill in the location of the item field with the command line as described above and set a suitable name for the database in the name for this shortcut field.

As noted in the command line section above, the initial current directory for the shortcut should be set to the program directory (e.g., C:\Max2\bin\) so that the VB code can find the Max2Dll.DLL file.

Initial Run #

Run the program. Select a month at least two (and maybe a few more) before the first month for which live data will be entered. Log on as user Manager with no password; this will need changing later.

A Max2 - State File Creation dialog box will be displayed asking Is this the month before the first month of data entry?. Reply Yes. A similar dialog box is now displayed asking Do you wish to create an empty state file for this month? Again, reply Yes.

Select the following month. Another Max2 - State File Creation dialog is displayed, this time with a few more options. This dialog is described in detail in Building State Files but in this case accepting the defaults and just answering Yes is the thing to do.

Configuration #

Create all the membership types, course types, trial lesson types, headings, cash headings, properties, special rule codes, charging rules and so as described in the Procedures chapter.

It is probably best to split this work over a number of months (hence the reference above to a few more months before the first for live data). For example, the membership types, headings and so on could all be set up in one month then the charging rules in the following month. That way, if you're not happy with the charging rules, say, and want to start again from a clean slate on them you can delete the transaction files for the offending month without losing your other work.

Obviously, the charging rules depend on the headings and properties and so on, so this has to be done in a reasonable order.

Similarly, creation of the initial set of accounts is probably best left to the month before the first live data.

With the Booker installation of the system some special import code was used to create a set of transactions to create accounts and bring balances forward from the Max1 system. Now those transactions exist and the Max1 data has long been lost that import code has faded into the mists of time as well.

For the Booker system the initial months are used as follows:

Database Backup #

Max2 does not contain any specific facilities to back up its database. Any backup strategy which can deal reasonably with a small number of files per month will suffice.

The files which need to be backed up are discussed in the Programmer's Guide under Backup

Database Restoration #

If disaster strikes and it is necessary to restore operation from a backup the following sequence would be appropriate:

Database Sharing #

Two or more executions of the Max software on the same or different machines can access the same database at the same time. The basic rule is that there can be either exactly one copy with write access or zero or more copies with read access. That is, any copy with write access excludes any access by other copies.

The motivation for this restriction is the huge increase in software complexity which would be entailed by the need to set up and apply transactions atomically if multiple writers had access.

The user interface aspects of this are discussed in the Overview chapter's Operation section under Database Access.

There was one incident of data corruption when a database was being accessed for write from a machine other than the one containing it. Though this seems to have been a one-off event which might not have had anything to do with the networking the tendency since has been to share databases for read-only access across the network and to do all the updates on the containing machine.

An important consideration is that when a database is shared between machines the versions of the software on each should be compatible (in most cases, should be the same). This is because, though great care is taken to ensure compatibility of the transactions files across software versions, the state file format can change. See Design Philosophy.

There are two ways of referencing the shared database from the sharing machine. Either the share can be mounted as a drive letter (e.g., M:) referenced as such on the shortcut command line or the share can be named directly (e.g., \\MaxMachine\LiveDB\). The corresponding command lines would be:

Database Duplication #

It can sometimes be useful to make a duplicate of a database. Typically, this can be done for testing - e.g., to try out changes to the charging rules. It could also make sense to duplicate a database to another machine then use the duplicate as the master database as a means of migration on hardware upgrade.

The operation is straightforward:

Database Mirroring #

A Max2 mirror database is a duplicate copy of a master database which is still associated with the master and can be easily updated with the changed contents of the master. It is read-only (because any changes made would be overwritten when the updates are taken from the master). Typically, a mirror database is on separate machine from the master.

The main purpose of a mirror database is to allow read-only access to a reasonably up-to-date copy of the master database while another user has the master open for write access. It can be used to answer telephone and direct inquiries without interrupting data input and for long operations which don't need write access, like printing statements, without getting in the way of access to the master database.

A secondary purpose of a mirror database is to act as a "hot standby" - a backup which is ready for immediate use as a replacement for the main database in the case of data loss. It is convenient and quick to copy from the main database to the mirror making it likely that the mirror will be up-to-date. Of course, this is only useful when the mirror database is on a separate machine.

The mirror database needs access to the master database. In the unusual case that the two databases are on the same machine this is easy - the fully qualified name of the master database directory can be used. Typically though, the mirror database is on a different machine in which case the master needs to be shared to the network and accessed as described under Database Sharing.

The information on whether a database is a mirror and, if so, which database it is a mirror of is stored in the Max2DB.ini file in the database directory.

Creation #

To create a mirror database:

Update #

To bring the mirror database up to date with the master follow the procedure described in Updating a Mirror Database.

Turning a Mirror Database into a Master Database #

It could be useful to turn a mirror database back into a normal (master) database, that is, to break the association with the master database and allow write access. For example, if a disk crash caused the loss of the master database then the mirror could be used as a ready and nearly up-to-date replacement.

To turn a mirror database into a master you must be logged on as a manager level operator. Unusually for operations which make changes to a database you don't have to have the database open for write (there'd be a bit of a Catch-22 situation otherwise as you can't open a mirror database for write).

Choose File | Make this a Master Database....

In the max2 - Convert Mirror to Master dialog box read the rubric with feigned concentration then choose OK. This will clear the information about being a mirror database in the Max2DB.ini file in the database directory leaving the database as a stand-alone master database.

EMail Software Installation #

The email components of Max2 are in the form of a separate program, written in the Java programming language, which are invoked by Max2 as described in External Account Processing and Appendix E - External EMail Program.

Java Runtime Installation #

If the target system doesn't have a Java Runtime Environment version 1.4.2_06 or later then install one. There's a Windows executable installer to do this on the Max2 installation media (e.g., D:\java\j2re-1_4_2_06-windows-i586-p.exe) or get a more up-to-date copy from the Sun Java website. Run the executable and follow the instructions.

Support Library Installation #

The Max2 Java email program requires two Java libraries (.jar files) which are used for manipulation and transmission of the generated e-mail messages. These, or more up-to-date versions, can also be obtained from the Sun site but there are copies on the Max2 installation media.

In both cases, the .jar files are distributed with other files in .zip files. The files to be installed and the sources are:

File Container
activation.jar D:\java\
mail.jar D:\java\

Note that the other files in the .zips are not needed and should not be copied to the target system.

The .jar files should be copied to the Java Runtime Environment extension library directory. Depending on the Java version and installation options chosen it will be named something like:

C:\Program Files\Java\j2re1.4.2_06\lib\ext

Max2 Java Installation #

Copy the compiled Max2 Java code (D:\max2java\Max2Java.jar) into the Max2 binary directory (C:\Max2\bin).