Skip to main contentIBM ZLPN Documentation

User's Guide and Reference for IBM z/VM Remote Access Programs

Preface

This document is intended to assist the user in accessing and using the z/VM Remote Development system. It covers all supported versions of z/VM. For terminology used in this document, please refer to Appendix B: Terms and definitions on page 34. For assistance, please refer to Technical support

Table of contents

1 Environment overview

The z/VM remote access environment is provided by the IBM Z and IBM LinuxONE Partner Network in conjunction with various IBM development laboratories. z/VM is an operating system from IBM which runs on IBM Z hardware that allows one physical processor complex to be configured with multiple "virtual" processors or machines. Each virtual machine, known as a guest, runs independently of every other virtual machine, and can run any IBM Z operating system (z/OS, z/VM, Linux on Z, CMS, etc.) and software. Please refer to the IBM Redbook Introduction to the New Mainframe: z/VM Basics SG247316 http://www.redbooks.ibm.com/redbooks/pdfs/sg247316.pdf

The remote access program is implemented using z/VM on an IBM Z processor to provide users with their own guest systems, each capable of supporting multiple users in a unique environment. Each remote access participant is provided with a dedicated guest system, accessible via the internet, which appears to the user as an IBM Z server running a native z/VM operating system.

1.1 System availability

Each Sunday, a maintenance window is reserved between 9:30 AM and 3:30 PM U.S. Central Time for hardware maintenance purposes. During this window, system access may not be available. The current maintenance schedule is bi-weekly with the exception of holidays. IBM sends optional notifications concerning upcoming maintenance windows or changes to support schedules. To be added to the notification list, please open a case in IBM Support by selecting "Other contracted support services" in the Type of Support field, "IBM Z and LinuxONE Partner Network" in the Service field, and “Maintenance Notification” in the Case Title.

1.2 System Backups

Participants are responsible for retaining and protecting their own data. The data stored in the remote access environment should never be the only copy. IBM may perform, but is under no obligation to perform, regular backups of the data disks for the remote access environments using tape media that is stored on-site. The purpose of any such backup is to provide a level of opportunity for the recovery of content in the event of a catastrophic hardware failure. IBM makes no guarantees that recovery of data will be possible. Such backups, if any, will be performed at the disk volume level and scheduled to expire after 90 days, after which time the backup content will be deleted. Copies of backups are not available to Participant. Any Participant content in backup at the time of cancellation or termination will remain in backup until the specified expiration date and be deleted in accordance with standard backup handling procedures. If requested, IBM will exclude Participant’s guest environment from the backup cycle. To request such exclusion, submit a case in IBM Support by selecting "Other contracted support services" in the Type of Support field and "IBM Z and LinuxONE Partner Network" in the Service field. IBM will confirm in writing Participant's virtual environment system has been excluded from the backup cycle.

2 Technical support

Technical and administrative support is available from 07:00 to 19:00 U.S. Central time Monday through Friday only. To receive technical support, open a case in IBM Support by selecting "Other contracted support services" in the Type of Support field and "IBM Z and LinuxONE Partner Network" in the Service field. Reference the CSP Quick Start Guide for additional instruction on working with technical support cases.

3 Connecting to the Guest System

3.1 User IDs

Accessing the guest system will require use of several IDs:

All participants are provided a guest z/VM system ID which is the guest z/VM system. All of the z/VM Personal user IDs provided as part of this program have the authority to activate the guest z/VM system IDs by way of the SVXLOG command. Once the Solution Developer activates the guest z/VM system ID, the user ID that does the activation becomes the z/VM control user ID (using the z/VM SECUSER function). This z/VM control user ID is the only user ID that can send commands to the guest z/VM system. This is done via the z/VM SEND command. The z/VM control user ID will remain the same until it is changed by someone with proper authority.

The guest z/VM system ID has the format ETPGVyy and the z/VM Personal user ID and z/VM control user ID has the format ETPDxxx.

3.2 TN3270 emulators

A TN3270 emulator is required to connect to the guest system. The TN3270 emulator must be SSL capable. Consult the TN3270 emulator documentation to determine the appropriate key sequences required for the ENTER, PA2, F12 and CLEAR functions.

Note: IBM Corporation has taken steps to enhance the security of the internet connections to the remote access systems, by blocking various ports from "INBOUND" traffic. Information about the blocked ports can be found at

3.3 Connecting to the guest system

Perform the following steps to connect to the guest system:

  1. Direct an SSL enabled TN3270 connection to URL dtsc.dfw.ibm.com, port 65512. The Remote Access Portal screen displays.
    SSL Portal
    Figure 1 SSL Portal Screen Shot

  2. Choose from the systems available by typing their name (VH1, VH2, etc.) and pressing the ENTER key.

  3. The next screen displayed will be a system LOGO indicating that the server has been reached.
    z/VM LOGO Screen
    Figure 2 z/VM LOGO screen example

  4. On the LOGO screen, logon to a z/VM Personal user ID by typing in a z/VM Personal user ID and password and pressing the ENTER key.

    • The password will be expired on first use of the z/VM Personal user ID or anytime after the password has been reset. The system will prompt a password change (as shown below).
    LOGON ETPDxxx
RPIMGR042I PASSWORD EXPIRED
To change your password - enter: nnn/nnn where nnn = new
password or, enter LOGOFF to cancel

    Enter a new password in the format of new_password/new_password and press the ENTER key. Entered text will not be visible to help assure the privacy of the z/VM Personal user ID password.

    PASSWORD RULES. The PASSWORD MUST:

    • Be eight characters in length
    • Only contain alphabetic, numeric and national characters i.e., $ # and @
    • Contain at least one alphabetic and one non-alphabetic character – A non-numeric first character
    • Contain no more than two identical consecutive characters
    • Not be reused until after at least eight iterations

  5. System “log messages” with information of general interest, are broadcast to all users on the system. Be sure to review the broadcast messages for important notices regarding scheduled outages. When the z/VM status indicator in the lower right-hand corner of the screen shows HOLDING or MORE..., press the CLEAR or PA2 key to continue.

Note: The CLEAR and PA2 keys are part of the IBM 3270 terminal architecture. Refer to the TN3270 emulator's documentation for information on these keys.

  1. Successful logon has occurred when the screen displays the CMS ready prompt and the z/VM status indicator in lower right-hand corner shows Running SVSCxxx. The system can now be initialized as described in IPL the Guest z/VM system.

4 IPL the Guest z/VM system

This release of z/VM is capable of IPL without a dedicated system console. Therefore, it is no longer a requirement to logon to the guest system userid. It will still be necessary to DIAL the individual guest system userid executing z/VM in order to interact with applications running on a particular z/VM system. Logon to a userid executing z/VM is not required. The messages which result from the initialization of the system cover more than one screen. In this documentation, be careful to review all of the screen examples associated with a particular event. Each part contains important information describing the IPL of the guest z/VM system in this environment.

Note: The F12 key has been defined to retrieve the last command(s) entered. This will be handy as several of the next steps require users to enter various z/VM commands prefixed by the same z/VM command syntax.

  1. After logging on to the z/VM Personal user ID, initialize the guest z/VM system by typing SVXLOG guest system ID command at the CMS Ready Prompt and then press the ENTER key. For guest system ID ETPGVyy, type the following command and press the ENTER key:

    SVXLOG ETPGVyy

    Once the SVXLOG command is entered, this z/VM Personal user ID becomes the z/VM control user ID for the guest system ID.

    The guest z/VM system will return messages to the z/VM control user ID screen:

    IPL Messages Part 1
    Figure 3 (Part 1 of 2) Initial Messages during z/VM IPL

    IPL Messages Part 2
    Figure 4 (Part 2 of 2) Initial Messages during z/VM IPL

  2. Test sending a z/VM command to the OPERATOR userID of the guest z/VM system. Type the following z/VM command and press the ENTER key.

    SEND ETPGVyy \CP VI VMSG Q DA

    The guest z/VM system will return with the messages shown below:

    Quary DASD Resonse
    Figure 5 z/VM Query DASD Command Response

  3. The z/VM control user ID can be used to control the z/VM system OPERATOR userid commands using THE SAME METHOD SHOWN PREVIOUSLY DURING IPL.

The guest z/VM system is now up and running. The guest z/VM system can be utilized as described in How to LOGON to MAINTvvv. z/VM commands can be sent to the guest z/VM system. The z/VM control user ID will also receive messages from the guest z/VM system.

5 How to LOGON to MAINTvvv

The following sections describe using the z/VM DIAL command or a TN3720 client session connected directly to an IP address for accessing applications through a full screen interface. The sections continue by describing TELNET for accessing applications through a line mode interface.

Note: The vvv in MAINTvvv refers to the version and release of the z/VM operating system in use and is the modern ID used in administering z/VM. For example, a z/VM 7.3 system would log on to the MAINT730 ID.

5.1 Connecting using z/VM DIAL

  1. Connect to the remote access portal, as instructed in Connecting to the guest system.

  2. Select the IBM Z server on which the guest z/VM system was started.

  3. Connect using the DIAL command as described below:

    • Enter the z/VM DIAL command on the COMMAND line of z/VM logon screen, specifying the name of the guest z/VM system ID. The system will automatically connect the terminal to the first available terminal in the guest z/VM system. For example, to DIAL system name ETPGVyy, type the following command: 
      DIAL ETPGVyy

    Note: In some cases, the terminal may not be activated. If the terminal appears to hang after DIALing, try using the following command: SEND ETPGVyy \CP VI VMSG ENABLE ALL

  4. Respond to message E120001: Enter your USERID: with the z/VM Personal user ID. See the system delivery email for the list of z/VM Personal user IDs assigned for use in accessing the guest system.

  5. Respond to message Enter your password: with the password associated with that z/VM Personal user ID.

    Note: Initial passwords for the z/VM Personal user IDs have been set to expire immediately and must be changed during first logon and at least every 60 days thereafter. See the system delivery password email for details.

Password example
Figure 6 z/VM password example

The z/VM LOGO screen displays.

Logo screen for MAINT
Figure 7 Example of z/VM LOGO screen for MAINTvvv

  1. Type MAINTvvv for the userid, type in the guest system ID for the password, and press the ENTER key.

5.2 Connecting TN3270 client session directly to an IP address

Refer to the system delivery email to obtain the assigned TCPIP address. If the assigned IP address requires the use of Client VPN, refer to the system delivery email for instructions for downloading the Cisco VPN Client software and using it to log into the VPN.

Configure a TN3270 client session using the assigned IP address and port 23. By default, SSL is not enable on the system, so it should not be enabled on the 3270 emulator. Once the session is configured, select the option to connect to the system.

Once connected, follow the instructions above to logon to MAINTvvv. See Figure 7 above.

6 How To log off z/VM and the secure portal

When ready to log off z/VM and return to the first level z/VM dial screen, enter:

UNDIAL

from the z/VM logo screen and press the ENTER key. UNDIAL issues the RESET command to return to the z/VM dial screen, then enter:

VMEXIT

and press the ENTER key. This will drop the connection to the z/VM system and the secure portal.

VMEXIT command
Figure 8 VMEXIT Command From SVSCDR2 LOGO Screen.

7 Managing the guest z/VM system with SLEEP and BEGIN

Note: Each user is assigned a "virtual machine" under IBM's z/VM (Virtual Machine) operating system which runs continuously and accumulates chargeable CPU time regardless of actual use by interactive users, batch jobs, etc. The user's account will be charged for CPU time used by the virtual machine even if no users are logged on and no batch activity is recorded. See Accounting information for information on how to obtain current usage statistics using the SESSREPT command.

It is possible and highly recommended to put the guest z/VM system to "sleep" when not in use (e.g. overnight) without having to drain, halt, or quiesce the guest z/VM system. The effect of the z/VM CP SLEEP command is that of temporarily "freezing" the guest z/VM system with the ability to resume at that same point at a later time, and with the additional benefit of not using chargeable CPU cycles when they are not needed.

Failure to correctly logoff (terminate) the guest z/VM system's virtual machine or put it to sleep, will cause the machine to run (idle) and the user will be charged for the CPU cycles consumed by the virtual machine.

7.1 Putting the guest z/VM system to SLEEP

While it is possible to place the virtual machine in an inactive state at any time, it is highly recommended that all batch and interactive activity be quiesced first, and that subsystems be halted or quiesced if possible to reduce the "shock" of waking up several hours (or days) later. The effect is similar to pushing the "STOP" button on the processor system console. The base z/VM system and IBM subsystems are expected to recover without issue, however IBM cannot be responsible for adverse side effects in vendor software systems under these circumstances.

To put the system to sleep, issue the following command from the z/VM control user ID:

SEND ETPGVyy \CP SLEEP

To verify that the guest z/VM system is sleeping, issue the QSLEEP (Query SLEEP) command from any one of the z/VM Personal user IDs (i.e. the user IDs used for DIAL and/or online documentation) or the z/VM control user ID. Put the guest z/VM system to sleep as usual, wait at least 60 seconds and then issue the QSLEEP command from the CMS Ready prompt of the z/VM Personal user ID. For example:

QSLEEP ETPGVyy

7.2 Using BEGIN to awaken the guest z/VM system

Once a virtual machine is placed into the CP SLEEP state it will remain inactive until it is awakened. To awaken a system, issue the following command from the z/VM control user ID:

SEND ETPGVyy \CP BEGIN

8 How to terminate a guest z/VM system

The process described below orderly terminates the guest z/VM system.

  1. Logon to the z/VM control user ID.

  2. Shutdown the guest z/VM with the following command:

    SEND ETPGVyy \CP VI VMSG SHUTDOWN

    The system will respond with several messages ending with SHUTDOWN COMPLETE.

  3. Instruct the guest z/VM system to logoff with the command:

    SEND ETPGVyy \CP LOGOFF

9 Guest z/VM system administration

The following topics will cover basic guest z/VM system administration functions required to maintain the system.

9.1 Issuing CP commands

Note: CP is the Control Program which operates within the first-level z/VM system.

Any CP commands issued on behalf of a guest z/VM system from the z/VM control user ID follows the format SEND [guest_system_ID] \CP [cp_command]. For example, to query the mindisks attached to guest system ID ETPGVyy, issue the following command from the z/VM control user ID:

SEND ETPGVyy \CP Q V DASD

9.2 Accounting information

Program fees include a specified amount of CPU work units in the base fee and any extra work units used for a month are charged at a specified per work unit rate. The number of work units included in the base fee and the additional per work unit rate are documented in the order confirmation email. The session report SESSREPT command is provided to monitor the work unit usage of the guest system. Accounting records are reported for each guest system that has had usage during the twelve hour period ending at 07:00 and at 19:00 US Central time each day.

Use the following CP command to obtain work unit accounting information for the guest z/VM system for a specified date range from a z/VM Personal user ID:

MSG SVUTIL SESSREPT ETPGVyy FDATE LDATE

where FDATE is the first date in the range and LDATE is the last date in the range.

An explanation of the syntax is provided in the SESSREPT help text which is retrieved with the command:

MSG SVUTIL HELP SESSREPT

SVUTIL messages
Figure 12 SVUTIL messages

After a short time, the SVUTIL service machine will send a detailed usage report to the z/VM Reader of the z/VM Personal user ID that sent the command.

When the report is returned, a message will be displayed on the z/VM Personal user ID CMS screen with an identifying file number. To view the contents of the file, enter the command:

PEEK file_number (FOR *

Alternatively, access the file using the z/VM ReadList command:

RL

From the list of reader files, cursor to the line of the file to view and press F11 (Peek).

While 'peeking' the file, it may be easier to view after entering the command V 1 78 on the command line. Use F7 and F8 to scroll the file forward and backward. Use F3 to quit looking at the file.

9.3 Switching the z/VM control user ID

The z/VM control user ID for a system can be changed using one of three methods. In the below examples, ETPGVyy is the guest system ID and ETPDxxx is the desired new z/VM control user ID:

For more information about the SVUTIL functions, issue command MSG SVUTIL ?. For syntax details, issue command MSG SVUTIL HELP xxx where xxx is the option.

10 Appendix A: Help for common problems

HOLDING in lower right‑hand corner of screen.

Press the CLEAR key to clear the screen and continue normal operation.

Note: See also Appendix B: Terms and definitions.

MORE... in lower right‑hand corner of screen.

Press the CLEAR key to clear the screen and continue normal operation. If no action is taken, the screen will clear automatically after 60 seconds. A beep will be issued 10 seconds before this happens.

NOT ACCEPTED in lower right‑hand corner of screen.

Wait for the NOT ACCEPTED to clear, backspace to the left margin, erase the command, and reenter it.

Message HCPDIA056E Line yyyy busy on xxxxxxxx appears after issuing a DIAL command.

The terminal address being DIALed to is busy (in use). Repeat the DIAL command with a different terminal address, or do not specify a terminal address.

Message HCPGIR450W CP entered; disabled wait PSW 000A0000 000000xx appears after attempting to IPL a guest z/VM system (xx is usually 32, 33, or 64).

LOGOFF and then LOGON to retry the IPL (possibly several times if needed). If the problem persists, contact IBM for Technical Support.

HCPSEC068E SEND command failed; receiver has console input waiting.

Ensure a backward slash \ is used preceding CP in the SEND command. If using a backward slash \ and receiving this message, try setting the code page associated with the session emulator to 1047.

HCPLGA054E Already logged on disconnected

The guest z/VM system is already up and running. Refer to Managing the guest z/VM system with SLEEP and BEGIN to see if the system is in SLEEP mode.

Trouble accessing the system from a remote application

Information about blocked ports can be found at http://dtsc.dfw.ibm.com/MVSDS/HTTPD2.DSN01.PUBLIC.HTML(BLKPORTS).

Unable to connect to the guest z/VM system

See section Managing the guest z/VM system with SLEEP and BEGIN.

Also review the information IPL the guest z/VM system.

If you are still unable to connect, contact IBM for Technical Support.

Message ACTCTC command failed rc=xxx, notify SVSC in response to SVUTIL ACTCTC command.

An unexpected error has occurred processing the ACTCTC command. Contact IBM for Technical Support.

11 Appendix B: Important Terms and Definitions

TermDefinition
Guest systemAn operating system running in a virtual machine managed by the z/VM Control program.
Control IDThe term z/VM control user ID is used to reference the specific z/VM Personal user ID used to initialize the guest z/VM system and currently holds the ability to perform functions for the system.
CPControl Program - The component of z/VM that manages the resources of a single physical processor complex such that multiple computing systems appear to exist. From the CONSOLE device, a user may toggle back and forth between CP and a guest system by pressing the PA1 (Program Attention 1) key.
Virtual MachineA functional equivalent of either a System/370 computing system, a System/370‑XA (Extended Architecture) computing system, a System/370‑ESA (Enterprise Systems Architecture), or a System/390 computing system. Each virtual machine is controlled by an operating system.
z/VMVirtual Machine. A software facility which enables multiple users to share the resources of a single physical processor complex such that each user appears to have the equivalent of a dedicated processor.

Note: The PA1, PA2, and CLEAR keys are part of the IBM 3270 terminal architecture and may be emulated by a different key or combination of keys depending on the actual terminal or personal computer emulation package being used.

The following are CP and CMS Status Indicators - these indicators may at times appear in the lower right hand corner of the display.

TermDefinition
CP READCP issued a read request to the display and is waiting for something to be entered before it continues processing.
VM READSimilar to CP READ but issued from CMS (Conversational Monitor System, a component of z/VM).
RUNNINGCP or CMS either is ready for the next CP or CMS command or is processing a previously entered command.
MORE...The output display area is full and CMS or CP has more lines to display. The data currently on the screen will be displayed for one minute. To get to the next screen, press CLEAR or PA2. To keep the current information on the screen, press the ENTER key. The HOLDING indicator then appears in the status area. If there is no response to the MORE... indicator within 1 minute, the next screen will automatically be displayed (display device will beep 10 seconds prior to display of the next screen).
HOLDINGThe ENTER key was pressed in response to a MORE... status indicator, or that the display screen contains priority messages from CP. To get to the next screen, press CLEAR or PA2.
NOT ACCEPTEDMeans that previous input has not yet been processed. Recommended response is to wait for the NOT ACCEPTED to clear, backspace to the left margin, erase the command, and reenter it.

The following are common abbreviations applicable to working with the guest system.

TermDefinition
ADSPAutomatic Data Set Protection – a RACF capability.
CMSConversational Monitor System – a z/VM operating system providing a basic terminal‑oriented command structure.
CP Control ProgramThe component of z/VM that manages the resources of a single guest system so that multiple computing systems appear to exist. Each virtual machine is the functional equivalent of a z/VM computing system.
DSMONData Security Monitor – a RACF reporting capability.
ETPEarly Test Program. A program administered by the IBM to enable Independent Software Vendors to access selected IBM software and products prior to General Availability.
GAGenerally Available.
GuestAn operating system running in a virtual machine managed by the z/VM Control program.
IPLInitial Program Load.
ISPFInteractive System Productivity Facility.
JES2Job Entry Subsystem 2.
JES3Job Entry Subsystem 3.
PDFProgram Development Facility.
RACFResource Access Control Facility.
RDPRemote Development Program.
RMFResource Measurement Facility.
SDSFSystem Display and Search Facility.
SETROPTSSET RACF Options – RACF command.
SMFSystem Management Facility.
SVSolution Developer. Also previously called Software Vendor.
SVSCSoftware Vendor Systems Center.
SVSCDR2Network name for one of the System z servers on which the remote access program is located.
SVTSCSoftware Vendor Technical Support Center.
System ZA series of computer hardware systems and control programs.
UACCUniversal Access – a RACF parameter.
z/VMVirtual Machine.
z/VM secondary user IDIn z/VM terminology, it is the secondary user for the guest system ID.