The output produced by executing this job appears at the bottom of this page.

Let's take each step in order, and see what each one does. The first step, IEHPROGM, deletes and uncatalogs a library if it exists. This step will produce a non-zero return code, which you can safely ignore, if the library does not already exist. The next step, ALLOC, creates the library anew. The assembly step, ASMF, reads the S/370 assembler source code and produces an object deck. The Link Edit step, LKED, reads the object deck and produces an executable load module. The final step, IEFBR14, executes our S/370 Assembler program from the load module.

Both IEHPROGM and IBM's IEFBR14 program are standard utilities, so we won't say anything else about them. If you're interested in them, check some of the links in the H390-MVS group's Links section.

We begin examing this MVS job with the ASMF step, which executes the S/370 assembler whose program name is IFOX00.

Let's briefly review the DDNAMEs for IFOX00.

The SYSLIB DDNAME is where the assembler finds any macros referenced in the source code. We don't have any macro references in our IEFBR14 program, but if we did that's where IFOX00 would look for them. We'll get to macros eventually, but not for awhile. Suffice it to say they're a way to generate assembler instructions that the assembler will process as if they were present in your source file.

SYSUT1, SYSUT2, and SYSUT3 are work files. For now, let's just say you need them and leave it at that.

SYSPRINT is where IFOX00 places the listing of the assembly.

SYSPUNCH would be where IFOX00 places the object deck, assuming it could produce one.

SYSIN tells IFOX00 where the source code comes from.

When we run our JCL, our assembly gets a return code zero from IFOX00, so the source code was assembled cleanly. We can tell from the message in our job's output that says:

IEF142I IEFBR14 ASMF - STEP WAS EXECUTED - COND CODE 0000

The MVS38j IFOX00 assembler, the VM "assemble" command, and about any other S/370 assembler you'll run across have some fairly standard requirements on how your source program must be formatted.

The S/370 assembler standard is that source records are 80 bytes in length. MVS source code datasets can be blocked or unblocked; you'll probably want to block them using DCB attributes such as RECFM=FB,LRECL=80,BLKSIZE=3200.

For the most part, S/370 assembler source is in uppercase, although comments can usually be mixed case. If you're using a more modern assembler, such as HLASM, most of the source code can be mixed case.

Source statements come in several varieties: comments, assembler statements, and instructions. Comments contain an asterisk (*) in column one. Columns are usually numbered beginning with one. Pretty much anything goes for comment lines, they're freeform.

Instructions are easy to identify: they're documented in POPs and the REFSUM. Everything else is an assembler statement, which provides instructions to the assembler.

Each S/370 assembler instruction is divided into several (somewhat freeform) fields: label, opcode, operand(s), comments, continuation column, and sequence numbers.

Labels are optional, and if present must begin in column one. They are used to defined symbolic locations, such as someplace you might like to branch. In S/370 assembler, labels can be from one to eight bytes in length. For now, you can think of IEFBR14 as a label although we'll describe it more specifically later.

Opcodes must be preceeded by one or more spaces, and followed by one or more spaces. Normally, opcodes begin in column 10 but that's more a convention than a requirement. In the IEFBR14 program, the opcodes are SLR (the subtract logical register instruction) and BR (the branch register instruction).

Operands are separated by at least one space from the opcode. By convention, most operands begin in column 16. In the IEFBR14 program, "15" and "14" are operands. On the SLR instruction, note that there are multiple operands, each separated by a comma. You can indicate the omission of operands by a standalone comma (,) such as I did in the IEFBR14 program on the CSECT and END statements.

Comments can also appear on either an instruction or assembler statement, and must be separated from the last operand by at least one space. Convention is less standard here, but most introductory assembler courses tell you start comments in column 35. But be careful about how long the comments are, because if you have a non-blank character in column 72 the assembler will think you want the next source line interpreted as a continuation line. The same syntax applies to operands as well.

Any non-blank character in column 72 tells the assembler that the next statement is a continuation line. Continuations may be continued, so you can have several lines with non-blank columns 72 appear consecutively.

Columns 73-80 are reserved for "sequence numbers". These sequence numbers serve two main purposes, one of them obsolete. First, back in the old days when programs were punched on physical cards, if you dropped the card deck and scattered the cards around the sequence numbers helped you put the card deck back together in the right sequence. Second, if you place the program source code in a dataset the sequence numbers serve as a reference point for an update utility program such as IEBUPDTE. Sequence numbers are optional.

If you're using the Turnkey system, I believe IFOX00 has Greg Price's usermod applied which allows entirely blank source lines to also appear in the source file. Without Greg's usermod or something similar, IFOX00 would complain when it saw an entirely blank line.

Most of this section on deciphering the assemble's output is also covered in the S/370 Language Guide. However, since we have yet to locate a copy of this manual that's available for download, I'll go into some of the details here.

Page 1, the External Symbol Dictionary

The first thing we see is the EXTERNAL SYMBOL DICTIONARY, which is a map of the "external symbols" in the output object deck. Remember I called IEFBR14 a kind of label? More precisely, it's an external symbol. External in the sense that the symbol is visible outside the source file. If we were to write another program, we could call IEFBR14 by referring to the external symbol. When we give the IEFBR14 object deck to the linkage editor, we will produce a load module and the IEFBR14 symbol will be visible in the load module as well.

There is only one external symbol in our program, IEFBR14 whose "type" is SD (Symbol Definition). There are several other types of external symbols, such as ER (External Reference), LD (Local Definition), WX (Weak External), XD (External something, from a DXD statement) and maybe some others. I'm being lazy and didn't look these up, they're off the top of my head so I might have a few wrong. The point of mentioning them is that the Linkage Editor cares about them, and they're important when it comes time to build your load module.

The assembler assigns each external symbol an ID number which is unique per each assembly. Unless you're going to tear apart a Linkage Editor or assembler program, you mostly don't care about the ID number.

The ADDR field gives the object-deck-relative offset where the symbol is defined. IEFBR14 begins at object-deck-relative offset zero, being the first thing in the object deck.

The LENGTH field gives the length in (hex) bytes of the code contained in the "section". In IEFBR14's case, the section is a CSECT meaning Control Section. Another popular type of section you'll encounter is a DSECT (Dummy Section). The difference between the two is that a CSECT actually consumes storage, while a DSECT describes storage located somewhere else. A DSECT is much like the overlay foils used on classroom projectors; conceptually you overlay the DSECT on some storage location and can then refer to the storage by the DSECT's labels.

The LDID field is blank because we didn't define any LDs. LDs are basically alternative Entry Points into your program, defined by the assembler ENTRY statement which we haven't gotten to yet. If we had defined another entry point, the LDID would refer to the ID of the CSECT in which the entry point was defined, and have an offset (ADDR) of the object-deck-relative place where the LD was defined. You can immediately forget that little tidbit for now.

Since IEFBR14 is so small, there's not much going on here. Let's look at the columns on this page.

LOC is the LOCation of storage definitions, which is what the assembler is all about. The assembler's main job is to produce an object deck containing sufficient information for the Linkage Editor to produce a Load Module (containing your instructions/data and where they go). The Load Module contains sufficient information for the operating system to place your instructions into storage so they may be executed.

Notice the IEFBR14 CSECT statement begins at LOC 000000 (hex) and that the SLR 15,15 instruction also begins at LOC 000000. The CSECT statement is an assembler statement and consumes no storage in your program. Notice also that the STMT number of the CSECT statement is 1. Each line of source code is assigned a STMT number, including those lines generated by macros. If we had any assembly errors, the ASSEMBLER DIAGNOSTICS AND STATISTICS section of the listing (jumping ahead) would refer to those STMT numbers. In a large program listing, that's helpful so you can more easily locate the error. For our four line program, STMT doesn't mean much.

OBJECT CODE shows the hexadecimal values the CPU will execute when it runs your program, or the data you define in your program. The SLR 15,15 instruction's object code is X'1FFF' and the BR 14 instruction's object code is X'07FE'. You can't tell from looking at the listing, but S/370 instructions are always 2, 4, or 6 bytes in length. It just so happens that both of the S/370 instructions in our program are 2 bytes.

There is no data in the ADDR1 and ADDR2 columns because we didn't refer to any storage locations in our program. If we had, these fields would have the relative offsets of the storage locations. It won't be long before we start referring to storage, and I'll tell you what "relative" means in this case.

The END statement didn't generate any object code either, because it's another assembler statement (as opposed to an instruction). The purpose of the END statement is to tell the Linkage Editor the default entry point (External Symbol) of the program. The default entry point may be overriden by the Linkage Editor with the ENTRY statement at link time.

As you can see from the above, the assembler and Linkage Editor work closely together to produce your load module. In MVS there are other ways to execute programs than load modules, but I doubt I'll have anything to say about that except to mention there is something called a Loader. In terms of the S/370 hardware itself, there is also a process called IPL (Initial Program Load) that can be used to execute a program; IPL is used to start the operating system itself. Once we get some assembler fundamentals behind us, we'll probably discuss IPL further.

Page 3, ASSEMBLER DIAGNOSTICS AND STATISTICS

NO STATEMENTS FLAGGED IN THIS ASSEMBLY is good news. Flagged means the assembler is concerned about something in your source code; it "flags" these source lines so you know to look at them for potential problems. If the assembler is really upset with you, it won't construct your object code properly; in some cases it will just throw some X'00's in the object deck when you've really confused it.

In the S/360, S/370, S/390, and z/Arch architectures, X'00' is not considered an executable instruction so your program will die if you try to execute the X'00's. Thus, one should always check the assembly return codes to see that your program was constructed as you expect (or perhaps hope).

The assembler return codes usually begin at 4 and increase in increments of 4. The higher the number, the worse the error. Return code 4 is considered a warning and can possibly be ignored; everything else should normally be fixed before you try to run your program.

There's some other stuff on this page, but I don't have anything to say about it right now. The IFOX00 Programmer's Manual goes into it in great depth. I'll let you know as soon as I find a URL for the assembler program documentation but I don't have one right now.

Next, we examine the LKED step, which executes the S/370 linkage editor whose program name is IEWL. The linkage editor is also sometimes referred to as LKED, an abbreviation for LinKage EDitor.

Let's briefly review the DDNAMEs for IEWL.

SYSPRINT is the listing of the linkage edit.

SYSLMOD is the resulting load module, if one was produced.

SYSUT1 is a work file.

SYSLIN is the primary input. Input object decks and control statements can be present on SYSLIN.

Let's briefly examine the Linkage Editor's output. We can't begin to do justice to explaining the MVS Linkage Editor as it's worthy of a tutorial of its own. You might notice that the assembler level F matches the Linkage Editor level F. That's frequently how things go; they tend to stay in sync with each other, since they're so dependent on each other.

If you'll refer back to the MVS JCL we used to execute the IEWL program, you'll notice we passed some PARM values; these are where the linkage editor retrieves it's options. LKED OPTIONS were LIST (show the input statements from SYSLIN), MAP (produce a load module map), XREF (produce a cross-reference), LET (mark the module executable even if it contains errors), NCAL (do Not use auto-CALl facility to resolve unresolved symbols), and RENT (mark the module reentrant). I'll only mention a few of these options.

If you omit NCAL, the SYSLIB DDNAME in the LKED step will be opened and searched for external symbols that can be used to satisfy LKED SYSLIN input requirements. First, SYSLIN is where we put the assembler's output object deck; LKED read it in as part of it's primary input. We concatenated an instream dataset (DD *) after the object deck, and provided a NAME statement with the replace (R) option. This NAME statement specifies the load module's name that gets stored in the load library's directory. The replace option says it's OK to replace the module if it already exists. Notice LKED control statements cannot begin in column 1 (for a somewhat obscure and probably not necessary reason), so we put the NAME in column 2. The Linkage Editor has its own manual, and it would be good to have one of those, as well as the LKED messages manual.

There are now two main columns: CONTROL SECTION and ENTRY. We already know what those are: a CSECT or something like it, and an entry point. Beneath each of these two main columns are some subcolumns (for lack of a better term).

Control section NAME is our old friend the IEFBR14 CSECT. Next is the ORIGIN column, which is another offset; this time it's the offset from the beginning of the load module. LENGTH means the same thing as the assembler External Symbol Dictionary length. Should a CSECT length not be divisible by 8, LKED will round the next CSECT up to the next doubleword boundary.

There's a reason LKED does this, having to do with some of the S/370 instructions that require some of their data to be aligned on a doubleword boundary (meaning a storage address evenly divisible by 8). If LKED did not do this CSECT alignment, then when the assembler produced it's object deck with the objective of placing some storage definition on a doubleword boundary, the data area might not actually end up on a doubleword boundary in the program once it was loaded in storage. So every now and again you'll see some "dead space" in your load modules to satisfy this requirement. As a further aside, doubleword alignment is why the MVS GETMAIN (allocate storage) service provides storage on a doubleword boundary. I've never seen this documented anywhere, but it seems a rational explanation (or so I speculate).

Having read all the input, LKED now assigns the ENTRY ADDRESS (again a load module relative offset) to the load module. Our END statement didn't specify an entry point address, and we didn't provide LKED with an ENTRY statement, so LKED takes it's default entry point which is the first CSECT it encounters in the primary input. In this case, it's the IEFBR14 CSECT.

TOTAL LENGTH of the load module is 8, just like we know as is required by CSECT alignment (even though there is only one CSECT).

****IEFBR14 NOW REPLACED IN DATASET means LKED respected our (R) option on the NAME statement. LKED places the output load module on the SYSLMOD DDNAME.

AUTHORIZATION CODE is a somewhat more advanced topic. I'll limit myself to saying that MVS provides an authorization facility called APF (Authorized Program Facility) used to allow a program to act as an extension of the MVS operating system. Such programs are called Authorized Programs, and they are marked as candidates for this grant of special privileges by linking them with a non-zero authorization code. MVS performs some additional checks before granting this privilege, namely checking that the load module came from an APF library which we won't talk about right now.

MODULE HAS BEEN MARKED ... some stuff. Remember our RENT option? Well, reentrant implies reusable and LKED is just being clear about that.

What is a reentrant program? It's a program which can be executed by more than one task without requiring another physical copy. MVS makes kind of a big deal out of this, as reentrant programming techniques allow MVS (and user programs) to provide their services with less overhead. The simplest definition (although not quite precise) is that reentrant programs don't modify their own storage. We'll leave the definition of "task" for another day.

Well, that's the Linkage Editor output. So where's the IEFBR14 output? There isn't any. Our IEFBR14 program didn't open any datasets, didn't write any output ... nothing.

If you'll glance up at the job's output below, you will see

IEF142I IEFBR14 IEFBR14 - STEP WAS EXECUTED - COND CODE 0000

How did IEFBR14 provide this return code to MVS? For the answer to that question, we'll have to learn a little bit more about how the program executed.

Stay tuned.

The following shows the entire MVS printer output our assembly, linkedit, and execution job produced.