This section includes a code example that shows the steps involved in the conversion from a major CMS-based project into a project based on a VDE database. The project involves the importation of multiple CMS libraries for the various software units---what VDE calls facilities---into VDE. Each facility is organized in a CMS library located under the project-specific root directory DISK$EVMSCMS:[VMS].

$ set noon $ $! These logicals will need to be (re)defined in the $! site-specific system startup command procedure. $ $ Define/System/Executive/Nolog VMS$ DISK$EVMSCMS:[VMS.]/Trans=Conceal $ Define/System/Executive/Nolog VSC$DATADISK $10$DKB400: $ Define/System/Executive/Nolog VSC$ROOTDISK $10$DKB400: $ Define/System/Executive/Nolog VSC$SNAPDISK $10$DKB400: $ Define/System/Executive/Nolog VSC$JNLDISK $10$DKB400: $ $ Define/System/Executive/Nolog VSC$DBDATA VSC$DATADISK:[evms.dbdata] $ Define/System/Executive/Nolog VSC$DBROOT VSC$ROOTDISK:[evms.dbroot] $ Define/System/Executive/Nolog VSC$DBSNAP VSC$SNAPDISK:[evms.dbsnap] $ Define/System/Executive/Nolog VSC$DBJNL VSC$JNLDISK:[evms.dbjnl] $ $ Create/Directory VSC$DBDATA $ Create/Directory VSC$DBROOT $ Create/Directory VSC$DBSNAP $ Create/Directory VSC$DBJNL $ $ VDE create librar VSC$DBROOT /DEFER - /NAME=EVMS /REMARK="EVMS Source Library" - /NOAUTO_CONVERT /AUTO_ADD_USER=VMS_SOURCE /AUTO_MAIL - /ASK_INFO_FILE /ASK_REPL_CAUSE /SHOW_GEN_EXPR - /NOHISTORY_NOTES /NOALLOW_DELETE /NOWILD_INS_GEN - /NOCMS_ELEM_HIST /CREATOR="Stephen Hoffman" - /DEF_PRIVILEGES=(CREMOD,RESREP) - /AUTH_PRIVILEGES=(CREMOD,RESREP) - /data=VSC$DBDATA/journ=VSC$DBJNL/snap=VSC$DBSNAP - ! SHOW DEFAULTS SHOW LIBRARY/FULL MODIFY CONTEXT/PUBLIC DEFAULT/NOSTREAM/NOFACILITY ! SET DIRECTORY/DELTA_FILES VMS$:[000000] SET DIRECTORY/DELTA_FILES/SUBDIRECTORY=VDE$CMS [.CMS] SET DIRECTORY/DELTA_FILES/SUBDIRECTORY=VDE$MARKER [.SRC] MODIFY FACILITY CODE/NAME=AAA_VDE_TEST/REMARK="Test facility for VDE developers" CREATE DIRECTORY_TREE/DELTA_FILES ! SHOW DIRECTORY/DELTA_FILES ! ! Set to the AAA_VDE_TEST facility for use by database administion, ! and populate it with a test module or two. ! SET FACILITY AAA_VDE_TEST CREATE MODULE/NODELETE/REMARK="VDE test module" LOGIN.COM /INPUT=SYS$LOGIN: CREATE MODULE/NODELETE/REMARK="VDE test module" SYSTARTUP_VMS.COM /INPUT=SYS$STARTUP: ! SET DIRECTORY/STAGING disk$common:[vms.stage] CREATE DIRECTORY_TREE/STAGING ! ! Rename stream MAIN to be MAINLINE. We will use this stream for a few ! selected modules that should always stay on the main development thread ! outside the normal development streams. ! MODIFY STREAM MAIN/NAME=MAINLINE/REMARK="Mainline thread for selected modules" SHOW STREAM/FULL MAINLINE SET DIRECTORY/STREAM disk$common:[VMSMAINLINE] CREATE DIRECTORY_TREE/STREAM ! ! Create the V6.1 parent stream to all others streams. Specification ! of /MAIN or /NOMAIN, and /PARENT and /SUCCESSOR are key factors in ! the CMS generation selection and the propogation processing. All ! streams must be created prior to specification of CREATE FACILITY ! /FROM_CMS_LIBRARY. See the reference manual for details. ! SET STREAM MAINLINE CREATE STREAM/CLOSED/MAIN V6.1/PARENT=MAINLINE/REMARK="create release class" CREATE STREAM/CLOSED/MAIN V6.2/PARENT=V6.1/REMARK="create release class" CREATE STREAM/CLOSED/MAIN V6.3/PARENT=V6.2/REMARK="create release class" ! SHOW DIRECTORY/DELTA_FILES ! Exit $ SHOW TIME $ VDE create facility ACAS/FROM_CMS/REMARK="ACAS" create facility ACC/FROM_CMS/REMARK="Accounting" create facility ACLEDT/FROM_CMS/REMARK="ACL Editor" .... create facility ZSYSGEN/FROM_CMS/REMARK="ZSYSGEN" create facility ZSYSVER/FROM_CMS/REMARK="ZSYSVER" Exit $ SHOW TIME

6.7.3 Example CMS Upload Procedures

VDE includes example command procedures and associated files in VDE$EXAMPLES:, the core example procedure used for uploading an existing CMS library into VDE is VDE$CREATE.COM. Files associated with VDE$CREATE.COM will need to be tailored to local requirements and to the local CMS library directory structure.

Also see Section 6.1.1 for information on VDE$UPLOAD, a tool that can directly perform the task of library creation based on a description of the desired VDE database contained in a data file.

6.7.4 Adding Individual Source Modules

Adding modules into a VDE library is a simple operation.

VDE„ CREATE MODULE/NODELETE/REMARK="user login module" - _VDE„ LOGIN.COM /INPUT=SYS$LOGIN:

For further information on the above command and for the available command options, please refer to the VDE Reference Manual.

This chapter explains how how to perform various maintenance operations. These operations include clearing deadlocks, performing the source code database backups, creating and maintaining the associated backup procedures, restoring the database after a failure, and recovering lost information in the CMS libraries on a VDE library. Also included are the procedures involved in periodic cleanups of the staging area directories, and one approach toward storage recovery within VDE libraries. Some of these commands and operations will require you to have the OpenVMS SETPRV or SYSPRV privileges.

Operations described in this chapter are normally performed only by the maintainers of the OpenVMS VDE libraries, or by those users maintaining their own VDE libraries.

The command procedures described in this chapter are located in directory MASD$JNL:[VMS.TOOL] on the journal disk for the OpenVMS VDE libraries. Because these procedures may be needed in case of journal disk failures, they are also stored in the directory VMS$:[TOOLS].

7.1 Creating SCT Notes Conferences

For the automatic submission of the SCT note to operate properly, the SCT notes conference must have the correct protections. The following shows the commands necessary to enable the security necessary for the typical SCT notes conference:

$ set security/acl=- _$ ((IDENTIFIER=VMS_SOURCE_READ,ACCESS=R+W+E),- _$ (IDENTIFIER=VMS_SOURCE,ACCESS=R+W+E)) - _$ NOTES$LIBRARY:SCT-*.NOTE $ set security/acl=- _$ ((IDENTIFIER=[DECNET,NOTES$SERVER],ACCESS=R+W),- _$ (IDENTIFIER=NETWORK,ACCESS=NONE)) - _$ /PROTECTION=(S:RWED,O:RWED,G:RE,W) - _$ NOTES$LIBRARY:SCT-*.NOTE

The above security attributes and resource identifiers can and should be adjusted for site-specific requirements.

Failure to correctly set up the security attributes can prevent the creation of SCT entries by VDE.

7.2 Taking VDE Offline

Depending on requirements, one can use the MODIFY LIBRARY/LOCK command to mark a particular VDE library as read-only to all but privileged VDE users, and one can define the logical name VDE$OFFLINE to take the VDE environment completely offline.

$ Define/System/Executive VDE$OFFLINE - _$ "Down for maintenance until 23:00"

Users with privileges within VDE can override the library lockout; a message indicating that a library lock is being overridden is displayed in this situation. For further information on this particular command, see the VDE Reference Manual manual.

Short of deassigning the VDE$OFFLINE logical name, there is no way to override the VDE$OFFLINE lockout---the VDE$_OFFLINE message and the translation of the logical name will be displayed to all users. Once this privileged logical name has been defined, users cannot invoke the VDE images, and users already executing VDE will be unable to invoke any new VDE commands.

Note that it can be difficult to debug certain VDE problems when the VDE$OFFLINE lockout is in place, as even the VDE maintainers cannot invoke the VDE images. This lockout is best suited for the protection of Rdb and CMS maintenance operations.

7.3 Resolving Database Problems

Various things have been seen to go wrong within VDE, or within Rdb. Failures include deadlocks, and various Rdb problems that result in process-level and system-level bugcheck dumps.

VDE has occasionally been known to deadlock at the Rdb level. This deadlock condition is usually heralded by a series of "VDE is wedged" complaints from various vociferous VDE users.

Process-level deadlocks occur infrequently, and they often involve high-traffic applications such as database backups or they involve a VDE command that was paused via [XOFF] command, and they can usually be easily and safely cleared using the following command:

$ RMU/CLOSE/CLUSTER/ABORT=DELPRC/WAIT- _$ VDE$:[ROOTDIR]VDE$DATABASE

The above RMU command deletes all processes currently connected to the specified database. As most VDE users utilize kept subprocesses, this process deletion is often entirely transparent to users.

To use the RMU/CLOSE command, you must possess the OpenVMS SYSPRV or BYPASS privilege, or you must have access via the Rdb database access control list. If the RMU/CLOSE command hangs for an extended interval (it should hang for a while pending cluster-wide closure), see if the "freeze" deadlock mentioned in Section 7.3.2 has occured.

7.3.2 Freeze in Rdb

It is possible for Rdb processes to deadlock waiting for the Rdb "freeze" resource.

When a "freeze" deadlock occurs, one normally finds any attempt to SET LIBRARY to the VDE library or to run various RMU commands---including the RMU/CLOSE command mentioned in Section 7.3.1 -- against the library will hang indefinitely. This deadlock can survive the shutdown of all Rdb database monitors, though a shutdown of the node holding the deadlocked recovery process can relieve the deadlock.

The following example shows the particular process holding the "freeze" lock:

$ RMU/SHOW LOCK/MODE=BLOCKING ========================================================================== SHOW LOCKS/BLOCKING Information ========================================================================== -------------------------------------------------------------------------- Resource: freeze ProcessID Process Name Lock ID System ID Requested Granted --------- --------------- --------- --------- --------- ------- Waiting: 224018E0 SHOFFMAN_00E0.. 3F00433E 00010002 CW NL Blocker: 20402DC8 RDM_RB60_1..... 5D00A098 00010002 PR PR

One can use ANALYZE/SYSTEM or similar to attempt to locate the reason the blocking process---RDM_RB60_1 in the above example---in an attempt to resolve the problem.

7.3.3 Rdb process dumps

Rdb generates a dump file when it encounters an unexpected condition. Under typical circumstances, Rdb will display a message indicating a dump is being generated.

VDE> set lib evms Generating bugcheck dump file WORK10:[user]RDSBUGCHK.DMP

One potential cause is the inability to write to the run-unit journal area, see Section 7.3.4 for information for details.

7.3.4 Rdb run-unit journal errors

The run-unit journal area is a key component of the Rdb processing, and allows Rdb to rollback incomplete or erroneous database operations. And when an unexpected condition occurs with the run-unit journal, Rdb tends to generate a dump file.

Errors involving the run-unit journal have a variety of footprints, including symptoms such as process-level Rdb bugcheck dumps and user process deletions.

7.3.4.1 Missing run-unit journal area

If the run-unit journal area is entirely messing, one can potentially see an Rdb bugcheck dump generated. By default, the run-unit journal is written to SYS$LOGIN_DEVICE:[RDM$RUJ], but this can be altered via the Rdb RDMS$RUJ logical name.

VDE> set lib evms Generating bugcheck dump file WORK10:[user]RDSBUGCHK.DMP

When the run-unit journal area is entirely messing or or is incorrectly protected, Rdb will generate a process-level bugcheck dump file, and VDE will not operate correctly. (In addition to the above message, it is also possible one may see VDE stack-dumps.

For any user seeing these errors, make certain that SYS$LOGIN_DEVICE:[RDM$RUJ] exists and is owned by [SYSTEM]. If it does not exist, create it. (Note that the directory is actually based on the device from SYS$LOGIN:, not from the SYS$LOGIN_DEVICE: specification.)

$ create/directory work10:[rdm$ruj]/owner=[system] $ set security/owner=[system] - _$ work10:[000000]rdm$ruj.dir,[rdm$ruj]*.*.* $ run sys$system:sysman SYSMAN> DISKQUTA ADD [SYSTEM] - _SYSMAN> /DEVICE=WORK10/PERM=100000/OVER=1000 SYSMAN> [CTRL/Z]

If [SYSTEM] already has a quota entry for WORK10:, use the SYSMAN command DISKQUTA MODIFY in place of DISKQUOTA ADD.

Based on Rdb documentation, one can also redirect the location of the SYS$LOGIN_DEVICE:[RDM$RUJ] directory via the Rdb RDMS$RUJ logical name. (Note that Rdb does not actually use SYS$LOGIN_DEVICE:, it appears to parse SYS$LOGIN:.)

This particular error is more common on volumes that were not initialized with [SYSTEM] ownership:

$ INITIALIZE work10: work10/SYSTEM

Also see Section 7.3.4.2 for a related problem.

7.3.4.2 Rdb run-unit journal diskquota errors

Rdb requires the creation of a run-unit journal file. By default, this is in the user's login device, in the directory [RDM$RUJ], and this location can be altered using the logical name RDMS$RUJ. If this creation operation fails or due to insufficient quota, one can see the following errors:

$ vde/library=evms %RDB-F-SYS_REQUEST, error from system services request -RDMS-F-FILACCERR, error creating run-unit journal file WORK1:[RDM$RUJ]VDE$DATABASE$0099C91EC6BCC945.RUJ;1 -RMS-E-CRE, ACP file create failed -SYSTEM-F-EXDISKQUOTA, disk quota exceeded

To resolve this particular error for the quotas present on device WORK1:, issue the following commands:

$ set security/owner=[system] - _$ work1:[000000]rdm$ruj.dir,[rdm$ruj]*.*.* $ run sys$system:sysman SYSMAN> DISKQUTA ADD [SYSTEM] - _SYSMAN> /DEVICE=WORK1/PERM=100000/OVER=1000 SYSMAN> [CTRL/Z]

If [SYSTEM] already has a quota entry for WORK1:, use the SYSMAN command DISKQUTA MODIFY in place of DISKQUOTA ADD.

Also see Section 7.3.3 for a related situation.

7.3.4.3 Rdb recovery process dumps

Rdb generates a dump file when the recovery process encounters an unexpected condition. (See Section 7.3.4.4 for one example of an unexpected condition.) There may or may not be any indication this dump is being written---in one particular case, the process that was triggering the failing recovery process was being logged off the system.

Under typical circumstances, the recovery process dump file is written to SYS$SYSTEM:RDMDBRBUG.DMP. The following is an example of a recovery process dump file:

================================================================================ Bugcheck dump SYS$SYSROOT:[SYSEXE]RDMDBRBUG.DMP;17 ================================================================================ This file was generated by DEC Rdb V6.0-1 upon detection of a fatal, unexpected, error. Please return this file, the query or program that produced the bugcheck, the database, monitor log, and any other pertinent information with an SPR. Current time is 21-JAN-1997 15:20:21.10 3-FEB-1997 16:23:35.84: Linked DBR (RDBVMS) RDMS$ALPHA_V0601:[KODABLD] 25-JAN-1997 08:06:24.32: Compiled KOD$DBR (KODA) KOD$ALPHA_V0601R:[DBR] 25-JAN-1997 08:06:15.13: Compiled KOD$LIBRARY (KODA) KOD$ALPHA_V0601R:[CODE] ================================================================================ Stack Dump ================================================================================ Saved PC = 001383C0 : STD$DUMP_ALPHA_STACK + 00000090 Saved PC = 001212E4 : KOD$BUGCHECK_DUMP + 00000D74 Saved PC = 000A1214 : KOD$BUGCHECK_AND_EXIT_HNDLR + 00000094 Saved PC = 80895D44 : S0 address Saved PC = 962A62BC : S0 address ***** Exception at 0006B930 : DBR$RECOVER + 000009F0 %RDMS-F-FILACCERR, error opening run-unit journal file WORK1:[RDM$RUJ]VDE$DATABASE$0099C91EC6BCC945.RUJ;1 -SYSTEM-W-ACCONFLICT, file access conflict Saved PC = 0006AB50 : DBR + 00000B90 Saved PC = 00057F0C : BLI$CALLG + 000000BC Saved PC = 0005011C : DBR$MAIN + 0000011C Saved PC = 962D3C44 : S0 address [...rest of dump file has been omitted...]

The above example clearly points to an access conflict on a run-unit journal file. The above recovery process failure was cleared by deleting the processes that were holding open run-unit journal, and restarting the recovery process.

$ run sys$system:sysman SYSMAN> set environment/cluster SYSMAN> set profile/privilege=all SYSMAN> do show device/file/nosystem work1: SYSMAN> [CTRL/Z]

7.3.4.4 Missing run-unit journal files

A recovery-process dump similar to Section 7.3.4.3 can also be seen when the RUJ file is missing. This can be a result in user process deletions and failed RMU backups, as well as other nasty behaviour.

One sees the following in an RMU/DUMP:

Active user with process ID 38810DD3 Stream ID is 1 Monitor ID is 2 Transaction ID is 16 Recovery journal filename is "WORK300:[RDM$RUJ]VDE$DATABASE$009A486CCA4B098E.RUJ; Read/write transaction in progress Transaction sequence number is 183093

and one sees the following in SYS$SYSTEM:RDMDBRBUG.DMP:

***** Exception at 000253ED : DBR$RECOVER + 000005CB %RDMS-F-FILACCERR, error opening run-unit journal file WORK300:[RDM$RUJ]VDE$DATABASE$009A486CCA4B098E.RUJ;1 -RMS-E-FNF, file not found

There's no good solution to this problem if the file cannot be located, short of locating the missing RUJ, or recovering the database from Rdb BACKUP.

The following steps will clear the missing RUJ and will leave the\ database accessable, but the database is now likely corrupt. Recovery from RMU/BACKUP is preferable.

$ RMU/ALTER databasename(1) RdbAlter> DISPLAY ROOT USER(2) RdbAlter> DEPOSIT ROOT USER # RUJ=""(3) RdbAlter> COMMIT(4) RdbAlter> EXIT $ RMU/UNLOAD...(5) $ RMU/VERIFY/ALL(6)