In a perfect world you might be able to design a perfect database the first time, never having to add, remove or change any fields, forms or procedures. In the real world you’ll often have to make these sort of changes. The Panorama Server does not allow you to make design changes directly on the server. Instead, changes are made on one of the local client computers, then uploaded to the server. From the server, the changes are then propagated to the other client computers. Each time you do this is called a “sharing generation”.
For example, suppose you have a company with four client computers (John, Susan, Bob and Bill) connected with a Panorama X Server. All four share a database that needs changes. The diagram below shows the flow of how these changes are made. (Note: The flow is a bit different if you are also adding, removing or rearranging fields, as you’ll see a bit later.) First, one of the clients, in this case John, makes changes to the procedure code, form design, and/or field properties of the database. Then the sharing generation process is used to transfer these changes to the server, and then on to Susan, Bob and Bill. The entire process usually only takes a couple of minutes.
In the following sections we’ll examine the details of the sharing generation process.
New Sharing Generation for Procedures, Forms and Field Options
If you need to change procedure code, modify form graphics, or change field properties (other than data type or choices), the first step is to actually make the necessary changes on a client computer (you should only do this on one computer at a time). To modify code, use the Procedure Editor. To modify a form, use Graphics Mode. To change field properties, use the Field Properties Panel. All these work exactly the same as they do in a non-shared, single user database. You can also add or remove procedures, and/or add or remove forms. (However, if you need to add or remove fields, or change a field’s data type, a different process is needed, see the following section).
Once the necessary changes have been made, they need to be transferred to the server and then to the other clients. This is done with the New Generations panel of the Database Options dialog (in the File menu). (If you don’t see this panel, it means your database isn’t currently shared. See Creating a Shared Database.)
This dialog has checkboxes that allow you to tell Panorama what changes have been made that need to be uploaded. Panorama doesn’t keep track of what has changed itself, so you have to explicitly tell it using this dialog. For example if you make changes to a form but don’t check that box, those changes won’t be uploaded to the server (they could be uploaded later, however).
This panel also gives you the option to type in notes explaining the change (or changes) that is being uploaded. Entering notes is entirely optional, but these notes can be displayed later so that you can view a history of all the changes that have been made to the database.
At this point you need to decide whether the changes you have made are critical or non-critical. If a change is critical that means that you want to ensure that all users are immediately prevented from continuing to use the previous version of the database. For example if you’ve made a code change to fix a serious bug, you would probably want to designate that the new generation is critical. To designate whether the changes are critical or not, use the popup menu.
If non-critical is specified (as shown above), the changes will be distributed gradually as other users synchronize their databases. Simply press Ok to upload the changes to the server. Once the changes are uploaded, they will automatically download to other client computers as each client synchronizes the database (which of course also happens when a client opens a database).
Uploading a Critical New Generation
If the changes are critical, the upload process is a bit more complex. Before you can actually upload critical changes to the server, all other users of this database must either close the database on their computers, or at a minimum temporarily disconnect the database from the server, allowing the data to be viewed but not modified (see Temporarily Disconnecting a Shared Database from the Server). Because of this restriction, you may want to wait to upload a critical new generation until after business hours, in the evening or on the weekend, when no one else is using the database. You can use the Server Administration Wizard to check to see if anyone else is using the database.
Once all other users have closed or disconnected the database, press the Ok button to upload the critical new generation to the server. Panorama will upload only the components you have specified. For example, if you checked only the Procedures option, only procedures will be uploaded, not forms or field properties. This makes the upload as fast as possible.
Note: If one or more other users failed to close or disconnect the database before you pressed the Ok button, you’ll see a warning alert, as shown below. You can either ask the other users to close or disconnect the database and try again immediately, or you can cancel and then re-submit the new generation later.
Once the critical upload is complete, the other users can re-open or re-connect the database. If the database was closed, they should re-open it the normal way – either by double clicking on the icon in the Finder, using the File>Recent menu, or other commands in the File menu. If the database was disconnected but is still open, they should reconnect with the File>Connect to Server command (see Temporarily Disconnecting a Shared Database from the Server). When they re-open or re-connect, Panorama will automatically download the changes and apply them to the database. This will be very fast, because only the specified changes are downloaded. In this particular example, only the procedure code will be downloaded, not the data, or the forms. So even if the database contains a million records, downloading the update will be very quick. Once the download is complete the database can be used normally.
The process of opening or reconnecting the database and downloading the new sharing generation update must be repeated on each client computer. Fortunately, Panorama takes care of this automatically as the database is opened on each client.
New Generations must be uploaded from the Master Computer
If a Master Computer has been designated in the Server Preferences panel (see Restricting Server Access), that is the only computer that is allowed to upload a new generation. If you attempt to upload a new generation from some other computer, you’ll see this warning.
If this message appears you’ll either need to change the Master Computer preference for the server, or you’ll need to move to the computer that has been designated as the master to make the necessary changes.
Manually Confirming New Generation Updates
As described above, new generations are normally automatically applied on each client computer when the database is opened or re-connected with the server. However, using the Client preferences panel you can configure Panorama to ask you to confirm before updating to a new generation. (Keep in mind that this preference only affects this client computer, if you want multiple client computers to work this way you must explicitly set this preference on each computer.)
If the Ask to Confirm option is enabled, Panorama will display an alert when you open a database that is out of date.
If you simply want to go ahead with the update, press the Update Now button. The changes will be downloaded and applied to the database.
For more detail about the changes in this update, press the View Update Notes button. This opens a panel that displays the date and time these changes were uploaded, what components were uploaded (in this case just procedures), the person and computer where the changes were made, and the notes that were input when the new generation was uploaded (if any). (This panel actually displays all new generations that have ever been uploaded for this database, not just the most recent.)
The final choice is Use Offline. If you choose this option, you can only view the database, you cannot modify it. The toolbar shows a lock icon to indicate that the data cannot be modified.
If you later change your mind and want to modify the database, use the File>Connect to Server command (see Temporarily Disconnecting a Shared Database from the Server). This will cause the new generation to be downloaded from the server so that the database structure is in harmony with all other users of the database. (You can also close the database and then later re-open it to download the new sharing generation.
New Sharing Generation for Adding, Removing or Rearranging Fields
If you need to change the arrangement of fields, or change the data type of one or more fields, the new generation process is slightly altered. Unlike changes to procedures or forms, you can’t just start making changes without any preparation. Before the field arrangement can be modified, all other users must close or disconnect the database, and you have to tell Panorama that you are starting the new generation process. This diagram illustrates the necessary steps.
Because of the restriction that no one else can use the database while you are changing the design, you may want to do this after business hours, in the evening or on the weekend, when no one else is using the database. You can use the Server Administration Wizard to check to see if anyone else is using the database.
Once all other users have closed or disconnected the database, open the File>Database Options dialog, switch to the New Generation panel, and check the Field Arrangement and Data Types option. When you do this, Panorama will automatically enable the other checkboxes as well. When a new sharing generation changes the field arrangement, it also automatically includes everything else in the database (procedures, forms, etc.). It also automatically designates this as a critical update (a change in the field arrangment cannot be non-critical).
You may also type in notes about the changes you intend to make (you’ll get another chance to type in these notes in a moment). Then press the Ok button to start the new sharing generation process. Panorama starts this process by synchronizing the data with the server (to make sure this computer has the most up-to-date data), then puts the database into a special paused mode. (Alternately you can use the pop-up menu to download the data from the server instead of synchronizing. This downloads the entire database from the server, so may be significantly slower than synchronizing. There is usually no reason to choose the slower option, but it is available.)
The special paused mode is indicated by a pause icon in the toolbar.
In this paused state, changes made to the database are not immediately synchronized with the server. The database behaves as if it was a single user database. You can edit data, but more importantly, you can add or remove fields, rearrange fields (by dragging them around), or change the data type of a field (for example from text to numeric). You can also modify forms and procedures, in fact, you can do anything you want. But you probably don’t want to take too much time making these changes – no one else can modify the database until you finish (though they can still view the data if they disconnected rather than closing the database, see Temporarily Disconnecting a Shared Database from the Server).
When you have finished making the changes you need, open the File>Database Options dialog again. You’ll see that the New Generation panel has now changed into the Upload New Generation panel.
You now have a second chance to type in notes explaining the changes that have been made. This is optional, but recommended for keeping track of the history of this database. Either way, the final step is to press the big Upload Now button. This uploads the entire database, with all changes, to the server. The dialog will close, and you can now resume using the database in normal sharing mode. The other users can also re-open or re-connect the database and resume normal use of the database, as described in the previous section.
Cancelling a New Sharing Generation
What if you go into the special pause mode to change the field arrangement and then decide you want to go back to the original arrangement? To do that, open the File>Database Options dialog and press the Revert to Last Generation on Server button. Panorama will discard any local changes you have made, going back to the last sharing generation that had been previously uploaded to the server. You can then resume using the database in shared mode.
Another option is to press the Abort New Generation button. This takes the database out of the special pause mode, but does not upload the changes to the server. The database will be offline, so it can’t be edited. There’s really no reason to ever do this unless you intend to detach the database from the server and use it independently as a single user database (see Detaching a Shared Database from the Server). As soon as you press the abort button, other users can re-open the database and resume using it (but they will not have access to any of the changes you have made).
Using New Sharing Generation for Making Mass Data Changes
The New Sharing Generation process can also be used for making bulk changes to the data itself, even if the field arrangement isn’t changed. For example when working with a shared database it’s not normally possible to use the Remove Unselected command to delete multiple records, or to use the Morph All Fields command or to Join another database to the current database. These operations are only allowed on single user databases. These operations are allowed, however, when sharing is temporarily paused by the New Sharing Generation process. If you need to perform one of these operations, first pause sharing using the steps described above for adding, removing or rearranging fields. Once sharing is paused, perform whatever bulk data change operation you need done - delete, join, etc. Once the operation is complete, use the File>Database Options to upload the revised database back to the server.
Performing a New Sharing Generation in Code
In addition to performing a new sharing generation manually using the Database Options dialog, it’s also possible to automate the process in code by using the startnewdatabasegeneration statement.
For example, suppose you periodically want to clear out a database and start from scratch with empty data. This can be done with just three lines of code.
startnewdatabasegeneration ""
deleteall
uploadnewgeneration "All data removed."
Of course you’ll want to be super careful with code like this – it will completely and permanently zap whatever data has been collected in this database. If you do create a procedure like this, you’ll probably want to prefix this code with a confirmation dialog, or possibly even ask for a special password. Or even better, you could save an archive copy of the data right before you delete it.
startnewdatabasegeneration ""
export info("databasename")+"_archive_"+timestampstr()+".txt",exportline(),lf()
deleteall
uploadnewgeneration "All data removed."
See startnewdatabasegeneration to learn more about automating the new sharing generation process in code.
See Also
- Creating a Shared Database -- convert a single user database into a shared database.
- Manually Uploading a Quick Patch to the Server -- uploading a procedure or form.
- Permanently Deleting a Database from the Server -- remove a database from the server.
- Permanently Detaching a Shared Database from the Server -- unshare a shared database.
- startnewdatabasegeneration -- starts a new generation of the current database to the server (must be a shared database).
- Temporarily Disconnecting a Shared Database from the Server -- pause database sharing.
History
| Version | Status | Notes |
| 10.2 | New | New in this version. |