VS VM Operating System Release 02.05.00 Software Release Notice 1st Edition -- October 1999 Copyright Wang Laboratories, Inc., 1999 DISCLAIMER OF WARRANTIES AND LIMITATION OF LIABILITIES The staff of Wang Laboratories, Inc., has taken due care in preparing this manual; however, nothing contained herein modifies or alters in any way the standard terms and conditions of the Wang purchase, lease, or license agreement by which this software package was acquired, nor shall Wang Laboratories, Inc., or its subsidiaries be liable for incidental or consequential damages in connection with or arising from the use of the software package, the accompanying manual, or any related manuals. Notice All Wang Program Products are licensed to customers in accordance with the terms and conditions of the Wang Laboratories, Inc., Standard Program Products License; no ownership of Wang software is transferred, and any use beyond the terms of the aforesaid License, without the written authorization of Wang Laboratories, Inc., is prohibited. CONTENTS PREFACE CHAPTER 1 ENHANCEMENTS 1.1 Introduction ......................................... 1-1 1.2 Enhancements New to This Release ..................... 1-1 CHAPTER 2 HARDWARE AND SOFTWARE REQUIREMENTS 2.1 Introduction ......................................... 2-1 2.2 Hardware Requirements ................................ 2-1 2.3 Software Requirements ................................ 2-2 CHAPTER 3 CORRECTED PROBLEMS 3.1 Introduction ......................................... 3-1 3.2 Problems Corrected ................................... 3-1 3.3 VS/VM Problems Open .................................. 3-2 2 CHAPTER 4 RESTRICTIONS AND SPECIAL CONSIDERATIONS 4.1 Introduction ......................................... 4-1 4.2 Architectural Considerations ......................... 4-1 4.3 Virtual Disks ........................................ 4-1 4.4 Workstations ......................................... 4-2 4.5 VM Debugger .......................................... 4-2 CHAPTER 5 SPECIAL CONDITIONS 5.1 Introduction ......................................... 5-1 5.2 Known Anomalies ...................................... 5-1 CHAPTER 6 MEDIA CONTENTS 6.1 Introduction ......................................... 6-1 6.2 Distribution Diskette ................................ 6-1 CHAPTER 7 INSTALLATION INSTRUCTIONS 7.1 Introduction ......................................... 7-1 7.2 New Installation ..................................... 7-1 Restore the Distribution Materials ................. 7-1 Run the Install Utility ............................ 7-1 Physical Device Address (PDA) Table ................ 7-4 Install IPLTEXT .................................... 7-6 IPL the VM System .................................. 7-6 7.3 VM Version Upgrade ................................... 7-7 Restore the Distribution Material .................. 7-7 Run the Upgrade Utility ............................ 7-7 IPL the System ..................................... 7-7 7.4 Suspending the VS/VM Operating System Temporarily .... 7-7 CHAPTER 8 UPDATES TO DOCUMENTATION 8.1 Introduction ......................................... 8-1 8.2 Command Updates ...................................... 8-1 8.3 Sections Updated This Release ........................ 8-2 8.4 Previously Updated Sections .......................... 8-3 3 PREFACE VS/VM Release, 02.05.00 is a maintenance release of the Wang VS/VM operating system. The last maintenance release of VS/VM was release 02.04.00. This document describes all enhancements and fixes made to VS/VM since that release. It also contains all updates to the VS/VM User's Guide since the User's Guide was published in July of 1989. Note: Throughout this document all references to the CP type CP9 also refer to the VS6000 CP type CP9E. Related Documents - VS/VM User's Guide (715-0234A) - VS/VM Analyst's Guide (714-0281) 4 CHAPTER 1 ENHANCEMENTS 1.1 Introduction This chapter describes enhancements made to the VS/VM operating system since the last release. The following sections provide a detailed listing of the enhancements in Release 02.05.00. 1.2 Enhancements New To This Release The new VS CPU model VS18000 is now supported in VM. The microcode for this machine is a dual architecture microcode which will support both VSE (pre-7.50) and VSXM (7.50) translation architectures concurrently. ______________________________________________________________________________ Enhancements 1-2 CHAPTER 2 HARDWARE AND SOFTWARE REQUIREMENTS 2.1 Introduction This chapter specifies the hardware and software you need in order to install Release 02.05.00 of the VS/VM Operating System. 2.2 Hardware Requirements This version of VS/VM is submitted for use on the following VS systems: VS5000 (except the VS5430) CP9 VS6000 CP9 VS6230 CP11 VS7000, VS300 CP8 VS8000 CP12 VS9000 CP12 VS10000 CP10 VS12000 CP14 VS16000 CP16 VS18000 CP18 Maximum Memory Supported -- up to 2 Gigabytes subject to hardware limitations. VM requires about .5 MB of real memory for the VM control program and its memory structures. (This amount varies with the number of devices in the configuration.) If the real machine size is 64 MB or less, the OPERATOR uses 128 KB of physical memory. If the real machine size is greater than 64 MB, 1 MB of physical memory is allocated to the OPERATOR. In addition, the real machine must be configured with enough memory to support the desired number of virtual machines. If the VM CPU microcode is not capable of VSE (pre-7.50) translation architecture, the operator virtual machine is non-pageable and occupies 1 MB of physical memory. The VM release series 1.02 is still maintained for use on CP4 and CP7 based machines. Version 1.02 will no longer be supported after December 31, 1999 in complience with the published support policy regarding CPUs that are not Y2K complient. ______________________________________________________________________________ Hardware and Software Requirements 2-2 CHAPTER 2 HARDWARE AND SOFTWARE REQUIREMENTS (continued) 2.3 Software Requirements The current microcode versions recommended for the best performance in a VS/VM environment are: VSXM/VSE 24/26-bit 24-bit only operation operation operation CP8-based CPU 8.82.65* 8.72.64 8.72.63 machines FPU 8.83.65* 8.73.64 8.73.63 CP9-based CPU N/A N/A 9.72.19 machines @MCRCU@ 1.07.02 1.07.02 1.07.02 CP10-based CPU N/A 10.72.10 10.72.09 machines CP11-based CPU 09.83.13 N/A N/A machines @MCRCU@ 1.07.02 1.07.02 1.07.02 CP12-based CPU 12.82.14 12.72.12 12.72.11 machines VS12000 CPU 10.83.07 10.73.02 N/A model 550 CP14-based CPU 14.82.07 N/A N/A machines CP16-based CPU 16.82.00 N/A N/A machines CP18-based CPU 18.82.02 N/A N/A machines *8.82.65 amd 8.83.65 are VSXM only Device microcodes @4230INX 07.02.15 @4250IMG 07.10.00 @4250INX 07.02.15 @2256MWS 07.10.00 @4230MWS 07.10.00 @MC50V67 02.00.05 @23V95TX 02.10.11 @23V97W 05.07.30 (32/64 devices) 55.07.30 (64/128 devices) @23V96RW 01.07.03 @MC4250 07.03.04 @MC4205 07.00.02 @MC4230 07.10.00 @MC4245 07.10.00 ______________________________________________________________________________ Hardware and Software Requirements 2-3 @MC2266S 05.01.03 @MC2266C 05.01.05 @4245MWS 07.10.00 @23V98 03.05.02 @23V95KN 02.05.03 @70V98E 03.04.44 @70V68 03.04.00 @70V68EW 01.01.00 @70V67 01.00.09 (64/128 devices) 51.00.09 (128/256 devices) @50V98 01.02.04 @SB50861 01.02.03 @50V97W 02.00.05 @MC2246C 07.00.04 @MC2246S 07.00.01 ______________________________________________________________________________ Hardware and Software Requirements 2-4 CHAPTER 3 CORRECTED PROBLEMS 3.1 Introduction This chapter describes the problems corrected in the VS/VM Operating System since the last release. 3.2 Problems Corrected If a virtual disk existed in more than one extent and a multi-block IO was attempted to it, the length field of the IOCW was incorrectly calculated. The resulting IOSW reported an error. If a VM file (eg: SYSSTART in @VMDSK) existed in exactly thirteen extents, VM would crash if opened for input. ______________________________________________________________________________ Corrected Problems 3-2 3.3 VS/VM Problems Open If virtual workstations on a real 50V97W serial controller are disconnected and reconnected using the VM commands, they will no longer work properly. This problem is a fault in the 50V97W microcode. CHAPTER 4 RESTRICTIONS AND SPECIAL CONSIDERATIONS 4.1 Introduction This chapter lists the restrictions and special considerations in Release 02.05.00 of the VS/VM Operating System. 4.2 Architectural Considerations If the OS is IPLed in native mode on a machine with 26-bit VM microcode the microcode will not allow 26-bit architecture to be enabled. The OS will run in 24-bit mode. Only a VSXM version of the VS/OS may be IPLed native on a CPU which is running a Version 8 VM CPU microcode. 4.3 Virtual Disks VS/OS virtual disks must now be REFORMATed using DISKINIT after they are created by VDINIT. VS type VTOCs on virtual disks created by VDINIT may not be compatible with newer OS versions. REFORMAT, RELABEL, and VERIFY are the only DISKINIT functions that can be safely used on virtual disks used by newer OS versions. DISKINIT in newer OS versions will enforce this restriction. Users with older versions of DISKINIT can only use the RELABEL function and must enforce this restriction manually. Virtual disk support was introduced in VS/OS version 7.21.05 with Device Support Package 3.70 and VS/OS version 7.30.04 with Device Support Package 4.30. Virtual machines must be IPL'd from a VIOP (as opposed to an IOP connected in real IOP mode). VM COPY and FSCOPY are designed to copy only consecutive files. ______________________________________________________________________________ Restrictions and Special Considerations 4-2 CHAPTER 4 RESTRICTIONS AND SPECIAL CONSIDERATIONS (continued) 4.4 Workstations Serial IOC microcode (@23V97W) version 05.07.xx has reduced device support capability. This version of IOC microcode supports a maximum of 32 physical devices and 64 logical devices. Version 55.07.xx of IOC microcode supports the full 64 physical/128 logical device capability of the hardware. VS/VM users who must upgrade to the 55.07.xx version of serial IOC microcode may obtain the 55.07.xx version free of charge. PC users connected to MWS type virtual devices should specify the /J switch to the WLOC program. Without this switch, WLOC may fail to connect to the VS after initial power on of the PC. RLOGON and WP can not be run from workstations connected to a VWS virtual device. WACS and 4600S/D type devices are not supported in shared workstation mode (MWS, VWS, INIXWS, IWS). Only ASYNCH RDEVs or VWS may be connected to virtual RCU ports 0 through 3. VWS is allowed because VM workstation 0 must be connected through VWS. 4.5 VM Debugger If the VM debugger and the OS debugger set traps at the same time, the OS traps will not be taken. Debugging does not work if a native VS/OS is IPLed on a real machine running VM microcode. 4.6 Removable Drives and Virtual Disks It is risky to put virtual disks on removable drives, because the VS operating system does not know of the existence of these virtual disks or their connection status. The VS operator seeing no open files on the volume dismounts it and removes it, and the connection to the virtual disks is broken. VM attempts to recover from this by asking that the drive be replaced. Depending on circumstances, it is not always successful. The problem becomes even more severe on controllers that do write caching. Currently, just one of these exists, the 70V68EW. Since there is no way of knowing if all blocks have been written prior to removing a drive, disk corruption can occur. ______________________________________________________________________________ Restrictions and Special Considerations 4-3 CHAPTER 4 RESTRICTIONS AND SPECIAL CONSIDERATIONS (continued) VS operating systems newer than (not including) 7.53.01 issue a command to the disk controller to flush its cache prior to dismounting a drive. This is currently the only synchronization mechanism for the 70V68EW controller. If you must define virtual disks on a removable drive on this controller, it is highly recommended that the last operation before physically removing the disk be a dismount of the physical disk (plug 0) from the VS operator console using operating system greater than 7.53.01. Future releases of VM may remove this requirement. ______________________________________________________________________________ Restrictions and Special Considerations 4-4 CHAPTER 5 SPECIAL CONDITIONS 5.1 Introduction This chapter describes the special conditions that you may encounter when using VS/VM 02.05.00. Procedures are provided to circumvent the problems that these special conditions can cause. 5.2 Known Anomalies Workstation screen output can be corrupted on the nondisplayed windows of a shared workstation when non-DP workstation microcode is in use (e.g., WP, 3270 emulation, etc). As a precautionary measure, before running such applications, cause all other windows to enter the command processor by pressing the HELP key. When the 50V67 IOC is connected in RIOP mode, the IOC loading assumptions in the VS/OS can interact with the VM IOC handling to cause system crashes when certain configuration control operations are performed. It is recommended that this controller be connected in VIOP mode to avoid this problem. The LIST PORT RIOP command displays the DEFINEd devices in definition order. This does not necessarily reflect the defined port. Users are strongly urged to use the LIST RDEV command to determine the port connections of RDEVs. VS/VM allows the definition of a TAPE RDEV on a 70V67 controller although this configuration is not supported on the real hardware. ______________________________________________________________________________ Special Conditions 5-2 CHAPTER 6 MEDIA CONTENTS 6.1 Introduction This chapter lists the files contained on the distribution diskette and their sizes in 2048-byte blocks. 6.2 Distribution Diskette VOLUME = VM2500 LIBRARY = VM020500 Protection Blocks Module Version Class Allocated Description CP 02.05.00 # 90 VM Kernel VM 02.05.00 # 75 VM operator application OPERATOR 02.05.00 # 69 VM standalone operator FSCOPY 02.05.00 # 6 VS to VM file copy utility VDINIT 02.05.00 # 8 Virtual disk creation utility VMSYSGEN 02.05.00 # 11 VM SYSSTART creation utility INSTALL 02.05.00 # 5 Installation utility UPGRADE 02.05.00 # 3 Version upgrade utility COPYMC # 3 Microcode copy procedure COPYPROG # 1 Utility copy procedure RETURNCP # 1 Utility used by INSTALL MONITOR 02.05.00 # 6 Performance monitor TSTVMPA # 3 VMPERF sample assembler pgm TSTVMPC # 2 VMPERF sample C program TSTVMIPC # 4 VMIPC sample assembler pgm VMOPTS # 6 Procedure to set VM options ______________________________________________________________________________ Media Contents 6-2 CHAPTER 6 MEDIA CONTENTS 6.2 Distribution Diskette (continued) LIBRARY = @MACLIB@ VMIPCBOX # 2 VM/IPC mailbox DSECT VMIPC # 3 VM/IPC macro interface VMPA # 1 VMPERF assembler DSECT VMPC # 1 VMPERF C include file LIBRARY = VSSUBS VMIPCSUB # 1 VM/IPC assembler routine VMPERF # 2 VM performance data API LIBRARY = GEN2SBI INSTALL # 4 GENEDIT support for a GENOPTS # 1 Second SBI in the VM Windows Application Total blocks required 308 ______________________________________________________________________________ Media Contents 6-3 CHAPTER 7 INSTALLATION INSTRUCTIONS 7.1 Introduction This chapter describes the procedures to use when - installing VS/VM on your system for the first time - upgrading your version of VS/VM to a new release - returning to a native VS/OS installation 7.2 New Installation Follow these steps to install VM for the first time. 7.2.1 Restore the Distribution Materials The distribution software volume should be restored to what is to be the VS/VM IPL volume. Do not rename any files or libraries. Installation will require about four megabytes of disk space. Although not required, the new IPL volume should be initialized with a dump slot of one megabyte. In the event of a failure of the VM operating system, a diagnostic dump will be recorded there. If you wish to use the VM Windows Application to maintain your VM configuration, use the SETUP.EXE on the enclosed distribution media to install the software on your PC running Microsoft Windows 3.1. Execute the application and refer to the Help Text to determine if you will use the application to maintain your VM configuration. 7.2.2 Run the INSTALL Utility The INSTALL utility provided in the release library will do everything necessary to install VM for the first time. ______________________________________________________________________________ Installation Instructions 7-2 CHAPTER 7 INSTALLATION INSTRUCTIONS (continued) 7.2.2 Run the Install Utility (continued) Run INSTALL in VM020500 on the VS/VM IPL volume. The utility will invoke the VMSYSGEN utility which will issue a GETPARM to prompt for the following installation dependent information: VOLIN= LIBIN= FILEIN= Identifies a VSOS configuration file that describes your system. The default will be the configuration file that was used for the current IPL. Ensure that the specified configuration file is one that defines the full physical system configuration, and will be the one that is used during the primary virtual machine (PVM) IPL. PVMSIZE= Enter the memory size to be allocated to the PVM virtual machine in Kbytes. The default is 1024K. Compute the PVM size by allowing 512K for the VS/VM kernel plus 128K (real machine 64M or less) or 1024K (real machine greater than 64M) for the OPERATOR and discounting for other virtual machines that will be run concurrently. For example, if the physical machine size is 8 megabytes (8192K) and one additional virtual machine running IN/ix will be created later with 1.5 megabytes (1536K): 8192K Physical machine size - 640K VS/VM CP Memory requirement and OPERATOR -1536K To be used for VS IN/ix 6026K Memory available for PVM If the physical machine size is 96 megabytes (98304K) and if one additional virtual machine running VS/OS will be created later with 32 megabytes (32768K), then use the following example: 98304K Physical machine size - 1536K VS/VM CP Memory requirement and OPERATOR -32768K To be used for SVM 64000K Memory available for PVM IPLPDA= Virtual physical device address (PDA) of the disk containing the VS/OS for the PVM. Table 1 in section 7.2.3 lists the PDAs for 30 IOCs. The last digit specifies the device number on the IOC in question. For example, device number 0 on IOC 1 (VS7310) is specified as PDA 2000, device number 3 on IOC 1 as PDA 2003. ______________________________________________________________________________ Installation Instructions 7-3 CHAPTER 7 INSTALLATION INSTRUCTIONS (continued) 7.2.2 Run the Install Utility (continued) For CP9 and CP11 installations, the IPLPDA is derived differently if the IPL disk resides on the virtual RCU SCSI chain. Table 2 in section 7.2.3 specifies IPL PDAs for the seven SCSI devices depending on the virtual RCU port that the IPL disk is connected to. Note that the "x" in the PDA entry will be a 0 if workstation 0 is a serial workstation (i.e. 4230) in PVM's virtual configuration; it will be an 8 if workstation 0 is an async workstation connected to the RCU. Refer to the tables on the following page for assistance in determining the proper PDA. Accept the default or enter new values for VOLOUT, LIBOUT and FILEOUT specification. These values will be used to create the VM startup file. Press ENTER to submit the GETPARM input. A screen that prompts for the size of the @VMDSK virtual disk will be displayed. The default values are adequate for most VM installations. If you plan to create a large number of VM procedures and copy them to @VMDSK for use by the standalone operator, you may wish to increase the size. Press ENTER to submit the GETPARM input. The INSTALL utility should run to completion. ______________________________________________________________________________ Installation Instructions 7-4 CHAPTER 7 INSTALLATION INSTRUCTIONS (continued) 7.2.3 Physical Device Address (PDA) Table Table 1 CP9 CP8/CP10/CP12/ CP11 CP14/CP16 IOC number SBI/IOC number PDA 0 1 / 1 200x 1 1 / 2 240x 2 1 / 3 280x 3 1 / 4 2C0x 4 1 / 5 300x 5 1 / 6 340x 6 1 / 7 380x 7 1 / 8 3C0x 8 1 / 9 400x 9 1 / 10 440x 10 1 / 11 480x 11 1 / 12 4C0x 12 1 / 13 500x 13 1 / 14 540x 14 1 / 15 580x 15 5C0x 16 2 / 1 600x 17 2 / 2 640x 18 2 / 3 680x 19 2 / 4 6C0x 2 / 5 700x 2 / 6 740x 2 / 7 780x 2 / 8 7C0x 2 / 9 800x 2 / 10 840x 2 / 11 880x 2 / 12 8C0x 2 / 13 900x 2 / 14 940x 2 / 15 980x ______________________________________________________________________________ Installation Instructions 7-5 CHAPTER 7 INSTALLATION INSTRUCTIONS (continued) 7.2.3 Physical Device Address (PDA) Table (continued) Table 2 Virt. RCU port Real RCU target PDA 11 6 2x30 10 5 2x34 9 4 2x38 8 3 2x3C 7 2 2x40 6 1 2x44 5 0 2x48 ______________________________________________________________________________ Installation Instructions 7-6 CHAPTER 7 INSTALLATION INSTRUCTIONS (continued) 7.2.4 Install IPLTEXT If you are not running VS/OS 7.50, skip this section and go on to IPL the VM System. Do not install a version 8 CPU microcode. If VS/OS 7.50 is not currently installed, edit the startup file that was created by the VM Install procedure above. Add the architecture option, VSXM, to the end of the DEFINE VM command line. Use FSCOPY to copy this file to @VMDSK in @VMDISK@ on your VM IPL volume. Install VS/OS 7.50 and relabel the VS/OS system volume. Install new IPLTEXT by using the 7.50 version of DISKINIT to RELABEL the VM IPL volume. Load the new version 8 CPU microcode appropriate for your CP type. 7.2.5 IPL the VM System If you have a CP9 or CP11 based machine, make sure that the CPU microcode, the boot, and diagnostic files exist in @SYSTEM@ on the VM IPL volume. Ensure that the required version of CPU microcode is loaded and INIT (CP9/CP11) or RESET (CP8/CP10/CP12) the system. After a short wait, workstation 0 will come up with the VM LOGO screen. If the RCU date and time on a CP9/CP11 or the SCU date and time on a CP8/10/12/14/16 machine passes minimum validity checks, the date and time will be set automatically by VM. If the date and time fails the validity test, you will be asked to enter them. If you wish to change the clock after VS/VM is up, you must do it through the SCU or RCU, and re-IPL. The operator screen will display a list of the virtual machines that currently exist. At this time, only the OPERATOR virtual machine that is controlling the console exists (created by VM during initialization). The cursor will be positioned to the command line. Enter the command: PERFORM SYSSTART (or the name of the startup file entered in the INSTALL process) That procedure will run for a moment and, upon completion, the operator screen will show a new virtual machine called PVM in addition to the OPERATOR virtual machine. The PVM virtual machine is now IPLing. ______________________________________________________________________________ Installation Instructions 7-7 CHAPTER 7 INSTALLATION INSTRUCTIONS (continued) 7.2.5 IPL the VM System (continued) The VM operator console doubles as workstation zero for the PVM virtual machine. It is switched between VM console service and VS Workstation 0 service by pressing the HELP key twice in rapid succession. Do this now to switch to the VS Workstation 0. The alternate screen is initialized with a WANG VM image until the VS operating system writes the configuration prompt. Respond to the configuration prompt in the usual manner. The PVM system will continue to IPL and be available just as it was before VM installation. 7.3 VM Version Upgrade Follow these steps to upgrade your current VM Release. 7.3.1 Restore Distribution Materials Restore the distribution volume to the VS/VM IPL volume. 7.3.2 Run the UPGRADE Utility The software can be upgraded on the current IPL volume. This practice, however, is discouraged because failure could render the disk unable to IPL. Run UPGRADE in VM020500 on the VS/VM IPL volume. The utility will install the new CP, the new OPERATOR, and the new utilities. VMSYSGEN will not be rerun, and device microcode files will not be recopied. If microcode files need to be updated, use the COPY command within the VM utility to copy the files into @VMDSK. 7.3.4 IPL the System IPL the VM system exactly as you did prior to the upgrade. 7.4 Suspending the VS/VM Operating System Temporarily If at some point you decide not to run VS/VM on your system, follow these instructions: ______________________________________________________________________________ Installation Instructions 7-8 CHAPTER 7 INSTALLATION INSTRUCTIONS (continued) 7.4 Suspending the VS/VM Operating System Temporarily (continued) 1. Rename the nucleus file. The VS/VM Operating System nucleus file is @SYSVMx@ or @SYSVMxx, where x stands for the CP type (e.g., on a CP8 system the nucleus file name is @SYSVM8@ and on a CP12 system the nucleus file name is @SYSVM12). Rename this nucleus file, residing in library @SYSTEM@, to @DONTUSE or something different from the original file name of @SYSVMxx. The file is now ignored during IPL. 2. IPL the system using the original CPU microcode. NOTE: If you are no longer running VS/VM, make sure to refer to the customer software release notice for your operating system for the appropriate hardware and software requirements. ______________________________________________________________________________ Installation Instructions 7-9 CHAPTER 8 UPDATES TO DOCUMENTATION 8.1 Introduction This chapter contains updates to the documentation beginning with Release 2.04.00 of VS/VM. The following sections provide new information concerning documentation changes made since the User's Guide was published. Within this chapter, modifications to existing documentation use the VS/VM User's Guide section numbers to facilitate updating the User's Guide. 8.2 Command Updates This release of VS/VM contains the following updates to the VS/VM User's Guide: Table of Contents 6.2 Add LASTPAGE to the list of display commands. 6.5 Add DELAY to the list of procedure commands. 6.14.10 DEFINE RDEV - remove the disclaimer of 50V68 support. 6.14.14.1 New command DELAY. 6.14.23.1 New command LASTPAGE. 6.14.24 Add @SYSTEM@ to the search order for the LINKed program. 6.14.33.3 Add the $START$ procedure for automatic startup. 6.14.36.1 Add the current location counter to the SEARCH command. 6.14.42 Add the warning message to the STOP command. Appendix A Add CP16 to the list of high-end CPUs. Include 50V68 and 50V68E in the list of low-end controllers supported in VIOP mode. Add CP18 to list of high-end CPUs (Version 2.05.00). Appendix E New section to specify SCSI VIOP connections. ______________________________________________________________________________ Updates to Documentation 8-2 CHAPTER 8 UPDATES TO DOCUMENTATION (continued) 8.3 Sections Updated this Release This section contains pages of the User's Guide that have changed due to enhancements new to this (and previous) release(s). The following pages set forth the modified sections of the VS/VM User's Guide. They are identified by the section numbers and headings used in the Guide. To print this section only, print pages 28 through 51 of this SRN. ______________________________________________________________________________ Updates to Documentation 8-3 CONTENTS PREFACE CHAPTER 1 WANG VS/VM SOFTWARE 1.1 Introduction .......................................... 1-1 1.2 VS/VM Operating System ................................ 1-1 @VMDISK@ ............................................ 1-2 @VMPROG@ ............................................ 1-2 1.3 PVM Operating System .................................. 1-2 1.4 Multiworkstations ..................................... 1-2 1.5 Virtual RSF ........................................... 1-3 CHAPTER 2 VIRTUAL MACHINE CONCEPTS 2.1 Overview .............................................. 2-1 2.2 Control Program and Guest Operating Systems ........... 2-1 2.3 Virtual Machine (VM) .................................. 2-1 2.4 Definition of Virtual Machines ........................ 2-2 2.5 Operator Program ...................................... 2-2 2.6 VM/IPC ................................................ 2-3 2.7 VM File System ........................................ 2-3 2.8 VM Security ........................................... 2-3 2.9 Primary and Secondary Virtual Machines ................ 2-3 2.10 Virtual I/O ........................................... 2-4 2.11 Memory Management ..................................... 2-4 2.12 Configuration Directives .............................. 2-5 2.13 Start-Up Files ........................................ 2-5 2.14 SYSSTART .............................................. 2-6 2.15 FSCOPY ................................................ 2-6 2.16 Advantages of Virtual Machines ........................ 2-7 2.17 Monitoring Performance ................................ 2-9 2 CONTENTS (continued) CHAPTER 3 IPL PROCEDURE 3.1 Overview .............................................. 3-1 3.2 IPL Procedure ......................................... 3-1 3.3 VS/VM System Crash and Memory Dumps ................... 3-4 General Information ................................. 3-4 Initiating a Dump ................................... 3-4 Control Mode Messages ............................... 3-4 Retrieving the Dump ................................. 3-5 REAL.MACHINE Dumps .................................. 3-5 Halt Codes .......................................... 3-6 CHAPTER 4 CONFIGURING VIRTUAL MACHINES 4.1 Overview .............................................. 4-1 4.2 Configuration Directives .............................. 4-2 4.3 Ways of Allocating I/O Resources ...................... 4-2 4.4 Real IOP Mode ......................................... 4-3 Configuration Directives for Real IOP Mode .......... 4-4 Defining Real Resources ............................. 4-6 4.5 Shared IOP Mode ....................................... 4-6 Virtual IOPs ........................................ 4-7 Configuration Directives for Sharing IOPs ........... 4-8 Order of Configuration Directives ................... 4-10 4.6 Shared Device Mode (Disks) ............................ 4-10 Virtual Disk Handler ................................ 4-12 Configuration Directives for Shared Disk Drives ..... 4-13 Logically Mounting Virtual Disks .................... 4-14 Using the MOUNT Command ............................. 4-15 Specifying Virtual Disks ............................ 4-17 Plugs and Ports ..................................... 4-17 4.7 Shared Device Mode (Workstations) ..................... 4-18 Virtual Workstation Handlers ........................ 4-19 Configuration Directives for Shared Workstations .... 4-20 4.8 Virtual RSF Mode ...................................... 4-22 Real and Virtual RSF Modes .......................... 4-22 Configuration Directives for RSF Modes .............. 4-22 4.9 VS 5000 and VS/VM ..................................... 4-23 Workstation Zero on VS 5000 Systems ................. 4-23 Virtual RCU Support ................................. 4-24 CHAPTER 5 STARTING UP SECONDARY VIRTUAL MACHINES 5.1 Introduction .......................................... 5-1 5.2 VM IPL Pack ........................................... 5-1 3 CONTENTS (continued) 5.3 VM Configuration File ................................. 5-2 Configuring Virtual Disks ........................... 5-2 Configuring Shared Workstations ..................... 5-3 Configuring the Operator's Console .................. 5-3 Configuring the IPL Drive ........................... 5-4 5.4 Start-Up Commands ..................................... 5-4 Listing I/O Resources ............................... 5-4 Sample Directives ................................... 5-4 The DEFINE VM Command ............................... 5-5 5.5 Entering Start-Up Commands ............................ 5-6 Running the Operator Program ........................ 5-6 Procedure Files ..................................... 5-6 Executing Procedure Files ........................... 5-7 Time of Execution ................................... 5-7 5.6 UNDEFINING Virtual Machines ........................... 5-8 CHAPTER 6 OPERATOR PROGRAM COMMANDS 6.1 Introduction .......................................... 6-1 6.2 Display Commands ...................................... 6-1 6.3 Resource Control Commands ............................. 6-2 6.4 Debugger Commands ..................................... 6-2 Sequence of Debugger Commands ....................... 6-3 Virtual, Physical, Real, and Absolute Memory ........ 6-3 6.5 Procedure Commands .................................... 6-3 6.6 PF Key Commands ....................................... 6-4 6.7 Miscellaneous Commands ................................ 6-4 6.8 Conventions of Notation ............................... 6-5 6.9 Specifying Numerical Values ........................... 6-5 6.10 Expressions ........................................... 6-6 Operators ........................................... 6-6 Operands ............................................ 6-6 Results ............................................. 6-6 Pseudo End-of-line Character .......................... 6-6 Variables ............................................. 6-6 Variable Names ...................................... 6-6 Variable Substitution ............................... 6-6 Variable Commands ................................... 6-6 Local Variables ..................................... 6-6 Global Variables .................................... 6-6 6.11 Naming Resources ...................................... 6-6 6.12 Specifying File Names ................................. 6-7 6.13 Control of Displays ................................... 6-8 6.14 Command Descriptions .................................. 6-9 ACK -- Acknowledge Message .......................... 6-9 ACQUIRE -- Acquire Memory ........................... 6-10 ALTER -- Alter Memory ............................... 6-11 ALTER -- Alter Register ............................. 6-14 4 CONTENTS (continued) CANCEL -- Cancel Procedure .......................... 6-15 CATALOG -- Make Virtual Disks Available ............. 6-15 CONNECT -- Connect Resources ........................ 6-16 CONTINUE -- Continue Execution ...................... 6-18 COPY -- Copy Files .................................. 6-19 CREATE .............................................. 6-22 DEBUG -- Debug Virtual Machine ...................... 6-23 DEFINE RDEV -- Define Real Device ................... 6-24 DEFINE RIOP -- Define Real IOP ...................... 6-25 DEFINE VDEV -- Define Virtual Device Handler ........ 6-26 DEFINE VIOP -- Define Virtual VIOP .................. 6-27 DEFINE VM -- Define Virtual Machine ................. 6-28 DELAY -- Wait Within a Procedure .................... 6-28 DELETE -- Delete a VM Virtual File .................. 6-29 DISASM -- Disassemble Object Code ................... 6-29 DISCONNECT -- Disconnect Resource ................... 6-30 DISMOUNT -- Dismount Disk .......................... 6-31 Display Memory ...................................... 6-32 DUMP -- Dump Physical Memory ........................ 6-33 ENTEREXIT -- Enter/Exit Control Mode ................ 6-34 Evaluate ............................................ 6-35 FINDCMD -- Locate a Previously Entered Command ...... 6-35 FP, CR, SCR -- Display Registers .................... 6-36 HALT -- Halt Virtual Machine ........................ 6-37 INIT -- Initialize Virtual Machine .................. 6-38 IPL -- IPL Virtual Machine .......................... 6-39 LASTPAGE -- Go to the End of a Display .............. 6-40 LINK -- Link to Program ............................. 6-41 LIST -- List Resource ............................... 6-42 LIST DIR -- List Directory .......................... 6-44 LIST EVENTS -- List Events .......................... 6-45 LIST FILE -- List File .............................. 6-47 LIST HISTORY -- List the Command History ............ 6-48 LIST PFKEY -- List PF Key Values .................... 6-49 LIST PLUG/LIST PORT -- List Connections ............. 6-50 LIST VAR -- List Variables .......................... 6-54 LOAD IOC -- Recover IOC ............................. 6-54 MON -- Monitor Performance .......................... 6-54 MOUNT -- Mount Disk ................................. 6-55 NEXTCMD -- Return the Oldest Command ................ 6-55 PAUSE -- Suspend Execution .......................... 6-56 PERFORM -- Perform Procedure ........................ 6-57 PERFORM Subcommand DO -- Loop Within a Procedure .... 6-60 PERFORM Subcommand IF -- Conditional Execution Within a Procedure ................................ 6-61 PERFORM STARTUP FILE Subcommand ..................... 6-63 PREVCMD -- Return the Last Command .................. 6-63 PRINT -- Print ...................................... 6-64 RECORD -- Record Commands ........................... 6-66 RUN -- Run Virtual Machine .......................... 6-68 SEARCH -- Search Memory for a Given Value ........... 6-69 5 CONTENTS (continued) SET CHANFREQ -- Set Channel Frequency ............... 6-71 SET CHARSET -- Set Character Set .................... 6-72 SET PATH -- Set Default Path ........................ 6-73 SET PFKEY -- Set PF Key Value ....................... 6-75 SET PRIORITY -- Set Dispatching Frequency ........... 6-75 SET REFRESH -- Set Refresh Timer .................... 6-76 SET STAT1 -- Set Status Line 1 ...................... 6-77 SET STAT2 -- Set Status Line 2 ...................... 6-78 SET VAR -- Define/Alter Variable Value .............. 6-78 SHOW PFKEY -- Show Single PF Key Value .............. 6-79 STATS -- List Status ................................ 6-80 STEP -- Step a Single Instruction ................... 6-80 STOP -- Stop Operator Program ....................... 6-81 SUPERCANCEL -- Cancel All Procedures ................ 6-82 TRANSOFF/TRANSON -- Disable/Enable Address Translation ....................................... 6-83 TRAP GR -- General Register Trap on Condition ....... 6-83 UNDEFINE -- Undefine Resource ....................... 6-84 UNSET VAR -- Undefine Variable ...................... 6-84 VERSION -- Display Microcode Version Numbers ........ 6-85 VMPRIV -- Set VM Privileges ......................... 6-86 CHAPTER 7 DEFINING VIRTUAL DISKS 7.1 Introduction .......................................... 7-1 7.2 VDINIT Menus .......................................... 7-1 7.3 Starting VDINIT ....................................... 7-2 7.4 FUNCTION GETPARM ...................................... 7-2 7.5 CREATE and REFORMAT GETPARMS .......................... 7-3 7.6 RELABEL GETPARM ....................................... 7-4 7.7 COPY GETPARM .......................................... 7-4 7.8 SCRATCH GETPARM ....................................... 7-5 7.9 PAGEPOOL GETPARM ...................................... 7-5 7.10 Accessing Virtual Disks ............................... 7-5 CHAPTER 8 VIRTUAL DEVICE SPECIFICATIONS 8.1 Introduction .......................................... 8-1 8.2 Virtual Workstation (VWS) ............................. 8-1 Ports and Plugs ..................................... 8-2 User Benefits ....................................... 8-2 Restrictions ........................................ 8-2 Sample Configuration Directives ..................... 8-2 8.3 Multiworkstation (MWS) ................................ 8-2 Ports and Plugs ..................................... 8-3 6 CONTENTS (continued) User Benefits ....................................... 8-3 Restrictions ........................................ 8-3 Sample Configuration Directives ..................... 8-3 8.4 IN/ix Workstation (INIXWS) ............................ 8-4 Ports and Plugs ..................................... 8-4 User Benefits ....................................... 8-4 Restrictions ........................................ 8-4 Sample Configuration Directives ..................... 8-4 8.5 Virtual Disk Handler (VDISK) .......................... 8-4 Ports and Plugs ..................................... 8-5 User Benefits ....................................... 8-5 Restrictions ........................................ 8-5 Sample Configuration Directives ..................... 8-5 8.6 Virtual Disk Cache (WORKCACHE) ........................ 8-6 Ports and Plugs ..................................... 8-6 User Benefits ....................................... 8-6 Restrictions ........................................ 8-6 Sample Configuration Directives ..................... 8-6 Possible EVENT Messages ............................. 8-6 8.7 VTOC VSCache .......................................... 8-7 Ports and Plugs ..................................... 8-7 User Benefits ....................................... 8-7 Restrictions ........................................ 8-7 Sample Configuration Directives ..................... 8-8 8.8 Multi-Plug ............................................ 8-8 Ports and Plugs ..................................... 8-8 User Benefits ....................................... 8-8 Restrictions ........................................ 8-8 Sample Configuration Directives ..................... 8-9 8.9 Virtual RSF ........................................... 8-9 Ports and Plugs ..................................... 8-9 User Benefits ....................................... 8-9 Restrictions ........................................ 8-10 Sample Configuration Directives ..................... 8-10 8.10 Image MultiWorkstation ................................ 8-11 Ports and Plugs ..................................... 8-11 User Benefits ....................................... 8-11 Restrictions ........................................ 8-11 Sample Configuration Directives ..................... 8-12 CHAPTER 9 VIRTUAL MACHINE INTER PROCESS COMMUNICATION (VM/IPC) 9.1 Introduction .......................................... 9-1 9.2 Establishing a Mailbox ................................ 9-2 9.3 Registering Mailboxes ................................. 9-2 9.4 Connecting Mailbox Sessions ........................... 9-2 7 CONTENTS (continued) 9.5 Replying Mailboxes .................................... 9-2 9.6 Sending a Message ..................................... 9-3 9.7 Receiving a Message ................................... 9-3 9.8 Reading a Message ..................................... 9-4 9.9 Establishing Message Priorities ....................... 9-4 9.10 Synchronizing Messages ................................ 9-5 9.11 Invoking the VMIPC Mailbox Service .................... 9-5 9.12 Invoking the VMIPCBOX Macro ........................... 9-8 9.13 Detailing the VMIPCBOX Macro .......................... 9-10 9.14 Service Codes ......................................... 9-12 DEFINE .............................................. 9-13 UNDEFINE ............................................ 9-13 REGISTER ............................................ 9-13 UNREGISTER .......................................... 9-14 CONNECT ............................................. 9-14 DISCONNECT .......................................... 9-14 ACCEPT .............................................. 9-14 DECLINE ............................................. 9-15 FORWARD ............................................. 9-15 SEND ................................................ 9-15 RECEIVE ............................................. 9-16 READ ................................................ 9-16 CHAPTER 10 VMPERF Subroutine Package 10.1 Introduction .......................................... 10-1 10.2 Subroutine Calls ...................................... 10-2 10.3 Data Items ............................................ 10-5 10.4 Errors ................................................ 10-7 10.5 Sample Assembler Program .............................. 10-8 10.6 Sample C Program ...................................... 10-11 10.7 Assembler Copy File ................................... 10-13 10.8 C Include File ........................................ 10-14 CHAPTER 11 VMOPTS Control Initialization Parameters 11.1 Introduction .......................................... 11-1 11.2 Control Tracing ....................................... 11-1 11.3 Control Operator Memory ............................... 11-2 11.4 Control Debugging ..................................... 11-2 APPENDIX A I/O CONTROLLERS SUPPORTED BY VS/VM A.1 Overview .............................................. A-1 8 CONTENTS (continued) Order Number and Descriptive Name ................... A-1 Model Number ........................................ A-1 Availability as a Virtual IOP ......................... A-2 Type ................................................ A-2 A.2 CP4 IOPs Supported by VS/VM ........................... A-2 A.3 CP7 DAs Supported by VS/VM ............................ A-4 A.4 High-end-CPU IOCs Supported by VS/VM .................. A-5 A.5 CP9/CP11 IOCs Supported by VS/VM ...................... A-6 APPENDIX B EVENT IDENTIFIERS B.1 Overview .............................................. B-1 B.2 Event Logging (EVE) Events ............................ B-1 B.3 I/O Load (IOL) Events ................................. B-2 B.4 Physical I/O (PIO) Events ............................. B-4 B.5 System (SYS) Events ................................... B-6 B.6 Virtual I/O (VIO) Events .............................. B-7 B.7 Virtual Resource Manager (VRM) Events ................. B-9 APPENDIX C CONFIGURING PERIPHERAL BAND DEVICES C.1 Overview .............................................. C-1 C.2 Peripheral Band Devices ............................... C-1 Network Multiplexers ................................ C-2 Manufacturing IDs ................................... C-2 Channels ............................................ C-3 C.3 Configuring P-Band Devices ............................ C-3 C.4 Configuring P-Band Devices in Real IOP Mode ........... C-3 Defining and Connecting a Real IOP .................. C-4 VM Configuration File ............................... C-4 C.5 Configuring P-Band Devices in Shared IOP Mode ......... C-4 Defining the P-Band IOP ............................. C-5 Defining the P-Band Device .......................... C-5 Defining and Connecting VIOPs ....................... C-5 Connecting P-Band Devices ........................... C-6 Listing the IOP and Device .......................... C-6 APPENDIX D WACS DEVICES D.1 Overview .............................................. D-1 D.2 Secondary Virtual Machine Restrictions ................ D-1 APPENDIX E SCSI CONNECTIONS E.1 Overview .............................................. E-1 E.2 70V68 ................................................. E-1 E.3 50V68 ................................................. E-1 9 CHAPTER 6 OPERATOR PROGRAM COMMANDS 6.1 INTRODUCTION This chapter describes the syntax, function, and arguments of commands entered to the OPERATOR program. Commands can be entered interactively or in a procedure file. For information on procedure files, refer to Section 5.5. OPERATOR commands can be grouped into the following functional categories: - Display - Resource Control - Debugger - Procedure - PF key - Miscellaneous Sections 6.2 through 6.7 discuss each of these categories. 6.2 DISPLAY COMMANDS Display commands allow you to view the disposition of resources on a VM system. They provide information necessary for defining and configuring virtual machines. The display commands are LASTPAGE -- Go to the last page of a display LIST -- List resources LIST DIR -- List directory LIST EVENTS -- List events LIST FILE -- List file LIST LVAR/GVAR -- List names and values of variables LIST HISTORY -- List previously entered commands LIST PLUG/PORT -- List connections MON -- Display system CPU and I/O utilization STATS -- List status ______________________________________________________________________________ Operator Program Commands 6-1 The procedure commands are CANCEL -- Cancel Procedure CONTINUE -- Continue Execution DELAY -- Delay Execution PAUSE -- Suspend Execution PERFORM -- Perform Procedure PERFORM Subcommands DO -- Loop within a Procedure IF -- Conditional Execution within a Procedure SET LVAR -- Define or Alter the Value of a Local Variable UNSET LVAR -- Undefine a Local Variable SUPERCANCEL -- Cancel all Procedures The Perform Procedure command initiates execution of a procedure file. The other commands control the consequent execution of the file. 6.6 PF KEY COMMANDS PF key commands set or display the assignment of commands to program function (PF) keys. PF key commands are LIST PFKEY -- List PF Key Values SET PFKEY -- Set PF Key Value SHOW PFKEY -- Show Single PF Key Value The OPERATOR program establishes a set of default assignments that you can list with the LIST PFKEY command. You can make your own assignments with the SET PFKEY command. Once an assignment is made, you can enter a command simply by pressing the associated PF key. When you press a PF key that is assigned to a command, the program concatenates the text of that command with any text that has been entered in the command line area of the screen. For example, if you type <[10] PVM> in the command line area and then press PF21, which by default is assigned to the command LIST PORT, the command LIST PORT[10] PVM is generated. 6.7 MISCELLANEOUS COMMANDS Miscellaneous commands are: ACK -- Acknowledge message ACQUIRE -- Acquire memory COPY -- Copy files DELETE -- Delete a VM file from a VM virtual disk ______________________________________________________________________________ Operator Program Commands 6-4 EVALUATE -- Evaluate the supplied expression or integer FINDCMD -- Locate a string in the command history LINK -- Link to a VS program NEXTCMD -- Retrieve the next command in the command history PREVCMD -- Retrieve the previous command in the command history PRINT -- Generate a VS print file RECORD -- Record commands SET CHARSET -- Set character set SET GVAR -- Define or alter the value of a global variable SET PATH -- Set default path SET REFRESH -- Set refresh timer STOP -- Stop OPERATOR program UNSET GVAR -- Undefine a global variable VERSION -- Display microcode versions VMPRIV -- Enable/disable VM privileges ______________________________________________________________________________ Operator Program Commands 6-4.1 6.14.10 DEFINE RDEV -- Define Real Device Syntax DEFINE RDEV DEFINE RDEV PBAND DEFINE RDEV PBAND1 DEFINE RDEV FIBER APA=xx yy For SCSI devices: DEFINE RDEV DISK TARGET=x LUN=y TAPE ITC Function Defines a real I/O device for the system. Defining a real device is a step in the logical configuration of that device to a virtual machine. Arguments NAME -- Specifies for the device a unique name from one to 16 characters long. Conventional names are as follows, where x denotes the device's real IOP and y denotes its port on that IOP: - WSxy - PRINTERxy - TCxy - DISKxy - TAPExy - ITCxy SCSI devices will use the following convention, where DDDD is the device type (DISK, ITC, or TAPE), x is the RIOP number, y is the SCSI logical unit number, and z is the target. - DDDDxyz MODEL -- Specifies the model, or type, of the real device. Allowable values are DISK, SERDEV, ASYNCH (VS5000 support), ITC, TAPE, PBAND, PBAND1, or FIBER. SERDEV is specified for all devices other than PBAND, PBAND1, and FIBER, attached to a serial IOC. When configuring a 70V67 IOC PBAND devices are located on the first PBAND modem and use the first channel specified in the DEFINE RIOP directive. PBAND1 devices are located on the second PBAND modem and use the second channel specified in the DEFINE RIOP directive. All other serial controllers use PBAND devices and the first channel specified on the DEFINE RIOP directive. ______________________________________________________________________________ Operator Program Commands 6-24 REAL IOP NAME -- Name of the real IOP that supports the real device being defined. The real IOP must have been defined for the system by a previous Define Real IOP command. In order to define PBAND or PBAND1 devices on a serial IOP the corresponding channel must have been specified on the DEFINE RIOP directive. PORT NUMBER -- Specifies the device's port number on the real IOP. NETMUXID -- A factory-supplied identifier. MFGID -- The manufacturing ID (MFGID) is the NETMUX ID followed by the port number enclosed in brackets. Note: The mfgid can also be entered as the sum of the factory-supplied NETMUX ID and number of the port (in the range of 0 to 7) to which the device is cabled. APA -- For FiberWay addressing, the xx is the APA number and yy is the RCS port. TARGET -- For SCSI devices, the SCSI target number. LUN -- For SCSI devices, the SCSI logical unit number. Examples DEFINE RDEV DISK10 DISK RIOP1 0 Define real disk device DISK10 as located on IOC 1, port 0 of the real machine. DEFINE RDEV WS65 SERDEV RIOP6 5 Define real workstation WS65 as a serial device located on IOC 6, port 5 of the real machine. DEFINE RDEV WS73 PBAND RIOP7 MFGID=ABCD000879658978[3] Define a P-Band workstation named WS73 that is located on the fourth port of a NETMUX whose ID is ABCD000879658978 which is communicating with IOC 7. DEFINE RDEV TAPE702 TAPE RIOP7 TARGET=2 LUN=0 Define a SCSI tape drive on RIOP 7 with a target number of 2 and a logical unit number of 0. ______________________________________________________________________________ Operator Program Commands 6-24.1 6.14.14.1 DELAY -- Delay the Execution of a Procedure Syntax DELAY Function Delays the execution of a VM procedure. In a debug procedure this command can be used to wait before checking if some event has occurred. In a startup procedure, you may wish to wait for a couple of seconds after defining VSDISK VDEVs so that the mounting of the disk completes before the CONNECT statements are executed. The DELAY command may be terminated prematurely by pressing RETURN or any PFKEY. Arguments Argument -- Number of hundredths of a second to delay. Usage The command - DELAY .1000 - will cause a procedure to wait for ten seconds before executing the next command in the procedure. _________________________________________________________________________ Operator Program Commands 6-28.2 6.14.23.1 LASTPAGE -- Go to the Last Page of a Display Syntax LASTPAGE Function Causes the workstation to display the last page of the current display. The LASTPAGE command is now assigned to PFKEY .19 by default when the Operator is initialized. Arguments None. Usage Use the LASTPAGE command to go to the end of the workstation display. For example, if the display currently shows the output of the LIST FILE @VMDSK:SYSSTART command, and you wish to see the IPL address for the virtual machine, the LASTPAGE command will position the display at the last page of the SYSSTART file. _________________________________________________________________________ Operator Program Commands 6-40.1 6.14.24 LINK -- Link to Program Syntax LINK program Function Links to the specified program. Upon that program's termination, control returns to the OPERATOR program. Thus, the command allows you to run another program without leaving the OPERATOR program. This command invokes the VS Operating System service LINK, and so can execute only on a VS virtual machine.. Arguments Program -- Specifies the program to be linked. The program can be specified in one of the following forms: - volume.library.file - library.file - file The default volume and library is the VS SET COMMON USAGE CONSTANTS volume RUNVOL (SYSVOL if not set) and RUNLIB (SYSLIB if not set). However, the SET PATH LINK command (see Section 6.14.37.1) can override these defaults. If the program is not found in the default or SET PATH library, the @SYSTEM@ library on the VS/OS system volume is searched for the program. _________________________________________________________________________ Operator Program Commands 6-40 6.14.33.3 Perform STARTUP FILE Subcommand Syntax VM Program: Format 1: ENTER STARTUP PATHNAME=' (STEP) Format 2: ENTER STARTUP PATHNAME='(STEP)(arguments>)' Standalone Operator: Place a VM Procedure file named '$START$' in @VMDSK using FSCOPY. Function Provide a facility by which a startup file may be performed. This allows the user to specify a VM procedure name to perform upon IPLing the real system or upon entering VM from a VS procedure. VM Program: Use format 1 to PERFORM a VS file before giving control to the user. Use format 2 to PERFORM a VM file before giving control to the user. Standalone Operator: When the VM system is IPLed, the Standalone Operator will check for the existence of a file named '$START$' in the VM File System, @VMDSK. If this file is found, it will be PERFORMed as a VM procedure file. If this procedure contains the statement 'PERFORM SYSSTART', the system will come up without operator intervention. The file to be performed (whether VS or VM) must follow the exact same syntax rules for regular procedure files (since these are executed in exactly the same way). If the procedure argument STEP is used, the logon procedure is placed in Step mode just as any other procedure would be. Also, the user may at any time during execution of a startup procedure, press PF32 to place the procedure into STEP mode. Note: The entire volume.library.file or VM vdisk:file MUST be entered in order for the file to be found; i.e., no default values are in effect here. _________________________________________________________________________ Operator Program Commands 6-63 Arguments Volume.library.file -- The name of a VS procedure to perform. This must be in the exact same format as if the command 'PERFORM volume.library.file' were entered in the command line EXCEPT that defaults are not in effect here; i.e., the entire VS pathname must be entered. VM vdisk:file -- The name of a VM procedure to perform. Again, it must be in the exact same format as if the command 'PERFORM VM vdisk:file' were entered in the command line EXCEPT that defaults are not in effect here, so the entire VM pathname must be entered. STEP -- Keyword specifying that the procedure be placed into Step mode. See Section 6.14.33 for details. Arguments -- The list of arguments to be passed to the procedure. See Section 6.14.33 for details. Again, used exactly as if the command were entered in the command line. _________________________________________________________________________ Operator Program Commands 6-63.1 6.14.36.1 SEARCH -- Search Memory for a Given Value Syntax SEARCH (<[length]>) ((P) ) Function Searches memory for the specified argument until finding it, or the end of data range (LOW through HIGH) is reached. If the argument is found, an address display screen pointing to the argument is created, and the SEARCH command remains on the screen to allow further searching. The SEARCH command may be terminated prematurely by pressing PFKEY 1. As the search procedes, the message 'Performing search, press pf1 to cancel.' is displayed above the command line on the workstation. At the end of this message, a counter is displayed. This counter reports the progress of the search in 64 kilobyte increments. The counter is displayed as the hexadecimal address of the current search location. The search is a byte-aligned search (i.e., the specified argument may be found anywhere in memory). Arguments Argument -- Value to be searched for. Can be specified as an expression, hexadecimal string, or a character string. [length] -- The length, in bytes, of the value to be searched for. Allowable values range from one to 256. The default value is the length of the supplied data. LOW -- Address where the search begins. Low defaults to 0 unless displaying an address, whereby LOW defaults to the address plus one byte. Address translation defaults to the TRANSON/TRANSOFF setting (i.e., virtual or physical). Keyword P indicates physical memory. Keyword V indicates virtual memory (P or V refer to both optional addresses LOW and HIGH). HIGH -- Address where the search ends. HIGH defaults to the memory size of the machine (i.e., the highest addressable byte). The address is always the same type (virtual or physical) as the LOW argument. Usage When the optional length argument specifies a field length different from the length of the supplied data, justification and padding take place as follows: _________________________________________________________________________ Operator Program Commands 6-69 Expressions and Hexadecimal Strings -- When the supplied data is smaller than the field length, the data is right justified and padded with zeros on the left. When the data length is greater than the field length, the data is truncated on the left. Character Strings -- When the data length is smaller than the field length, the data is left justified and padded with blanks (X'20'). When the data length is greater than the field length, the data is truncated on the right. _________________________________________________________________________ Operator Program Commands 6-69.1 6.14.42 STOP -- Stop OPERATOR Program Syntax STOP Function When issued to an OPERATOR program running on a VS virtual machine, this command terminates the program and returns the user to the Command Processor screen. When issued to an OPERATOR program running in a pageable virtual machine, such as OPERATOR, this command stops and then restarts the machine. This command is equated to PF key .16 by default. If this command is issued and a debugging session is in progress, the OPERATOR program prompts for confirmation: "Debug in progress. PF16 to exit VM, RETURN to continue." Press PFKEY .16 to execute the STOP command. Press RETURN to continue with the debugging session. _________________________________________________________________________ Operator Program Commands 6-81 A.4 High-end-CPU IOCs SUPPORTED BY VS/VM Table A-3 lists CP8, CP10, CP12, CP14, and CP16 IOCs supported by VS/VM. These controllers are configured to the VS 7000, VS10000, VS 8000, VS12000, and VS16000 series of computers. Table A-3. CP8, CP10, CP12, CP14, and CP16 IOCs Supported by VS/VM Order Model Number Description Number VIOP Type 23V14 RSF I/O Controller 23V14 Yes RSF 23V24 System Image Controller 23V24 No 23V46 64 port Asynch IOC 23V46 No 23V66 LAN Controller 23V66 No 23V67 Universal Serial Controller 23V67 Yes Serial 23V79 911 CIU IOC 23V79 No 23V86 2110 Asynch MLTC IOC 23V86 No 23V95-1 Kennedy Mag Tape IOC 23V95-1 Yes Tape 23V95-2 Telex Mag Tape IOC 23V95-2 Yes Tape 23V96 Multiline TC IOC 23V96 No 23V97W Universal Serial IOC 23V97W Yes Serial 23V98-4 4 port SMD Disk Controller 23V98 Yes Disk 23V98-8 8 port SMD Disk Controller 23V98 Yes Disk 23V98-12 12 port SMD Disk Controller 23V98 Yes Disk 23V98-16 16 port SMD Disk Controller 23V98 Yes Disk 70V14 Fiber Optic RSF I/O Controller 70V14 Yes RSF 70V56 LAN Controller 70V56 No 70V67 High Capacity Serial Controller 70V67 Yes Serial 70V68 External SCSI Controller 70V68 Yes Disk,Tape 70V98-4 Caching Disk Controller 70V98 Yes Disk Note: Because of hardware restrictions, not all of the above controllers are supported on the second System Bus Interface (SBI). ______________________________________________________________________________ I/O Controllers Supported by VS/VM A-5 A.5 CP9/CP11 IOCs SUPPORTED BY VS/VM Table A-4 lists CP9/CP11 IOCs supported by VS/VM. These controllers are configured to the VS 5000 and VS 6000 series of computers. Table A-4. CP9/CP11 IOCs Supported by VS/VM Order Model Number Description Number VIOP Type RCU RCU RCU Yes RCU 50V56A VS to VS Comm IOC 50V56A No 50V56B VS to VS Comm IOC 50V56B No 50V67 Serial 928 IOC 50V67 Yes Serial 50V68 1 Port SCSI IOC 50V68 Yes Disk,Tape 50V68E Caching SCSI IOC 50V68E Yes Disk,Tape 50V76-1 1 Port TC RS232 Async IOC 50V76-1 No 50V96 8 Port TC IOC 50V96 No 50V97W Serial IOC 50V97W Yes Serial 50V98-4 SMD Disk IOC 50V98-4 Yes Disk ______________________________________________________________________________ I/O Controllers Supported by VS/VM A-6 APPENDIX E SCSI CONNECTIONS IN VS/VM E.1 OVERVIEW SCSI IOCs are now supported in virtual IOP mode on both the high-end and low-end machines. These are the 70V68 and 50V68 controllers, respectively. In order for the devices on these controllers to be addressed correctly, they must be connected to the PORT on VIOP that will correspond to the PORT that is expected by GENEDIT. There are arithmetic algorithms to calculate the correct PORT of connection. These algorithms differ for each of the two types of controllers. E.2 70V68 The algorithm for calculating the correct port of connection for devices connected to a 70V68 VIOP is as follows, using the TARGET, PORT, and LUN from GENEDIT: PORT = (LUN * 16) + (PORT * 8) + TARGET For example: TARGET = 1, PORT = 0, LUN = 0 gives PORT = 1; TARGET = 2, PORT = 1, LUN = 0 gives PORT = .10; TARGET = 3, PORT = 1, LUN = 1 gives PORT = .27. A sample connect statement for the third example would be: CONNECT VDISK31B[0] PVMVIOP3[.27] E.3 50V68 The algorithm for calculating the correct port of connection for devices connected to a 50V68 VIOP is as follows, using the TARGET and LUN from GENEDIT: PORT = (((absolute value(TARGET - 6)) * 4) + LUN) For example: TARGET = 6 and LUN = 0 gives a PORT of zero; TARGET = 5 and LUN = 1 gives a PORT of 5; TARGET = 4 and LUN = 0 gives a PORT of 8. A sample connect statement for the third example would be: CONNECT VDISK304[0] PVMVIOP3[.8] ______________________________________________________________________________ SCSI Connections in VS/VM E-1 CHAPTER 8 UPDATES TO DOCUMENTATION (continued) 8.4 Previously Updated Sections This section contains pages of the User's Guide that have changed due to enhancements in previous releases. The following pages set forth the modified sections of the VS/VM User's Guide. They are identified by the section numbers and headings used in the Guide. To print this section only, print pages 53 through 124 of this SRN. ______________________________________________________________________________ Updates to Documentation 8-3 2.17 Monitoring Performance VS/VM provides a performance monitor that displays CPU usage and I/O totals. Information displayed by the monitor can indicate the need for changes in virtual machine priority. OPERATOR can monitor performance and prioritize virtual machines through the MON CPU, MON IO, SET REFRESH, and SET PRIORITY commands. A VS guest operating system can also monitor performance by running the MONITOR program. The MONITOR program prompts users for the kind of statistics needed (CPU or I/O), the sampling interval, an output file option, and an end time. The end time is only valid if the MONITOR program is running in background via procedure. The print option is the only valid option when run in background. When run interactively, CPU or I/O information can be returned in either display or display/print mode. ______________________________________________________________________________ Virtual Machine Concepts 2-9 3.3 VS/VM System Crash and Memory Dumps The following sections document memory dumps associated with system crashes. 3.3.1 General Information When a serious error is detected, signaling a loss of system integrity, the system crash procedure is automatically initiated. The procedure saves the state of the system, stores diagnostic information, initiates a system dump, and records the dump automatically on the system disk if space is available. Otherwise, the dumper requests a tape. 3.3.2 Initiating a Dump Although the system automatically initiates a dump as the final step of the crash procedure, there can be occasions when a dump is needed but the system hasn't crashed (for example, when the system is hung). Under these circumstances, the following actions initiate the dumper: 1. Put the system in control mode. 2. Set the PCW instruction address. Note: For VS/VM release 01.02.xx, set the PCW address to the value found at physical address X'1E8'. For VS/VM Release 01.03.01 and greater, set the PCW address to X'800'. 3. Set the second part of the PCW to zeroes. 4. To begin execution, exit control mode. 3.3.3 Control Mode Messages The dumper enters control mode for several reasons, indicated as message values in general register zero. The following list shows message values and responses. 0 -- Dump completed normally, VM HALT CODE stored in general register 1. Re-IPL the system. 1 -- No disk dump area found; dumper requires a tape. Mount the tape, set the second word of the PCW to zeroes, and exit control mode. Dump should start. The default tape drive is drive zero on RIOP3. The Physical Device Address (PDA) for that device is X'2C00' and is found in general register 1 when the mount is requested. Another PDA can be substituted by altering the contents of register 1 to the new value before leaving control mode. ______________________________________________________________________________ IPL Procedure 3-2 2 -- Unrecoverable I/O error. Dump is lost. Re-IPL the system. 3 -- The tape mounted is WRITE PROTECTED. Remount the tape with a write-ring. 3.3.4 Retrieving the Dump If the dump was made to tape, nothing more need be done. If the dump was made to disk, it should be retrieved from the system dump slot after IPL by using the VS BACKUP utility to transfer the dump file (@CMDUMP@ in library @SYSDUMP on the VS/VM system volume) to some portable media. When a tape is used, some indication that the dump is a backup tape as opposed to a dump tape created directly by the dumper is helpful. Caution: In mailing a tape (which is believed to contain a copy of the dump) many people end up sending a blank tape. This is due to a misunderstanding about the BACKUP program: In an effort to save room during routine backups, versions of BACKUP prior to 7.x3.16 will deliberately omit the dump slot. Version 7.x3.16 and later will copy the dump slot, but only if explicitly told to do so (not if performing a backup of the entire disk). Note that the x in version 7.x3.16 should read as a 1 for releases of the operating system prior to 7.18, and read as a 2 for OS release 7.18 and later. Thus, depending on what version of BACKUP is used, it may or may not be possible to copy the dump slot directly to tape. As a conservative measure, it is recommended that the dump be copied first to an intermediate holding area on disk. From there it can be copied, in turn, to tape. The dump slot can be cleared as soon as the initial copy is complete. 3.3.5 REAL.MACHINE Dumps The capability to dump all of physical memory to a VS file without having to re-IPL the system exists in VS/VM versions greater than 01.10.05. The following steps accomplish this dump: 1. Run the VM utility, because a REAL.MACHINE dump can not be taken using the standalone OPERATOR at Workstation 0. 2. DEBUG REAL.MACHINE. (For further information consult Wang support personnel.) 3. DUMP vsvol.vslib.vsfile. Note: The system continues to run while memory is written out to disk. As such, the dump can contain inconsistencies with some internal data structures. ______________________________________________________________________________ IPL Procedure 3-3 3.3.6 Halt Codes -1 CPERRUNSPECIFIED Unspecified error x'01' UNDEFINED x'02' CPERRCPPC Program check in the Control Program x'03' CPERRFINDMODEL Caller passed bad parameter to routine x'04' CPERRMAINT Error while IOC in maintenance mode x'05' CPERRSECURITY Internal CPSECURE error x'06' CPERRNOMEMORY Insufficient free memory to continue x'07' UNDEFINED x'08' CPERR$FILESERVER Internal CPFS error x'09' CPERRIPCMSGCHN IPC message chain incorrect - IPC system problem x'0A' CPERRDELREC Error encountered in DELREC x'0B' CPERR$CPEVENT Internal CPEVENT error x'0C' CPERRIPCDEL IPC mailboxes couldn't be destroyed in INIT x'0D' CPERROP Unrecognized instruction trapped x'0E' CPERRMEMCHK GETIOQ macro not used to call CPGETIOQ x'0F' CPERRIPCTRANS Previously verified translate failed x'10' CPERRSPIPC Unexpected return code using IPC x'11' CPERR$ISBCDUMP Dump requested by another processor x'12' UNDEFINED x'13' CPERRBADVMC Error occurred during Control Poke x'14' CPERRVRMIPC Bad return code from internal IPC call x'15' CPERRBOOT IPC error in CPBOOT x'16' CPERR$INVISBCMSG Invalid ISBC message received x'17' CPERR$CONFIG Unsupported CPU type x'18' CPERRPRILIST CPLOWPRIORITY integrity check x'19' CPERRIPL Unable to DEFINE/CONNECT IPL device x'1A' CPERRVSDISK Error in VSDISK handler x'1B' UNDEFINED x'1C' CPERRNOPAGE No pager RCB found x'1D' CPERRWS0 Unable to DEFINE/CONNECT WS0 for operator x'1E' CPERRBADTRANS Bad translation database x'1F' CPERROPVM Error in DEFINE of operator VM x'20' CPERRFSOP File system error during operator IPL x'21' CPERRUNKNOWNIO Unknown I/O hit the pager x'22' CPERRIOERWS0 I/O error on WS0 in CPBOOT x'23' CPERRTBUFID CPCDTBUFTICKET wrapped to zero x'24' CPERRSPINIT Error during process initialization x'25' CPERRIOLOAD Error in IOLOAD x'26' CPERRVMINIT Unrecognized return code from CPVMINIT. x'27' UNDEFINED x'28' CPERRREGIONLINK Couldn't find region in list x'29' CPERRBADFIX Couldn't fix a needed page x'2A' CPERRBADPAGIN VRM couldn't page in a needed page x'2B' CPERRPAGERQEL Tried to delete pageable VM without PQEL x'2C' CPERRPAGEBLOCK Error in get pager GETBLOCK routine x'2D' CERRBADCALL Invalid call to CPPAGEDE or CPPAGECR x'2E' CPERRBADFRAME Invalid Absolute Frame Number x'2F' CPERRBADPOST Pager posted where should be ______________________________________________________________________________ IPL Procedure 3-4 x'30' CPERRVIOH27 Error in CPVIOH27 (RFS VDEV) x'31' UNDEFINED x'32' CPERRINP No PAGERQUEL for PFTE x'33' CPERRBADDEQ No PFTE on page in operation x'34' CPERRBADSCAN No blocks left in paging file x'35' CPERRNOPAGQEL No paging request elements available x'36' CPERRPBAND Error in Peripheral Band support x'37' CPERRCACHE Error in WorkCache processing x'38' CPERRPUTIOQEL Attempt to PUTIOQEL free IOQEL x'39' CPERRVIOSYNCH Integrity check VIO synchronization x'3A' CPERRPIOSYNCH Integrity check PIO synchronization x'3B' CPERRGUESTHALT Guest asked VM to dump and halt x'E0' CPERRCMDUMP Dump initiated by user from control mode. ______________________________________________________________________________ IPL Procedure 3-5 4.7.1 Virtual Workstation Handlers To allow the sharing of a workstation, the CP provides a software mechanism called a virtual workstation handler, to which the workstation is logically connected. When defining a virtual workstation handler, specify the number of windows it can handle. The CP treats each window of the workstation as a workstation plugged into the handler. These "workstations" are mapped by CONNECT directives to workstations defined in the configuration files of the sharing VMs. VM has the following four types of virtual workstation handlers: - Multiworkstation handler (MWS) - IN/ix workstation handler (INIXWS) - Default workstation handler for Workstation 0 (VWS) - IMAGE multiworkstation handler (IWS) An MWS can handle up to four windows, numbered 0 to 3 (Window numbers are also referred to as plug numbers.). You can connect the windows only to VMs that run under VS operating systems. The INIXWS handles two windows, numbered 0 and 1. Window 0 must be connected to a VS VM; window 1 must be connected to an IN/ix VM. An IWS can have up to four windows, numbered 0 to 3 (Window numbers are also referred to as plug numbers.). An IWS is designed to allow 4250IMG imaging workstations to have connections to as many as four VS guests with imaging capabilities on each. When the workstation is connected or powered up, the CP loads it with microcode that is appropriate to the type of handler to which the workstation is connected. Note: WACS devices may be used in REAL Device mode. However, you may not connect WACS devices to IWS, MWS, VWS or INIXWS workstation handlers. Refer to Appendix D for more WACS specifications. Figure 4-8 is a virtual I/O map that includes a multiworkstation handler. The handler implements the sharing of a workstation between two VMs. The workstation being shared and the sharing VMs are the same as in Figure 4-7. The map is drawn by the sample directives found in Section 4.7.2. ______________________________________________________________________________ Configuring Virtual Machines 4-19 6.3 RESOURCE CONTROL COMMANDS Resource control commands allow you to define a virtual machine and logically configure I/O resources to the machine. The resource control commands are CONNECT -- Connect resources DEFINE RDEV -- Define real device DEFINE RIOP -- Define real IOP DEFINE VDEV -- Define virtual device handler DEFINE VIOP -- Define virtual IOP DEFINE VM -- Define virtual machine DISCONNECT -- Disconnect resource DISMOUNT -- Dismount disk INIT -- Initialize virtual machine IPL -- IPL virtual machine LOAD IOC -- Load IOC microcode MOUNT -- Mount disk SET CHANFREQ -- Set channel frequency SET PRIORITY -- Control virtual machine resource utilization UNDEFINE -- Undefine resource 6.4 DEBUGGER COMMANDS Debugger commands allow you to - Display the contents of registers and of the physical memory space of a VM while the VM is running - Alter the contents of registers and of the physical memory of a VM after you have halted the VM - Dump the physical memory of a VM to a file ______________________________________________________________________________ Operator Program Commands 6-2 The debugger commands are ALTER -- Alter memory/register DEBUG -- Debug virtual machine Display Memory DISASM -- Disassemble machine code DUMP -- Dump physical memory ENTEREXIT -- Enter/exit control mode FP,CR, SCR -- Display registers HALT -- Halt virtual machine LOAD -- Load object code file into memory LOADVM -- Load a dump file into memory RELO -- Set relocation factor RUN -- Run virtual machine SEARCH -- Search memory for a given value SET STAT1 -- Set status line 1 SET STAT2 -- Set status line 2 STEP - Execute a single instruction TRANSOFF/TRANSON -- Disable/enable address translation TRAP AD -- Set virtual machine address trap TRAP GR -- Set virtual machine general register trap TRAP MM -- Set virtual machine memory trap TRAP OFF -- Turn off virtual machine traps TRAP OP -- Set virtual machine op code trap TRAP STEP - Set virtual machine step trap TRAPRANGE -- Set process level range for traps TRAPS -- Display the virtual machine trap table ______________________________________________________________________________ Operator Program Commands 6-2.1 6.10 EXPRESSIONS Numerical values can be entered as arithmetic expressions. Expressions are composed of any number of arithmetic operators with their corresponding operands enclosed in parentheses; for example, (3+(2*(6-1))) is an expression. Operands can be any combination of character strings and/or numerical values. Numerical values may be expressed in decimal or hexadecimal notation. 6.10.1 OPERATORS The operators are executed according to the rules of algebra: operators within parentheses are executed first. Within parentheses, the order of execution follows the hierarchy of operators, and then proceeds from left to right. Only certain operators are valid for character strings. The hierarchy of operators is: Operators by Priority Level Valid for Strings? Level 9 @ Map Field Resolution yes - Unary Negative no . Unary Not no Level 8 ** Exponentiation no Level 7 >> Shift Right Logical no << Shift Left Logical no * Multiplication no / Division no Level 6 + Addition no - Subtraction no Level 5 <=,=<,.> Less or Equal, Not Greater yes >=,=>,.< Greater or Equal, Not Less yes <>,><,.= Not Equal yes < Less yes > Greater yes = Equal yes ? Bit Test no ________________________________________________________________________ Operator Program Commands 6-6 Level 4 // Mod (Remainder) no Level 3 & Logical AND no !! Exclusive OR no Level 2 ! Logical OR no 6.10.2 OPERANDS Operands can be one of two kinds, numerical or character strings. Numerical operands are 32-bit integers. They are considered to be hexadecimal unless preceded by a period, in which case they are considered to be decimal. Character strings can be up to 68 characters long. A character string may contain blanks or special characters if it is enclosed in single or double quotes. If either or both operands of an expression are numerical then a numerical operation is performed. Only if both operands are character strings, will a string operation be performed. If a character string and a numerical value are involved in an operation, the character string will be treated as an integer. If the string is four characters or more, the binary value of the first four characters will be treated as the integer. If the string is less than four characters, it will be padded on the right to four characters with blanks, X'20'. String comparisons assume the length of the shorter operand. 6.10.3 RESULTS The result of an evaluated expression is always a numerical value that occupies one word or eight hexadecimal digits. When necessary, the leftmost digits are truncated. For example, (123456789*1) evaluates to 23456789. The result is right-justified and, when necessary, padded on the left with zeros. In the case of comparison operators, the numerical value will be zero if the comparison is false, or one if the comparison is true. ________________________________________________________________________ Operator Program Commands 6-6.1 6.10.4 PSEUDO END-OF-LINE CHARACTER Multiple commands may be entered on the same line by using the pseudo end-of-line character, ';'. The pseudo end-of-line character is not recognized by the procedure interpreter, only the command line interface. The pseudo end-of-line character is still a valid character in file names and resource names. Therefore, the pseudo end-of-line character must be preceded by a blank in order for the interpreter to recognize it as such. The pseudo end-of-line character need not be followed by a blank. As many commands as will fit may be entered on the 70 character command line. If one of the commands on the command line encounters an error condition, the entire command line will be echoed to the workstation and the cursor will be placed on the command in error. If any commands on the line have been successfully executed, they will be protected by a FAC and they can not be altered during the corrections. The workstation display will be refreshed at the completion of each command on the command line. Example: If you are debugging a virtual machine and have loaded a structure map (using MAPLOAD), you may enter the following commands on a single line to map a structure that is pointed to by a field of another structure. STRUCT OF POINTERS 1234 ;STRUCT (@POINTER1) where: STRUCT OF POINTERS is a structure at location 1234 which contains a field, POINTER1, which points to another structure of type STRUCT. The fields of STRUCT will be displayed. NOTE: Please be aware that if you enter a PFKEY, the value of that PFKEY is inserted in the command line at the beginning of the current command. If there is existing text on the command line, it will follow the value of the PFKEY. This may cause unwanted results in some cases. For example, you enter PFKEY .14 multiple times to find a previous command that you wish to reenter. One of the commands returned, before the one that you want, consists of multiple commands entered using the pseudo end-of-line character. Entering PFKEY .14 causes the command PREVCMD to be inserted at the beginning of the line. The command parser will execute the PREVCMD and continue parsing the command line. All commands after the pseudo end-of-line character will also be executed. To avoid this problem, clear the command line before entering PFKEY .14. ________________________________________________________________________ Operator Program Commands 6-6.2 6.10.5 VARIABLES Variables in VM are simple substution variables. When the name of a variable is encountered on the command line or in a procedure, the value of the variable is substituted for the name of the variable. There are two types of VM variables, local and global. 6.10.5.1 VARIABLE NAMES All variable names begin with a percent sign. Variable names can be made up of any characters and/or numerals that are valid for resource names. The first character of the variable name, following the percent sign, must be alpha/numeric. Variable names may be up to 32 characters long. 6.10.5.2 VARIABLE SUBSTITUTION Commands entered on the command line or read from a procedure file are immediately scanned for all occurances of a percent sign. The characters following the percent sign are compared to the names of the defined variables. If a procedure is active, the list of local variables associated with that procedure is searched first. If no match is found, the list of global variables is searched. If a variable name is referenced, and that variable has not been previously SET, an error results. If the variable name is found in one of the lists of variables, substitution occurs. Once all substitution is completed, the command line is processed by the command processor. Variables are stored in one of the two lists, local or global, in descending order of the length of the variable name. When substitution occurs, the length of the variable name is used to compare the characters following the percent sign with the variable name. For example: Assume two variables are defined, %A = '123' and %ABC = '456'. If "%ABCD" is encountered on the command line, "456D" will remain after the substitution, not "123BCD". Variables are always stored as character strings. After the value of the variable has been substituted for the variable name on the command line, normal rules of conversion and interpretation apply. ________________________________________________________________________ Operator Program Commands 6-6.3 When the value of a variable is substituted for its name, and the value length is greater than the name length, the remainder of the command line is moved right to allow room for the substitution. Although the command line on the workstation screen is 70 bytes, the internal command line is 80 bytes. This allows the command line, after variable substitution, to be 10 bytes longer than the workstation command line. If the substitution of a variable would cause the command line to exceed 80 bytes, an error message is issued. If the replacement of the text following the variable causes non-blank characters to be truncated, an error message is issued. When a command is entered into the history of commands entered, all 80 bytes of the command are archived. Note that, in this case, when the command is recalled from the history, only 70 bytes fit on the command line. Variables may be used in much the same way as PFKEYs are used. If the command "SET LRIOP 'LIST RIOP'" is issued, and "%LRIOP" is then entered on the command line, the command LIST RIOP will be executed. 6.10.5.3 VARIABLE COMMANDS Variables are defined and their values changed through the use of the SET command. That is, a variable is defined and given its initial value using the SET command (similar to the DEFINE command with an INITIAL parameter in the VS Procedure Language). Subsequent SET commands for that variable alter the value (similar to the ASSIGN command in the VS Procedure Language). The UNSET command is used to undefine variables. Multiple variables may be UNSET using a single command. The UNSET command also provides a mechanism for undefining all local or global variables. The LIST command is used to list variable names and their values. If the command is issued without a parameter, all variables are listed. If the name of a variable is entered after GVAR or LVAR, the name and value of that variable will be listed. The variable name in the SET, UNSET, and LIST commands is not preceded by a percent sign. This requirement avoids variable substitution on that occurance of the name. Variable substitution occurs immediately after reading a command line from the workstation or from a VM procedure. All occurances of the percent sign cause substitution to take place. This includes the SET command. Therefore, it is not possible to save a variable name as part of the value of a variable. For example: Assume that %A is SET to contain a value of 1. If the command "SET B '%A+1'" is issued, the value of B is "1+1", not "%A+1". ________________________________________________________________________ Operator Program Commands 6-6.4 6.10.5.4 LOCAL VARIABLES Nine local variables are set when a procedure is invoked. These nine local variables are defined automatically for each procedure invoked. Their names are %1 through %9. The initial value of one of these local variables is the positional parameter value entered on the command line when the PERFORM commmand is issued. If there is no positional parameter entered on the command line for a particular variable, that variable is initialized to "' '" (single quote, space, single quote). Besides the nine automatically defined local variables, you may define as many others as you like, using the SET LVAR command. Local variables can only be referenced while executing the procedure for which they are defined. They are no longer defined when the procedure completes. Local variables of a calling procedure can not be referenced in the called procedure. The value of local variables may be altered using the SET LVAR command. Local variables may be undefined using the UNSET LVAR command. 6.10.5.5 GLOBAL VARIABLES Global variables can be defined in a procedure or on the command line, using the SET GVAR command. Global variables remain set until UNSET, or until the OPERATOR is restarted or VM is stopped. Global variables may have the same name as local variables. These global variables may be referenced from a procedure if the local variable with the same name is UNSET. 6.11 NAMING RESOURCES When entering DEFINE commands, you assign a name to a resource. By convention, the name of an I/O resource reflects its type and location. ________________________________________________________________________ Operator Program Commands 6-6.5 6.14.5.1 CATALOG -- Catalog Virtual Disks Syntax CATALOG volser Function Causes the VM control program to scan the VTOC of the specified volume for virtual disks, in @VMDISK@ of the volume, and make those virtual disks available for connections. Argument volser -- Specifies the VOL1 label of a real volume on the system. Usage The CATALOG command is provided for error recovery only. If the size, location, or existence of a virtual disk is changed using VS/OS functions, VM will not know that the change has taken place. All alterations to virtual disks must be done using VDINIT. If VS/OS functions are used to alter virtual disks the CATALOG command can be used to correct the VM attributes of the virtual disks on a volume. Be aware that loss of data may occur between the time a virtual disk is altered by an OS function and the time the attributes are corrected. Example CATALOG VMIPL Read the VTOC of the real volume labeled VMIPL and build new attribute tables for all virtual disks on that volume. ______________________________________________________________________________ Operator Program Commands 6-15.1 6.14.6 CONNECT--Connect Resources Syntax CONNECT ( ON ) Function Logically connects one resource to the port of another. If no port number is specified by the command, the CP makes the connection to the first available port. For this operation to succeed, nothing must be currently connected to that port. Figure 6-2 (see Section 6.14.30) illustrates the different connections that can be made by this command. Before being connected, a resource must be defined by a Define Resource command. This command identifies the model of the resource. The Connect Resources command must name resources whose models are compatible. For example, only real and virtual disk devices can be connected to VIOPs of the model 23V98; only real and virtual workstations can be connected to VIOPs of the model 23V97W. For more information on the compatibility of devices and IOPs, refer to Appendix A. The Connect Resource command implicitly disconnects the named resource if that resource is already connected to a port not specified in the command. The command does not notify you of this disconnection. Arguments PLUG NAME and PORT NAME -- Either resource plug name is connected to a port of the resource port name. Plug name and port name must have been specified in a previous DEFINE command. [PLUG NUMBER] -- The first argument, plug name, is extended by plug number when that argument names a virtual workstation handler. Plug number identifies the window to be connected to the resource named by the second argument. Plug numbers begin at 0; for example, MWS55[0] specifies the first window of virtual workstation handler MWS55. Virtual disk handlers also have numbered plugs; but, as explained in Section 4.6.4, you should connect a virtual disk by name rather than by plug number. ______________________________________________________________________________ Operator Program Commands 6-2 [PORT NUMBER] -- The second argument, port name, always names a type of resource that has ports; so, that argument can always be extended by a port number. If no port number is supplied, the CP makes a connection to the first available port. If no port is available, an error message is displayed. VIRTUAL DISK NAME -- The name of a virtual disk previously created by VDINIT. VOLUME -- The name of the volume (VOL1 label) of the real volume containing the virtual disk. If the ON volume clause is omitted, the virtual disk that will be connected is the one with the specified name marked with an asterisk on the LIST VDSK display. Examples CONNECT PVMVIOPB PVM[B] Connect virtual IOP PVMVIOPB to the twelfth slot of virtual machine PVM. CONNECT MWS55[3] PVMVIOPB[6] Connect the fourth window of multiworkstation handler MWS55 to port 6 of virtual IOP PVMVIOPB. CONNECT TEMP ON SYSTEM PVMVIOP1 Connect the virtual disk TEMP that resides on volume SYSTEM to the next available port on PVMVIOP1. ______________________________________________________________________________ Operator Program Commands 6-3 6.14.11 DEFINE RIOP -- Define Real IOP Syntax DEFINE RIOP Function Defines a real IOP for the system. A real IOP must be defined before it or the devices it supports can be connected to a virtual machine. Arguments NAME -- Specifies for the real IOP a unique name from one to 16 characters long. MODEL -- Specifies the model, or type, of the real IOP. Appendix A lists the allowable values. SLOT NUMBER -- Number of the IOP's slot in the I/O chassis. CHANNEL -- Specifies the channel to be used by the PBAND modem on a serial IOP. Valid values are 0 thru 6, 8 thru 15, 19 thru 31, and 255. If 255 is used the channel is not set and PBAND real devices may not be defined on the RIOP. One or two channels may be specified, separated by a space. The second channel is meaningful only on a 70V67 IOP, and specifies the channel to be used by the PBAND modem on the second device adapter. Examples DEFINE RIOP RIOP4 23V98 4 Define a real disk IOP in slot 4 (counted from zero) of the real machine. DEFINE RIOP RIOP5 23V97W 5 Define a real serial IOP in slot 5 of the real machine. This IOP will not use PBAND devices because a channel has not been set. DEFINE RIOP RIOP6 70V67 6 CHANNEL=01 02 Define a real high capacity serial IOP in slot 6 of the real machine. This IOP has two PBAND modems. The modem on device adapter 1 will use channel 1. Its devices are defined as PBAND RDEVs. The modem on device adapter 2 will use channel 2. Its devices are defined as PBAND1 RDEVs. DEFINE RIOP RIOP7 70V67 7 CHANNEL=FF 01 Define a real serial IOP in slot 7 of the real machine. This IOP has only one PBAND modem, on the second device adapter. It will use channel 1. Its devices are defined as PBAND1 RDEVs. ______________________________________________________________________________ Operator Program Commands 6-25 6.14.12 DEFINE VDEV -- Define Virtual Device Handler Syntax DEFINE VDEV VSDISK MWSn IWSn INIXWS VWS RSF DISKMUX WORKCACHE Function Defines a virtual device handler. Arguments VDEVNAME -- Specifies for the virtual device handler a unique name from one to 16 characters long. As shown in the example, the name conventionally ends with two digits that denote, respectively, the RIOP and port of the real device that is plugged to the virtual device handler being named. VSDISK, MWSn, IWSn, INIXWS, VWS, RSF, DISKMUX, and WORKCACHE -- Any one of these specifies the model of the virtual device handler being defined. Virtual device handlers are described in sections 4.6.1 and 4.7.1. - VSDISK denotes a virtual disk handler - MWSn denotes a multiworkstation handler; the numerical value specifies the number of windows to be handled; allowable values are one to four - IWSn denotes an IMAGE multiworkstation handler; the numerical value specifies the number of windows to be handled; allowable values are one to four - INIXWS denotes an IN/ix workstation handler; this model always handles two windows - RSF denotes a virtual resource sharing facility handler - DISKMUX denotes a disk multiplexer handler - WORKCACHE denotes a memory resident disk cache ______________________________________________________________________________ Operator Program Commands 6-26 Example DEFINE VDEV MWS65 MWS3 Define virtual device MWS65 as a multiworkstation handler with three windows. The digits 6 and 5 indicate that a workstation on RIOP6, port 5 will be connected to this handler. _____________________________________________________________________________ Operator Program Commands 6-26.1 6.14.14 DEFINE VM -- Define Virtual Machine Syntax DEFINE VM Function Defines a virtual machine of the specified name and architecture, and allocates memory of the specified amount to the virtual machine. Configuration commands and the IPL or INIT command must also be entered to make the defined virtual machine operational. Arguments VMNAME -- Specifies a name for the virtual machine. This name must be unique among the names of all resources known to the system. The name can be from one to 16 characters long. VMSIZE -- The amount of physical main memory to be allocated to the virtual machine. The value is in kilobytes. The amount of memory currently available for the virtual machine is displayed by the Display Status command. A decimal value must be preceded by a period (for example, .2048); otherwise, a hexadecimal value is assumed. VS virtual machines -- A VS Operating System has the same memory requirements whether it is running on a virtual machine or on a standalone machine. For more information on the memory requirements of a particular release, refer to the customer software release notice (CSRN) for that release. IN/ix virtual machines -- Refer to the appropriate IN/ix CSRN for IN/ix memory requirements. VMPRIORITY -- One or more virtual machines (other than OPERATOR) must be set to 0. When VMPRIORITY=0, the virtual machine's dispatch frequency does not change. A priority of 0 is the highest priority and indicates that the virtual machine never goes to a blocked state following the entire use of its time slice. If omitted, VMPRIORITY defaults to 0. As VMPRIORITY increases, the virtual machine's dispatch frequency decreases using the formula 100 milliseconds times VMPRIORITY. The maximum value of VMPRIORITY is 20, indicating that the virtual machine unblocks at two second intervals. Refer to the SET PRIORITY command for further information. VSMODEL -- Defines the VS MODEL of this virtual machine. If omitted, VSmodel defaults to that of the real machine. ______________________________________________________________________________ Operator Program Commands 6-28 VSE, PAG, or VSXM -- Specifies characteristics of the virtual machine's architecture related to address translation. VSE is specified for a virtual machine running under Release 7.10 through Release 7.40 of the VS Operating System, or under the IN/ix Operating System. PAG is specified for a virtual machine, like OPERATOR, whose paging is handled by the Control Program. VSXM is specified for a virtual machine running under Release 7.50 of the VS Operating System. VSE is the default. Usage The first two arguments are required and must be entered in the following order: . PRIORITY, if entered, must be the third argument. The VS model and architecture arguments, if entered, can be entered as the last arguments in any order. Examples DEFINE VM TEST01 .2048 A VSE Define virtual machine TEST01 with 2048 KB of memory, a VMPRIORITY of 10 (Hex A), and VSE architecture (that is, the architecture compatible with VS Operating System, Release 7 Series). DEFINE VM TEST02 .2048 Define virtual machine TEST01 with 2,048 KB of memory. The VMPRIORITY defaults to 0, the architecture defaults to VSE and the VS model defaults to that of the real machine. DEFINE VM TEST03 .4096 VSXM Define virtual machine TEST03 with 4,096 KB of memory. This virtual machine will run VS/OS Release 7.50 and use the VSXM translation architecture. The CPU microcode must be capable of VSXM translations. ______________________________________________________________________________ Operator Program Commands 6-28.1 6.14.14.02 DISASM -- Disassemble Object Code Syntax: DISASM (P)
Function: Displays memory allocated to the virtual machine being debugged. DISASM shows the assembler mnemonics of the disassembled instructions and the hexidecimal translations of the operands. The operand addresses of the current (PCW) instruction are displayed on the title line. See "Display Memory" section for usage notes referring to the "P" keyword and memory translation. Arguments: address Starting memory address. ______________________________________________________________________________ Operator Program Commands 6-29.1 6.14.15 DISCONNECT-- Disconnect Resource Syntax DISCONNECT ( ON ) Function Logically disconnects the named I/O resource from another resource. Arguments RESOURCE NAME -- Specifies the name assigned to the resource by a previous Define command. [PLUG NUMBER] -- The resource name argument must be extended by a plug number when that argument names a virtual workstation handler. The plug number identifies the window to be disconnected. Virtual disk handlers also have numbered plugs: but, as explained in Section 4.6.4. you should disconnect a virtual disk by name rather than by plug number. VIRTUAL DISK NAME -- The name of a virtual disk previously created by VDINIT. VOLUME -- The name of the volume (VOL1 label) of the real volume containing the virtual disk. If the ON volume clause is omitted, the virtual disk that will be disconnected is the one with the specified name that is marked with an asterisk on the LIST VDSK display. Usage To disconnect a virtual workstation handler, you must disconnect each of its connected windows by a command that includes a plug number. Suppose that the virtual workstation handler MWS55 has been defined as having four windows, and that the first two have been connected to virtual machines. To disconnect the handler, you must issue the commands DISCONNECT MWS55[0] DISCONNECT MWS55[1] The command is not legal. ______________________________________________________________________________ Operator Program Commands 6-30 Examples DISCONNECT PVMVIOPB Cancel the current connection of PVMVIOPB. PVMVIOPB has been defined as a virtual IOP and, in accordance with naming conventions, has been connected to the twelfth slot of virtual machine PVM. DISCONNECT TEMP ON SYSTEM Disconnect the virtual disk TEMP that resides on volume SYSTEM from the port to which it is connected. ______________________________________________________________________________ Operator Program Commands 6-30.1 6.14.19.01 FINDCMD -- Locate a Previously Entered Command Syntax FINDCMD Function Locates and displays on the command line the last command entered that contains . Argument -- Specifies a one to sixteen character string that is to be located in the command history. Imbedded blanks are interpreted as the end of the string. Usage FINDCMD will be assigned to PF12 by default when the operator is initialized. Refer to LIST HISTORY for a complete discussion of the command history. ______________________________________________________________________________ Operator Program Commands 6-35.1 6.14.25 LIST -- List Resource Syntax LIST ( ()) * * * Function Displays a list of resources that have been DEFINEd to the system. Arguments RESOURCE TYPE -- Resource type is one of the following uppercase values: - VM Virtual machines - RDEV Real devices - RIOP Real IOPs - RM Real machine - VDEV Virtual device handlers - VDSK Virtual disks - VIOP Virtual IOPs RESOURCE NAME -- Name given to a resource by the DEFINE command. RESOURCE MODEL -- Model specified when the resource is defined. The models of real and virtual IOPs are model numbers (for example, 23V97W, 23V98). The models of real and virtual devices are descriptive names (for example, DISK, SERDEV). Appendix A lists valid model numbers; the descriptions of DEFINE commands list valid model names. Usage The arguments of this command, other than asterisks, act as filters or qualifiers. Asterisks indicate an omitted argument. The action of arguments as filters is illustrated by the following three commands: LIST * * * -- This command has no filters and lists all resources on the system. LIST * * 23V97W -- This command lists all resources of the Model 23V97W. (Resources with this model number are real and virtual IOPs.) LIST VIOP * 23V97W -- This command lists virtual IOPs of the Model 23V97W. ______________________________________________________________________________ Operator Program Commands 6-42 Asterisks are required to indicate omitted arguments that precede a specified argument. An exception to this rule is presented by the command used to list all resources on the system. This command takes the form of one of the following: LIST * * * LIST * In the case of this command, an asterisk is required even though it is not followed by a supplied argument. Arguments omitted after a specified argument need not be indicated by an asterisk. The following command, which supplies only the first argument, is valid: List VM Examples LIST VM List the status of currently created virtual machines. The consequent display shows the name, state (running or stopped), architecture, memory size, and priority of each virtual machine. Refer to SET PRIORITY for an explanation of priority. LIST RDEV * PBAND or LIST RDEV * FIBER List all P-band or FiberWay resources. The consequent display shows the resource, APA, port, model, and manufacturer's id. LIST * PVMVIOP9 List a resource named PVMVIOP9. The resulting display shows the model number of this VIOP. LIST * * VSDISK List all virtual disk handlers. The consequent display shows names of all virtual disk handlers and the names and plug numbers of virtual disks plugged to each handler. ______________________________________________________________________________ Operator Program Commands 6-43 6.14.28.01 LIST HISTORY -- List the Command History Syntax LIST HISTORY Function Displays the history of commands entered by the operator. Usage This command is available to the standalone operator and the operator application. It will display the command history on the operator workstation. The command history is a circular buffer of the last fifty commands entered at the workstation. If fewer than fifty commands have been entered, all of the commands will be displayed. Otherwise, the last fifty commands will be displayed. The last command entered will be displayed first. The commands in the history can be returned to the command line of the operator screen using NEXTCMD, PREVCMD, and FINDCMD. Once returned to the command line, commands can be edited and re-executed. Two pointers to the saved commands will be maintained. One (the save pointer) will point to the next place to save an entered command. The other (floating pointer) will point to the current command returned by PREVCMD, NEXTCMD, or FINDCMD. In general, entering a command will reset the floating pointer to the same place as the save pointer. The operator can search through the history of commands using PREVCMD, NEXTCMD, and/or FINDCMD, find the command he wishes to reissue, edit it (possibly), and execute the command. This command will be saved in the history in the position pointed to by the save pointer. Both pointers will then be set to the next available slot in the history. Entering PREVCMD at this point will return the command just entered. Entering NEXTCMD after just executing a command will retrieve the oldest command in the history. By repeating NEXTCMD and/or PREVCMD the operator can cycle through the saved history to locate the desired command. FINDCMD allows the operator to enter a string of up to 16 characters on the command line as the operand of FINDCMD. Imbedded blanks are interpreted as the end of the string. These characters will be searched for in the command history starting with the last command entered and continuing backwards. If the string is located in a command, that command is returned to the command line. The floating pointer will be updated to the address of the returned command. If the string is not located, no command will be returned and no error will be returned. ______________________________________________________________________________ Operator Program Commands 6-48.1 The last character string entered will be saved. If FINDCMD is entered with no operand the saved character string will be searched for, starting at the location of the floating pointer and continuing backward. The floating pointer may be pointing to the last command entered or to a different spot in the history if the last command was PREVCMD, NEXTCMD, or FINDCMD. Note that the operator must clear the command line after issuing a FINDCMD in order to continue searching for the next command that contains the saved string. In other words, if one types FINDCMD PF and the command LIST PFKEY is displayed on the command line, hitting PF12 (FINDCMD) will find the next occurance of LIST not PF. If the command LIST PFKEY is erased from the command line, hitting PF12 (FINDCMD) will return the next occurance of PF, which may be SET PFKEY .12 FINDCMD. Some commands will not be saved in the history, nor will they cause the floating pointer to be reset. These are PREVCMD, NEXTCMD, PREVDISP, NEXTDISP, PREVPAGE, NEXTPAGE, PREVLINE, NEXTLINE, FIRSTPAGE, and FINDCMD. Commands entered in the body of a procedure will not be entered in the history unless the procedure is executed in step mode. The command that executes the procedure will be entered in the history. The procedure contents may be displayed using the LIST FILE command. Commands found to be in error are not saved but are redisplayed on the workstation, as in the past. Commands entered with the use of PF keys are saved with the translation of the PF key so that each command saved is re-executable by recalling the command and hitting enter. Blank lines entered on the command line are not saved, but they do cause the floating pointer to be reset. PREVCMD will be assigned to PF14 by default when the operator is initialized. NEXTCMD will be assigned to PF30. FINDCMD will be assigned to PF12. ______________________________________________________________________________ Operator Program Commands 6-48.2 6.14.30 LIST PLUG/LIST PORT-- List Connections Syntax LIST PLUG([levels]) name([plug number]) PORT([levels]) name([port number]) ( ON ) Function Shows how resources have been logically connected by DEFINE and CONNECT directives. This command can be entered with either the PLUG or PORT options. The difference between these options can be generally understood by imagining the resources of a system as progressing from real to virtual. The progression starts with real devices and ends at a virtual machine. Figure 6-1 illustrates this progression. . Real Devices / \ . . . LIST Real IOPs LIST . . . . PLUG Virtual Devices PORT . . . . Virtual IOPs . . . \ / Virtual Machines . Figure 6-1. Progression of Resources LIST PLUG shows a resource's connections in one direction, toward the virtual machine: LIST PORT shows a resource's connections in the other direction, toward the real devices. The LIST PLUG command answers the question, "What is the named resource CONNECTed to?" The LIST PORT command answers the question, "What is CONNECTed to the named resource?" LIST PLUG Figure 6-2 illustrates in detail the connections shown by the LIST PLUG command. ______________________________________________________________________________ Operator Program Commands 6-50 The arrows in Figure 6-3 indicate the connections shown when you name a resource of a certain type in the LIST PORT command. When you enter LIST PORT , you are shown the virtual and real IOPs connected to slots of the VM. By specifying three levels of connection (LIST PORT[3] ), you can see the path of connections from the virtual machine through the virtual or real IOP to real devices. When you enter LIST PORT , you are shown the virtual and real devices connected to ports of the VIOP. When you enter LIST PORT , you are shown the real device connected to port 0 of the handler. When you enter LIST PORT[2] REAL.MACHINE you are shown the real IOPs and devices connected to slots of the real machine. (Only two levels of connection are supported by this particular command.) When you enter LIST PORT , you are shown real devices connected to ports of the real IOP. Arguments [levels] -- Specifies the levels of connections to be displayed. Meaningful values are 1 to 4. The default is to show all levels of connection. Name -- Specifies the name of the resource whose connections are to be shown. The name is that previously assigned to the resource by a DEFINE or CREATE command. The real machine is designated by the name REAL.MACHINE. [port number] and [plug number] -- These optional extensions to the name argument apply to resources that support multiple connections. The extensions specify the particular connection to be shown. applies to IOPs and VMs. For example, the command LIST PORT VIOPX[3] shows the device connected to port 3 of the named VIOP. applies to virtual device handlers. For example, the command LIST PLUG MWSX[3] shows where the fourth device of the named handler is connected. The default is to list connections for all ports or plugs of the named resource. Usage The LIST PLUG command shows only those connections explicitly established by CONNECT directives. When defined, real devices are implicitly connected to real IOPs, and real IOPs are implicitly connected to the real machine. Thus, these connections of real devices and real IOPs are not shown by the LIST PLUG command. ____________________________________________________________________________ Operator Program Commands 6-52 6.14.30.1 LIST VAR -- List Variable Names and Values Syntax LIST LVAR GVAR Function Displays the names and current values of defined variables. Argument LVAR or GVAR -- indicates whether the variable is a local or a global variable. variable name -- Specifies the name of a variable to list. NOTE: When entering the do not include a percent sign as the first character of the name. The percent sign will cause substitution to occur and an unexpected result will be produced. Usage This command is available to the standalone operator and the operator application. It will display the the names and current values of defined variables. If is ommited, the names and values of all variables are displayed. If is supplied, the name and value of the entered variable will be displayed. If a procedure is active, local variables may be listed. Use the SET command to define variables and alter their values. Use the UNSET command to undefine variables. Examples LIST GVAR -- List all global variables and their values. LIST GVAR COUNT -- List the name and value of the global variable COUNT, which was defined using the SET GVAR command. LIST LVAR 1 -- List the name and value of the local variable 1, which was defined automatically when the procedure was invoked. ________________________________________________________________________ Operator Program Commands 6-54.1 6.14.30.02 LOAD IOC -- Recover IOC Syntax LOAD IOC (RIOPx) [(DUMP=volume.library.file)] [(DUMP=library.file)] [(DUMP=file)] Function LOAD IOC reinitializes the controller without re-IPLing the system. The DUMP option provides a file for use in debugging. This command is supported only for IOCs configured in shared IOP mode. Caution: This command allows a system administrator to reload an IOC even when the IOC services more than one guest operating system. The standalone OPERATOR can not use the DUMP option. Arguments RIOPx -- The name of the controller to be recovered. VOLUME, LIBRARY, FILE -- Specification of the VS file for the DUMP output. ______________________________________________________________________________ Operator Program Commands 6-54.2 6.14.30.02 MON -- Monitor Performance Syntax MON CPU MON IO Function The MON command provides virtual machine and device performance statistics. Totals are measured within an elapsed time period. Refer to the SET REFRESH command for further information concerning this time period. Examples MON CPU -- MON CPU looks at each virtual machine and each CPU in the system. For each virtual machine, MON CPU displays the percent of CPU time consumed by the virtual machine, and retains maximums. MON CPU also displays the percent of each CPU's time consumed by all virtual machines, by the control program, and by idle time. Note: Total system-wide CPU usage is 100%, but this total can be slightly reduced by truncation. MON IO -- MON IO displays the total I/Os for each virtual machine account, each IOC, each disk, and the system as a whole. ______________________________________________________________________________ Operator Program Commands 6-54.3 6.14.31.01 NEXTCMD -- Return the Oldest Command Syntax NEXTCMD Function Return the oldest command in the command history to the command line. Usage NEXTCMD will be assigned to PF30 by default when the operator is initialized. Refer to LIST HISTORY for a complete discussion of the command history. ______________________________________________________________________________ Operator Program Commands 6-55.1 6.14.33.04 PREVCMD -- Return the Last Command Syntax PREVCMD Function Return the last command entered to the command line. Usage PREVCMD will be assigned to PF14 by default when the operator is initialized. Refer to LIST HISTORY for a complete discussion of the command history. ______________________________________________________________________________ Operator Program Commands 6-63.1 6.14.36.2 SET CHANFREQ -- Set Channel Frequency Syntax SET CHANFREQ Function Set the channel frequency of the specified serial IOP. Arguments NAME -- The name of the serial IOP. XX and YY -- Specify the channels to be used by the PBAND modems on a serial IOP. Valid values are 0 thru 6, 8 thru 15, 19 thru 31, and 255. If 255 is used the channel is not set and PBAND real devices may not be defined on the RIOP. One or two channels may be specified, separated by a space. The second channel is meaningful only on a 70V67 IOP, and specifies the channel to be used by the modem on the second device adapter. Examples SET CHANFREQ RIOP2 01 This command causes VS/VM to set the channel frequency for the first or only PBAND modem on the serial IOP, RIOP2, to 1. SET CHANFREQ RIOP4 FF 01 This command causes VS/VM to set the channel frequency for the second PBAND modem on the serial IOP, RIOP4, to 1. Note that the channel frequency for the first modem is not to be set. ______________________________________________________________________________ Operator Program Commands 6-71 6.14.38.1 SET PRIORITY -- Set Dispatching Frequency Syntax SET PRIORITY Function Set the dispatch frequency of virtual machines. Refer to the MON command to display CPU and I/O statistics. Arguments VMNAME -- The virtual machine name set by DEFINE VM. LIST VM can display current virtual machine names. VMPRIORITY -- One or more virtual machines (other than OPERATOR) must be set to 0. When VMPRIORITY=0, the virtual machine's dispatch frequency does not change. A priority of 0 is the highest priority and indicates that the virtual machine never goes to a blocked state following the entire use of its time slice. Note: OPERATOR is always set at 0 and can not be changed. As VMPRIORITY increases, the virtual machine's dispatch frequency decreases using the formula 100 milliseconds times Vmpriority. The maximum value of Vmpriority is 20, indicating that the virtual machine unblocks at two second intervals. Caution: Lower the dispatch frequency in small steps while carefully monitoring the results, using the MON CPU command. Note: Virtual machines that execute 50 or more I/Os per second can be severely penalized by reducing their dispatch frequency. ______________________________________________________________________________ Operator Program Commands 6-75.1 6.14.39.3 SET VAR -- Define or Alter a Variable Syntax SET LVAR GVAR Function Define a variable and set its value or alter the value of a previously defined variable. Arguments LVAR or GVAR -- indicates whether the variable is a local or a global variable. variable name -- The name of the variable to be defined or altered. NOTE: When entering the do not include a percent sign as the first character of the name. The percent sign will cause substitution to occur and an unexpected result will be produced. value -- The value that is to be assigned to the variable specified in variable name. Usage If variable name has not been previously defined it will be defined as a local (if a procedure is active) or global variable. It will be given the initial value specified in the value argument. If variable name has been previously defined as a local or global variable, the value of the variable will be set to the new value specified in the value argument. If value is enclosed in parentheses, the value will be computed by the expression evaluator and assigned to the variable. If value is enclosed in single or double quotes, the character string within the quotes will be assigned to the variable. Note that variable substitution will occur before assigning the value. Even if a variable name with a preceeding percent sign is enclosed in quotes, substitution will occur. Use the LIST VAR command to list the names and values of variables. Use the UNSET command to undefine variables. _________________________________________________________________________ Operator Program Commands 6-78.1 Examples SET GVAR A 1 -- Define the variable A and set its value to one. SET GVAR A (%A+1) -- Set the variable A to the previous value of A plus one. SET GVAR A '(%A+1)' -- Set the variable A to the string '(2+1)', assuming the current value of the variable A is two. The quotes will not be included in the value. The expression will not be evaluated until %A is encountered on a command line and substitution has occurred. SET GVAR A %A+1 -- Set the variable A to the previous value of A. Because of the rules of parsing in VM, A will be set to the first 'token' encountered. The '+1' is ignored. No error is indicated by VM, but it is not likely that this is what the user wanted. SET SO 'TRAP OFF ;STEP OVER ;TRAP STEP' -- Assign this character string of commands to the variable SO. Typing %SO and a carriage return on the command line will cause the three commands to be executed. ';' is the pseudo end-of-line character. _________________________________________________________________________ Operator Program Commands 6-78.2 6.14.41 STATS -- List Status Syntax: STATS Function: Displays the current usage of main memory on the real machine, the current version of the Control Program, and the current version of the CPU microcode running on the real machine. The display shows usage of - VM memory - The static file (VM free memory) - Control Program memory VM memory is the memory used by virtual machines running on the system. The static file is used by the Control Program for data structures and buffers. For VM memory and the static file, the display shows the amount of memory currently used by each and the amount of memory still available for each. Thus, you can use the command before creating a virtual machine to see how much memory is available. The VERSION and MON commands provide additional system statistics. The VMOPTS utility can be used to alter the amount of memory allocated to the static file at VM IPL time. ______________________________________________________________________________ Operator Program Commands 6-80 6.14.41.1 STEP -- Step a Single Instruction Syntax: STEP () () Function: Sets a virtual machine breakpoint to trap after executing instructions. defaults to 1. If the operand is OVER an address range trap will be set for the range from PCW address plus two to PCW address plus ten. If n is specified, the trap is removed immediately after stepping n instructions. If OVER is specified, the trap is removed when it is executed. If the trap is not executed, it will remain pending. It can be removed by using the TRAP OFF command. Arguments: n -- Specifies the number of machine instructions to be executed before trapping. OVER -- Specifies that program execution should stop on the next in-line instruction. The next in line instruction will not be the next instruction executed if the current instruction is a branch. If the current instruction is a subroutine call (BAL, JSCI, etc.) execution will halt upon return from the subroutine call. ______________________________________________________________________________ Operator Program Commands 6-80.1 6.14.44.1 TRAP GR -- Set Virtual Machine General Register Trap Syntax: TRAP GR Function: Sets a virtual machine breakpoint trap when the comparison of the register and value, using the relational operator, is true. Arguments: REGISTER NUMBER -- Specifies the general register. Valid values are 0-9 and A-F in hex or .1 to .15 in decimal. The space between GR and register number may be omitted. RELATIONAL OPERATOR -- A keyword denoting the type of comparison to perform. Valid keywords are: EQ (equal), NE (not equal), GT (greater than), LT (less than), GE (greater or equal), and LE (less or equal). VALUE -- Specifies the comparison value. Examples: TRAP GRA NE 0 Cause the virtual machine to halt when general register 10 is not equal to zero. TRAP GR .10 EQ 10 Cause the virtual machine to halt when general register 10 is equal to X'10' (16 decimal). ______________________________________________________________________________ Operator Program Commands 6-83.1 6.14.45.1 UNSET VAR -- Undefine a Variable Syntax UNSET LVAR ... GVAR <*> Function Undefine a variable. Arguments LVAR or GVAR -- indicates whether the variable is a local or a global variable. variable name -- The name of the variable to undefine. As many variable names as will fit on the command line may be entered. NOTE: When entering the do not include a percent sign as the first character of the name. The percent sign will cause substitution to occur and an unexpected result will be produced. * -- Indicates all of the variables of the specified type are to be undefined. Usage The variable(s) specified on the UNSET command line will be undefined. Multiple variables may be undefined using a single UNSET command. If GVAR is specified global variables will be undefined. If LVAR is specified local variables will be undefined. All variables of the specified type may be undefined by using a variable name of '*'. If the specified variable was not previously SET, an error message is displayed. Use the SET VAR command to define and alter variables. Use the LIST VAR command to list variables and their values. Examples UNSET GVAR A -- Undefine the global variable with the name A. UNSET GVAR A B C -- Undefine the global variables A, B, and C. UNSET LVAR * -- Undefine all local variables for the currently executing procedure. _________________________________________________________________________ Operator Program Commands 6-84.1 6.14.45.1 VERSION -- Display Microcode Version Numbers Syntax: VERSION Function: VERSION displays the following information: - Control program version - Real machine CP microcode version - Device and controller microcode versions (Only microcodes that are loaded by the VS/VM Control Program are listed. The microcode files examined and listed are those files on @VMDSK. VERSION also indicates if a specified file does not exist in @VMDSK.) - The IPL PDA, RDEV name, and VOLID of the VM IPL volume ______________________________________________________________________________ Operator Program Commands 6-85 CHAPTER 7 DEFINING VIRTUAL DISKS 7.1 INTRODUCTION Virtual disks are large disk files that can be accessed by virtual machines (VMs) as if the files were actual disks. The VDINIT utility defines a virtual disk, complete with its own VTOC, in the library @VMDISK@ of a physical volume. WARNING: All changes to virtual disks, CREATE, SCRATCH, RENAME, COPY, and REFORMAT, must be done using the VDINIT program. The use of any other VS/OS facility to manipulate virtual disks has the potential of corrupting data on disk. Do not run compress in place, CIP, on a volume that contains virtual disks. It is strongly recommended that you do not connect plug zero of volumes containing virtual disks. VS/OS virtual disks must now be REFORMATed using DISKINIT after they are created or reformatted by VDINIT. VS type VTOCs on virtual disks created by VDINIT may not be compatible with newer OS versions. REFORMAT, RELABEL, and VERIFY are the only DISKINIT functions that can be safely used on virtual disks used by newer OS versions. DISKINIT in newer OS versions will enforce this restriction. Users with older versions of DISKINIT can only use the RELABEL function and must enforce this restriction manually. Virtual disk support was introduced in VS/OS version 7.21.05 with Device Support Package 3.70 and VS/OS version 7.30.04 with Device Support Package 4.30. Menus of the VDINIT utility resemble those of the DISKINIT utility, which is used to initialize real disk volumes. This chapter frequently refers to the description of DISKINIT found in the VS System Utilities Reference. 7.2 VDINIT MENUS VDINIT displays six GETPARMS. The first, FUNCTION, presents a choice of the five possible functions you can perform: Create, Reformat, Relabel, Scratch, Copy, and Catalog. If you select any function, other than Catalog, you will be presented with a second GETPARM to supply additional information for the selected function. The Create and Reformat GETPARMS present a third level of GETPARM if you choose to define a page pool. ______________________________________________________________________________ Defining Virtual Disks 7-2 7.3 STARTING VDINIT VDINIT runs under the VS Operating System. The virtual machine on which VDINIT is run must have OPERATOR and IPC privileges. Use the VMPRIV command to enable these privileges. The volume to receive a virtual disk must have been initialized by the DISKINIT utility. After mounting the initialized volume, invoke VDINIT from the command processor. If the drive on which you mount the volume is logically connected to a virtual disk handler, plug 0 of that handler must be connected to your virtual machine. (Virtual disk handlers are described in Section 4.6.1) 7.4 FUNCTION GETPARM The first menu presented by VDINIT is the FUNCTION GETPARM. The following choices are found in this menu: Field Description FUNCTION Specify one of the six functions: Create, Reformat, Relabel, Scratch, Copy, or Catalog. Create will allow you to create a new virtual disk. Reformat allows you to erase the data on a virtual disk while changing the VTOC size, page pool options, and/or the extent options. Relabel allows you to change the name of a virtual disk. Relabel also changes the VOL1 label of the virtual disk. Scratch will delete a virtual disk. Copy will copy the specified virtual disk to another volume or file. You may increase the size of a virtual disk while it is being copyied. Copy will update the VOL1 label of the output disk to contain the correct values for number of cylinders and records per cylinder according to the characteristics of the output volume. Catalog causes the VM control program to read the new attributes of all virtual disks on the specified volume. Catalog is automatically performed after each of the other functions and is included only for error recovery. NOTE: The Create, Reformat, and Relabel functions write out a Release 7 IPLTEXT. This IPLTEXT may or may not be compatable with your VS/OS. After using one of these functions on an IPL disk you should CONNECT the virtual disk, run DISKINIT, and relabel the virtual disk. VIRTDISK Specify the name of a virtual disk. This name can be up to six characters in length. If, on this same menu, you specify a VSID (volume set identifier), the name used by the system is a concatenation of the name and VSID. For example, if you enter the name VMDATA and the VSID 01, the virtual disk is listed by the Manage Files/Libraries function as VMDATA01. This field is ignored by the Catalog function. ______________________________________________________________________________ Defining Virtual Disks 7-3 DISKTYPE Specify the type of VTOC to be defined on this virtual disk. The VM Operating System (i.e., the Control Program) and VS Operating System use different file systems and different types of VTOCs. Specify DISKTYPE = VS to apply the specified function to a virtual disk that will be mounted to a VS Operating System. Specify DISKTYPE = VM to apply the specified function to a virtual disk that will be used by the Control Program. Only when installing a VM system is there occasion to specify DISKTYPE = VM. The DISKTYPE parameter is ignored when you choose the Relabel, Scratch, Copy, and Catalog functions. VSID Specify the volume set identifier. This parameter is required only if the virtual disk against which you are running is a member of a multivolume set. This parameter is ignored for DISKTYPE = VM virtual disks, or if the specified function is Relabel, Scratch, Copy, or Catalog. VOLUME Specify the physical volume on which VDINIT is to find or place the virtual disk. This volume must have been initialized by DISKINIT. 7.5 CREATE and REFORMAT GETPARMS Choosing the Create or Reformat function causes a second GETPARM that contains the same fields for either function. If DISKTYPE = VM on the FUNCTION GETPARM, the only choices on the second GETPARM are DISKSIZE and VTOCSIZE. If DISKTYPE = VS, all of the following choices are presented by the second GETPARM. If the specified function is Reformat, the DISKSIZE cannot be changed. Field Description TOLERATE Specify a level of fault tolerance. For VS-type VTOCs, VDINIT provides two levels: no tolerance and crash tolerance. (Media tolerance is not provided.) When you specify CRASH, the number of blocks allocated for a VTOC is twice the value that you supply for the VTOCSIZE parameter on this menu. For VM-type VTOCs, VDINIT provides crash tolerance only. For a discussion of fault tolerance, refer to the description of DISKINIT in the VS System Utilities Reference. DISKSIZE Specify the size of the virtual disk to be defined. The minimum size for a virtual disk is 1 MB. The size of a virtual disk used as an IPL pack should be at leaset 30 MB. ______________________________________________________________________________ Defining Virtual Disks 7-4 VTOCSIZE Specify the number of 2,048-byte blocks to be allocated for the virtual disk's VTOC. The minimum size of a VTOC is four blocks; the default size is eight blocks. The number of blocks to be allocated depends chiefly on the number of files to be placed on the virtual disk. In most cases, 50 blocks per megabyte is sufficient for a VS-type VTOC and eight blocks is sufficient for a VM-type VTOC. PAGEPOOL Specify whether blocks are to be allocated on the virtual disk for a page pool. Specifying YES causes a third GETPARM that requests page pool size. It is recommended that a page pool exist on an IPL pack (virtual or real) of the VM. The default No assumes that the virtual disk being defined or reformatted is not the IPL pack. For a discussion of page pools, refer to the description of DISKINIT in the VS System Utilities Reference. XTNTOPEN Specify the maximum number of extents that can be allocated to a file when it is opened for definition. The default value of 3 is intended to reduce possible fragmentation of a file over multiple extents and, consequently, to improve access time. XTNTTOTL Specify the total number of extents that can be allocated to a file. The total comprises the number of extents allocated at definition time plus any extents allocated later when the file grows. The default value of 13 is intended to reduce possible fragmentation of a file over multiple extents and so to improve access time. Extent limits for volume sets can be set only on the root volume. Values set on secondary volumes are ignored. 7.6 RELABEL GETPARM If you specified RELABEL as the function on the FUNCTION GETPARM, you will be presented with the RELABEL GETPARM. The RELABEL GETPARM gives you basic facts about the size and location of the virtual disk. It also asks you to enter the new name for the virtual disk. This name will be used for both the file name of the virtual disk and its VOL1 label. 7.7 COPY GETPARM If you specified COPY as the function on the FUNCTION GETPARM, you will be presented with the COPY GETPARM. The COPY GETPARM gives you basic facts about the size and location of the virtual disk. In addition, it also requires the following input: ______________________________________________________________________________ Defining Virtual Disks 7-5 Field Description NEWVOL Specify the name for the new virtual disk. This name will be used for the virtual disk file name and the VOL1 label of the virtual disk. NEWDISK Specify the volume label of the real disk volume that is to contain the copy of the virtual disk. The default is the same volume as the input virtual disk. NEWSIZE Specify the size in megabytes of the output virtual disk. This size must be equal to or greater than the size of the input virtual disk. 7.8 SCRATCH GETPARM If you specified Scratch as the function on the FUNCTION GETPARM you will be asked to verify that you wish to scratch the specified virtual disk. Press PFKEY 3 to continue. Press PFKEY 1 to abort the scratch operation. 7.9 PAGEPOOL GETPARM Requesting a page pool on the CREATE or REFORMAT GETPARM causes the display of the PAGEPOOL GETPARM, which requests the size of the page pool. The description of DISKINIT in the VS System Utiilities Reference provides a full discussion of estimating page pool sizes. 7.10 ACCESSING VIRTUAL DISKS After defining a virtual disk, you make it available for I/O by 1. Physically mounting the physical volume on which the virtual disk resides. You mount the volume on a drive that is logically connected (by a CONNECT directive) to a virtual disk handler. 2. Connecting (by a CONNECT directive) the virtual disk to a virtual machine. 3. Logically mounting the virtual disk. This step is necessary only if in step 2 you connect the virtual disk to a virtual machine that is running under Release 6.43 of the VS Operating System. The procedure for logically mounting a virtual disk is explained in Section 4.6.3. ______________________________________________________________________________ Defining Virtual Disks 7-6 8.5.1 Ports and Plugs Use the following configuration when establishing VSDISK. - Number of Ports: 1 - Port Type: Disk - Number of Plugs: Up to 256 - Plug Type: Disk - VDEV Model: VSDISK 8.5.2 User Benefits By allowing a single disk to be shared among several virtual machines, the virtual disk handler eliminates the need and expense of purchasing additional disks to support the multi-machine environment. The virtual disk handler also allows real disk resources to be allocated as required to different virtual machines and can improve performance slightly by channel scheduling in the Control Program (CP). 8.5.3 Restrictions Plug 0 of a virtual disk handler is never assigned to a virtual disk. Plug 0 is assigned to the physical disk volume mounted on the drive that is connected to the virtual disk handler. When plug 0 is connected to a VM, that VM can access all the blocks (i.e., any virtual disk) on the physical volume. For security reasons, it is not advisable to connect plug 0 to a virtual machine. Disconnect plug 0 for maximum security. The VS/OS definition in GENEDIT must correctly match the type of the real disk if plug 0 is connected. Failure to adhere to this restriction will cause unpredictable results. 8.5.4 Sample Configuration Directives Listed below are sample configuration directives for VSDISK. DEFINE VDEV VDISK01 VSDISK CONNECT DISK01 VDISK01[0] CONNECT VDISK01[0] PVMVIOP0[1] /*Unless maximum security desired CONNECT Virtdiskl PVMVIOP0[3] . . . CONNECT Virtdiskn PVMVIOP8[2] Virtdisk1 through Virtdiskn are the names of files in library @VMDISK@ on the physical volume. To view the files, use the LIST VDSK command. For a complete discussion of virtual disks, see Chapter 7. ______________________________________________________________________________ Virtual Device Specifications 8-5 8.6 VIRTUAL DISK CACHE (WORKCACHE) The virtual disk cache provides caching of the most recently used disk blocks in main memory. Each WORKCACHE reserves 256K of absolute memory (from the VM memory pool) for caching purposes. The entire port volume VTOC is maintained in memory and the remaining memory is used to retain the most recently referenced disk blocks. 8.6.1 Ports and Plugs Use the following configuration when establishing WORKCACHE. - Number of Ports: 1 - Port Type: Disk - Number of Plugs: 1 - Plug Type: Disk - VDEV Model: WORKCACHE 8.6.2 User Benefits By connecting WORKCACHE to a relatively small volume (128 MB or less), you can reduce compile, assembly, and program run times in a program development environment. WORKCACHE is generally effective in any environment where the work volume is frequently referenced. 8.6.3 Restrictions Several restrictions are now enforced by the VDEV handler. Connecting a WORKCACHE VDEV to a WORKCACHE is no longer allowed and results in the message: 'Incompatible plug types'. After a disk is connected to a WORKCACHE, volume is checked for compatibility. If the volume is compatible with WORKCACHE, no messages are displayed and I/Os begin to be cached. If the volume is not compatible, an appropriate message is posted to the EVENT LOG and WORKCACHE becomes INACTIVE, passing all I/Os through unaltered. If WORKCACHE has been INACTIVE, the connection of a new, compatible disk will result in a message that the WORKCACHE is now ACTIVE. The following are the conditions that must be met for a volume to be compatible: - The volume must be less than 128MB in size. - The VTOC of the volume must contain fewer than 127 blocks. - The volume must not be a member of a Multi-volume Fileset. - The volume must not contain any libraries other than @SYSDUMP when connected. ______________________________________________________________________________ Virtual Device Specifications 8-6 Because WORKCACHE maintains VTOC in memory, there is no advantage to using WORKCACHE with VSCACHE. 8.6.4 Sample Configuration Directives Listed below are sample configuration directives for WORKCACHE. DEFINE VDEV VOLWCACHE WORKCACHE CONNECT VOLW VOLWCACHE[O] CONNECT VOLWCACHE[0] PVMVIOP8[3] 8.6.5 Possible EVENT Messages VIO0000 Workcache ACTIVE, is connected. VIO9000 Workcache INACTIVE, the VTOC of is too large. VIO9001 Workcache INACTIVE, is too large. VIO9002 Workcache INACTIVE, may contain only @SYSDUMP. VIO9003 Workcache INACTIVE, may not belong to an MVF set. ______________________________________________________________________________ Virtual Device Specifications 8-6.1 8.10 IMAGE MULTIWORKSTATION (IWS) The image multiworkstation (IWS) makes it possible to share a 4250IMG workstation between several virtual machines, because an image multiworkstation has one port and multiple plugs. An image multiworkstation can handle up to four windows. 8.10.1 Ports and Plugs Use the following configuration when establishing IWS. - Number of Ports: 1 - Port Type: Serial - Number of Plugs: Up to 4 - Plug Type: Serial - VDEV Model: IWSl, IWS2, IWS3, IWS4 8.10.2 User Benefits The image multiworkstation allows the user to connect a single 4250IMG workstation to up to four different virtual machines. 8.10.3 Restrictions VS WIIS workstation microcode (@4250IMG) must be present on the system. Workstations supported by this microcode are PCs configured as WIIS workstations per the WIIS Workstation emulation CSRN. ______________________________________________________________________________ Virtual Device Specifications 8-2 8.10.4 Sample Configuration Directives Listed below are sample configuration directives for IWS. DEFINE RIOP RIOP3 23V97W 3 DEFINE RDEV WS34 SERDEV RIOP3 4 DEFINE VDEV IWS34 IWS2 /* IMAGE w/s with two windows CONNECT WS34 IWS34[0] DEFINE VIOP VMlVIOP2 23V97W DEFINE VIOP VM2VIOP2 23V97W CONNECT VMlVIOP2 VM1[2] CONNECT VM2VIOP2 VM2[2] CONNECT IWS34[0] VMlVIOP2[0] /* Connect window 0 to VMl CONNECT IWS34[1] VM2VIOP2[0] /* Connect window 1 to VM2 Note: Each window must be configured to the VS (GENEDIT) as a single window 4250IMG. Failure to do so will result in improper operation of the physical workstation. ______________________________________________________________________________ Virtual Device Specifications 8-3 CHAPTER 10 VMPERF - Subroutine Package for Retrieving VM Performance Data 10.1 INTRODUCTION In order to allow VM users to develop applications that archive and analyze VM performance data, the VMPERF subroutine package has been developed and is now distributed with the VM product. VMPERF provides an easy to use set of subroutines that are linked with the user's application. The user's application is responsible for taking samples at the required intervals, retrieving the sampled data, making any required calculations, and displaying or archiving the data in the desired format. The VMPERF package consists of the following files: VMPERF - an object code file containing the VMPERF subroutines VMPA - a VS assembler copy file that defines the VMPERF record and VMPERF errors VMPC - a C include file that defines the VMPERF record and VMPERF errors TSTVMPA - a VS assembler program that demonstrates the calling of the VMPERF subroutines TSTVMPC - a C program that retrieves VM performance data and displays it on the workstation The VM INSTALL and UPGRADE procedures copy VMPERF into the VSSUBS library on the VM IPL volume. TSTVMPA and TSTVMPC are installed in @VMPROG@ on the VM IPL volume. VMPA and VMPC are installed in @MACLIB@ on the VM IPL volume. ______________________________________________________________________________ VMPERF 10-2 10.2 Subroutine Calls The following subroutines are all contained in the VMPERF module. Their linkage convention conforms to the Common Language Environment. They are callable by any language that passes parameters by reference. Register 1 must point to a list of addresses, which in turn point to the passed variables. If errors are encountered, they will be indicated in the RETCODE parameter. Error codes are defined in the include files. VMPERF("OPEN ",RETCODE,VMPVERS) Where: "OPEN " is capital ASCII characters "OPEN" filled with two ASCII blanks. RETCODE is a 32 bit integer that will contain zero on successful completion or a number indicating the error code on failure to open VMPERF. VMPVERS is a 32 bit integer that will indicate to VMPERF the version of the data formats. Currently the only supported version is one. VMPVERS is defined in the VMPA and VMPC include files. The user of VMPERF must call this entry point once in order to initialize the VMPERF interface. The version number passed will be checked for compatibility with the linked subroutines. The version number is hard coded in the INCLUDE files distributed with the product. Besides checking version compatibility, this routine will initialize the VRM interface that is used for retrieving data from the VM kernel. VMPERF("SAMPLE",RETCODE) Where: "SAMPLE" is capital ASCII characters "SAMPLE". RETCODE is a 32 bit integer that will contain zero on successful completion or a number indicating the error code on failure to retrieve the VM performance data from the VM kernel. A call to this subroutine will cause data to be collected from the VM kernel using a VRM call. All data items will be collected each time this routine is called. These data items will be held by VMPERF and returned to the calling program via VMPERF READ calls. ______________________________________________________________________________ VMPERF 10-3 VMPERF("READ ",RETCODE,TYPE,PERFREC) Where: "READ " is capital ASCII characters "READ" with two ASCII blanks at the end. RETCODE is a 32 bit integer that will contain zero on successful completion or a number indicating the error code on failure to return a VMPERF record. TYPE is a four character parameter that specifies the type of VMPERF record that is to be returned. The valid types are: " " return the next sequential record "CPU " return the next sequential CPU utilization record "RIOP" return the next sequential RIOP I/O count record "VM " return the next sequential VM I/O count record "RDEV" return the next sequential RDEV I/O count record (DISK and TAPE are the two models of RDEV for which VM maintains counts) "VIOP" return the next sequential VIOP I/O count record PERFREC is the data area that will contain the returned VMPERF data record on successful completion. Each call to this subroutine will return a single record described in VMPDATA. The first call after a VMPERF SAMPLE or VMPERF RESET will return the first record of the sampled data that matches the TYPE parameter passed. The order of records in the sample is not specified. Each subsequent call will return the next sequential record that matches the specified type. If all records have been read, an EOF indication will be returned in RETCODE. The calling program should call VMPERF SAMPLE or VMPERF RESET before changing TYPE in order to avoid skipping records. ______________________________________________________________________________ VMPERF 10-4 VMPERF("RESET ",RETCODE) Where: "RESET " is capital ASCII characters "RESET" with an ASCII blank at the end. RETCODE is a 32 bit integer that will contain zero on successful completion or a number indicating the error code on failure to reset the VMPERF pointer. A call to this subroutine will reset the current record pointer to the beginning of the sample. A new sample will not be taken. The next call to VMPERF READ will return the first record of the sampled data. VMPERF("CLOSE ",RETCODE) Where: "CLOSE " is capital ASCII characters "CLOSE" with an ASCII blank at the end. RETCODE is a 32 bit integer that will contain zero on successful completion or a number indicating the error code on failure to close VMPERF. A call to this subroutine will return free memory used by VMPERF and close the VRM connection. VMPCVTOD(TOD,YYMMDD,HHMMSS) Where: TOD is an eight-byte VM time-of-day value. YYMMDD is a six character field that will contain the date that is represented by the TOD value after successful completion of this subroutine call. HHMMSS is a six character field that will contain the time of day on the date YYMMDD that is represented by the TOD value after successful completion of this subroutine call. This subroutine will convert VM time-of-day values to printable format. No errors are returned. If the passed TOD is zero or too large for division (first byte must be zero) a value of 000000 is returned for both YYMMDD and HHMMSS. VM time-of-day values are eight-byte integers that represent the number of 2.5 MHz clock ticks since 00:00:00 on 01/01/1900. VMPTOD in VMPDATA is a VM time-of-day value. CPU utilization times, VMPTIME in VMPDATA, can also be converted to printable durations using this subroutine. Remember that such durations are relative to 000000 (HHMMSS) on 000101 (YYMMDD). ______________________________________________________________________________ VMPERF 10-5 VMPC4TOD(TOD,YYYYMMDD,HHMMSS) This subroutine has the same purpose and is used the same as VMPCVTOD except that an eight character field is returned as the second parameter. If the TOD value that is passed represents a two digit year, the VM TOD epoch is assumed to be 01/01/1900. In this case VMPC4TOD will assume the first two digits of the year to be 19 if the second two digits are less than 51. If the second two digits are greater than 50, the first two digits of the year are assumed to be 20. If the TOD value that is passed represents a four digit year, the VM TOD epoch is assumed to be 01/01/0000. In this case VMPC4TOD will return the exact conversion of the TOD passed. 10.3 Data Items VMPTYPE is a 32 bit unsigned integer that denotes which type of VMPERF record has been read. It has two possible values, VMPCPU (value of one) and VMPIO (value of two). A VMPCPU record contains information about CPU utilization. A VMPIO record contains information start I/O counts for a particular resource. VMPTOD is a VM time-of-day value. VM time-of-day values are eight-byte integers that represent the number of 2.5 MHz clock ticks since 00:00:00 on 01/01/1900 or 01/01/0000 depending on whether a two or four digit year was entered using the SCU or the VM time prompt at IPL. VMPTOD is the time of day when the VMPERF sample was taken. All records in a given sample will have the same VMPTOD value. VMPTOD can be converted to an ASCII date and time using the VMPCVTOD subroutine or the VMPC4TOD subroutine. VMPNAME is the sixteen character name of the resource. For a VMPCPU record the possibilities are VMCPU0, CPCPU0, WAITCPU0, or VM name. If VMPNAME is VMCPU0, then VMPTIME contains the number of 2.5 MHz clock ticks used by all virtual machines since VM was IPLed. If VMPNAME is CPCPU0, then VMPTIME contains the number of clock ticks used by the VM control program since IPL. If VMPNAME is WAITCPU0, then VMPTIME contains the number of clock ticks that the real machine has spent in wait since IPL. Any other value in VMPNAME is a virtual machine name. If VMPNAME is a VM name, then VMPTIME contains the number of clock ticks used by that virtual machine since VM was IPLed. The sum of all VM times will equal the time used by VMCPU0. ______________________________________________________________________________ VMPERF 10-6 For a VMPIO, record VMPNAME contains the resource name of the RIOP, VIOP, virtual machine, or RDEV. RDEV I/O counts are only maintained for disk and tape RDEVs. The VMPMODEL field will indicate which type is returned. A VMPIO record will not contain the VMPTIME field, but in its place it will have VMPMODEL, VMPIOTYP, and VMPIOCNT. VMPTIME occupies the last 8 bytes of a VMPCPU record. It contains an integer that represents the number of 2.5 MHz clock ticks used by this resource since VM was IPLed. The last 20 bytes of a VMPIO record contain three fields. VMPMODEL is a 12 character field that denotes the model of the resource. A VM record may have a model of VS7310, for example. An RIOP may be 23V98. A VIOP may also be 23V98. An RDEV may only be DISK or TAPE. VMPIOTYP is a 4 character field that indicates the type of I/O resource being reported on by this record. The possible values are VM, VIOP, RIOP, and RDEV. VMPIOCNT is a 32 bit unsigned integer. If VMPIOTYP is VM, then VMPIOCNT contains the number of start I/O instructions issued by the named virtual machine since it was defined. If VMPIOTYP is VIOP, then VMPIOCNT contains the number of start I/O instructions issued to this VIOP since it was defined. If VMPIOTYP is RIOP, then VMPIOCNT contains the number of start I/O instructions issued to this RIOP since VM was IPLed. If VMPIOTYP is RDEV, then VMPIOCNT contains the number of start I/O instructions issued to this disk RDEV since VM was IPLed. Note: It is possible for VMPIOCNT values to "wrap". You must be sure to sample the data often enough so that it does not wrap twice in the same sample. If incremented 1000 times per second, a 32 bit integer will wrap in about 50 days. The assembler instruction subtract logical (SL or SLR) will yield a correct difference between two samples even if the counter has wrapped once. ______________________________________________________________________________ VMPERF 10-7 10.4 Errors ERRDEFIN indicates that VMPERF was unable to define the VRM mailbox that is used to communicate with the VM control program. Any virtual machine that runs VMPERF must have VM IPC privileges. ERRCONN indicates that VMPERF was unable to connect to the VM control program via the VRM mailbox. ERRRCV indicates that VMPERF got an error on an IPC receive while communicating with the VM control program through the VRM mailbox. ERRSEND indicates that VMPERF got an error on an IPC send while communicating with the VM control program through the VRM mailbox. ERRALLOC indicates that VMPERF got an error on an OS GETHEAP call trying to obtain free memory for storing the performance data retrieved from the VM control program. ERRREAD indicates that VMPERF got an error on an IPC read while communicating with the VM control program through the VRM mailbox. ERROPT indicates that the first parameter passed to VMPERF is not one of the valid VMPERF options. Make sure that the first parameter is the address of a 6 character field containing upper case ASCII characters and blanks. ERROPND indicates that a second call was made to VMPERF OPEN after VMPERF was already opened. ERRNOPN indicates that a VMPERF call, other than OPEN, was made prior to a VMPERF OPEN call. ERRNSAMP indicates that a call to VMPERF READ was made before a call to VMPERF SAMPLE. There is no data to read before a sample is taken. ERRVERS indicates that the version passed on the VMPERF OPEN call is not a supported version. ERREOF indicates that all records of the specified type have already been returned by VMPERF READ. Be sure to call VMPERF RESET before changing types. ______________________________________________________________________________ VMPERF 10-8 10.5 Sample Assembler Program * The CALLR macro is included to facilitate compliance with the * required calling convention in assembler * MACRO CALLR &NAME,&ARG .* .* The &NAME parameter may be specified as: .* .* NAME which generates JSI =V(NAME) .* *NAME which generates JSI =A(NAME) .* $NAME which generates JSI NAME .* .* The argument &ARG may be specified as a sublist to .* accommodate multiple arguments. .* .* ARG which generates PUSHA 0,ARG .* $(reg) which generates PUSH 0,reg .* $ARG which generates PUSHC 0(4,0),ARG .* (reg) which generates PUSH 0,reg In setup .* PUSHA 0,-- In parameter list .* POP 0,reg In post processing .* .* NOTE: to specify a single register parameter, code ((ARG)). .* LCLA &WORD Count of words built on stack LCLA &I,&J,&K Work registers LCLA ®WORD(16) Relative position of register value LCLC ®NAME(16) LCLC &TEMP .* .* Run through parameter list and stack any register parameters. .* .PRELOOP ANOP , &I SETA &I+1 AIF (N'&ARG EQ 0).GENCALL Skip all this if no parameters AIF (&I GT N'&ARG).PARMLOOP If end of list go to next phase .* &TEMP SETC '&ARG(&I)' AIF ('&TEMP'(1,1) NE '(').PRELOOP Loop if not a reg &J SETA K'&ARG(&I) &K SETA &J-2 AIF ('&TEMP'(&J,1) NE ')').PRELOOP &TEMP SETC '&TEMP'(2,&K) ®NAME(&I) SETC '&TEMP' PUSH 0,&TEMP Stack register argument &WORD SETA &WORD+4 ®WORD(&I) SETA &WORD .* AGO .PRELOOP ______________________________________________________________________________ VMPERF 10-9 .* .* Run through parameter list and build the pointer list. .* .PARMLOOP ANOP , AIF (&I NE N'&ARG).NOTLAST If "last" in list OI 0(15),X'80' Set list delimiter .NOTLAST ANOP , &I SETA &I-1 AIF (&I EQ 0).GENJSI .* AIF ('®NAME(&I)' EQ '').PARM10 If not a reg PUSHA 0,&WORD-®WORD(&I).(15) Stack --> reg value &WORD SETA &WORD+4 AGO .PARMLOOP .* .PARM10 ANOP , &TEMP SETC '&ARG(&I)' Need workink copy .* AIF ('&TEMP'(1,1) NE '$').PARM20 If not indirect &TEMP SETC '&TEMP'(2,255) Strip off "$" AIF ('&TEMP'(1,1) EQ '(').PARM15 .* PUSHC 0(4,0),&TEMP Stack argument &WORD SETA &WORD+4 AGO .PARMLOOP .* .PARM15 ANOP , PUSH 0,&TEMP Stack argument &WORD SETA &WORD+4 AGO .PARMLOOP .* .PARM20 ANOP , PUSHA 0,&TEMP Stack --> parm &WORD SETA &WORD+4 AGO .PARMLOOP .* .* Now generate the call. .* .GENJSI ANOP , LR 1,15 Set --> parameter list .* .GENCALL AIF ('&NAME'(1,1) NE '*').GEN10 &TEMP SETC '&NAME'(2,255) JSI =A(&TEMP) AGO .GENFIN .* .GEN10 AIF ('&NAME'(1,1) NE '$').GEN20 &TEMP SETC '&NAME'(2,255) JSI &TEMP AGO .GENFIN ______________________________________________________________________________ VMPERF 10-10 .* .GEN20 ANOP , JSI =V(&NAME) .* .GENFIN AIF (N'&ARG EQ 0).EXIT &I SETA N'&ARG POPN 0,&I*4 .* .POSTLOOP AIF ('®NAME(&I)' EQ '').POST10 .* POP 0,®NAME(&I) .POST10 ANOP , &I SETA &I-1 AIF (&I GT 0).POSTLOOP .* .EXIT MEXIT MEND * * Sample ASSEMBLER program to illustrate the VMPERF calling * convention * TSTVMPA CSECT USING *,R12 RLA R12,* LR R13,R14 AL R13,=R($TSTVMP) USING $TSTVMP,R13 CALLR VMPERF,(=C'OPEN ',RC,VMPVERS) CALLR VMPERF,(=C'SAMPLE',RC) CALLR VMPERF,(=C'READ ',RC,TYPE,PERFREC) LA R6,PERFREC USING VMPDATA,R6 CALLR VMPCVTOD,(VMPTOD,YYMMDD,HHMMSS) CALLR VMPERF,(=C'RESET ',RC) CALLR VMPERF,(=C'CLOSE ',RC) RT ADDRAREA DS 0F LTORG COPY VMPA $TSTVMP STATIC RC DS F YYMMDD DS CL6 HHMMSS DS CL6 * * TYPE of READ: blank is next sequential record * 'CPU' is next CPU utilization record (CPCPU, VMCPU, * WAITCPU, or VM time) * 'RIOP' is RIOP I/O count * 'VIOP' is VIOP I/O count * 'RDEV' is RDEV I/O count * 'VM ' is VM I/O count TYPE DC CL4' ' PERFREC DS CL(VMPDATAL) REGS END ______________________________________________________________________________ VMPERF 10-11 10.6 Sample C Program /* This program illustrates how to call the VMPERF subroutines from a C program. It asks the user for a record type. It then retrieves all records of that type and prints them on the workstation. After 21 records and at end of file it puts a read up at the workstation to allow the user to scan the data. The call to VMPERF RESET is provided merely as an example, it is of no value to this program. */ #include "STDIOH" #include "VMPC" tstvmpc() /* TYPE of READ: blank is next sequential record 'CPU' is next CPU utilization record (CPCPU, VMCPU, WAITCPU, or VM time) 'RIOP' is RIOP start I/O count 'VIOP' is VIOP start I/O count 'RDEV' is RDEV start I/O count 'VM ' is VM start I/O count */ VMPDATA perfrec; long rc; char eofchar; char YYMMDD[7]; /* C wants null terminated */ char HHMMSS[7]; /* strings */ char NAME[17]; char IOTYP[5]; char IOMODEL[13] char rectype[5]; long x; long linectr; ______________________________________________________________________________ VMPERF 10-12 vmperf("OPEN ",&rc,&VMPVERS); vmperf("SAMPLE",&rc); printf("Enter record type (4 chars):\n"); scanf("%s",rectype); for(x = 0;x < 4;x++) rectype[x] &= 0xFF - 0x20; /* Make upper case */ if(rectype[x] == '\0') rectype[x] = ' '; /* Pad with blanks */ vmperf("READ ",&rc,rectype,&perfrec); vmpcvtod(perfrec.VMPTOD,YYMMDD,HHMMSS); do for(linectr=1;(linectr < 22)&(rc != ERREOF);linectr++) for(x = 0;x < 16;x++) NAME[x] = perfrec.VMPNAME[x]; printf("%d %s %s %s ",perfrec.VMPTYPE,YYMMDD,HHMMSS,NAME); if(perfrec.VMPTYPE == VMPCPU) printf("%d %d\n",perfrec.VMPREDEF.CPUREC.VMPTIME[0], perfrec.VMPREDEF.CPUREC.VMPTIME[1]); else for(x = 0;x < 4;x++) IOTYP[x] = perfrec.VMPREDEF.IOREC.VMPIOTYP[x]; for(x = 0;x < 12;x++) IOMODEL[x] = perfrec.VMPREDEF.IOREC.VMPMODEL[x]; printf("%s %s %d\n",IOTYP,VMPMODEL, perfrec.VMPREDEF.IOREC.VMPIOCNT); vmperf("READ ",&rc,rectype,&perfrec); printf("Press RETURN to continue:"); eofchar = getc(stdin); while(rc != ERREOF); vmperf("RESET ",&rc); vmperf("CLOSE ",&rc); ______________________________________________________________________________ VMPERF 10-13 10.7 Assembler Copy File VMP DS 0F * * Errors returned by VMPERF * ERRDEFIN EQU 1 Unable to define VRM mailbox ERRCONN EQU 2 Unable to connect VRM mailbox ERRRCV EQU 3 IPC receive error ERRSEND EQU 4 IPC send error ERRALLOC EQU 5 Memory allocation error ERRREAD EQU 6 IPC read error ERROPT EQU 7 Invalid VMPERF request ERROPND EQU 8 VMPERF already opened ERRNOPN EQU 9 VMPERF not opened ERRNSAMP EQU 10 Sample not taken before READ ERRVERS EQU 11 Unsupported VMP version ERREOF EQU 12 End of file on READ * * Version number of this data description * VMPVERS DC F'1' * * Description of data record returned by VMPERF * VMPDATA DSECT Data record returned by VMPERF VMPTYPE DS F VMPERF record type VMPCPU EQU 1 CPU useage record VMPIO EQU 2 IO count record VMPTOD DS XL8 2.5 mhz TOD (1/1/1900 epoch) VMPNAME DS CL16 Name of resource * For CPU record: VMCPU0, CPCPU0, WAITCPU0, or VM name * For IO record: Name of resource * VMPREDEF DS 0H * The following section describes the remainder of a CPU record VMPTIME DS XL8 2.5 mhz ticks used by this * resource since IPL * * The following section describes the remainder of an IO record ORG VMPREDEF VMPMODEL DS CL12 Model of resource * DISK, TAPE, 23V98, ... VMPIOTYP DS CL4 Type of IO resource * VM, VIOP, RIOP, RDEV VMPIOCNT DS F SIO count for this resource ORG VMPDATAL EQU *-VMPDATA ______________________________________________________________________________ VMPERF 10-14 10.8 C Include File /* Errors returned by VMPERF */ #define ERRDEFIN 1 /* Unable to define VRM mailbox */ #define ERRCONN 2 /* Unable to connect VRM mailbox */ #define ERRRCV 3 /* IPC receive error */ #define ERRSEND 4 /* IPC send error */ #define ERRALLOC 5 /* Memory allocation error */ #define ERRREAD 6 /* IPC read error */ #define ERROPT 7 /* Invalid VMPERF request */ #define ERROPND 8 /* VMPERF already opened */ #define ERRNOPN 9 /* VMPERF not opened */ #define ERRNSAMP 10 /* Sample not taken before READ */ #define ERRVERS 11 /* Unsupported VMP version */ #define ERREOF 12 /* End of file on READ */ /* Version number of this data description */ long VMPVERS = 1; /* Description of data record returned by VMPERF */ typedef struct long VMPTYPE; /* VMPERF record type */ #define VMPCPU 1 /* CPU useage record */ #define VMPIO 2 /* IO count record */ unsigned long VMPTOD[2]; /* 2.5 mhz TOD (1/1/1900 epoch) */ char VMPNAME[16]; /* Name of resource */ /* For CPU record: VMCPU0, CPCPU0, WAITCPU0, or VM name For IO record: Name of resource */ union /* Start of record variant */ /* The following section describes the remainder of a CPU record */ struct unsigned long VMPTIME[2]; /* 2.5 mhz ticks used by this */ /* resource since IPL */ CPUREC; /* The following section describes the remainder of an IO record */ struct char VMPMODEL[12]; /* Model of resource i.e. DISK, TAPE, 23V98, ... */ char VMPIOTYP[4]; /* Type of IO resource */ /* VM, VIOP, RIOP, RDEV */ unsigned long VMPIOCNT; /* SIO count for this resource */ IOREC; VMPREDEF; VMPDATA; ______________________________________________________________________________ VMPERF 10-15 CHAPTER 11 VMOPTS - Utility for Setting VS/VM IPL Parameters 11.1 INTRODUCTION In order to allow one installation to have more control over the operation of its VS/VM system the VMOPTS utility is provided. This utility will allow the system administrator to set some of the runtime parameters that control the initialization of VS/VM. These include: - Control I/O and Static File Tracing - Control Operator Memory Allocation - Control Real Machine Debugging To invoke the VMOPTS utility run VMOPTS in the VM release library (VM020202, for example) on the volume where VS/VM was installed. The first display shows the default VS/VM system file and assigns PFKEYS to the various functions. If VS/VM is not installed on the same volume as the VS/OS, correct the volume assignment. The default library, @SYSTEM@, and the default file name, @SYSVM12 (depending on CPU type), should be correct. Select a PFKEY to perform the desired function. Possible errors are: File not found The VM system file as entered could not be found. VM Version not supported by VMOPTS The specified VM system file is not supported by this version of VMOPTS. Undefined PFKEY The user has entered an unassigned PFKEY. 11.2 CONTROL I/O AND STATIC FILE TRACING VS/VM is shipped with I/O and Static File tracing enabled. This has been done to aid Wang maintenance personnel in problem determination if VS/VM fails and a dump is sent to Wang for analysis. This tracing uses 2K of memory and CPU cycles to create trace entries for each physical I/O operation initiated and completed, and each call for and return of Static File memory. By disabling tracing your system will use 2K less Static File and will run slightly faster. Please be aware that if you disable tracing and experience a problem that you wish to have Wang analyze, the dump may not contain all of the information required to solve the problem. You may be asked to enable tracing and obtain another dump by recreating the problem. ______________________________________________________________________________ VMOPTS 11-2 11.3 CONTROL OPERATOR MEMORY ALLOCATION The VS/VM Operator runs in its own virtual machine. When the VS/VM kernel is IPLed it initializes this virtual machine, connects a workstation, loads the standalone operator program into the virtual machine, and starts its execution. The operator virtual machine is initialized according to the values contained in low memory of VS/VM and according to certain defaults. If VS/VM is IPLed with the defaults, the following rules apply: - If the physical machine is over 64 megabytes, the OPERATOR is defined as a non-pageable virtual machine with 1 megabyte of memory. - If the machine is 64 megabytes or less, the OPERATOR is defined as a pageable VSE virtual machine with 1 megabyte of virtual memory using 128 kilobytes of physical memory. The 1 megabyte of virtual memory actually resides in the file @VMPAG in @VMDISK@ on the VM IPL volume. You may alter these defaults using the VMOPTS utility. If the operator is made non-pageable, the standalone operator will execute much faster. For most functions the operator only requires 256 kilobytes (X'40000') of physical memory, if non-pageable, or virtual memory, if pageable. The only known exception is MAPLOAD of a large map file. If the operator is made smaller than the default 1 megabyte, less physical memory will be occupied if the operator is non-pageable, or less virtual memory will be used if the operator is pageable. Virtual memory occupies space on disk in the file @VMPAG in @VMDISK@ on the VM IPL volume. If the operator is given less than 256 kilobytes of memory, the system may not IPL. Changing these defaults does not affect the VM program that runs under the VS/OS. You cannot make the operator pageable if your real machine is over 64 megabytes. 11.4 CONTROL REAL MACHINE DEBUGGING VS/VM has a facility to display and alter the contents of real memory. This is done by entering the DEBUG REAL.MACHINE command from the operator or VM program. The VMOPTS utility must be used to enable this facility. If this facility is enabled, any user who can run the VM program or has access to the VM operator has the ability to crash the VM kernel or to display secure data in memory. Enabling this facility may be an unacceptable security risk in many installations. Enabling real machine debugging also has the following side effect: The device handlers for the serial VIOP, the disk VIOP, the tape VIOP, and the SCSI VIOP will allow dump IOCWs to be passed through to the real IOP. While this does allow a virtual machine to obtain a dump of the IOP it may also adversely affect devices attached to the real IOP. Some of these devices may be attached to other virtual machines. ______________________________________________________________________________ VMOPTS 11-3