|Powered by QM on a Rpi server|
KnowledgeBase 00096: Moving QM Accounts Between Systems
This article was originally published as a Tip of the Week.
Users sometimes need to move one or more QM accounts between systems, perhaps as part of redeployment on a new system or creation of a backup copy of the application. This article sets out how this can be achieved.
Moving all accounts in an entire QM system or a single account that is entirely contained within the account directory is usually relatively easy. If everything can be restored to the same pathnames as on the original system, little more should be required.
If the requirement is simply to move an entire QM system to a new computer, the easiest approach is to copy all QM account directories, including QMSYS, to the new location. If QM is already installed on the new system, it should be shut down before copying any files by use of
qmsvc -stop (Windows) qm -stop (Linux)After copying all files, install (or re-install) QM on the new system to update system files and apply the licence for the changed system id code. If there has been a change of operating system from Windows to Linux or vice versa, it will be necessary to run the *FIXPATH globally catalogued program to update file pathnames in the VOC. This program is documented in the QM Reference Manual.
Selective transfer can be more challenging, especially if the account(s) to be saved have interactions with other accounts such as shared files.
Similarly, moving an account to a different pathname on the target system may require changes to pathnames of items that are not referenced by simple relative name.
What Tools Should Be Used?
Although QM includes an ACCOUNT.SAVE command to create Pick style account save media, this is not really adequate for transferring applications between QM systems. The media format was defined by Pick long ago and is incapable of recording some information relevant to QM systems such as triggers, encryption or distributed files.
QM uses operating system level structures to represent the application data files. The best way to move applications is simply to use operating system level backup tools. The block level data transfer performed by these tools will usually be significantly faster than a record level transfer. It will include all control information relating to indices, encryption, triggers, etc and will preserve the layout of the application in terms of both pathname hierarchy and, with most tools, file permissions.
In many cases, simply saving the account directory and all sub-structures will be adequate. Data files stored within this structure will appear as subdirectories and will, therefore, be restored to their correct locations on the target system.
The following sections consider situations where copying just the account directory may not be sufficient.
Files that are located somewhere other than the account directory will need to be included in the saved data. These might be, for example:
If the account is restored to a different location than it had on the source system, the VOC entries for any files referenced by F-type entries with full pathnames will need to be updated. The default behaviour of QM when a file is created in the account directory is to use a relative filename that will not need to be changed.
If an application opens files by pathname and the account is restored to a different path, the relevant application programs must be modified.
Programs catalogued in local mode will be included in an account directory save unless the object code file (e.g. BP.OUT) is a remote file as discussed above. If the saved data is restored to a different pathname, the VOC entries corresponding to locally catalogued programs will need to be updated. These VOC entries can be selected with a command of the form
SELECT VOC WITH TYPE = "V" AND F2 = "CS"
Programs in the private catalogue will be included in an account directory save unless the optional $PRIVATE.CATALOGUE VOC record has been used to relocate the private catalogue directory (normally named cat under the account directory).
Globally catalogued programs reside in the gcat subdirectory of the QMSYS account. Global cataloguing is usually used for programs that should be visible to multiple accounts but it is not easy to know whether any specific account references individual globally catalogued items. If global cataloguing may have been used, it is probably best to save all user items in gcat. Note that, unless the source and target systems are running the same version of QM it is important that system supplied items in gcat are not updated. From release 3.4-0, QM includes a globally catalogued tool named *IMPGCAT to import user written items from another QM system, ignoring standard system supplied items. Prior to introduction of this tool, the best that can be achieved in an automated process is to omit items with names that begin with a dollar sign ($), an exclamation mark (!), or an asterisk though this may omit some user written items. Note that the directory file record name translations will have changed the leading asterisk to be %A.
If files use data encryption, the same encryption key names must exist on the target system, using the same encryption mode and key string. It is not necessary to save the original key vault ($VAULT in the QMSYS account directory) if the keys can easily be recreated. If the key vault is transferred to the target system it will be necessary to use the RESET.MASTER.KEY command to make the file usable.
Pick Style Form Queue Definitions
Applications that use Pick style form queues will have stored the associated printer configuration parameters in the $FORMS file. This file, referenced by an F-type record in the VOC of all accounts, is normally located in the QMSYS account directory but can be relocated. This is usually only done to allow multiple separate applications running on the same system to use distinct form definitions.
If the account being transferred uses QMNet, equivalent server definitions must be set up on the target system. This may not be as simple as just copying the $SERVERS file from the QMSYS directory as IP addresses and user security rules may need to differ.
The Accounts Register
A suitable entry for the account must be created in the accounts register of the target system.
Extended Character Set Mode
An application that uses Extended Character Set (ECS) mode may require that modified character maps are moved from the ecs-maps subdirectory of the source system to the target system.
Any application that has stored items in the QM.VOCLIB file may require these to be copied to the target system. In most cases, this would be adequately handled by the process described for remote files above.
Some applications may have licensing that is tied to the underlying QM licence. In such cases, it may be necessary to have an equivalent application licence for the target system.
It may be necessary to examine any QM configuration parameters that have been changed from their default values to determine whether similar changes are needed on the target system.
Handling System Architecture Differences
A further complication is introduced if the source and target systems are of different types.
Moving an account from Linux to Windows or vice versa requires that all pathnames in VOC items are updated to change the directory delimiter character. There is a program in the global catalogue as *FIXPATH that can be executed from the command prompt of the relevant account to so this job. It can also be used from elsewhere with the account name or pathname on the command line.
If the target system has a different byte ordering from the source system, the qmconv utility must be run from the operating system command prompt to update all hashed data files.
Could It Be Automated?
Why isn't there a standard tool to do all of this?
Perhaps there should be. It has certainly been investigated. Perhaps it will appear in a future release.
Some of the above is relatively easy if it is accepted that the restored account will use the default locations for all items rather than trying to replicate the original layout of an application that used remote file locations for load balancing, etc.
There are, however, aspect of this that are far from trivial. For example, it is not possible to identify which globally catalogued programs are used by an application or which Pick style form queue definitions should be copied. Simply copying all global catalogue items or all form queue definitions may not accurately reproduce the original ssytem as it could result in items that are not relevant to the transferred account being overwritten.
00093: Application Portability Between Platforms