BSP - Beratung, Schulung, Projekte

Table of Contents

HOW TO .... document

This documents provides information about various aspects of working with Hercules and/or MVS. You will find links to different documents in this cookbook, and you will also find new articles.

Table of Contents

HOW TO ... Start Up Hercules

I think you should take a look at the Tur(n)key Operations manual.

Table of Contents

HOW TO ... Change the Console/Terminal configuration

The default Console and Terminal configuration is probably sufficient for your needs. If you wnat to change it, though, this can be easily done. Just check the setterm documentation

Table of Contents

HOW TO ... Use the C3270 Terminal Emulator

The C3270 terminal emulator is an open source emulator which as included on the Tur(n)key CD, where you will find the documentation as well.

Table of Contents

HOW TO ... Connect a TN3270 session to Hercules

If you want to connect a 3270 session to Hercules, you will first need a 3270 emulator program. Then you should edit the startterm script to name the 3270 emulator of your choice. Then run it before you initialize MVS. All the terminals that connected to Hercules should now show a screen like this:

 Hercules version 2.16.2 built at May 21 2002 16:33:56 device 00C0
 running on BSPW0103 (CYGWIN_NT-5.0 1.3.10(0.51/3/2))

Table of Contents


Ahh, you managed to start Hercules, and now you want to start the operating system MVS as well. Very simple, take a look at the MVS IPL documentation. When MVS has completed initialization, then all the non-console terminals should show the LOGON screen:

            Welcome to MVS3.8J, running under the Hercules emulator

    TT      UU    UU   RR    RR   NNN    NN   KK  KK     EE          YY  YY
    TT      UU    UU   RR    RR   NNNN   NN   KK KK      EE          YY YY
    TT      UU    UU   RRRRRRR    NN NN  NN   KKKK       EEEEEEE      YYY
    TT      UU    UU   RRRR       NN  NN NN   KK  KK     EE           YY
    TT      UU    UU   RR  RR     NN   NNNN   KK   KK    EE          YY
    TT      UU    UU   RR   RR    NN    NNN   KK    KK   EE         YY
    TT       UUUUUU    RR    RR   NN     NN   KK     KK  EEEEEEE   YY

                       \      _,,,---,,_                brought to you by
                ZZZzz /,`.-'`'    -.  ;-;;,              Volker Bandke
                     ,4-  ) )-,_. ,\ (  ''-'  
                    '---''(_/--'  `-'\_)

 Logon ===>

Table of Contents

HOW TO ... Re-connect a TN3270 session to Hercules

You connected a 3270 session to Hercules, after VTAM was activated, and cannot do anything with it? Well, you will have to tell VTAM that a new session has been establish. At the MVS console enter

v net,inact,id=cuu0c3,i
(Of course, you need to provide the correct LUname. My use of CUU0C3 is just an example). This command should then be followed by
v net,act,id=cuu0c3
Both commands are combined in on function key on the OS console. You invoke them via PFK 2.

Table of Contents

HOW TO ... Logon to TSO

There are five predefined TSO users in the MVS Tur(n)key System:
Userid Description Password
IBMUSER Emergency user  
HERC01 System Programmer Userid  
HERC02 System Programmer Userid CUL8TR
HERC03 Standard user  
HERC04 Standard user PASS4U
In order to logon to TSO, you enter

logon xyz
at the logon screen (where xyz is the Userid which you want to use). For the five predefined userids above you can omit the word logon. If you omit the Userid, then you will be prompted for a correct userid. The TSO session will be initiated right away. You can also use the full set of TSO LOGON parameters as can be seen by entering
help logon
when connected to TSO. One option that can be very useful is the reconnect option. If your 3270 session was somehow terminated, and you reconnected the session, you should LOGON to the system by following the userid with the word reconnect. That way, if your previous TSO address space is still available, the terminal session will be reconnected to the TSO address space, and you can resume your work

Table of Contents

HOW TO ... Edit a Dataset

Well, if you want to edit a dataset, you would normally use SPF or a similar package. Unfortunately, SPF is a licenced program product and thus cannot be distributed as part of the Tur(n)key system. Enters Rob Prins, who has written a nice editor that is something of an SPF look-alike. It is called RPF (for Rob's Programming Facility). Just enter RPF at the command prompt, and off you go. You might also take a look at the RPF User's guide in the /cookbook/pdf on the CD-ROM

RPF has one drawback, though. It only works with fixed length record datasets. If the file you want to edit has variable record size, then you need to use FSE, the Full Screen Editor. It is not an SPF look-alike system, but follows its own set of rules. You should enter
help fse
to get a description of the FSE editor and the editor commands. The editor itself is, of course, pre-installed and is invoked by entering FSE at the TSO command prompt

Another alternative is the TSO edit command, which is

At the TSO command prompt enter
help edit
to get more information

Table of Contents

HOW TO ... Create a new TSO User

You must be logged on with a Sysprog type user, like Herc01, to be able to define new users. Take a look at the job in SYS2.JCLLIB(ADDUSER). You need to change the invokation parameter HLQ to the new userid, and you need to specify if the new user is a system programmer, or not. Creating a "normal", non-sysprog type user will be done with a jcl line like this

whereas a sysprog type user would be defined via

Note:The users just created have no password set!

Creating a new user also means creating a new entr for the user's alias into the master catalog. If the master catalog is password protected (as it is in the Tur(n)key System) then an MVS WTOR will be issued to which you will have to reply with the correct password. For more info on password protection take a look at How to use Passwords

Table of Contents

HOW TO ... Create a new TSO user with a Password

This is nearly exactly like above. Just run job SYS2.JCLLIB(ADDUSERP) (note the P at the end of the member name). This will create a new user and assign a standard password: CUL8TR for system programmers and PASS4U for the others

Table of Contents

HOW TO ... Change a User's Password

Just run job SYS2.JCLLIB(CHGPWD) and specify the userid and the new password to be used. The user may not be logged on when changing his password

Table of Contents

HOW TO ... Shutdown MVS

The easiest way to shutdown the system is via the autopilot. Go to an MVS console and enter one of the following commands

f bsppilot,shutdown
f bsppilot,shutfast
f bsppilot,shutnow
Any one of these commands will terminate MVS. The shutdown will warn logged on user about the upcomming shutdown, an will give them a certain grace period in which they can save what they have been doing and then log off. The shutfast command is similar, it just gives a shorter grace period. And the shutnow doesn't warn, and doesn't give a grace period either, it just starts the shutdown sequence.

If you have initiated a shutdown command, you can cancel it during the grace period by using

f bsppilot,shutcanc
at the master console.

Table of Contents

HOW TO ... Shutdown JES2

After everything has come to a grinding halt, you will now have to stop JES2 by entering

Sometimes the system may reply that JES2 is not dormant. You either still have jobs or started tasks running, or some of the JES devices are still active. You can issue a
command to find which devices are still active. Very often this will be device the RDR1 at 00C, which will be in wait with a "Intervention Required" message. If this is the case, just submit the job jcl/dummy through the reader (possibly via the sub script in the jcl directory):
sub dummy
When the job has been submitted, the Intervention Required message will disappear, and you probably can now enter the $p jes2 successfully.

Every so often, JES2 get the hiccups, reports some catastrophic error, and then issues message


If you look up the possible replies in the modern JES2 manuals, you are out of luck. They don't work. You have the following options:

  1. R xx,snap
  2. R xx,dump
  3. R xx,purge
to request a snap dump, and SVC dump, or just to shutdown JES2

Table of Contents

HOW TO ... Submit a Job

The answer to this question depends where the job (=JCL stream) is located.

Submit commands in MVS

It the job is a member of a PDS in MVS, you open the member with RPF and enter the sub editor subcommand
 CMD => sub                                               SCOPE 01,80 SCROLL CSR
 ...... ----+----1----+----2----+----3----+----4----+----5----+----6----+----7--
 000002 //             'Define an Alias',
 000003 //             CLASS=A,
 000004 //             MSGCLASS=A,
 000005 //             MSGLEVEL=(2,1),
command in the command field. An alternative would be using the TSO SUBMIT command from the TSO prompt:

Sub commands in Linux/Windows

Now, what if the JCL is not located inside of MVS, but is a file in the directory of our PC? Then you must pass the job to MVS via a reader. A reader was a device that used to read punch cards and feed them to MVS. We, of course, don't use punch cards any more. And, we don't have a real reader, either. But Hercules emulates a reader device. The turnkey system actually has 2 reader devices, one for feeding JCL to MVS, and one for other purposes. The reader that feeds JCL to MVS is at device address 00C. As distributed, this device is waiting for JCL coming its way via TCP/IP: It is listening at a specified port (default 3505) for incoming data. The only thing you need to do is send the data to that port on the machine where Hercules is running.

There is a command file or bash script, conveniently called sub, that does this for you.


There is a program called hercrdr.exe in the hercules directory of the installation JCL. Copy this file into a directory in your path. There is also a file called sub.bat that should also be copied into a directory in your path. Then you can just enter
sub myjob
to submit the file myjob to MVS.


When a superuser/root user runs the Turnkey setup script, an option will be presented to install certain utility functions. One of the utilities that is offered for installation is netcat, a tool to send data all around the network. Ask your system administrator to install that utility for you. Next you should copy the sub into a directory in your path. Then you can just enter

sub myjob
to submit the file myjob to MVS.

How does it work

The magic is in the hercules setup file. Device 00c is defined with a line like this

000C 3505 myhost:3505 sockdev ascii trunc eof
!    !    !      !    !       !     !     !
!    !    !      !    !       !     !     +- signal eof to reader device
!    !    !      !    !       !     +------- truncate data > 80 bytes
!    !    !      !    !       +------------- The incoming data is ASCII
!    !    !      !    +--------------------- This is a socket reader
!    !    !      +-------------------------- Use port 3505 for inbound data
!    !    +--------------------------------- Name of machine running Hercules
!    +-------------------------------------- device type: reader device
+------------------------------------------- device address: 00C

Which tells Hercules to wait for incoming data on port 3505. The Windows and/or Hercules utilities send data to that machine, even across the network. With other words, you can submit JCL that is located on machine A to MVS that is running under Hercules on machine B

If you want a more technically oriented discussion of this topic, tape a look at the this article in the Hercules documentation

devinit command in Hercules

The last alternative I mention here is the Hercules devinit command. It is entered at the Hercules consol panel and assigns a PC file to a Hercules device. In out case the command would be

devinit 00c myjcl/dir/myjob eof ascii trunc
        !   !               !   !     !
        !   !               !   !     +--- truncate data that is longer
        !   !               !   !          than 80 bytes (optional)
        !   !               !   +--------- incoming data is ASCII
        !   !               !              (optional, can autodetect)
        !   !               +------------- Signal EOF on end of data
        !   +----------------------------- name of dataset to be fed to device
        +--------------------------------- Device address
which would make Hercules read the file in myjcl/dir/myjob and pass it to device 00C.

While Hercules understands backwards slashes in pathnames under Windows, it also understands the forward slash. The path entered is relative to the Herculesexecution path, unless a leading (back)slash is provided to indicate an absolute path

Table of Contents

HOW TO ... use the Hercules GUI

David B. Trout (aka FISH) has provided a very nice Graphical User Interface for Hercules. This interface is only available on the Window platforms, and will be installed on request when you install Hercules from the Tur(n)key CD. A description can be found at Hercgui User's Guide.

There is a parameter in the Turnkey configuration file that is not yet understood by the HercGUI. You can overcome this problem by starting the GUI (via the startgui command file) and then

File ---> Preferences ---> Misc ---> ignore configuration file parse error(s)

Table of Contents

HOW TO ... Compile a COBOL program

You might get error messages that compile fails due to insufficient buffer space:


If that happens, increase the compilers buffer space in the compile parms like this

// PARM='SIZE=2048K,BUF=1024K,...*,
// REGION=4096K
The buffers for files ( BUF= ) comes from memory in the total size ( SIZE= ), so SIZE= must be larger than BUF=

Table of Contents

HOW TO ... protect a Dataset

MVS allows to assign passwords to dataset in order to protect them from unauthorized access. Take a look at Password Protection