So, you want your own mainframe? // Hercules z/Architecture Emulator Tutorial

I attribute about 95% of my learning to actually doing work.  Most of my peers would agree and even push it further to “95% of my learning is by screwing things up.”  For many computing platforms, it is very easy to spin up a VM and get working.  However, it seems nearly impossible to do with the mainframe.  That is, until you hear about Hercules.

When I first heard about Hercules in college, I was fascinated.  You are telling me I can run a mainframe off my laptop?  I rushed to the dorms to begin my journey to become a mainframe expert.   Then, it hit me…

“Wow, there is WAAAAYY too many things here I have no idea about.  I don’t even know where to begin…Well, I guess it is time to learn more about Linux…”

And that was it.  It is not that the Hercules documentation is poorly written.  It is not that the system is just too complex.  It is the culture of the mainframe world.  Every mainframer I talk to, every manual I read – they all assume knowledge.  And rightfully so.  There is so much information and so many things you can do with a mainframe.  It is impossible to have an easy Mainframe 101 crash course.

But, impossible has never stopped me from trying before…

Mainframe 101: Crash Course – Step 1: Obtain a Mainframe

Step 1 – Get a Debian-based server going

Step 2- Download the following:

Step 3 – Install Hercules on your Server

  1. Install Hercules from the repo:

    sudo apt-get install hercules

Step 4 – Configure MVS System (TurnKey)

  1. Extract the TurnKey ISO to ~/turnkey
  2. Change directory into turnkey

    cd turnkey

  3. Change the permissions on ./setup

    sudo chmod 777 setup

  4. Run standard setup

    ./setup -a

  5. Confirm the installation with a ‘Y’ when prompted
  6. Enter ‘SECRET’ as the catalog password
  7. Press ENTER to complete the install when prompted

Step 5 – Start up the Machine

  1. Change directory to ../mvs38j

    cd ../mvs38j

  2. Start the machine


  3. WAIT!

    You will be prompted to ensure you have 3270 sessions for consoles and TSO terminals.  Make sure you have these running before you IPL.  You will waitstate if you do not have these connected.

Step 6 – Setup your 3270 sessions

  1. Install wc3270 from the download in Step 1 on your client pc
  2. Launch wc3270wiz.exe
  3. Enter ‘1’ to Create new session
  4. Enter ‘console1’ for session name
  5. Enter the IP address of your server
  6. Enter ‘3’ to change TCP Port
  7. Enter port ‘3270’
  8. Press ENTER on the Options screen to confirm the settings
  9. Enter ‘y’ to create session file
  10. Enter ‘y’ to create desktop shortcut
  11. Enter ‘1’ for Create new session
  12. Enter ‘tso1’ for session name
  13. Enter the IP address of your server
  14. Enter ‘2’ to change the ‘Logical Unit Name’
  15. Enter ’00C0′ for the LU
  16. Enter ‘3’ to change TCP Port
  17. Enter port ‘3270’
  18. Press ENTER on the Options screen to confirm the settings
  19. Enter ‘y’ to create session file
  20. Enter ‘y’ to create desktop shortcut
  21. Enter ‘8’ to exit
  22. Start the two session on your client pc

Step 7 – IPL!

  1. On your server, press ENTER to complete starting Hercules
  2. Enter ‘ipl 148’
  3. On your console session, you will receive a message:
  4. Enter the following to specify no system parameters and create a link pack area:

    R 00,CLPA

  5. If you see the following message:
    hasp479Enter the following command:

    R 00,Y

    And then start JES2 with the following:


    Reply to the UNABLE TO OBTAIN… message again:

    R 01,Y

    And then reply to the confirmation message:

    R 02,Y

  6. Issue the following to display the running tasks:

    D A,L

    If you see TSO running, you can login with your TSO session.

  7. On your TSO 3270 session, login as IBMUSER
  8. You are now on your mainframe. Have fun!


How to shutdown the system:

  1. From the console, issue the following command:


  2. Once you see that the shutdown is complete, verify JES2 is the only running task:

    D A,L

  3. Shutdown JES2:


  4. Once JES2 is terminated, halt the SMF recording:

    Z EOD

  5. The MVS system is now down.  On the Hercules console, issue:


Available User IDs:

User ID User Password Description
IBMUSER -n/a- Default Emergency ID
HERC01 -n/a- Sysprog User ID #1
HERC02 CUL8TR Sysprog User ID #2
HERC03 -n/a- Standard User ID #1
HERC04 PASS4U Standard User ID #2
IBMUSER -n/a- Default Emergency ID
IBMUSER -n/a- Default Emergency ID

Useful Links:

Connor Kurkoski Link:

Hercules Link:
Turnkey Link:
RPF Tutorial:
QUEUE Information:

Free Debian (Ubuntu) Link:
VMware Virtualization:

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

<span>%d</span> bloggers like this: