Skip to main contentIBM ZLPN Documentation

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

Table of contents

  1. Preface

    1.1. Links

  2. Overview – Remote Access Environment

    2.1. Hardware / Software Platform

    2.2. Introduction to the Virtual Machine Concept

    2.3. z/OS Remote Access Environment

    2.4. Printers

    2.5. System Availability

    2.6. Maintenance Windows

    2.7. Remote Access System Backup

  3. Accessing the IBM Z (Dallas) ISV Center

    3.1. Connecting to the IBM Z (Dallas) ISV Center server

    3.2. Connecting to the Guest z/OS System

    3.3. Connecting Using z/VM “DIAL”

    3.4. Connect a TN3270 Client Session Directly to an IP Address

    3.5. Connect Directly to an IP Address Using SSH

    3.6. Connect Using SFTP

  4. IPL of the Guest z/OS System

    4.1. How to IPL the Guest z/OS System (Quick Steps)

    4.2. How to IPL the Guest z/OS System (Detailed Description)

    4.2.1. Log on the z/VM Control User ID

    4.2.2. Initialize (IPL) the Guest z/OS System

    4.2.3. Disconnect the z/VM Control User ID

    4.2.4. Reconnect the z/VM Control User ID

  5. How to Shut Down a Guest z/OS System

  6. Managing the Guest z/OS System with “SLEEP” and “BEGIN”

    6.1. Putting the Guest System to Sleep From the Control User ID

    6.2. Putting the Guest System to Sleep From a TSO Session

    6.3. Using “BEGIN” to Awaken the Guest System

  7. Accessing TSO

    7.1. Logging on to TSO

    7.2. Logging off from TSO

  8. Return to z/VM When Using z/VM “DIAL”

  9. Guest z/OS System Administration

    9.1. Adding More TSO User IDs

    9.2. Backing Up and Restoring User Data

    9.2.1. Backing Up User Data Steps

    9.2.2. Restoring User Data Steps

    9.3. Add PROCS to start when the system comes up

    9.4. IPCS

    9.5. Issuing CP Commands

    9.6. Accounting Information

    9.6.1. Obtaining Program Account Information

    9.7. Switching the z/VM Control User ID

    9.8. DASD Configuration

    9.8.1. System Managed Storage

    9.9. IBM Z (Dallas) ISV Center Provided Data Sets

    9.10. Default LINKLIST Concatenation

    9.11. Default LPA List

    9.12. Default PROCLIB Concatenation

    9.13. CATALOG Structure

    9.14. Highlights from LVL0.PARMLIB

    9.15. SMP/E Data Sets and Maintenance Information

    9.16. RACF Information

    9.17. VTAM Definitions

    9.18. JES2 Information

    9.19. TSO Logon Procedures and Data Set Concatenation

    9.19.1. Sample Jobs and CLIST/REXX Availability

  10. Help for Common Problems

  11. Other Information

    11.1. Terms and Definitions

    11.2. Technical Support

    11.3. z/OS System Customization

    11.4. Trademarks

    11.5. Notices

1 Preface

This document is intended to assist the user in accessing and using the z/OS Remote Development or Early Test system. This is version 7.0 of the User's Guide and Reference for IBM z/OS Remote Access Programs document. For terminology used in this document, please refer to 11.1 Terms and Definitions. For assistance, please refer to 11.2 Technical Support.

Here you will find links that will enhance the use of the remote development program guest z/OS systems:

IBM Z (Dallas) ISV Center: https://dtsc.dfw.ibm.com/public

Getting Started at IBM Z (Dallas) ISV Center: https://dtsc.dfw.ibm.com/MVSDS/'HTTPD2.DSN01.PUBLIC.SHTML(HEADSTAR)'

IBM Support Portal: https://www.ibm.com/mysupport

z/OS Basic Skills Education: https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.zbasics/homepage.html

z/OS Internet Library: https://www.ibm.com/docs/en/zos

IBM Redbooks online: https://www.redbooks.ibm.com/

TecDocs – IBM Technical Sales Library: https://www.ibm.com/support/pages/ibm-techdocs-technical-sales-library

2 Overview – Remote Access Environment

The remote access environment is provided by the IBM Z (Dallas) ISV Center organization in conjunction with various IBM development laboratories. z/OS is an operating system from IBM which runs on IBM Z® server hardware.

2.1 Hardware / Software Platform

The remote access program is implemented on an IBM Z server which is accessible to Solution Developers participating in the remote access program via the INTERNET. The IBM Z server runs the IBM z/VM® (Virtual Machine) operating system which supports multiple guest systems, each capable of supporting multiple users in a unique environment. Each remote access participant is provided with a dedicated guest system, which appears to the user as an IBM Z server running a native z/OS operating system

Note: Remote access program participants will be required to logon to the z/VM host system and perform a limited number of z/VM tasks in order to IPL and access their guest z/OS system in it's virtual machine environment. Required z/VM commands and tasks are described in this document; no previous knowledge of the z/VM operating system is required.

2.2 Introduction to the Virtual Machine Concept

Virtual Machine (VM) is a software facility 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, CMS, etc.) and software.

Please refer to the IBM Redbook Introduction to the New Mainframe: z/VM Basics: https://www.redbooks.ibm.com/redbooks/pdfs/sg247316.pdf

2.3 z/OS Remote Access Environment

z/OS is available as part of the remote access program as a "dedicated" second-level guest system on the z/VM platform. The guest z/OS system will Initial Program Load (IPL) automatically when an authorized z/VM Personal user ID logs on and issues the “SVXLOG” command to start the process. Please see 4.2.2 Initialize (IPL) the Guest z/OS System, for additional information. Users can request to be added to an autostart program that will be run after scheduled system recycles. Please contact the IBM Z (Dallas) ISV Center support team using one of the methods described in 11.2 Technical Support, to be added to the autostart program.

Users will be responsible for performing z/OS console operations (such as issuing commands to start tasks associated with IBM IMS™, IBM DB2®, IBM CICS®, etc. as needed), TSO user ID administration, security administration (if desired), etc. The operator commands required to perform basic initialization, operation and termination of the system are included in this document. For additional information regarding console operations, refer to IBM publication z/OS MVS System Commands.

The z/OS manuals are available on the IBM z/OS Internet Library: https://www.ibm.com/docs/en/zos

The guest z/OS system and z/OS console are confined within a virtual machine "owned" by the Solution Developer. The system use, is dedicated and restricted to the assigned Solution Developer and is not accessed by the support staff at the IBM Z (Dallas) ISV Center without prior permission (detailed information of this z/OS system may be found in 9. Guest z/OS System Administrator).

IMPORTANT NOTICE

  • Each Solution Developer is assigned a “virtual machine” under IBM’s z/VM operating system, which runs continuously and accumulates CPU time REGARDLESS of actual use by interactive users, batch jobs, etc.

  • The Solution Developer’s account will be charged for CPU time used by the virtual machine even if no users are logged on and no batch activity recorded. The amount of work units (CPU time) consumed by the virtual machine is available via the “SESSREPT” command (See 9.5.1 Obtaining Program Account Information).

  • To avoid unnecessary charges, always remember to stop the guest z/OS system’s virtual machine when not using it by either putting it to sleep or shutting it down and logging it off (See 6.1 Putting the Guest z/OS System to Sleep From z/OS Control User ID, and 5. How to Shut Down a Guest z/OS System).

  • Solution Developers must logoff the guest z/OS system’s virtual machine or put it to sleep. Otherwise, the machine will continue to run (idle) and the Solution Developer will be charged for the time used by the virtual machine.

2.4 Printers

There are no real printers attached to the IBM Z server. Each guest z/OS system has unit 002 defined as a virtual printer for JES. All printers are drained at IPL and starting a printer will cause JES to write the output to the virtual printer. This just means it will move from one SPOOL to another but will not physically print on paper.

In a JES2 environment, use SDSF, the “TSO OUTPUT” command or ISPF OUTLIST utility (option 3.8) to browse printer files online. The “TSO OUTPUT” command and ISPF OUTLIST utility require the system output be in a HOLD queue. Typically, this is defined as SYSOUT class "H" (see 9.17 JES2 Information for specific information).

2.5 System Availability

The remote access program host systems are generally available 24 hours per day, 7 days per week (except for scheduled maintenance windows). Technical and administrative support is available from 07:00 to 18:00 USA Central Time, Monday – Friday only.

2.6 Maintenance Windows

The IBM Z (Dallas) ISV Center has implemented the following policy regarding maintenance windows:

Every Sunday between the hours of 09:30 and 15:30 U S A Central Time, the IBM Z (Dallas) ISV Center may choose to make any of the processors unavailable. This time will be used to perform system IPL's and to implement new or updated releases of software. All Solution Developers requiring an orderly guest z/OS system shutdown should perform the shutdown prior to that time and should not plan to resume operations until after 15:30 Central Time on Sunday.

A maintenance window will not be required every Sunday. Therefore, Solution Developers may choose to work during this time, but only at their own risk. Notices will be posted whenever possible (via host system broadcast messages) but all activity during this window is subject to immediate interruption. Solution Developers with special requirements for this time, should contact the IBM Z (Dallas) ISV Center as early as possible.

2.7 Remote Access System Backup

The z/VM disks that contain the remote access system are backed up to tape every week and are available for 3 months. The intent of these backups is to enable us to recover from a DASD failure. The backup and restore process operates only at the z/VM disk level, therefore the restoration of individual files from these backups is difficult and time-consuming and not generally available (for information on how you can back up your data, please refer to 9.2 Backing Up and Restoring User Data).

All participants in IBM Z (Dallas) ISV Center programs are encouraged to maintain a copy of their data / information on another system physically located at another site. Although the staff managing the IBM Z (Dallas) ISV Center complex, in accordance with the program agreements, may maintain a copy of each participant's system on tape, it is always possible that an issue with the backup process or backup media would invalidate the copy.

Please also note: the backups of the entire volumes of each system are performed externally to the system and are not kept off-site.

The techniques used for saving data will vary depending on the guest operating system in use and may be discussed in the User's Guide and Reference applicable to your guest operating system. To obtain details of the backups for the remote access system, or to change the frequency of the backups, please contact the IBM Z (Dallas) ISV Center.

3 Accessing the IBM Z (Dallas) ISV Center

Before utilizing the guest z/OS system, Solution Developers must first follow the steps below to access the IBM Z server (for example, VH1) and initialize (IPL) the guest z/OS system. Access to the IBM Z server requires access to the Internet. The method, line speed, and choice of Internet Service Provider are determined by the Solution Developer.

There are several different user IDs described in this document:

In this guide, we will refer to the example Guest-System ID as ETPGJON. The z/VM Personal User ID and z/VM Control User ID was ETPDESY.

All the z/VM Personal User IDs provided as part of this program have the authority to activate the Guest-System IDs by using the “SVXLOG” command. Once the Solution Developer activates the guest z/OS system, the user ID that does the activation becomes the z/VM Control User ID. This z/VM Control User ID is the only ID that can send commands to the guest z/OS system. This is done via the z/VM “SEND” command. The z/VM Control User ID will remain the same ID until it is changed by someone with proper authority to do so or until the Guest-System ID is shut down. (Please see 9.6 Switching the z/VM Control User ID)

Also, as applicable, Solution Developers may have:

TN3270:

You will need a TN3270 emulator.

Note: IBM Corporation has taken steps to enhance the security of the internet connections to the IBM Z Dallas ISV Center remote access systems, by blocking various ports from inbound traffic. More Information about the blocked ports can be found on the IBM Z Dallas ISV Center website at: https://dtsc.dfw.ibm.com/MVSDS/'HTTPD2.DSN01.PUBLIC.SHTML(BLKPORTS)'

3.1 Connecting to the IBM Z (Dallas) ISV Center server

To access the IBM Z server, an Internet connection must first be established. Once that is established, perform the following steps:

Step 1. Direct a TLS 1.2 enabled TN3270 connection to the IBM Z (Dallas) ISV Center Secure Portal at: dtsc.dfw.ibm.com:65512 (port 65512). For additional information on configuring IBM Personnel Communication 3270 Emulator Software, please refer to the IBM Z (Dallas) ISV Center public website: https://dtsc.dfw.ibm.com/public

Step 2. Type from the list of available processors (VH1, for example). Once the connection is set up, the Remote Access Portal screen (below) will be shown. Choose the system identified in the delivery email by entering in the system name and pressing the ‘ENTER’ key. VH1 (DTSCVH1) will be our example processor moving forward in the guide.

Step 3. The next screen displayed will be the IBM Z (Dallas) ISV Center system Logon Screen, indicating that the IBM Z (Dallas) ISV Center server has been reached.

Step 4. On the Logon 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 upon first use of the z/VM Personal User ID or any time after the IBM Z (Dallas) ISV Center has reset the password. The system will prompt you to change the password. Enter a new password in the format of xxxxxxxx/xxxxxxxx and press the ‘ENTER’ key. The text you type will not be visible to help assure the privacy of the z/VM Personal User ID password.

Passwords expire 60 days after changed. You can change your password sooner than this interval.

NOTICE REGARDING PASSWORD RULES

  • Be eight characters in length
  • Only contain alphabetic, numeric, and national characters ($, # and @)
  • Contain at least one alphabetic and one non-alphabetic character
  • Have the first and last characters be non-numeric
  • Contain no more than three identical, consecutive characters from the previous password
  • Contain no more than two identical, consecutive characters
  • Not contain the user ID as part of the password
  • Not be reused until after at least eight iterations

Step 5. System log messages, containing information of general interest, will 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 continue2

Step 6. 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 DTSCVH1”.

3.2 Connecting to the Guest z/OS System

There are two types of applications on a guest z/OS system. One type of application is accessed through a full screen interface and the other through a line mode interface. 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.

3.3 Connecting Using z/VM “DIAL”

Step 1. Connect to the IBM Z (Dallas) ISV Center Secure Portal, as covered in 3. Accessing the IBM Z (Dallas) ISV Center Server.

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

Step 3. There are two methods when using the “DIAL” command. Both are described below:

  1. Enter the z/VM “DIAL” command on the COMMAND line of the IBM Z DTSCVH1 Logon Screen specifying the name of the Guest-System ID. The system will automatically connect the terminal to the first available VTAM terminal in the guest z/OS system. For example, to dial to system name ETPGJON, type the following command:

    DIAL ETPGJON

    “D” may be used as an abbreviation for the “DIAL” command.

  2. To use data transfer (IND$FILE) from a TN3270 emulator, specify an address in the range of F00-F07 to the end of the “DIAL” command. For example, to dial to system name ETPGJON using specific terminal address F04, type the following command:

    DIAL ETPGJON F04

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 z/OS system. Respond to message Enter your password: with the password associated with that z/VM Personal User ID.

If message HCPDIA056E appears instead, see 10. Help For Common Problems.

Note: Passwords for the z/VM Personal User IDs have been set to expire immediately and must be changed during first logon, and every 60 days thereafter. Passwords can be changed sooner than 60 days interval.

3.4 Connect a TN3270 Client Session Directly to an IP Address

Refer to the system delivery email to obtain the assigned TCP/IP address. If the assigned IP address requires the use of Client VPN, please 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 623 (Do Not configure or enable SSL support for this session). Once the session is configured, select the option to connect to the system.

3.5 Connect Directly to an IP Address Using SSH

Issue the following command from the z/VM Control User ID to start SSHD:

SEND ETPGJON \CP VI VMSG S SSHD

Once SSHD is started, use any SSH client to connect to the guest z/OS system.

3.6 Connect Using SFTP

Using any SFTP client to connect to z/OS, issue the following:

sftp USER@0.0.0.0

Replace USER with your TSO User ID and 0.0.0.0 with your guest z/OS system IP address.

You will be prompted for your TSO User ID and password. Change the directory to an MVS data set name or UNIX file name by enclosing the MVS data set or UNIX file name in quotes.

Before connecting with SFTP, the SSH daemon must first be started on the guest z/OS system. See the prior section for the command.

4 IPL of the Guest z/OS System

4.1 How to IPL the Guest z/OS System (Quick Steps)

This section provides a list of quick steps to IPL a z/OS system. The section 4.2 How to IPL the Guest z/OS System (Detailed Description), below, provides detailed instructions (including examples to initialize a system).

Step 1. Access the IBM Z server over the Internet through the IBM Z (Dallas) ISV Center Secure Portal using an TLS enabled TN3270 emulator. See 3. Accessing the IBM Z (Dallas) ISV Center Server, for detailed instructions.

Step 2. Log on a z/VM Personal User ID which will be used to control the guest z/OS system. The user ID is now referred to as the z/VM Control User ID. Do NOT log-on to the guest z/OS system ID.

Step 3. Initialize (START/IPL) the guest z/OS system with the command “SVXLOG Guest-System ID”: SVXLOG ETPGJON

Step 4. You will see a lot of messages scrolling by. Look for the message that TN3270 is listening on port 623. At this stage, you can logoff from z/VM and connect to your z/OS system using either IP or z/VM “DIAL”.

4.2 How to IPL the Guest z/OS System (Detailed Description)

4.2.1 Log on the z/VM Control User ID

The messages which result from the initialization of the system cover more than one screen. In this documentation, be careful to review all the screen examples associated with a particular event. Each part contains important information describing the IPL of the guest z/OS system in this environment. Before continuing, please follow the directions in 3. Accessing the IBM Z (Dallas) ISV Center Server for information on establishing a session and logging on to the z/VM Personal User ID that will be used for initialization of the Guest-System ID.

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 that you enter various z/OS commands prefixed by the same z/VM command syntax.

4.2.2 Initialize (IPL) the Guest z/OS System

Step 1. After logging on to the z/VM Personal User ID, initialize (IPL) the guest z/OS system by typing the “SVXLOG Guest-System ID” command at the CMS Ready Prompt and then press the ‘ENTER’ key. For the example Guest-System ID ETPGJON, the command would go as follows:

SVXLOG ETPGJON

Once the “SVXLOG” command is entered, this z/VM Personal User ID becomes the z/VM Control User ID for the Guest-System ID.

Note: You can enter an alternate IPL parm to the “SVXLOG” command. Issue the command SVXLOG ? for additional information about specifying an alternate parm. The guest z/OS system will return messages to the z/VM Control User ID screen.

At this point in the IPL of the Guest-System ID, there is a brief pause before more messages are displayed. Once the messages start flowing again, watch for the following message: IEE389I MVS COMMAND PROCESSING AVAILABLE.

There are situations when messages similar to those listed below will appear during IPL:

*$HASP478 CONFIRM INITIAL CHECKPOINT READ FROM CKPT1
        (SYS1.HASPCKPT ON VPSPOL)
    LAST WRITTEN MONDAY, 16 MAY 2022 AT 23:00:38 (LOCAL TIME)
    COMPANION DATA SET IS CKPT2 (SYS1.HASPCKP2 ON VPSPOM)
    LAST WRITTEN MONDAY, 16 MAY 2022 AT 23:00:38 (LOCAL TIME)
*01 $HASP441 REPLY 'Y' TO CONTINUE INITIALIZATION OR 'N' TO TERMINATE
IN RESPONSE TO MESSAGE HASP478

Until the HASP441 message is answered, JES2 will not start. When required, answer HASP441 with the following command:

SEND ETPGJON \CP VI VMSG $$,Y

Where “$$” is the number immediately preceding $HASP441.

The following messages below may also appear during the IPL. Although they may be highlighted, they are not usually cause for concern. No additional actions are required.

*ASB010I THE SUBSYSTEM JES2 EXISTS BUT IT IS NOT ACTIVE.
*$HASP493 JES2 ALL-MEMBER WARM START IS IN PROGRESS
*$HASP400 ENTER REQUESTS
*IEA405E WTO BUFFER SHORTAGE – 80% FULL

Step 3. Multiple messages from the IPL process may be received. Once the messages seem to have stopped, use the following z/VM command to check for outstanding messages (ensure you replace ETPGJON with your Guest-System ID):

SEND ETPGJON \CP VI VMSG D R,L

The response should be as shown below.

IEE112I 13.36.22 PENDING REQUESTS 790
RM=0 IM=0 CEM=0 EM=0 RU=0 IR=0 NOAMRF
NO MESSAGES OUTSTANDING

When the response is a HASP441 message as shown below, respond as instructed in the previous step.

*01 $HASP441 REPLY 'Y' TO CONTINUE INITIALIZATION OR 'N' TO TERMINATE
IN RESPONSE TO MESSAGE HASP478

Continue to use the z/VM Control User ID to control the guest z/OS system with IBM MVS™ and JES commands using the same method shown previously during IPL.

Step 4. While it is preferable to access the guest z/OS system from another TN3270 emulator session, it is not required. When using a TN3270 terminal emulator that only provides for one session, disconnect from the z/VM Control User ID so that the same session can be used to access the guest z/OS system (see 4.2.3 Disconnect the z/VM Control User ID, below).

The guest z/OS system is now up and running. TSO is up on the guest z/OS system and can be utilized (as described in 7. Accessing TSO). z/OS commands can be sent to your guest z/OS system once the system has been IPL’d. The z/VM Control User ID will also receive messages from the z/OS system.

After disconnecting the z/VM Control User ID, follow the instructions in 4.2.4 Reconnect the z/VM Control User ID, below, to reconnect to the z/VM Control User ID.

4.2.3 Disconnect the z/VM Control User ID

Step 1. Disconnect the z/VM Control User ID using the z/VM “DISCONNECT” command (which can be abbreviated to “DISC”). On the z/VM command line, type “DISC” and press the ‘ENTER’ key. The z/VM system will return with the following messages:

Step 2. Press the ‘ENTER’ key as the message indicates. The z/VM system will return to the z/VM System Logon Screen.

Step 3. From the Logon Screen, enter “VMEXIT” on the COMMAND line to drop the connection to the z/VM system.

Note: It is possible to log on to another z/VM Personal User ID or connect to the guest z/OS system using the “DIAL” command. The “DIAL” command is discussed in 3.2 Connecting to the Guest z/OS System.

4.2.4 Reconnect the z/VM Control User ID

To reconnect the z/VM Control User ID, follow these steps:

Step 1. From the CMS Ready Prompt on DTSCVH1, enter the z/VM Control User ID and the associated password and press the ‘ENTER’ key (Refer to 3.1 Connecting to the IBM Z ISV Center server for more information on this topic).

Step 2. Once logged back on, notice that displayed in the lower right-hand corner of the screen is CP READ. Type “B” and press the ‘ENTER’ key. When required, clear the screen afterwards by pressing the ‘CLEAR’ or ‘PA2’ key to complete the reconnect process.

5 How to Shut Down a Guest z/OS System

The process described below orderly terminates the guest z/OS system. To force error recovery or to terminate only a portion of the system to reduce the charges, please contact the IBM Z (Dallas) ISV Center for assistance.

Note: To save typing time, use the ‘F12’ key while logged on to the z/VM Control User ID to recall previous commands entered. Then type over the part following the word VMSG.

Step 1. Logon to the z/VM Control User ID (as described in 4.2.1 Log on the z/VM Control User ID).

Step 2. Terminate any applications and subsystems that may have been started (such as IMS, DB2, or CICS). Please issue the following command to display the tasks running in your environment.

SEND ETPGJON \CP VI VMSG D A,L

Step 3. Terminate any system tasks that are currently up and running on the guest z/OS system. Look at the System Task Termination by Order below for the correct command to terminate Specifics tasks.

Step 4. Flush all SMF data to the SMF data sets and write a record in the SMF data sets indicating an orderly system shutdown with the command:

SEND ETPGJON \CP VI VMSG Z EOD

The message IEE334I HALT EOD SUCCESSFUL will be returned by the system.

Step 5. Logoff the guest z/OS system with the command:

SEND ETPGJON \CP LOGOFF

Step 7. When leaving the guest z/OS system in a dormant state for a period of time, issue the “LOGOFF” command and, once back to the z/VM Logon Screen, enter “VMEXIT” in the COMMAND line and press the ‘ENTER’ key.

System Task Termination by Order

NameTermination CommandVerification Message
TSOSEND ETPGJON \CP VI VMSG P TCAS$HASP395 TCAS ENDED - RC=0000
CSFSEND ETPGJON \CP VI VMSG P CSF$HASP395 CSF ENDED - RC=0000
TN3270SEND ETPGJON \CP VI VMSG P TN3270$HASP395 TN3270 ENDED - RC=0000
ResolverSEND ETPGJON \CP VI VMSG P RESOLVER$HASP395 IEESYSAS ENDED
TCP/IPSEND ETPGJON \CP VI VMSG P TCPIP$HASP395 TCPIP ENDED - RC=0000
RRSSEND ETPGJON \CP VI VMSG SETRRS SHUTDOWNATR167I RRS RESMGR PROCESSING COMPLETED
Health CheckerSEND ETPGJON \CP VI VMSG P HZSPROC$HASP395 HZSPROC ENDED - RC=0000
Runtime DiagnosticsSEND ETPGJON \CP VI VMSG P HZRHZR0113I RUNTIME DIAGNOSTICS HAS ENDED
SDSFSEND ETPGJON \CP VI VMSG P SDSF$HASP395 SDSF ENDED - RC=0000
VTAMSEND ETPGJON \CP VI VMSG Z NET,QUICKIST102I VTAM IS NOW INACTIVE
OMVSSEND ETPGJON \CP VI VMSG F OMVS,SHUTDOWNH *BPXI056E OMVS SHUTDOWN REQUEST HAS COMPLETED SUCCESSFULLY
OAMSEND ETPGJON \CP VI VMSG P OAM$HASP395 OAM ENDED - RC=0000
JES2SEND ETPGJON \CP VI VMSG $P JES2$HASP085 JES2 TERMINATION COMPLETE
EODSEND ETPGJON \CP VI VMSG Z EOD(ENDS WITH JOB PURGES)

6 Managing the Guest z/OS System with “SLEEP” and “BEGIN”

It is possible, running under z/VM, to put the guest z/OS system to sleep at any given point (overnight, for example) without having to drain, halt or quiesce (pause) the guest z/OS system. The effect of the z/VM “CP SLEEP” command is that of temporarily "freezing" the guest z/OS system at any given point with the ability to resume at that same point at a later time and with the benefit of not using CPU cycles when they are not needed.

Once a virtual machine is placed into the CP SLEEP state it will remain inactive until it is awakened with the “CP BEGIN” command.

To verify that the guest z/OS system is sleeping, issue the “QSLEEP” (Query SLEEP) command from any one of the z/VM Personal User IDs or the z/VM Control User ID. Put the guest z/OS 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 ETPGJON

While it is possible to place the virtual machine in an inactive state at any given moment, 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/OS system and IBM subsystems recover with no problems, however the IBM Z (Dallas) ISV Center cannot be responsible for adverse side effects in vendor software systems under these circumstances.

There are two methods for putting a virtual machine into sleep mode. They are both described below.

6.1 Putting the Guest System to Sleep From the Control User ID

From the z/VM Control User ID, issue the following command:

SEND ETPGJON \CP SLEEP

6.2 Putting the Guest System to Sleep From a TSO Session

It is possible to put the guest z/OS system to sleep from a TSO session without the inconvenience of logging off TSO.

Type “%SLEEP” from an ISPF command line and logoff from TSO within the next 60 seconds. “%SLEEP” is a REXX exec which submits a batch job from a TSO session. The batch job waits a specified amount of time and then issues the appropriate z/VM CP commands to put the system to sleep. The time delay may be specified as a parameter on the “%SLEEP” command (the default is 60 seconds).

When other terminals are connected to the system, the “%SLEEP” command will prompt to either continue or quit (cancel) before submitting the batch job.

Note: Accidentally issuing the “%SLEEP” command and failing to log off TSO before the time delay expires, causes the guest z/OS system to stop and the TSO session will appear to go dead. To recover from this situation, locate an alternate terminal or terminal session and wake up the sleeping system as described in 6.3 Using “BEGIN” to Awaken the Guest System, below.

WARNING

Be careful not to modify the system in any way (such as installing certain JES exits) which will cause the batch job submitted by “%SLEEP” to fail, as this would cause the system to continue running after issuing “%SLEEP”.

6.3 Using “BEGIN” to Awaken the Guest System

From the z/VM Control User ID, issue the following command:

SEND ETPGJON \CP BEGIN

7 Accessing TSO

Below are instructions for logging on to and logging off from TSO on the guest z/OS system.

7.1 Logging on to TSO

All remote access guest z/OS systems are predefined with one TSO User ID, called IBMUSER, for use by the Solution Developer's system administrator. This user ID has full TSO ACCOUNT, OPERATOR, and SPECIAL authorities. Use it to add additional TSO User IDs to the guest z/OS system (see 9.1 Adding More TSO User IDs). The initial password for IBMUSER is set to IBMUSER. This password has been set to expire immediately and must be changed during first logon.

To reset the password for IBMUSER, issue the following command from the z/VM Control User ID:

SEND ETPGJON \CP VI VMSG S RACFUR

This will reset the password to IBMUSER, which will expire immediately upon logon. Please note that All TSO User IDs will be revoked after 6 consecutive unsuccessful logon attempts.

Note: A second TSO User ID, SVTSCU, has been included in the guest z/OS system for use by the IBM Z Dallas ISV Center to provide maintenance to the system and to assist in the event of a problem that requires access to the system. It is recommended that this user ID is NOT removed as the IBM Z Dallas ISV Center staff may be unable to assist in the event of a problem requiring access to the system. Access to this user ID is strictly controlled by the IBM Z Dallas ISV Center and the user ID will not be used without permission.

Step 1. After connecting to the guest z/OS system using z/VM “DIAL” or a TN3270 client, the z/OS VTAM Logon Screen will be presented:

Connecting a TN3270 client directly to the IP address assigned to the guest z/OS system will present a similar z/OS VTAM Logon Screen. Type “TSO” and press the ‘ENTER’ key. Any of the other TSO selections may also be picked, based on the screen size configured in the TN3270 session (this option is only available when connected using z/VM “DIAL”). Message IKJ56700A ENTER user ID will prompt for a TSO User ID. Reply with the TSO User ID and press the ‘ENTER’ key. The standard TSO logon screen will be presented.

Step 2. Type in the TSO password and press the ‘ENTER’ key. Continue to press the ‘ENTER’ key when the screen fills and *** appears on the last line displayed.

Note: Logon PROC SPFPROCE is the default logon procedure. For information on access to DB2 libraries for the specific version of DB2 running on the guest z/OS system, please contact the IBM Z Dallas ISV Center.

After successful logon to TSO, the ISPF Primary Option Menu will be presented. Press the ‘ENTER’ key to clear the copyright information on the ISPF Option Menu. Press F8 and F7 to page forward and backward through additional ISPF Primary Menu options.

Note: The presence of an IBM product on an ISPF selection panel does not necessarily indicate the presence of the product within the system.

The first TSO logon after any IPL will cause the following messages to be generated:

IEF196I IEF237I 0CD0 ALLOCATED TO SYS00005
IOS000I 0CD0,98,WRI,05,0200,,00010000,VPCOMA,CATALOG , 586
800200002800000000000010320000042301641900420F0000004CE100000000
IEF196I IEF237I 0CD0 ALLOCATED TO SYS00006
IOS000I 0CD0,98,WRI,05,0200,,00010000,VPCOMA,CATALOG , 588
800200002800000000000010320000042301641900420F0000004CE100000000
IEF196I IEF237I 0CD0 ALLOCATED TO SYS00007
IOS000I 0CD0,98,WRI,05,0200,,00010000,VPCOMA,CATALOG , 590
800200002800000000000010320000042301641900420F0000004CE100000000

These messages can be ignored. They appear because many of the data sets in the system are configured on read-only disk volumes. The read-only disk volumes allow the IBM Z (Dallas) ISV Center to correct problems and deliver maintenance with a minimal amount of disruptions to participants.

7.2 Logging off from TSO

To log off TSO, press the ‘F3’ key until you are back to the ISPF Primary Option Menu. Type “X” on the OPTION line and press the ‘ENTER’ key, or you can accomplish the same by typing “=X” from any ISPF screen.

In some cases, a screen will be presented after typing “=X” and pressing the ‘ENTER’ key. This screen requires your desired disposition of log data set information. The normal response is to enter “2” followed by the ‘ENTER’ key. on the process options line. Normally, there is no need to retain the USERID.SPFLOG2.LIST data set. The next screen, will be the TSO READY prompt. Type in “LOGOFF” and press the ‘ENTER’ key.

8 Return to z/VM When Using z/VM “DIAL”

This section describes how to return to z/VM when connected using z/VM “DIAL”.

In order to allow users to return to the first level z/VM system from the VTAM Logon Screen, a VTAM application program called EXITMVS has been installed to issue a “CP RESET” command upon session disconnect, allowing you to return to the z/VM Logon Screen.

After logging off of the guest z/OS system and returning to the VTAM Logon Screen, type “EXITMVS” and press the ‘ENTER’ key.

To disconnect from the z/VM Logon Screen, type “VMEXIT” on the next screen and press the ‘ENTER’ key. “VMEXIT” will drop the connection to the IBM Z (Dallas) ISV Center Secure Portal.

9 Guest z/OS System Administration

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

9.1 Adding More TSO User IDs

To add TSO User IDs:

Step 1. log into TSO with the TSO User ID IBMUSER.

Step 2. Type “%ADDUROM” at the TSO READY prompt. Every parameter can be specified. There are default values that can be taken (see 9.15 RACF Information, on page 36 for more information before executing this command).

Step 3. After executing the “%ADDUROM” CLIST, create the OMVS home directory in the following format /u/xxxxxxx (where 'xxxxxxx' is the user ID you’re creating). We also recommend that you create your own UNIX file system to be mounted on this directory.

When more than one user will be using the guest z/OS system, it is recommended to run the RACF DSMON (Data Security Monitor program) and review the system SETROPTS parameters, making adjustments as necessary to define the system as required.

Note: System Security and Isolation: RACF protection is not needed to protect the resources from other users in other guest z/OS systems – they are isolated from this guest z/OS system by the z/VM operating system and the z/VM security system (RACF).

9.2 Backing Up and Restoring User Data

There may be times when the Solution Developer will need to backup user data and compress it to send off-site. It may also be necessary to restore data that has been previously backed up. This section will provide guidelines to accomplish these tasks.

The following programs will be used in this section to help us in our data backup and restoration:

TRSMAIN

TRSMAIN is a utility program to compress and decompress data (pack and unpack). Output from TRSMAIN pack, creates fixed-length 1024 byte records. TRSMAIN also includes information in the fixed-length records to rebuild data in its original format. The fixed-length records make the data easily transportable using FTP (see 3.6 Connect Using FTP on page 13) When the data arrives at the target system and the fixed-length, 1024 byte records are recreated (unpack), the original data can be rebuilt. A sample TRSMAIN JCL job can be found in our systems at:

LVL0.SVSC.CNTL(TRSMAINP) and (TRSMAINU) respectively.

FTP

FTP can be used to upload or download the TRSMAIN packed data.

DFSMSdss

DFSMSdss Logical Dump and Restore will be used to backup and restore user data. Sample JCL is listed below for both backup and restore processes.

9.2.1 Backing Up User Data Steps

Step 1. DFSMSdss Logical Dump – To backup user data, use DFSMSdss Logical Dump Format. Below is sample JCL for performing this function:

//ST1 EXEC PGM=ADRDSSU
//SYSPRINT DD SYSOUT=*
//OUTPUT DD DSN=User.data.LDUMP,UNIT=SYSDA,
//    DISP=(NEW,CATLG),
//    SPACE=(CYL,(xxx,yyy),RLSE),VOL=SER=(VPWRKx))
//SYSIN DD *
  DUMP DS (INCLUDE( -
      User.DATA.** -
      ) -
      EXC(SYS1.VTOCIX.** - SYS1.VVDS.** -
      )) -
      ODD(OUTPUT) -
  CANCELERROR ALLDATA(*) ALLEXCP COM TOL(ENQFAILURE) SHR

The ALLDATA(*) and ALLEXCP parameters mean the data sets will be restored as allocated.

Step 2. TRSMAIN – Use sample JCL member TRSMAINP found in data set LVL0.SVSC.CNTL to perform the pack.

Step 3. Downloading data using FTP – The following text assumes that the FTP server is located on the guest z/OS system.

Output that has been packed can be transmitted from the guest z/OS system using FTP. Log on to the z/OS FTPSERVE daemon (refer to section 3.6 Connect Using FTP) and use the “GET” command to retrieve a packed output file. Be sure to set the transfer type to BINARY before using the “GET” commands as shown on the following page.

Additional information regarding use of the “GET” command can be found in the z/OS Communications Server IP User's Guide and Commands manual.

    ftp> bin
    ftp> get terse.dump
    ftp> exit

9.2.2 Restoring User Data Steps

To restore user data, use DFSMSdss Restore format. First upload the compressed data set using FTP to the system and then use the TRSMAIN program to unpack it before performing the restore.

Step 1. Uploading data using FTP – the following text assumes that the FTP server is located on the guest z/OS system. FTP to the guest z/OS system using the “PUT” command:

Output that has been packed can be transmitted to the guest z/OS system using FTP. Log on to the z/OS FTP daemon (refer to section 3.6 Connect Using FTP) and use the “PUT” command to send a packed backup file. Be sure to set the transfer type to BINARY before using the “PUT” commands as shown below.

Additional information regarding use of “PUT” commands can be found in the z/OS Communications Server IP User's Guide and Commands manual.

    ftp> bin
    ftp> quote site cyl pri=xxx sec=yyy
    ftp> quote site lrecl=1024 blksize=55296 recfm=fb
    ftp> quote site unit=3390 volume=VPWRKx
    ftp> put terse.dump
    ftp> quit

Step 2. TRSMAIN – use sample JCL member TRSMAINU found in data set LVL0.SVSC.CNTL to perform the unpack.

Step 3. DFSMSdss Restore – below is sample JCL for performing a restore.

//ST4         EXEC PGM=ADRDSSU
//SYSPRINT    DD SYSOUT=*
//TAPE DD     DSN=user.data.LDUMP,
//            DISP=(OLD,KEEP),UNIT=3390,
//            VOL=SER=VPWRKx
//SYSIN DD *
    RESTORE DS(INC( -
              user.DATA.** -
              ) -
              EXC(SYS1.** -
              )) ODY(VPWRKx) IDD(TAPE) CAN -
              NULLSTORCLAS BYPASSACS(**) TOL(ENQF)
/*

9.3 Add PROCS to start when the system comes up

If you have a started task that you will like to have it started when the system comes up, please add your changes to VENDOR.PARMLIB(ALLJ2) member.

9.4 IPCS

Prior to using IPCS for the first time, each user must specify the volume that IPCS will use. Issue the following command from the ISPF command line:

TSO BLSCDDIR VOLUME(VPxxxx)

VPxxxx = volume to be specified. Once this command has been issued, start IPCS using ISPF option IP.

9.5 Issuing CP Commands

CP commands can be issued in one of two ways, from the z/VM Control User ID or from the TSO environment using REXCPCMD. CP is the Control Program which operates within the first-level z/VM system.

Any CP commands issued on behalf of a guest z/OS system from the z/VM Control User ID follows the format:

SEND Guest-System ID \CP command

command = CP command you wish to send to the guest z/OS system.

SEND ETPGJON \CP Q V DASD

Any CP commands issued on behalf of a guest z/OS system from a TSO environment will follow the format REXCPCMD command. Here’s an example of the s a m e query commands issued from a TSO environment:

TSO REXCPCMD Q V DASD

9.6 Accounting Information

Many of the IBM Z (Dallas) ISV Center Remote Access Program fees include a specified amount of CPU work units in the base fee. 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 Program Charges section of the Exhibit included in the program enrollment package. The session report (“SESSREPT”) command is provided for you to monitor the work unit usage of your GuestSystem ID. Accounting records are stored for each Guest-System ID that has had usage during the twelve hour period ending at 07:00 and at 19:00 USA Central Time each day.

9.6.1 Obtaining Program Account Information

Work unit accounting information may be obtained for the guest z/OS system, for a specified date range by issuing the following CP command from a z/VM Personal User ID.

MSG SVUTIL SESSREPT ETPGJON FDATE LDATE

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

MSG SVUTIL HELP SESSREPT

SVUTIL: SVUTIL SESSREPT COMMAND SYNTAX:
SVUTIL:
SVUTIL: "MSG SVUTIL SESSREPT UUUUUUUU FDATE LDATE"
SVUTIL:
SVUTIL: WHERE UUUUUUUU = USERID FOR SESSION REPORT
SVUTIL:     FDATE = FIRST DATE TO BE REPORTED (MM/DD/YY)
SVUTIL:     LDATE = LAST DATE TO BE REPORTED (MM/DD/YY)
SVUTIL:
SVUTIL: ALL PARAMETERS ARE REQUIRED. DATES MUST BE BETWEEN 1989 AND
SVUTIL: THE CURRENT DATE. ONE OR TWO DIGITS OK FOR MONTH AND DAY.
SVUTIL:
SVUTIL: EXAMPLE TO REQUEST A SESSION REPORT:
SVUTIL:
SVUTIL: "MSG SVUTIL SESSREPT ETPXX01 8/14/93 8/15/93"

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’s CMS screen with an identifying file number. To view the contents of the file, enter the command:

PEEK filenum (FOR *

filenum = file number displayed on Personal User ID’s CMS screen.

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’ to peek. While peeking at the file, it may be easier to view after entering “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.7 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, ETPGJON is the guest system ID and ETPDESY is the desired new z/VM Control User ID:

Method 1: From the current z/VM Control User ID, issue the following command:

SEND ETPGJON \CP SET SECUSER ETPDESY

Method 2: From any z/VM Personal User ID owned by the customer, issue the following command:

MSG SVUTIL SECUSER ETPGJON ETPDESY

Method 3: From ISPF main menu in TSO, select option 6 and then enter the following command:

REXCPCMD SET SECUSER ETPDESY

Note: SVUTIL is a service machine that does a variety of things. To find out what it does, issue the command “MSG SVUTIL ?“. To get the syntax of any of the options, issue command “MSG SVUTIL HELP ###” (where ### is the option).

9.8 DASD Configuration

A guest z/OS system is comprised of the 3390 DASD volumes shown in Table 1. Other volumes may be available to the guest z/OS system. To display the volumes in the guest z/OS system, use ISMF or enter the following command from the SDSF log display:

/D U,DASD,ONLINE,,256

The following table lists the DASD Volume Serial Labels in the guest z/OS System.

Volume SerialAccessVOLSTATEDescription
VPMVSBRead/WritePRIV/RSDNTz/OS data sets including the Master Catalog, SMF data sets, Dump data sets which must be available to the guest z/OS system in write mode.
VPMVSCRead/WriteSTRG/RSDNTApproximately 213 MB of free disk space for user data sets. (252 cylinders on a 3390 DASD unit). This volume contains participant data that has been customized for the remote access program. In many cases, this volume can be moved to other programs facilitating productive data transitions.
VPMVSERead/WriteSTRG/RSDNTApproximately 420 MB of free disk space for user data sets. (420 MB is approximately 495 cylinders on a 3390 DASD unit). This volume contains participant data that has been customized for the remote access program. In many cases, this volume can be moved to other programs facilitating productive data transitions.
VPMVSDRead/WritePRIV/RSDNTData sets which have the high level qualifier of VENDOR. These data sets are integrated into the system to assist participants with the customization of the system. This volume contains participant data that has been customized for the remote access program. In many cases, this volume can be moved to other programs facilitating productive data transitions.
VPZFSBRead/WritePRIV/RSDNTSmall amount of free disk space under the control of DFSMS. This volume contains ZFS files for OpenEdition.
VPSMSBRead/WritePRIV/RSDNTSmall amount of free disk space under the control of DFSMS. This volume contains the couple data sets required in a sysplex and some of the ZFS files for OpenEdition.
VPSMSCRead/WritePRIV/RSDNTSmall amount of free disk space under the control of DFSMS. This volume is for user data sets like ZFS files. This volume contains participant data that has been customized for the remote access program. In many cases, this volume can be moved to other programs facilitating productive data transitions.
VPSMSDRead/WritePRIV/RSDNTSmall amount of free disk space under the control of DFSMS.
VPSPOLRead/WritePRIV/RSDNTJES2 Spool and Checkpoint volume.
VPSPOMRead/WritePRIV/RSDNTJES2 Duplex Checkpoint volume.
VPPAGARead/WritePRIV/RSDNTPLPA, Common and Local page data sets.
VPPAGBRead/WritePRIV/RSDNTLocal page data set.
VPPAGCRead/WritePRIV/RSDNTLocal page data set.

9.8.1 System Managed Storage

9.9 IBM Z (Dallas) ISV Center Provided Data Sets

Most of the data sets listed below are located on the disk volume labeled VPMVSD. Volume VPMVSD is available to the system in | Read/Write | mode. There are also data sets on volume VPMVSB which influence the operation of the guest z/OS system. Most other volumes are available to the system in Read/Only. Data sets on Read/Only volumes cannot be modified.

Data Set NameIntended Usage
VENDOR.PARMLIBPDS for users' provided parameters. Useful to hold "SYSIN" data for PROCLIB members.
VENDOR.PROCLIBEmpty procedure library in the JES2 default procedure concatenation for user created procedures (PROCS.)
VENDOR.ISPLLIBEmpty ISPF messages data set in the ISPF default ISPMLIB DD concatenation for user ISPF messages.
VENDOR.ISPMLIBEmpty ISPF messages data set in the ISPF default ISPMLIB DD concatenation for user ISPF messages.
VENDOR.ISPPLIBEmpty ISPF panel data set in the ISPF default ISPPLIB DD concatenation for user panels.
VENDOR.ISPSLIBEmpty ISPF skeleton data set in the ISPF default ISPSLIB DD concatenation for user ISPF skeletons.
VENDOR.ISPTLIBEmpty ISPF table data set in the ISPF default ISPTLIB DD concatenation for user tables.
VENDOR.CLISTTSO CLIST data set in the TSO default SYSPROC DD concatenation for user provided global CLISTs.
USERID.CLISTTSO CLIST data set, when found at logon will be included in the TSO default SYSPROC DD concatenation for individual user CLISTs.
VENDOR.HELPEmpty data set in the default SYSHELP DD concatenation for user HELP text.
VENDOR.LPALIBEmpty data set included in the LPA list concatenation for user provided modules which need to be in PLPA. This data set has also been APF authorized.
VENDOR.LINKLIBEmpty data set included in the link list concatenation for user provided modules which need to be in the link list. This data set has also been APF authorized.
VENDOR.SYSEXECEmpty data set in the default SYSEXEC DD concatenation for user REXX language EXEC source.
VENDOR.VTAMLIBEmpty data set included in VTAMLIB concatenation in member VTAM for user supplied VTAM exits, USS tables, etc..
VENDOR.VTAMLSTEmpty data set included in VTAMLST concatenation in member VTAM for user supplied VTAM exits, USS tables, etc..

This system implements dynamic linklist. Please see the PROG= parameter in LVL0.PARMLIB(IEASYSLV). The easiest way to review the linklist is with the operator command:

D PROG,LNKLST

The PROG= parameter is used for APF authorization also. Please be sure to review all the PROGxx members referenced in the PROG= parameter. The easiest way to review the APF list is with the Operator command:

D PROG,APF,ALL

9.11 Default LPA List

To determine the LPALST concatenation please review the LPA= parameter of LVL0.PARMLIB(IEASYSLV).

9.12 Default PROCLIB Concatenation

The following list describes the PROCLIB concatenation as initially delivered, in order of concatenation:

9.13 CATALOG Structure

The master catalog is named MASTERV.CATALOG. All user catalogs have a high level qualifier of CATALOG. Most data sets will get cataloged in the master catalog unless additional aliases are added.

9.14 Highlights from LVL0.PARMLIB

This system exploits the concatenated PARMLIB feature. All changes traditionally implemented by changing members in SYS1.PARMLIB should be made in VENDOR.PARMLIB. All references through out this document to SYS1.PARMLIB should be considered as references to the PARMLIB concatenation

Member IEASYS00 contains very few parameters and the IBM Z (Dallas) ISV Center expects these to be static. The one parameter that might be changed is CLPA.

Member IEASYSLV contains most of the parameters used to influence system initialization. Member CLOCKSV is set to USA Central Time. Modify this to a different time zone if desired. Member JES2420A contains the JES2 initialization parameters.

9.15 SMP/E Data Sets and Maintenance Information

The SMP/E control information for z/OS and other closely related products can be referenced in MVS.GLOBAL.CSI.

NOTICE

Because these VSAM data sets are located on Read/Only disk volumes, several error messages will be issued during data set opening and closing. These messages have no effect on the retrieval of information from the data sets and may be ignored.

Listed below is an example of the messages which are issued to TSO users during the initial access of the SMP/E data set MVS.GLOBAL.CSI using the ISPF SMP/E Dialogs.

IEC251I 037(246,000,IGG0CLHA)-006,SVTSCU,SPFPROCESPFPROCE,SMPCSI,,,
IEC251I MVS.GLOBAL.CSI,MVS.GLOBAL.CSI.DATA,CATALOG.OS390
IEC251I 037(246,000,IGG0CLHA)-006,SVTSCU,SPFPROCESPFPROCE,SMPCSI,,,
IEC251I MVS.GLOBAL.CSI,MVS.GLOBAL.CSI.INDEX,CATALOG.OS390

Listed below are examples of the messages which are issued to the z/OS operator console during the same initial access of the SMP/E data set MVS.GLOBAL.CSI using the ISPF SMP/E Dialogs. Each of these messages will be issued several times.

IEF196I IEC331I 050-018(00201110),SVTSCU ,SPFPROCE,,IGG0CLE2
IOS000I 222,16,WRI,05,0200,80020000C4BC2000,02BC0000,VDMVSB,SVTSCU
IOS000I 222,16,WRI,05,0200,80020000C4BF2000,02BF0000,VDMVSB,CATALOG
IEC331I 050-018(00201110),SVTSCU ,SPFPROCE,,IGG0CLE2
IEC251I 037(246,000,IGG0CLHA)-006,SVTSCU,SPFPROCESPFPROCE,SMPCSI,,,
IEC251I MVS.GLOBAL.CSI,MVS.GLOBAL.CSI.DATA,CATALOG.OS390

9.16 RACF Information

The RACF Data Security Monitor (DSMON) should be executed. This RACF utility will give details about the specific RACF implementation which have not been included in this document. JCL for this utility can be found in member DSMON of data set LVL0.JCLLIB.

CLIST ADDUROM located in LVL0.CLIST will add user IDs to RACF, TSO and optionally SYS1.UADS. The CLIST requests all the required information by prompting the invoker with questions. To use the CLIST from the TSO READY prompt, type “ADDUROM” and press the ‘ENTER’ key. TSO user IDs cannot be greater than 7 characters.

The ADDUROM procedure assumes that predefined RACF groups, TSO accounts, and TSO logon procedures will be used. The following have been predefined for use on the guest z/OS system:

Example 1:

Pre-defined optionValue
RACF group for new usersGROUP2
TSO account numberGROUP2
TSO logon procedureSPFPROCE
USS UIDxxx
USS User Directory/u
USS SHELL/bin/sh

Example 2 (for more authority):

Pre-defined optionValue
RACF group for new usersGROUP1
TSO account numberFB3
TSO logon procedureSPFPROCE
USS UID0
USS User Directory/u
USS SHELL/bin/sh

These items would be used in response to the ADDUROM prompts.

Unless there is a real need, it is not recommended to create new RACF groups, TSO account numbers, or TSO logon procedures. However, these are the general steps required to accomplish the corresponding RACF definitions:

To define a new RACF group, issue the TSO ADDGROUP command (e.g. "AG GROUP3"). This group will then need to be permitted to the TSO account number and logon procedure to be used (see below). In addition, issue the command to PERMIT this group to the TSOAUTH commands RECOVER and JCL and possibly others (e.g. "PE xxxx CL(TSOAUTH) ID(GROUP3) ACCESS(READ)", substituting for xxxx with ACCT, PARMLIB, OPER, RECOVER, and/or JCL as desired).

To define a new TSO account, first issue the TSO RDEFINE command (e.g. "RDEF ACCTNUM GROUP3"), then issue the TSO PERMIT command (e.g. "PE GROUP3 CL(ACCTNUM) ID(GROUP3) ACCESS(READ)"), and then issue the TSO SETROPTS command to refresh the instorage profiles (e.g. "SETR RACLIST(ACCTNUM) REFRESH").

To define a new TSO logon procedure, first issue the TSO RDEFINE command (e.g. "RDEF TSOPROC PROCXX"), then issue the TSO PERMIT command (e.g. "PE PROCXX CL(TSOPROC) ID(GROUP3) ACCESS(READ)"), and then issue the TSO SETROPTS command to refresh the instorage profiles (e.g. "SETR RACLIST(TSOPROC) REFRESH").

The user password interval is 60 days. The initial password for IBMUSER is IBMUSER. RACF will require the initial password to be changed the first time this user ID is logged on. Note that all TSO user IDs will be revoked after 6 consecutive unsuccessful logon attempts.

RACF Exit Routines:

RACF Groups:

RACF General Resource Class TSOPROC is active. The only profile is SPFPROCE.

RACF General Resource Class ACCTNUM is active. The only profiles are FB3 and GROUP2.

RACF General Resource Class PERFGRP is active. No profiles have been defined.

RACF General Resource Class TSOAUTH is active. Profiles for this class are ACCT, JCL, MOUNT, OPER, PARMLIB, and RECOVER.

9.17 VTAM Definitions

The terminals defined at E00-E07 do not have the extended data stream attribute. Specifically, the VTAM parameters FEATUR2=MODEL2 and DLOGMOD=S3270 have been coded in the VTAM terminal definition. The terminals defined at F00-F07 have the extended data stream attribute.

Specifically, the VTAM parameters FEATUR2=EDATS and DLOGMOD=NSX32702 have been coded in the VTAM terminal definition. Use this for data transfer (IND$FILE) from a TN3270 emulator.

VTAM USS Tables – Only one VTAM USS table exists in the system. Member USSTAB1 in LVL0.SVSC.CNTL contains the source. Member USSTAB1@ will assemble and link edit a new table.

Below are pieces from LVL0.PROCLIB(VTAM):

//VTAMLST DD DISP=SHR,DSN=VENDOR.VTAMLST
//    DD DISP=SHR,DSN=SVTSC.VTAMLST
//    DD DISP=SHR,DSN=LVL0.VTAMLST
//    DD DISP=SHR,DSN=SYS1.VTAMLST

//VTAMLIB DD DISP=SHR,DSN=VENDOR.VTAMLIB
//    DD DISP=SHR,DSN=SVTSC.VTAMLIB
//    DD DISP=SHR,DSN=LVL0.VTAMLIB
//    DD DISP=SHR,DSN=SYS1.VTAMLIB

Using this structure, custom changes for VTAMLST should be placed in VENDOR.VTAMLST. Changes for VTAMLIB should be placed in VENDOR.VTAMLIB.

9.18 JES2 Information

Initiators 1-5 and 9 are activated at JES2 initialization. These initiators service execution classes A, B, H, K, L, S, 4, and 7. The default output class is A. The default HOLD output class is H. Use this output class to place TSO and batch job output in a HOLD queue for browsing with the TSO OUTPUT command and the ISPF OUTLIST utility (option 3.8).

There are no site specific required job card parameters.

WARNING REGARDING JES2 AUTOMATIC PURGE

Output class Z is defined as a JES2 purge class – all output directed to this class will be automatically purged immediately. Use this output class with care.

Output classes D and W are periodically purged by a JES2 automatic command output directed to these classes will be automatically purged at the next automatic command interval (every 60 minutes for class W, every 2.5 hours for class D). Some of the system started tasks (such as TCAS) direct their output to class W. This output will remain in the output queue for a period of time and then will be purged permanently. Use these output classes with care.

Note: The JES2 automatic commands may be found at the bottom of the JES2 PARMLIB member SYS1.PARMLIB(JES2420A).

Printer 1 at address 002 is defined as a 3211 to z/OS and z/VM. It is placed in a drained status during JES2 initialization. This is a virtual printer, and should normally remain drained. Starting a virtual printer will write the output to the z/VM SPOOL (where it will be inaccessible from the guest z/OS system.) The data will not actually print on a real printer.

9.19 TSO Logon Procedures and Data Set Concatenation

There are two TSO logon procedures defined in LVL0.PROCLIB. These members are named SPFPROCE and IKJACCNT. These logon procedures contain very few DD statements. Most data set allocation is completed through CLIST/REXX procedures invoked at logon. Additional procedures may exist for other software products like DB2.

Listed below, in the order of invocation, are the CLIST/REXX procedures which get executed during logon. Beside each procedure is a brief description of its function. All CLIST/REXX procedures are located in LVL0.CLIST, except as noted.

CLIST/REXXFunction
SETUPInvoked from the logon procedure. Invokes the other CLIST/REXX described below and then PDF.
SYSPROCInvoked by the CLIST SETUP. Creates the SYSPROC DD concatenation.
SYSEXECInvoked by the CLIST SETUP. Creates the SYSEXEC DD concatenation.
SYSHELPInvoked by the CLIST SETUP. Creates the SYSHELP DD concatenation.
LOGMSGInvoked by the CLIST SETUP. Delivers any messages that the IBM Z (Dallas) ISV Center needs to broadcast to users. Please do not override this CLIST or the call to this CLIST.
ISPPROFInvoked by the CLIST SETUP. Allocates the ISPF/PDF profile data set.
ISPFDSInvoked by the CLIST SETUP. Allocates the ISPF/PDF DD concatenations for ISPLLIB, ISPPLIB, ISPMLIB, and ISPSLIB.
ISPFTABInvoked by the CLIST SETUP. Allocates the ISPF/PDF DD concatenations for ISPTABL, SMPTABL, and ISPTLIB.
VENDORCInvoked by the CLIST SETUP. This REXX is provided by the IBM Z (Dallas) ISV Center in VENDOR.CLIST. This REXX is the place during TSO LOGON where the user should perform any customizations.

9.19.1 Sample Jobs and CLIST/REXX Availability

WARNING

When security internal to the guest z/OS system is required (i.e. between users of the guest z/OS system), remove or otherwise protect this procedure from casual use as it enables access to a RACF SPECIAL user ID. To effectively remove the procedure, create a dummy procedure of the same name and place it in the VENDOR.PROCLIB data set.

10 Help for Common Problems

PROBLEMACTION TO BE TAKEN
HCPSEC068E SEND command failed; receiver has not authorized senderRead 9.7 Switching the z/VM Control User ID
HOLDING in lower right-hand corner of screen.Press the ‘CLEAR’ key to clear the screen and continue normal operation.
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 IEE362A SMF ENTER DUMP FOR SYS1.SYSNAME.MANx ON vvvvvv appears on MVS console and system log.Use the SMF dump program to dump the data set for future processing. If SMF data does not need to be retained, clear the condition by starting task CLRMAN1 for SYS1.SYSNAME.MAN1 or CLRMAN2 for SYS1.SYSNAME.MAN2.

Note: Only the inactive SMF data set may be cleared. Use the "ISMF" MVS command to switch SMF data sets if necessary.
Message IOS152E DEVICE dddd BOXED BY SUBCHANNEL RECOVERY appears on MVS console and system log.For tape devices, this message is usually caused by putting the system to sleep without first detaching the attached tape device (Always vary offline and detach the tape device before putting the guest z/OS system to sleep). The tape device was forcibly detached without first being varied offline to MVS, resulting in the boxed condition. The device address will be unusable until the next IPL. Substitute another tape device address for the next tape mount request (e.g. if you were using address 590 and now 550 is boxed, use 551).
Messages $HASP488, $HASP479, and $HASP454 appear on the MVS console and system log.Reply "Y" to message $HASP454 to bypass the multi-system integrity lock and allow JES2 to continue initialization (the actual command entered would be "R nn,Y" where "nn" is the reply number to the left of message $HASP454).
Message $HASP601 appears on the MVS console and system log.Enter the "$S A,ALL" command to restart JES2 automatic command processing. This message may appear as a result of an extended period during which the system was halted (for example, put to sleep over a weekend). The JES2 automatic commands are used to periodically cleanup unwanted SPOOL output files from TCAS, etc.
Message UNABLE TO ESTABLISH SESSION – INIT SELF FAILED WITH SENSE 08570002 appears after typing "TSO" on the MVS VTAM screen to access TSO.The TSO application is not active. On the MVS Master Console, start the TSO application with the "START TCAS" command. After TSO has started (messages IKT005I and IKT007I appear), reenter the "TSO" command.

Note: It is not necessary to clear the screen or re access the VTAM logo – type "TSO" on the same screen with the UNABLE TO ESTABLISH SESSION error message.
Message HCPGIR450W CP entered; disabled wait PSW 000A0000 000000xx appears after attempting to IPL a guest z/OS 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 the IBM Z (Dallas) ISV Center for assistance.
HCPSEC068E “SEND” command failed; receiver has console input waitingBe sure you are using a backward slash () preceding CP in the “SEND” command.

If you are using a backward slash () and receiving this message, try setting the code page associated with your session emulator to 1047
HCPLGA054E Already logged on disconnectedThe guest z/OS system is already up and running. Refer to 6. Managing the Guest z/OS System with “SLEEP” and “BEGIN” to see if the system is in SLEEP mode.
HCPLGA054E Already logged on LUNAME ... when logging onto a z/VM Personal User IDType “LOGOFF” and press the ‘ENTER’ key to return to the logo screen. On the logo screen, tab to the COMMAND line and type “L ETPDESY HERE” and press the ‘ENTER’ key.
Guest z/OS system fails to complete IPL

or

$HASP454 SHOULD JES2		Issue the command:

SEND ETPGJON \CP VI VMSG D R,L

Look for $HASP454 message. Respond 'Y' to this message
BYPASS THE MULTI-MEMBER INTEGRITY LOCK? ('Y' OR 'N')SEND ETPGyyy \CP VI VMSG R 2,y

Please complete the remaining steps to IPL the guest z/OS system. Review the information in section 4.2 How to IPL the Guest z/OS System (Detailed Description).
Trouble accessing the Remote Development system from a remote application.Information about blocked ports can be found on the IBM Z (Dallas) ISV Center Website at URL:

https://dtsc.dfw.ibm.com/MVSDS/'HTTPD1.DSN01.PUBLIC.HOME.SHTML(BLKPORTS)'
$HASP050 JES2 RESOURCE SHORTAGETo verify the problem, issue the command: $DSPL

To cleanup all spool older than 7 days, issue the command: $POJOBQ,ALL,PROTECTED,DAYS>7

Automatic cleanup of syslog output can be done to help prevent
$HASP050 JES2 RESOURCE SHORTAGE (Continued… )the spool space full condition. This can be done by placing the following command at the bottom of the JES2 parameter deck:

$TA,T=00.30,I=86400,'$POJOBQ,Q=C,DAYS>7

This will delete any class C output every 24 hours at 00:30 am that is greater than 7 days old.

Class C output is the normal class specified in IEASYSLV in LVL0.PARMLIB for the syslog output class. If the class is changed then the command will need to be modified as well.
Unable to log on to TSO,

or IEA602I ADDRESS SPACE CREATE FAILED. A STORAGE SHORTAGE EXISTS

or IRA200E AUXILIARY STORAGE SHORTAGE		This condition is caused by a shortage of slots in the Auxiliary storage configuration. This can be resolved by removing unneeded tasks that are currently running. If you require all SHORTAGE EXISTS tasks, contact the IBM Z (Dallas) ISV Center to obtain additional storage needed.

Prior to logoff and restarting the guest z/OS system for problem determination, please issue the following commands:

D ASM

D R,L

D A,L

W
Unable to connect to the guest z/OS systemPlease see 6. Managing the Guest z/OS system with “SLEEP” and “BEGIN”.

Please review the information in 4.2 How to IPL the Guest z/OS System (Detailed Description).

If you are still unable to connect, please open an IBM Support case for assistance.

11 Other Information

11.1 Terms and Definitions

TermDefinition
Guest systemAn operating system running in a virtual machine managed by the z/VM Control program.
Control User IDThe term z/VM Control User ID is used to reference the specific z/VM Personal User ID used to initialize the guest z/OS system and currently holds the ability to perform functions for the system.
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/VM Virtual 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.

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 READMeans that CP 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).
RUNNINGMeans that CP or CMS either is ready for the next CP or CMS command or is processing a previously entered command.
MORE...Means that the output display area is full and that 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 you do not respond to the MORE... indicator within 1 minute, the next screen will automatically be displayed (your display device will beep 10 seconds prior to display of the next screen).
HOLDINGMeans that the ‘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’.
Special KeysThe ‘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.
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.

11.2 Technical Support

Technical support is provided through the IBM Support Portal: https://ibm.com/mysupport Please open a case for the "IBM Z and LinuxONE Partner Network" service. To get started with opening cases for the "IBM Z and LinuxONE Partner Network" service in IBM Support, please use the CSP Quick Start Guide.

Hours of attended operation are 07:00 to 19:00 US Central time Monday through Friday except IBM USA holidays. Cases received after hours, on weekends, or on holidays will be processed the next business day.

11.3 z/OS System Customization

The User's Guide and Reference contains basic information about working with the guest z/OS system. For more detailed information about customizing the guest z/OS, please visit the “Getting Started at IBM Z (Dallas) ISV Center” link on the IBM Z (Dallas) ISV Center website at URL https://dtsc.dfw.ibm.com/public

11.4 Trademarks

The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol (® or ™), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, or service names may be trademarks or service marks of others.

11.5 Notices

This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.