Table of Contents

• Introduction
• HALSFC
• Installation of HALSFC
• Where the Wild HAL/S Files Are
  
• Some Differences Between the Old and the New
• EBCDIC vs ASCII
• COMMON Memory
• Overstruck Lines in Reports
  
• Compiler Options, Part One
  
• More on the Compiler Options
• Debugging-Aid Options
  
• Files Used or Created by the HAL/S Compiler
• Validating the Compiler
• My Mind-Reading Trick
• Validating Phase 1
• Validating Phase 1.5 and Phase 2
• A Glossary and Some References

Introduction

The principal claim to fame of the HAL/S computer language is that the bulk of the flight software for the Space Shuttle was written in it, as supplemented by source code in the assembly language of the Shuttle's General Purpose Computers (GPC).  GPCs were IBM AP-101S computers or (for early missions) IBM AP-101B computers.  HAL/S also seems to have been used for the flight software of the Galileo probe, though in that case the onboard computers were based on RCA 1802 COSMAC microprocessors.

Aside:  The other claim to fame is that HAL/S has an optional pseudo-mathematical notation in which arithmetical expressions look more like mathematics than they generally do in other programming languages.

HAL/S was devised by the company Intermetrics, Inc., and touted as one of the "standard" languages in which NASA flight software should be written.  In spite of the two successes I mentioned above, I haven't found much evidence that it ever became a NASA standard.  Indeed, a 1983 report that investigated the language candidates HAL/S versus ADA versus Modula 2 concluded that only ADA met all of the desired criteria.  Today, I'd regard HAL/S as a dead language, though I'd be happy to be instructed otherwise.

One factor greatly in its favor, both as a language for flight software and for general-purpose computing, is a very fine book about the language, namely Michael Ryer's Programming in HAL/S.  That may sound like an odd advantage to mention, but "very fine books about them" are something that computer languages with a minimal user base tend to lack.  Authors have more incentive to spend their time writing about widely-successful languages with large numbers of users.

Nevertheless, the Space Shuttle's flight software was written in HAL/S, so anybody interested in working with that flight software also needs appropriate tools for working with HAL/S.  The Space Shuttle's flight software came in two very-different flavors, namely the primary flight software (PASS) and the backup flight software (BFS), with the BFS being basically a clean-room implementation of a subset of PASS functionality.  By emphasizing PASS and BFS I don't mean to disparage Galileo's software.  However, I have seen no Galileo flight software, and as far as I know right now have no prospect for ever getting my hands on it.  If you have Galileo flight software source code, or even related documentation, by all means contact me.  I'll expand the scope of HAL/S quicker than you can bat an eyelash.

A 1981 article summarizes the HAL/S activity up to that point in time, describing a number of implementations of HAL/S compilers for various types of computers.  None of them are available for computers accessible to the general public, of course.  The IBM PC didn't even become available until 1981 anyway, and (as I can tell you from personal experience) the personal computers available prior to that were literally sneered at as toys by the mass of mainframe computer users who hadn't the vision to even consider the possibility that widely-available low-cost computers available to everybody might largely supplant the giant mainframes upon which their careers depended.  But time ticks on, obviously, and so today we need HAL/S tools that run on the computers actually available to us.  Which is to say, on Linux, Mac OS, or Windows computers.  (Or on hand-held devices, though I confess that it's hard to envisage working with HAL/S software on a cellphone!)

My initial iteration of a solution to this problem was to develop a Linux/Mac/Windows based HAL/S compiler which could translate HAL/S source code into a language I called PALMAT, for which I also had an emulator.  The compiler and emulator could optionally be combined into a HAL/S interpreter, into which the user could input HAL/S statements and immediately see the result of executing that statement.  I called this software yaHAL-S-FC.  The software functions pretty well, though it never reached the point of implementing 100% of HAL/S's features, nor of being extremely polished for user friendliness.  I halted work on it mainly because the effort of extending it to 100% functionality seemed to be expanding rather than contracting.  But it could be useful as an interactive learning aid for those who (for example) are working their way through Ryer's book.  The software remains available in the Virtual AGC software repository, and is the subject of two of our pages, one about the compiler itself and one about the interpreter alone.  I will not mention it again here.

The HAL/S development tools we focus on here are:

1. A HAL/S compiler, implementing 100% of HAL/S features, producing IBM AP-101S object code.
2. An IBM AP-101S assembler.
3. An IBM AP-101S linker.
4. An IBM AP-101S emulator.

The list above is in some ways a roadmap for future development, because at the present time we have only the compiler.  So the bulk of the discussion will concern just the compiler.

The HAL/S compiler, which I will refer to as HALSFC, is based on the source code for the original Intermetrics HAL/S compiler called HAL/S-FC.  Intermetrics actually had three separate HAL/S compilers that I know about:

• HAL/S-360 was a compiler that converted HAL/S source code into IBM 360 object code.
  
• HAL/S-FC was the compiler that compiled the primary flight software (PASS) and produced AP-101S object code.
• HAL/S-BFC was the compiler that compiled the backup flight software (BFS) and produced AP-101S object code.
  

Aside:  The surviving documentation is almost silent on the subject of having separate compilers for PASS vs BFS, but here's my understanding of what happened:

• At first, say in 1975, there was a single HAL/S-FC compiler for producing AP-101S object code.
• But at some unknown point, differences between PASS and BFS became too tricky to be handled by a single compiler.  This problem may have been caused or exacerbated by the fact that Intermetrics was writing PASS, whereas Rockwell International was responsible for independently writing BFS, and they weren't always conforming to the same conventions.  But whatever the reason, to handle these differences, the source code for HAL/S-FC branched into two separate source-code trees that proceeded to be developed independently from each other.  And of course, divergent software trees only continue diverge over time, rather than magically converging back into a single tree.
  
• Still later, at PASS release 23V2 and BFS release 6V0 in late 1991, management noticed that it was twice as expensive to develop two compilers as it was to develop just one compiler, said "aw, shucks!", kicked up some dirt with their boot tips, grumbled menacingly, and commanded that the source-code trees once again be merged into a single tree.  [Editor's note:  I made up some of that.]
  
• But even though the source code for the two compilers has once again been unified into a single release that eventually evolved into the release 32V0/17V0 that we have today, it turns out that there were still two separate methods for building that source code, thus producing two separate compiler programs anyway.  The "HAL/S Compiler System Specification" expresses it thusly:  "Although much of the source became common between the two compilers, there exist differences that can be attributed to required PASS/BFS interfaces and certain desired but not required compiler features".  Besides the two different build methods for the HAL/S compilers, there's also the consideration of the runtime libraries needed to actually run the AP-101S object produced by the two compilers.  And in fact, the runtime libraries needed for the flight software was not merged, and continued to be different in PASS versus BFS.  I.e., there are still two separate runtime libraries, similar perhaps, but not merged into a single source-code tree.
  
• And as for how this dichotomy affected other development tools, there was a separate linker for BFS versus the linker for PASS, as well as a bunch of separate BFS utilities that seem not to have survived. 
  
• Finally, as far as I can tell, Intermetrics/USA developers simply refer to these two versions of the compiler as "the PASS compiler" and "the BFS compiler".  I will sometimes refer to them as HAL/S-FC and HAL/S-BFC, respectively, although generally I'll just use HAL/S-FC as a generic term when it doesn't really matter which of the two compilers I'm referring to.
  

And if all of that wasn't enough for you, the structure of HAL/S-FC, in either the PASS or BFS version, is actually more complex than I may have implied.  In fact, HAL/S-FC was not just one program, but rather seven stand-alone "passes", some of them optional, that were run in succession to perform the full compilation:

Aside:  At present, modern implementations of PASS3/PASS3B/PASS4 have not yet been created, though as you can see from the table above, they're not needed merely for compilation of object code.

Aside:  Probably, you're beginning to see a truly explosive confusion of terminology around the word "pass":  There are 7 passes of the compiler, some of which are named PASSx and some of which are not, but meanwhile, "PASS" is also the name of the primary flight software!  Intermetrics also used the following alternate terminology, which is less confusing, and I may use it from time to time as well:

• The term "Phase 1" corresponds to PASS1 of the compiler.  It is where HAL/S source code is parsed.
  
• The term "Phase 1.5" corresponds to FLO, OPT, and AUX of the compiler.  It is where optimization occurs.
  
• The term "Phase 2" corresponds to PASS2 of the compiler.  It is where object-code generation occurs.
• The term "Phase 3" corresponds to PASS3 of the compiler.  It is where diagnostic and simulation data (i.e., Simulation Data Files, AKA SDF) is produced.
• The term "Phase 4" corresponds to PASS4 of the compiler.  It dumps Simulation Data File (SDF) contents for debugging purposes.
  

The original Intermetrics compilers, HAL/S-FC and HAL/S-360, were written in a high-level computer language I call XPL/I, with some "inline" IBM 360 machine code.  To get our modern HAL/S compiler, HALSFC, I first had to write an XPL/I compiler (which I call XCOM-I), and to compile Intermetrics's source code for HAL/S-FC.  There's a separate page dedicated to the XPL/I language and to XCOM-I.  Neither topic will be mentioned further here, except in passing.  Prior to that, the source code for PASS1/PASS1B of HAL/S-FC had been manually translated into the Python 3 language, creating a program I call HAL_S_FC.  This Python port is very useful for cross-checking HALSFC, but is (no longer) intended to be run directly by developers, and I've created no separate documentation for it beyond what's covered on the XCOM-I page.

As compiled by XCOM-I, the various passes of HAL/S-FC actually names like HALSFC-PASS1[.exe] or HALSFC-OPTB[.exe].

I know that all of this probably seems very complex.  It does to me!  However, HALSFC has been designed to hide all of that complexity from the developer.  I hope you'll find operation of HALSFC to be quite simple.

HALSFC

As I've mentioned, the many pieces of the modern HAL/S compiler are referred to by the blanket name HALSFC, and HALSFC is the only program you need to invoke to compile a HAL/S program into IBM AP-101S object code.

Let's just briefly examine how to use HALSFC.  Since we haven't yet covered how to install the program — that's covered in the next section! — you can't actually try out the commands I show you, but you can come back after installation and try them.  Installation, unfortunately, does have some complexity associated with it, and I'd prefer to encourage you with the simplicity first, before discouraging you with the complexity.  Besides, having a clear idea of what HALSFC can do and what it cannot do at present may help you to decide whether you want to install it at all.

DEBUG ¢D¢E¢F
 
 HELLO: PROGRAM;
    DECLARE I INTEGER;
    DECLARE MY_NAME CHARACTER(20) INITIAL('RON BURKEY');
    DECLARE INTEGER, J;
    REPLACE PRINTER BY "6";
    WRITE(PRINTER) 'THE BEGINNING';
    DO FOR I = 1 TO 5;
       WRITE(PRINTER) I, 'HELLO, WORLD!';
       DO FOR J = 2 TO 8 BY 2;
          WRITE(PRINTER) J, MY_NAME, 'SAYS ISN''T THIS FUN?';
       END;
    END;
    WRITE(6) 'THE END';
 CLOSE HELLO;

What this program does isn't important, though most of it is probably obvious at a glance, and other than the first line, the rest is easily understood by consulting Ryer's book.  The first line is an example of a compiler directive, which in this case is specific to the Intermetrics implementation and just affects that items appear on the compiler's printouts.

HALSFC is actually a shell script.  Or more accurately, two shell scripts:  HALSFC for Linux or Mac OS, and HALSFC.bat for Windows.  They are almost identical in operation, so there's not much reason to distinguish between them.

HALSFC SOURCEFILE.hal TEST "PARAMETERS" TARGET EXTENSION

• SOURCEFILE.hal, of course, is the name of the HAL/S source-code file.   The file-extension ".hal" is customary, and you shouldn't use anything else.  If you need to compile multiple HAL/S files, you need to invoke HALSFC separately for each one, and then to link all of the object files together as a final step.
• TEST determines whether or not validity checks are performed on the results of the compilation.  The default (an empty position) is to perform no test.  If non-blank, then a test is performed.  Presently, the only available test is to run compiler phase 1 twice, once as compiled from XPL/I source code and once using the Python port, and to compare the results.  This requires the NOTABLES compiler options (see the next item).
  
• "PARAMETERS" is the "PARM field" covered in the section on compiler options.  For example, it might look like "SRN,LIST,LISTING2,X6,NOTABLES".  The list needs to be quoted if it contains any spaces (which should only be if the TITLE option is present), but for Windows it always needs to be quoted.  Also, if the TEST option is used (see above), it can't contain any spaces even if quoted.
  
• TARGET would be either PFS or BFS, defaulting to PFS.  I.e., primary flight software versus backup flight software.
  
• EXTENSION indicates the filename extension used for executable files.  It defaults to HALSFC's guess of what the extension should be, which is .exe in Windows and blank in Linux or Mac OS.  This argument is ignored on Windows.
  

Let's just try compiling HELLO.hal:

HALSFC HELLO.hal "" "LIST"

After a short period of time we're told:

Compilation successful. Results in "HALSFC Wed Aug 21 07:14:36 AM CDT 2024.results".

(or whatever your actual date and time is!) and our directory now contains both the HELLO.hal we started with, but also a subdirectory called "HALSFC Wed Aug 21 07:14:36 AM CDT 2024.results", which contains a lot of files.   Every time you run HALSFC, a new results-directory is created.  Since they're all named *.results, though, they're easy to find later and delete, and we don't have to have our working directory cluttered up with innumerable files, of which only a small subset are likely to be of interest.  I'll cover the files in this folder later, in probably-boring detail.

Note:  The results folder just mentioned is created only at the end of the compilation process, so if you manually abort HALSFC prior to completion, you will find the multitude of files that normally appear in the results folder now clutter up the working folder in which you're running HALSFC.  Compilation is normally pretty fast, since individual HAL/S source-code files tend to be short, so there's not usually a lot of reason for premature aborts, but it's still something to be aware of.  These files generally have names of the form *.bin, *.rpt, *.out, *.txt, or *.parms.

    HAL/S REL32V0                T I T A N  S Y S T E M S  C O R P .                 AUGUST 8, 2024    12:51:35.21     PAGE 1


   HAL/S COMPILER PHASE 1 -- VERSION OF AUGUST 8, 2024.  CLOCK TIME = 4:31:2.00.


TODAY IS AUGUST 8, 2024.  CLOCK TIME = 12:51:35.21.

 PARM FIELD: LIST


 COMPLETE LIST OF COMPILE-TIME OPTIONS IN EFFECT


       *** TYPE 1 OPTIONS ***

        NOADDRS
        NODECK
        NODUMP
        NOHALMAT
        NOHIGHOPT
          LFXI
          LIST
        NOLISTING2
          MICROCODE
        NOREGOPT
        NOSDL
        NOSREF
        NOSRN
        NOTABDMP
          TABLES
        NOTABLST
        NOTEMPLATE
        NOVARSYM
          ZCON


       *** TYPE 2 OPTIONS ***

       BLOCKSUM = 400
       CARDTYPE =
       COMPUNIT = 0
            DSR = 1
      LABELSIZE = 1200
         LINECT = 59
     LITSTRINGS = 2000
      MACROSIZE = 500
           MFID =
          PAGES = 2500
        SYMBOLS = 200
          TITLE =
       XREFSIZE = 2000


 *** NO LANGUAGE SUBSET IN EFFECT ***

------------------------------------------------------------------------------------------------------------------------------------------------------
  HAL/S REL32V0                T I T A N  S Y S T E M S  C O R P .                 AUGUST 8, 2024    12:51:35.21     PAGE 2
STMT                                                                  SOURCE                                                                  REVISION



     D| EBUG `D`E`F                                                                                         |

------------------------------------------------------------------------------------------------------------------------------------------------------
  HAL/S REL32V0                T I T A N  S Y S T E M S  C O R P .                 AUGUST 8, 2024    12:51:35.21     PAGE 3
STMT                                                  SOURCE                                                  CURRENT SCOPE

   1 M| HELLO:                                                                                              |HELLO
   1 M| PROGRAM;                                                                                            |HELLO
   2 M|   DECLARE I INTEGER;                                                                                |HELLO
   3 M|   DECLARE MY_NAME CHARACTER(20) INITIAL('RON BURKEY');                                              |HELLO
   4 M|   DECLARE INTEGER, J;                                                                               |HELLO
   5 M|   REPLACE PRINTER BY "6";                                                                           |HELLO
   6 M|   WRITE(PRINTER) 'THE BEGINNING';                                                                   |HELLO
                ^^^^^^^
   7 M|   DO FOR I = 1 TO 5;                                                                                |HELLO
   8 M| 1   WRITE(PRINTER) I, 'HELLO, WORLD!';                                                              |HELLO
                  ^^^^^^^
   9 M| 1   DO FOR J = 2 TO 8 BY 2;                                                                         |HELLO

     E|                            ,                                                                        |
  10 M| 2     WRITE(PRINTER) J, MY_NAME, 'SAYS ISN''T THIS FUN?';                                           |HELLO
                    ^^^^^^^
  11 M| 1   END;                                                                                            |ST#9
  12 M|   END;                                                                                              |ST#7
  13 M|   WRITE(6) 'THE END';                                                                               |HELLO
  14 M| CLOSE HELLO;                                                                                        |HELLO

------------------------------------------------------------------------------------------------------------------------------------------------------
  HAL/S REL32V0                T I T A N  S Y S T E M S  C O R P .                 AUGUST 8, 2024    12:51:35.21     PAGE 4



**** C O M P I L A T I O N   L A Y O U T ****

 HELLO: PROGRAM;

------------------------------------------------------------------------------------------------------------------------------------------------------
  HAL/S REL32V0                T I T A N  S Y S T E M S  C O R P .                 AUGUST 8, 2024    12:51:35.21     PAGE 5



S Y M B O L  &  C R O S S   R E F E R E N C E   T A B L E   L I S T I N G :

         (CROSS REFERENCE FLAG KEY:  4 = ASSIGNMENT, 2 = REFERENCE, 1 = SUBSCRIPT USE, 0 = DEFINITION)

 DCL  NAME            TYPE                          ATTRIBUTES & CROSS REFERENCE

   1  HELLO     PROGRAM                            FLAGS=20040, NEST=0, SCOPE=1, PTR=2, LENGTH=0, LINK1=-1, LINK2=0, SYT_NO=1,
                                                   ARRAY=-8192, ADDR=0, CLASS=2, TYPE=73     XREF: 0 0001
   2  I         INTEGER                            SINGLE, ALIGNED, STATIC, FLAGS=808208, NEST=1, SCOPE=1, PTR=0, LENGTH=0,
                                                   LINK1=0, LINK2=0, SYT_NO=2, ARRAY=0, ADDR=0, CLASS=1, TYPE=6      XREF: 0 0002
                                                   4 0007  2 0008
   3  MY_NAME   CHARACTER(20)                      ALIGNED, STATIC, INITIAL, FLAGS=8A08, NEST=1, SCOPE=1, PTR=0, LENGTH=20,
                                                   LINK1=0, LINK2=0, SYT_NO=3, ARRAY=0, ADDR=0, CLASS=1, TYPE=2      XREF: 0 0003
                                                   2 0010
   4  J         INTEGER                            SINGLE, ALIGNED, STATIC, FLAGS=808208, NEST=1, SCOPE=1, PTR=0, LENGTH=0,
                                                   LINK1=0, LINK2=0, SYT_NO=4, ARRAY=0, ADDR=0, CLASS=1, TYPE=6      XREF: 0 0004
                                                   4 0009  2 0010
   5  PRINTER   REPLACE MACRO                      FLAGS=C000, NEST=1, SCOPE=1, PTR=0, LENGTH=0, LINK1=0, LINK2=0, SYT_NO=5,
                                                   ARRAY=0, ADDR=0, CLASS=6, TYPE=0, MACRO TEXT="6"  XREF: 0 0005  2 0006  2 0008
                                                   2 0010



L I T E R A L   T A B L E   D U M P:

 LOC  TYPE          LITERAL

   1 ARITH  4214000000000000
   2  CHAR  RON BURKEY
   3 ARITH  4160000000000000
   4  CHAR  THE BEGINNING
   5 ARITH  4110000000000000
   6 ARITH  4150000000000000
   7 ARITH  4160000000000000
   8  CHAR  HELLO, WORLD!
   9 ARITH  4120000000000000
  10 ARITH  4180000000000000
  11 ARITH  4120000000000000
  12 ARITH  4160000000000000
  13  CHAR  SAYS ISN'T THIS FUN?
  14 ARITH  4160000000000000
  15  CHAR  THE END



------------------------------------------------------------------------------------------------------------------------------------------------------
  HAL/S REL32V0                T I T A N  S Y S T E M S  C O R P .                 AUGUST 8, 2024    12:51:35.21     PAGE 6


       OPTIONAL TABLE SIZES

NAME       REQUESTED    USED
^^^^       ^^^^^^^^^    ^^^^

LITSTRINGS      2000      68
SYMBOLS          200       5
MACROSIZE        500       2
XREFSIZE        2000      13
BLOCKSUM         400       0


CALLS TO SCAN        = 85
CALLS TO IDENTIFY    = 14
NUMBER OF REDUCTIONS = 202
MAX STACK SIZE       = 9
MAX IND. STACK SIZE  = 5
END IND. STACK SIZE  = 1
END ARRAY STACK SIZE = 0
MAX EXT_ARRAY INDEX  = 1
STATEMENT COUNT      = 14
MINOR COMPACTIFIES   = 0
MAJOR COMPACTIFIES   = 0
REALLOCATIONS        = 0
MAX NESTING DEPTH    = 1
FREE STRING AREA     = 16620316


END OF HAL/S PHASE 1, AUGUST 8, 2024.  CLOCK TIME = 12:51:35.22.

17 CARDS WERE PROCESSED.
NO ERRORS WERE DETECTED DURING PHASE 1 .


NUMBER OF FILE 6 LOCATES          = 1
NUMBER OF FILE 6 READS            = 0
NUMBER OF FILE 6 WRITES           = 0


TOTAL CPU TIME FOR PHASE 1      0:0:0.02.
CPU TIME FOR PHASE 1 SET UP     0:0:0.01.
CPU TIME FOR PHASE 1 PROCESSING 0:0:0.00.
CPU TIME FOR PHASE 1 CLEAN UP   0:0:0.01.

There's lots of information here, though the most-significant thing is probably the message "NO ERRORS WERE DETECTED DURING PHASE 1".  What phase 1 (PASS1) has accomplished is mostly to output a processed form of our HAL/S program as expressed in an "intermediate language" called HALMAT.  Unfortunately, most of the documentation about HALMAT has not survived, but since the additional passes of the compiler do understand HALMAT, we don't necessarily need to understand it ourselves.  The HALMAT form of the program is the file halmat.bin.

The compiler then proceeded to further process halmat.bin, using the "phase 1.5" programs (FLO, OPT, and AUXP).  Those programs don't produce useful reports, at least not by default, so we don't need to look at their reports.  However, what they do is to "optimize" the HALMAT, producing new HALMAT related files called optmat.bin and auxmat.bin.

The "phase 2" program (PASS2) then pulls in all of those HALMAT and HALMAT-related files, and generates object code from them.  Let's look at PASS2's report, pass2.rpt:

PAGE 1


   HAL/S COMPILER PHASE 2  --  VERSION OF AUGUST 8, 2024.  CLOCK TIME = 4:32:17.00

HAL/S PHASE 2 ENTERED AUGUST 8, 2024.  CLOCK TIME = 12:51:35.64


------------------------------------------------------------------------------------------------------------------------------------------------------
PAGE 2
SYMBOL   TYPE  ID  ADDR  LEN(HEX)  LEN(DEC)         BLOCK NAME


$0HELLO   SD 0001 000000 000040          64         HELLO
#EHELLO   SD 0002 000000 000006           6
#DHELLO   SD 0003 000000 000033          51
@0HELLO   ER 0004
#QIOINIT  ER 0005
#QCOUT    ER 0006
#QHOUT    ER 0007

------------------------------------------------------------------------------------------------------------------------------------------------------
PAGE 3
  LOC    CODE        EFFAD           LABEL   INSN   OPERANDS            SYMBOLIC OPERAND


0000000                             ST#1     EQU    *
00000                               #EHELLO  CSECT        ESDID= 0002
00000 0000                                   DC     X'0000'
00001 0000                                   DC     X'0000'
00002 00000700                               DC     A'00000700'         #DHELLO
00004 0000                                   DC     X'0000'
00005 0000                                   DC     X'0000'
00000                               $0HELLO  CSECT        ESDID= 0001
0000000                             HELLO    EQU    *
00000 E8F3 0000                              LHI    R0,0()              @0HELLO
00002 E9F3 0000                              LHI    R1,0()              #DHELLO
00004 B914           0005                    STH    R1,5(R0)
00005 E0FB 0014                              IAL    R0,20()
00007 EB11           0004                    LA     R3,4(R1)
00008 BB24           0009                    STH    R3,9(R0)
0000009                             ST#2     EQU    *
0000009                             ST#3     EQU    *
00009                               #DHELLO  CSECT        ESDID= 0003
00009 000008                                 ORG    *-1
00008 140A524F                               DC     X'140A524F'
0000A 4E204255                               DC     X'4E204255'
0000C 524B4559                               DC     X'524B4559'
000000E                             ST#4     EQU    *
000000E                             ST#5     EQU    *
000000E                             ST#6     EQU    *
00009                               $0HELLO  CSECT        ESDID= 0001
00009 BEE8                                   LFXI   R6,6
0000A BDE5                                   LFXI   R5,3
0000B D0FF 3800                              SCAL@# R0,0(R1,R3)         #QIOINIT
0000D EAAD           002B                    LA     R2,43(R1)           C'THE BEGINNING'
0000E D0FF 3800                              SCAL@# R0,0(R1,R3)         #QCOUT
0000010                             ST#7     EQU    *
00010 BFE3                                   LFXI   R7,1
00011 DF84           0033                    BCF    7,*+34              B     LBL#3 (WITHIN ST#12)
0000012                             LBL#4    EQU    *
0000012                             ST#8     EQU    *
00012 BEE8                                   LFXI   R6,6
00013 BDE5                                   LFXI   R5,3
00014 D0FF 3800                              SCAL@# R0,0(R1,R3)         #QIOINIT
00016 1DE7                                   LR     R5,R7
00017 D0FF 3800                              SCAL@# R0,0(R1,R3)         #QHOUT
00019 EA8D           0023                    LA     R2,35(R1)           C'HELLO, WORLD!'
0001A D0FF 3800                              SCAL@# R0,0(R1,R3)         #QCOUT
000001C                             ST#9     EQU    *
0001C BCE4                                   LFXI   R4,2
0001D DF3C           002D                    BCF    7,*+16              B     LBL#5 (WITHIN ST#11)
000001E                             LBL#6    EQU    *
000001E                             ST#10    EQU    *
0001E BEE8                                   LFXI   R6,6
0001F BDE5                                   LFXI   R5,3
00020 D0FF 3800                              SCAL@# R0,0(R1,R3)         #QIOINIT
00022 1DE4                                   LR     R5,R4
00023 D0FF 3800                              SCAL@# R0,0(R1,R3)         #QHOUT
00025 EA21           0008                    LA     R2,8(R1)            MY_NAME
00026 D0FF 3800                              SCAL@# R0,0(R1,R3)         #QCOUT


------------------------------------------------------------------------------------------------------------------------------------------------------
PAGE 4
  LOC    CODE        EFFAD           LABEL   INSN   OPERANDS            SYMBOLIC OPERAND

00028 EA61           0018                    LA     R2,24(R1)           C'SAYS ISN'T THIS FUN?'
00029 D0FF 3800                              SCAL@# R0,0(R1,R3)         #QCOUT
000002B                             ST#11    EQU    *
0002B BCE4                                   LFXI   R4,2
0002C 840F           0007                    AH     R4,3(R3)            J
000002D                             LBL#5    EQU    *
0002D BC0F           0007                    STH    R4,3(R3)            J
0002E B5E4 0008                              CHI    R4,8
00030 DE4E           001E                    BCB    6,*-18              BLE   LBL#6 (WITHIN ST#9)
0000031                             LBL#7    EQU    *
0000031                             ST#12    EQU    *
00031 BFE3                                   LFXI   R7,1
00032 870B           0006                    AH     R7,2(R3)            I
0000033                             LBL#3    EQU    *
00033 BF0B           0006                    STH    R7,2(R3)            I
00034 B5E7 0005                              CHI    R7,5
00036 DE96           0012                    BCB    6,*-36              BLE   LBL#4 (WITHIN ST#7)
0000037                             LBL#8    EQU    *
0000037                             ST#13    EQU    *
00037 BEE8                                   LFXI   R6,6
00038 BDE5                                   LFXI   R5,3
00039 D0FF 3800                              SCAL@# R0,0(R1,R3)         #QIOINIT
0003B EA4D           0013                    LA     R2,19(R1)           C'THE END'
0003C D0FF 3800                              SCAL@# R0,0(R1,R3)         #QCOUT
000003E                             ST#14    EQU    *
000003E                             LBL#2    EQU    *
0003E C9F9 0000      0000                    SVC    0(R1)               H'21', X'0015'
0000E                               #DHELLO  CSECT        ESDID= 0003
0000E 000000                                 ORG    *-14
00000 0015                                   DC     X'0015'
00004 000013                                 ORG    *+15
00013 00075448                               DC     X'00075448'
00015 4520454E                               DC     X'4520454E'
00017 4400                                   DC     X'4400'
00018 00145341                               DC     X'00145341'
0001A 59532049                               DC     X'59532049'
0001C 534E2754                               DC     X'534E2754'
0001E 20544849                               DC     X'20544849'
00020 53204655                               DC     X'53204655'
00022 4E3F                                   DC     X'4E3F'
00023 000D4845                               DC     X'000D4845'
00025 4C4C4F2C                               DC     X'4C4C4F2C'
00027 20574F52                               DC     X'20574F52'
00029 4C442100                               DC     X'4C442100'
0002B 000D5448                               DC     X'000D5448'
0002D 45204245                               DC     X'45204245'
0002F 47494E4E                               DC     X'47494E4E'
00031 494E4700                               DC     X'494E4700'
                                             END

------------------------------------------------------------------------------------------------------------------------------------------------------
PAGE 5


RLD INFORMATION

POS.ID (P) IS THE ESDID OF SD FOR THE CONTROL SECTION THAT CONTAINS THE ADDRESS CONSTANT
REL.ID (R) IS THE ESDID OF ESD ENTRY FOR THE SYMBOL BEING REFERRED TO

         FLAG        TYPE                                ACTION PERFORMED

       V00000ST      YCON      RELOCATION FACTOR IS ADDED TO ADDRESS CONSTANT.  IF ADDRESS IS GREATER THAN 15 BITS, SET BIT "0" ON.
       000001ST      ACON      RELOCATION FACTOR IS ADDED TO ADDRESS CONSTANT.
       V00100ST      ZCON      ADD RELOCATION FACTOR TO FIRST HALFWORD.  IF GREATER THAN 15 BITS, UPDATE BSR FIELD.
                               (BRANCH RELOCATION FOR 32-BIT BRANCH)
       V10000ST      ZCON      UPDATE DSR FIELD WITH HIGH ORDER 4 BITS OF THE 19-BIT RELOCATION FACTOR.
                               (DATA RELOCATION FOR 32-BIT BRANCH)
       V01000ST      ZCON      UPDATE BSR FIELD WITH HIGH ORDER 4 BITS OF THE 19-BIT RELOCATION FACTOR.
                               (BRANCH RELOCATION FOR 32-BIT DATA)
       V10100ST      ZCON      ADD RELOCATION FACTOR TO FIRST HALFWORD.  IF GREATER THAN 15-BITS, UPDATE DSR FIELD.
                               (DATA RELOCATION FOR 32-BIT DATA)

       V = SIGN OF THE YCON IN THE TEXT RECORD
            0 = THE YCON IS POSITIVE
            1 = THE YCON IS THE ABSOLUTE VALUE OF A NEGATIVE NUMBER
       S = DIRECTION OF RELOCATION
            0 = POSITIVE
            1 = NEGATIVE
       T = TYPE OF NEXT RLD ITEM
            0 = NEXT RLD ITEM HAS DIFFERENT R OR P POINTERS; THEY ARE IN THE NEXT ITEM
            1 = NEXT RLD ITEM HAS SAME R AND P POINTERS; HENCE THEY ARE OMITTED

 POS.ID    CSECT(P)    ADDRESS   FLAGS      REL.ID    CSECT(R)

  0001     $0HELLO     000001     00         0004     @0HELLO
  0001     $0HELLO     000003     00         0003     #DHELLO
  0001     $0HELLO     00000C     00         0005     #QIOINIT
  0001     $0HELLO     00000F     00         0006     #QCOUT
  0001     $0HELLO     000015     00         0005     #QIOINIT
  0001     $0HELLO     000018     00         0007     #QHOUT
  0001     $0HELLO     00001B     00         0006     #QCOUT
  0001     $0HELLO     000021     00         0005     #QIOINIT
  0001     $0HELLO     000024     00         0007     #QHOUT
  0001     $0HELLO     000027     00         0006     #QCOUT
  0001     $0HELLO     00002A     00         0006     #QCOUT
  0001     $0HELLO     00003A     00         0005     #QIOINIT
  0001     $0HELLO     00003D     00         0006     #QCOUT
  0002     #EHELLO     000002     10         0001     $0HELLO
  0002     #EHELLO     000002     40         0003     #DHELLO

------------------------------------------------------------------------------------------------------------------------------------------------------
PAGE 6



 VARIABLE OFFSET TABLE
    LOC IS THE CSECT-RELATIVE ADDRESS IN HEX OF THE DECLARED VARIABLE.
    B IS THE BASE REGISTER USED FOR ADDRESSING THE DECLARED VARIABLE.  IF B IS NEGATIVE, THIS IS A VIRTUAL REGISTER AND CODE
          MUST BE GENERATED TO LOAD A REAL REGISTER.
    DISP IS THE DISPLACEMENT USED FOR GENERATING BASE-DISPLACEMENT ADDRESSES FOR ACCESSING THE DATA ITEMS.
    LENGTH IS THE SIZE IN DECIMAL HALFWORDS OF THE VARIABLE.
    BIAS IS THE AMOUNT OF THE ZEROTH ELEMENT OFFSET.
    NAME IS THE NAME OF THE VARIABLE.


  LOC    B DISP     LENGTH    BIAS   NAME

         UNDER HELLO     STACK=20
000006   1 006          1       0    I
000008   1 008         11       0    MY_NAME
000007   1 007          1       0    J


------------------------------------------------------------------------------------------------------------------------------------------------------
PAGE 7



MEMORY MAP FOR DATA CSECT #DHELLO

NAME                  LEN(DEC)  OFFSET(DEC)   B  DISP(HEX)  SCOPE

**LOCAL BLOCK DATA**        2         4                     HELLO
I                           1         6       1    0006     HELLO
J                           1         7       1    0007     HELLO
MY_NAME                    11         8       1    0008     HELLO

TOTAL SIZE OF ALIGNMENT GAPS FOR CSECT: 0 HW



INSTRUCTION FREQUENCIES

INSN  COUNT
LFXI    12
LR      2
STH     4
LA      6
AH      2
SCAL    11
IAL     1
BCB     2
BCF     2
SVC     1
LHI     2
CHI     2


       OPTIONAL TABLE SIZES

NAME       REQUESTED    USED
^^^^       ^^^^^^^^^    ^^^^

LITSTRINGS      2000      68
LABELSIZE       1200       8


42 HALMAT OPERATORS CONVERTED

47 INSTRUCTIONS GENERATED

70 HALFWORDS OF PROGRAM, 51 HALFWORDS OF DATA.

MAX. OPERAND STACK SIZE            =9
END  OPERAND STACK SIZE            =0
MAX. STORAGE DESCRIPTOR STACK SIZE =1
END  STORAGE DESCRIPTOR STACK SIZE =0
NUMBER OF MINOR COMPACTIFIES       =0
NUMBER OF MAJOR COMPACTIFIES       =0
NUMBER OF REALLOCATIONS            =5
FREE STRING AREA                   =16623408

END OF HAL/S PHASE 2 AUGUST 8, 2024.  CLOCK TIME = 12:51:35.65


------------------------------------------------------------------------------------------------------------------------------------------------------
PAGE 8


TOTAL CPU TIME FOR PHASE 2       0:0:0.01
CPU TIME FOR PHASE 2 SET UP      0:0:0.00
CPU TIME FOR PHASE 2 GENERATION  0:0:0.00
CPU TIME FOR PHASE 2 CLEAN UP    0:0:0.01

The most-significant thing about PASS2's report is probably that it gives us a glimpse — well, actually a full listing — of the assembly-language into which the compiler has transformed our HAL/S sample program.  PASS2 doesn't actually put such a listing in its report, by the way, at least not by default.  It only did so in this case because we compiled it with the LIST option.  After all, software that's merely printed in a report has very little use from the computer's point of view.  In fact, I've only included it in the report as eye candy!

Rather, useful object code is emitted in the form of a file, called cards.bin.  The cards.bin file is what would be used by a linker or loader.  The object code is, of course, IBM AP-101S object code.  You can read all about it, in all its gory detail, in the document "Space Shuttle Model AP-101S Principles of Operation, with Shuttle Instruction Set".

Rather than compiling HELLO.hal using the command given earlier, I'd be more likely to compile it using the command

HALSFC HELLO.hal TEST "LIST,NOTABLES,LISTING2"

The difference, you'll recall, is that TEST additionally performs some verification of the compiler results, and that TEST requires NOTABLES. (NOTABLES simply means not to run the compiler's PASS3 and PASS4, which we weren't even looking at in this example anyway.  LISTING2 means to produce a secondary, "unformatted" source-code listing.)  In fact, here are the messages we get,

======================================================
PASS1 cross-comparison test:
Files pass1A.rpt and pass1pA.rpt are identical
Files FILE1.bin and halmat.bin are identical
Files LISTING2.txt and listing2.txt are identical
======================================================
Compilation successful. Results in "HALSFC Wed Aug 21 07:39:24 AM CDT 2024.results".

What we're told is that essentially the same compilation has been performed, but that additionally we gained some confidence that the various of the compiler outputs are correct.  By the way, the secondary listing looks like this:

1  H A L   C O M P I L A T I O N   --   P H A S E   1   --   U N F O R M A T T E D   S O U R C E   L I S T I N G             PAGE 1
-        D| EBUG `D`E`F                                                                    | 1    
0      1 M|                                                                                | 2    
0      1 M| HELLO: PROGRAM;                                                                | 3    HELLO
0      1 M|    DECLARE I INTEGER;                                                          | 4    HELLO
0      2 M|    DECLARE MY_NAME CHARACTER(20) INITIAL('RON BURKEY');                        | 5    HELLO
0      3 M|    DECLARE INTEGER, J;                                                         | 6    HELLO
0      4 M|    REPLACE PRINTER BY "6";                                                     | 7    HELLO
0      5 M|    WRITE(PRINTER) 'THE BEGINNING';                                             | 8    HELLO
0      6 M|    DO FOR I = 1 TO 5;                                                          | 9    HELLO
0      7 M|       WRITE(PRINTER) I, 'HELLO, WORLD!';                                       | 10   HELLO
0      8 M|       DO FOR J = 2 TO 8 BY 2;                                                  | 11   HELLO
0      9 M|          WRITE(PRINTER) J, MY_NAME, 'SAYS ISN''T THIS FUN?';                   | 12   HELLO
0     10 M|       END;                                                                     | 13   HELLO
0     11 M|    END;                                                                        | 14   HELLO
0     12 M|    WRITE(6) 'THE END';                                                         | 15   HELLO
0     13 M| CLOSE HELLO;                                                                   | 16   HELLO

The characters in column 1 are so-called ANSI control characters, as described later.

Installation of HALSFC

For Linux, Mac OS, or Windows.

1. Install XCOM-I, per the instructions on the XPL/I page.
2. Perhaps you can download pre-built HALSFC executables.  I give you no guarantee that they'll work, and you run the risk of not necessarily getting the most up-to-date version of the compiler.  If those things bother you (they should!) then go on to step 3 instead.  But if you do download them, and if the stuff described in the preceding section works for you after doing so, then you're all done with the installation.
   

• Windows:  Download the compiler's exe files from here, unzip the zipfile, and put the exe files somewhere in your PATH.
• Mac OS:  Download the compiler's executable files from here, unzip the zipfile, and put the files somewhere in your PATH.
• Linux:  I have faith that you don't need any shortcuts!  Well, that and the fact that it's tough to insure that you have all of the libraries you need to run any executables I give you without putting a lot more work into it than I'm willing to countenance.  Move on to step 3.
  

3. (Optional but recommended.)  Verify that XCOM-I works, by following the instructions appropriate to your computer type, as given in the following sections of the XPL/I page:

• Testing the Installation
• Emulating the IBM System/360 CPU
• Insane Bootstrapping!

4. Build HALS/S-FC executable files, using the instructions on the XPL/I page.

Where the Wild HAL/S Files Are

Naturally, the most-important HAL/S source-code files for us will be the PASS and BFS source-code files of the Space Shuttle. 

In lieu of those, however, it would be nice to have some HAL/S source-code files other than HELLO.hal or files we have to write for ourselves!  Fortunately, Ryer's book Programming in HAL/S is a rich source of source.  A hundred or so short source-code files have been extracted from Ryer, and can be found in the directory "virtualagc/yaShuttle/Source Code/Programming in HAL-S".

The HAL-S-360 Users Manual is a much-more feeble source of source, though if you look in the directory "virtualagc/yaShuttle/Source Code/HAL-S-360 Users Manual" you'll find a file called DEMO.hal that I've taken from the Users Manual.  It is interesting because it also shows us what the compiler listing was supposed to look like.  That listing is not quite the same as ours today.  But given that it was a version of the HAL/S compiler 30 years younger than ours, and that the compiler used was HAL/S-360 rather than HAL/S-FC, it's hardly surprising that there are some differences.

There may be other HAL/S source among our collected documentation, that I've overlooked.  If you notice any — or for that matter, have any! — let me know.

Some Differences Between the Old and the New

EBCDIC vs ASCII

• All printable characters common to both EBCDIC and ASCII.
• Except that the ASCII characters carat (^), tilde (~), backtick (`), and backslash (\) were not legal.
• Whereas the non-ASCII characters logical-NOT (¬), U.S. cent (¢), and the punchcard-but-non-EBCDIC "end-of-file" were legal.

I say "basically", because technically there are some quibbles about some of the characters (^, \, and end-of-file) with which I will not bore you.  But I will mention that in spite of the technical illegality of it, legacy HAL/S and XPL source code often already uses either '~' or '^' in place of '¬'.

Given these facts and the obvious technical advantages of using a 7-bit character set for everything, the modern tool-set:

• Expects HAL/S source code to be provided in 7-bit ASCII, with the caveats mentioned below.  Specifically, EBCDIC source code is not accepted.
  
• Uses '~' in place of both '¬' and '^'.  If either of the latter is encountered in HAL/S source code, it is translated to the former.
• Uses '`' in place of '¢', again with automatic translation to the former.
• Uses '\' in place of end-of-file, though this is very, very rare indeed.

These restrictions apply only to HAL/S source code.  And, any human-readable reports generated by the compiler are pure 7-bit ASCII with the substitutions mentioned.  This should not be taken to imply that character data is maintained internally by the compiler in ASCII encoding, nor that all files output by the compiler have text encoded in ASCII.  In fact, that's not true:  Internally, the compiler uses mostly EBCDIC, and other than files which are human-readable, characters are encoded in the same manner as the original compiler encoded them.  For example, textual data in AP-101S object-code files uses Display Electronics Unit (DEU) encoding (seen in the figure to the right), which is neither EBCDIC nor ASCII, though in some ways being ASCII-like.

COMMON Memory

Much of the data transferred from one compiler pass to the next resided in so-called COMMON memory.  I refer here not to the HAL/S compilation unit known as a COMPOOL, but rather to sections of IBM 360 memory which were expected to be left intact when one pass of the compiler (say, PASS2) terminated and the next pass of the compiler (say, PASS3) was loaded and began executing.  Given that the modern HAL/S compiler implements each pass of the compiler as a stand-alone program, no such continuity of physical memory is possible.  So some other means must be used to preserve this data.

The modern compiler handles this by storing COMMON data in files.  Upon termination, a compiler pass writes an output-file describing the state of COMMON memory.  And similarly, upon startup, a compiler pass reads and input-file describing the state of COMMON memory.  The compiler maintains a model of the IBM 360 24-bit memory space, and the addresses of all COMMON data remain the same in this 24-bit model throughout any compilation run.

Overstruck Lines in Reports

Since the original compiler physically printed reports and could control whether or not the printer advanced the paper, it was capable of overstriking those printed lines with decorations such as underlines.  The corresponding reports output by the modern compiler are plain ASCII text, and overstriking is not possible.  For example, in a source-code listing, expansion of a macro was originally indicated by underlining the macro.

The modern compiler mimics the original underlining with a line of text, such as

THIS IS MY UNDERLINED TEXT

with two lines of text, thusly:

THIS IS MY UNDERLINED TEXT
           ^^^^^^^^^^

While this nicely conveys the underlining effect, I think, the fact that some single printed lines are replaced by dual printed lines does affect the vertical alignment and the pagination.

Compiler Options, Part One

There are a number of options that are specific to the modern HAL/S compiler, versus the original HAL/S compiler (which naturally didn't have these "modern" options).  I'll resist the temptation of going through those in detail.  If you're interested, I'd suggest using the command

HALSFC-PASS1 --help

to get descriptions of them.  Most of them relate to debugging the HAL/S compiler itself, and hence are of little value to anybody wishing merely to use the compiler.  All of the other compiler passes (HALSFC-FLO, HALSFC-OPT, and so on) will list all of the same options, so you needn't look past HALSFC-PASS1.

• --ddi=N,F[,U][,E] — This attaches an input file for sequential reading.  F is the path to the file.  You can think of these as being text files that are read in a line at a time.  The lines are padded or truncated to 80 columns, as necessary.  The U clause, in the unlikely event that it's present, means that the text should be automatically translated to upper case as it is read in.  The optional E clause would be used if the input file contains EBCDIC, or more precisely, if the text does not need to be recoded as it is read in.  But by default, the input text is assumed to be 7-bit ASCII and will be recoded into EBCDIC as it is read in.  The compiler thinks of the file as being a numbered device.  The value of N (0 through 9) is the number of the device to which the file is assigned.
  
• --ddo=N,F[,E] — Same as --ddi, but for output files rather than input files.  The U clause is not available.  Note that the same sequential file shouldn't be simultaneously attached for both input and output.
  
• --pdsi=N,F[,E] — Same as --ddi, but for Partitioned Data Sets (PDS) rather than sequential files.  A PDS is more similar a directory than to a file, thus it is implemented as a directory and F in this case is the name of a directory.  A PDS has named members which the software can select at runtime, and it's the named members that act like files.
• --pdso=N,F[,E] — Same as --pdsi, but for output rather than for input.  The same directory can be attached simultaneously for both input and output.
• --raf=I,R,N,F — Attaches "random-access file" F to device number N.  Think of these as being binary files of fixed record sizes, which are read or written only in integral numbers of records.  The value of I (I, O, or B) determines in principle whether the file is used for input, output, or both, but in practice it is always B for both.  The record size is determined by R.  By the way, note that while the --ddi, --ddo, --pdsi, and --pdso, options share the same pool of device numbers among themselves, the pool of device numbers for --raf is separate from them.  For example, device N=5 for --raf could be reused for --ddi without any unpleasant side effects.  Data from a random-access file never undergoes any recoding or translation (such as EBCDIC-to-ASCII or vice-versa) upon reading or writing.
• --commoni=F — Path to the file containing the state of COMMON memory upon program start.
• --commono=F — Same as --commoni, except that it's the state of COMMON at program termination.  Warning:  Do not use the same file simultaneously for both --commoni and --commono on the same compiler pass.
  

More on the Compiler Options

HALSFC-PASS1 --parm="..." etc.

 PARM FIELD: LIST


 COMPLETE LIST OF COMPILE-TIME OPTIONS IN EFFECT


       *** TYPE 1 OPTIONS ***

        NOADDRS
        NODECK
        NODUMP
        NOHALMAT
        NOHIGHOPT
          LFXI
          LIST
        NOLISTING2
          MICROCODE
        NOREGOPT
        NOSDL
        NOSREF
        NOSRN
        NOTABDMP
          TABLES
        NOTABLST
        NOTEMPLATE
        NOVARSYM
          ZCON


       *** TYPE 2 OPTIONS ***

       BLOCKSUM = 400
       CARDTYPE =
       COMPUNIT = 0
            DSR = 1
      LABELSIZE = 1200
         LINECT = 59
     LITSTRINGS = 2000
      MACROSIZE = 500
           MFID =
          PAGES = 2500
        SYMBOLS = 200
          TITLE =
       XREFSIZE = 2000

1  H A L   C O M P I L A T I O N   --   P H A S E   1   --   U N F O R M A T T E D   S O U R C E   L I S T I N G             PAGE 1
-        D| EBUG `D`E`F                                                                    | 1    
0      1 M|                                                                                | 2    
0      1 M| HELLO: PROGRAM;                                                                | 3    HELLO
0      1 M|    DECLARE I INTEGER;                                                          | 4    HELLO
0      2 M|    DECLARE MY_NAME CHARACTER(20) INITIAL('RON BURKEY');                        | 5    HELLO
0      3 M|    DECLARE INTEGER, J;                                                         | 6    HELLO
0      4 M|    REPLACE PRINTER BY "6";                                                     | 7    HELLO
0      5 M|    WRITE(PRINTER) 'THE BEGINNING';                                             | 8    HELLO
0      6 M|    DO FOR I = 1 TO 5;                                                          | 9    HELLO
0      7 M|       WRITE(PRINTER) I, 'HELLO, WORLD!';                                       | 10   HELLO
0      8 M|       DO FOR J = 2 TO 8 BY 2;                                                  | 11   HELLO
0      9 M|          WRITE(PRINTER) J, MY_NAME, 'SAYS ISN''T THIS FUN?';                   | 12   HELLO
0     10 M|       END;                                                                     | 13   HELLO
0     11 M|    END;                                                                        | 14   HELLO
0     12 M|    WRITE(6) 'THE END';                                                         | 15   HELLO
0     13 M| CLOSE HELLO;                                                                   | 16   HELLO
0     14 M|                                                                                | 17   HELLO

Debugging-Aid Options

In addition to compiler options originally supplied by JCL, but now supplied by command-line switches as described in the preceding section, there are also compiler options which can be supplied within the HAL/S source code itself.  These typically (but not always) differ from the command-line options in that they tend to take effect at the position in the HAL/S source code at which the compiler encounters them.  As the title of this section implies, such options are often (but not always) for the purpose of debugging the compiler itself. 

Such options are inserted into the code via DEBUG compiler directives aligned with column 1 of the source code, and you can see examples of them (highlighted in green) in our little sample HELLO.hal program:

DEBUG ¢D¢E¢F
 
 HELLO: PROGRAM;
    DECLARE I INTEGER;
    DECLARE MY_NAME CHARACTER(20) INITIAL('RON BURKEY');
    DECLARE INTEGER, J;
    REPLACE PRINTER BY "6";
    WRITE(PRINTER) 'THE BEGINNING';
    DO FOR I = 1 TO 5;
       WRITE(PRINTER) I, 'HELLO, WORLD!';
       DO FOR J = 2 TO 8 BY 2;
          WRITE(PRINTER) J, MY_NAME, 'SAYS ISN''T THIS FUN?';
       END;
    END;
    WRITE(6) 'THE END';
 CLOSE HELLO;

This example turns on debugging-aid options D, E, and F.

Section 2.2.7 ("Debugging Aids") of the HAL/S-FC & HAL/S-360 Compiler System Program Description describes many such options, although as you've probably come to expect, by no means all of them.

Debugging-aid options are of two general types:

1. Options of the form ¢T, where T is a letter (A-F), are used mainly (but not entirely) for PASS1.  They can:
• Enable the option if specified as ¢T+
• Disable the option if specified as ¢T-
• Toggle the if specified merely as ¢T with no suffix.  The options are all disabled by default, and so in our HELLO.hal example above, the three toggles for D, E, and F enable all of them.
2. Options of the form H(N), where N is a decimal number (0-255), are used in later compiler passes.  I haven't put any of them in our HELLO.hal example above, but they too are specified within DEBUG compiler-directives.  Only one H(N) option is in effect at any given time.  Number N=0 has no effect at all, whereas numbers N=1-127 affect FLO, OPT, and/or AUX, while N=128-255 affects PASS2.  PASS1 simply inserts N into a tag field in the next HALMAT intermediate-language SMRK instruction generated — which is at the beginning of the next HAL/S statement —, and then resets the N=0 internally.  Yes, I know it's not obvious what that means, but the point is that if multiple H(N) switches were encountered, then only the final one could take effect (at the beginning of the next statement).
   

Here's a table of the debugging-aid options that I'm aware of, usually with samples of how the options affect the reports output by the various compiler passes.  You won't have to look too long to realize that any of these options, if they remain enabled, can increase the size of output reports dramatically.  And if options are combined, the increase can be astounding.  So rather than just enabling options at the beginning of the HAL/S program and leaving them enabled as I do in many of these examples for illustrative purposes, a more-normal usage would be to enable an option just prior to some place in the source code just prior to where a problem has been observed, and to disable them after the problematic section of code.

Files Used or Created by the HAL/S Compiler

Validating the Compiler

My Mind-Reading Trick

Validating PASS1

Validating Phase 1.5 and Phase 2

• The complete HAL/S and AP-101S source code for some version of the Space Shuttle flight software (roughly 700K lines of code).
• A knowledge of the compiler options and the module ordering used to compile that flight software.
• A complete binary dump of the compiled flight software of the same version.

If so, it would be possible to perform an automated end-to-end check that the compiled source code produced an executable that was byte-for-byte correct, and that it had presumably exercised every feature of the HAL/S language.

A Glossary and Some References

• Organizations:
• Intermetrics, Inc.:  The company which originally developed the Space Shuttle flight software and the development tool-chain for it.  At this writing, its current successor is L-3 Communications.
  
• United Space Alliance (USA):  The company which eventually took over the flight-software development.  It was a joint venture of Rockwell International (succeeded by Boeing) and Lockheed-Martin.  It was dissolved in 2019, without a successor that I'm aware of, and no longer exists.
  
• Timeframes:
• Contemporary or original or Intermetrics:  I use these terms more-or-less interchangeably to refer to the software and/or documentation created for the Space Shuttle project itself, in the rough time-frame 1975-2010.
• Modern:  I use this term to refer to software developed primarily by Virtual AGC in the post-Shuttle era to replace or supports the contemporary development tool-chain.
  
• Computer hardware:
• IBM System/360:  This, and its descendants (the 370 and 390), were the types of mainframe computers on which the development tool-chain ran.
• IBM AP-101S or General Purpose Computer (GPC):  This is the type of computer onboard the Space Shuttle in which the flight software ran; each Shuttle had 5 of these computers.  Technically, early Shuttle flights used the AP-101B computer.
  
• Native system:  This is the term I'll use to describe the computer system you might be using today to run the software from this page; presumably not an IBM 360 or AP-101S!  I have in mind any computer running the Linux operating system, or to the extent it's feasible for me to support, the Mac OS or Windows operating systems.
• Computer languages:
• HAL/S:  The high-level computer language in which the Space Shuttle flight software was primarily written.  I refer specifically to the version of HAL/S implemented by Intermetrics, Inc., which though sharing the same name, would not have been 100% compatible with HAL/S implementations by other companies for other purposes.
  
• AP-101S assembly language:  The low-level computer language in which some of the flight software was written.
  
• HALMAT:  A contemporary "intermediate language" into which HAL/S program was compiled.  HALMAT is more of a binary file format than a "language", since there is no easily-human-readable form of it, nor did humans ever write programs in HALMAT.  Rather, the virtues of HALMAT were that it was agnostic as to the targeted computer type, that it was subject to optimization, and that target-specific assembly language could be generated from it.
• PALMAT:  A modern intermediate language, similar in spirit to HALMAT, but differing from HALMAT in all details.
  
• XPL (or sometimes, standard XPL):  A computer language defined by a book called A Compiler Generator (1979), by William M. McKeeman, James J. Horning, and David B. Wortman.  This language was specialized for the purpose of writing compilers for other computer languages.
• XPL/I:  This is an extended but ofttimes undocumented form of XPL that was implemented by Intermetrics, Inc.  The term "XPL/I" is my own; Intermetrics, and everyone else as far as I know, simply referred to it as "XPL", as if it were the same thing as standard XPL.
  
• Basic Assembly Language (BAL):  This is the low-level language of the IBM System/360, 370, and 390 computers.  If you look for adequate reference material, it's best to think of it as IBM 390 assembly language.  Confusingly, Intermetrics/USA also referred to AP-101S assembly language as "BAL".
  
• Python and C:  Modern computer languages for native computer systems.  By "Python", I refer to Python 3 (as opposed to Python 2).  By "C", I refer to the language compiled by GNU gcc, or by 100%-compatible compilers such as clang.
  
• Space Shuttle Flight Software:
• Primary Flight Software (PFS):  This is what's usually thought of as the flight software.  Written primarily in HAL/S, but with some AP-101S assembly language.
  
• Flight Control Operating System (FCOS):  The operating system which the PFS ran atop.  Written in AP-101S assembly language.
• Primary Avionics Software Subsystem (PASS):  PFS+FCOS.
• Backup Flight Software (BFS):  Flight software written independently of PFS, specializing only in critical tasks, to provide improved reliability; in such critical flight phases, BFS ran on one of the Shuttle's 5 GPCs while PFS ran on the other 4 GPCs, so that BFS could quickly take over for PFS if needed.  Written primarily in HAL/S, with some AP-101S assembly language.
• Backup Operating System (BOS):  The operating system atop which BFS ran.  Written in AP-101S assembly language.
  
• Especially-relevant documentation:
• McKeeman:  I use this term to refer to the book A Compiler Generator (1979), by William M. McKeeman, James J. Horning, and David B. Wortman.
• Ryer:  I use this term to refer to the book Programming in HAL/S, second edition (1979), by Michael Ryer.
• Related Virtual AGC website pages:
• Space Shuttle
• HAL/S section of the Space Shuttle Document Library
• XPL/I programming language
• Other terms you may encounter here:
• FSW:  Flight Software.
  
• SDF:  Simulation Data Files, used when running digital simulations of the Shuttle flight software in AP-101S load-file form.

This page is available under the Creative Commons No Rights Reserved License
Last modified by Ronald Burkey on 2024-08-21