Simple Samples: Learn IBM370 Assembly Programming... For Mainframe Madness!

Learn IBM370 Assembly Programming... For Mainframe Madness!

Simple Samples

This series covers a single JCL (asm) file which performs a task in the most basic way possible, it's intended to be easy for you to build upon to make your own programs.

All these examples were written for the Hercules emulator and assembler, their function cannot be guaranteed for other systems.

Useful Links:

Hercules Emulator

OS Setup

Minimal ASM Example - See: Compile/Assemble and Execute

JCL file format Reference

Warning! Windows Defender may detect 'NCAT' as a 'threat' and delete it!!
Without it the scripts won't be able to send the ASM jobs to the server, so you'll need to restore it if it does.

The version provided is the one which came with Hercules, but obviously use it at your own risk.

Lesson S1 - Hello World on the IBM370
Lets get started with the IBM 370 Oh Hercules, we'll write our first JCL to show a hello world message to the screen.

Hello.jcl

WThis example assumes you have a working hercules server, and you know how to start it up!

If you don't look at the devtools page, and download the authors pre-configured server and startup scripts

A Minimal Hello!

Here is our hello world example, It shows Two hello messages in two ways! An ASM file cannot be assembled on its own, we need to send a JCL Job file to the server. The Job commands start // Here is the minimal Header and Footer to a JCL which will assemble and run our program. The ASM source code is in the middle of this JOB script These are only ASM tutorials... We will not go into details of JCL in these tutorials To build this JCL file, use the Hercules Job option in my devtool scripts
If you use my build scripts, the results of the assembly will be shown in the console window I've written some tools to scan the PRT00e printer output for possible assembly errors and show them onscreen The result of the execution is shown from mvslog The output is then shown on the screen by the execute script
The output will also be shown on the terminal

The Job file

JCL lines start // The first two JOB lines define the Job name, memory and specifications for how it outputs information The next EXEC ine starts the ASMFCLG program to assemble the program the final // line is a 'null line' marking the end of the job (technically We don't actually need this!)
Some scripts may include a DD * line, This specifies the following lines as data to be passed to the program, however the hercules assembler does not seem to need this

The ASM file

Lines *starting with a are comments Text after a program line is also a comment**
The CSECT command and END define the ASM code for the HELLO program.
At the start of our program we backup all the registers with SAVE We use *BALR 12,0 and USING ,12 to set up register R12 for use by the assembler for addressing calculations. At the end of our program we use RETURN** to restore the registers and pass control back to the OS

WTO - Write To Operator

WTO is a macro we can use to send text to the user. The simplest form of this macro is shown here.
Here is the results
The WTO macro actually uses SVC 035 It defines a data block containing the settings and string to show!
Here are the results

Sending the job to Hercules

We send our job file to the server using NCAT - we TYPE it with the Pipe operator | to send it.

The server is on our machine - localhost 127.0.0.1 on port 3505

Lesson S2 - Dumping Registers and memory with the IBM370
Lets use the WTO buffer to print the contents of registers and memory, we can use these to test and view the results of our programs.

ShowM.jcl

Using WTO as a buffer

We want to build up a line for output in stages - sometimes character by character,

We define a 76 character 'buffer' called WTOTEXT,

We use register R11 as a pointer to the next character in the buffer, and use this to store characters
for example, if the low byte of R1 contained a character to store, "STC 1,0(11) A 11,=F'1'" would store the character, and increment R11 to point to the next character.

we use the PRINTLIN function to print the buffer, then clear the buffer with the PRINTCLR loop

Showing a labeled register

We're going to create a function called 'SHOWREG' It shows the contents of R0 to the screen as Hexadecimal, with the 4 characters in R8 shown as a 'label' We need to use PRINTLIN to clear the buffer and send it to the screen.
Here are the results
The SHOWREG function writes the 4 characters in R8 to the WTO buffer pointer R11 We then run the SHOWHEX8 - the 8 refers to 8 nibbles (4 bytes)
The ShowHex routine selects the top nibble of the 32 bit value. We convert the number to a character by adding the character '0', but if the nibble >0 we need to show 'A-F' so we subtract 57 from the character shown. REMEMBER! all the characters are in EBDIC! We write the character into the WTO buffer After each character we shift the value to show 4 bits left, moving the next most significant bit into the 'draw position'

Dumping memory as Hex and characters

Our MEMDUMP routine shows R5 lines (8 bytes per line) from address R8. Here we dump 16 bytes of the code of the 'ShowReg' function
Here are the results
Our MEMDUMP routine starts by showing the address in R8 to the screen with the SHOWHEX8 routine (which shows all 8 nibbles of the 32 bit value) We then show the : to the screen after the address. Next we show 8 bytes to the screen as HEX, each has a space after it, we use SHOWHEX2 as we only show two nibbles. We then show the same data as Characters (EBDIC) Finally we use PRINTLIN to dump the buffer to the operator's screen. We then repeat

JCL - Job Control Language

Command	Format	Example	Purpose
JOB	//{Jobname} JOB ({Account num}) {operands} {comments}	`//ASMFCLG JOB (001),'ASM HELLO WORLD', // CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),REGION=128K`	Job
EXEC	//{Stepname} EXEC {program} {operands} {comments}	`//HELLO EXEC ASMFCLG`	Execute
DD	//{dd name} DD {operands} {comments}	`//ASM.SYSUT1 DD UNIT=SYSDA`	Data Definition
PROC	//{name} PROC {operands} {comments}	`//DEF PROC STATUS=OLD,LIBRARY=SYSLIB,NUMBER=777777`	Procedure
PEND	//{name} PEND {comments}	`// PEND`	Procedure End
	/* //*	/* I am a comment	Comment

JOB:
Class = Time slicing class (A=Default) PRTY = Priority
MSGCLASS = Output class (A-z / 0-9)
MSGLEVEL= (statements,messages) .... 1,1 = output all
Region= Memory to allocate in 1024 byte blocks (eg 128K)

DD:

* = Prompt for input (//ddname DD *)
UNIT = device / group containing data set

Server console / Terminal Notes

Server

Start Server:
C: ipl 150
T: enter
T: r 0,u
T: r 1,format,noreq

to stop errors (in console)
OSTAILOR QUIET

To reply to a message:
r <message number>,<response>

Rexx Files:
regina condcode.rexx prt00e.txt smp4p44

Telnet
Ctrl ]
set localecho
enter

F12 to continue read of messages

shutdown: (in telnet)
$p jes2
z eod
quiesce
quit (in console)

Tape to asci?
hetget -a tape/stage1.het stage1.output 1