Lacking Natural Simplicity

The Ada Quality and Style: Guidelines for Professional Programmers is available on the web, but I don't think that there is a PDF copy anywhere easily found, so I'm making a copy available here. This is the style guide for Ada 83, by the way. I got it from the Ada Information Clearinghouse. I downloaded the file style-ps.zip into a temporary directory and then ran the shell script make-83style-pdf.sh to create the PDF file:

#! /usr/bin/env bash
# First, unzip style-ps.zip.  Then, in another directory, unzip all six of
# those zip files.  Then do the following:
set -x
mkdir tmp &&
    cd tmp &&
    unzip -L ../style-ps.zip &&
    mkdir tmp &&
    cd tmp &&
    for i in ../*.zip; do unzip -L $i; done  &&
    for i in *.ps; do ps2pdf $i $(basename $i .ps).pdf; done &&
    qpdf --empty -pages covers.pdf 1-3 -- covers_fixed.pdf &&
    pdfunite covers_fixed.pdf preface.pdf ack.pdf toc.pdf intro.pdf source_c.pdf readabil.pdf prog_str.pdf prog_pra.pdf concurr.pdf portabil.pdf reuse.pdf performa.pdf complete.pdf appendix.pdf ref.pdf bib_0188.pdf index.pdf 83style.pdf

Note the qpdf command? That pulls out the first three pages of covers.pdf, because the other pages duplicate stuff that is in the other .pdf files.

Then I read through the PDF and made a bookmarks file for use with jpdfbookmarks (I use one of the releases from this github repo):

Ada Quality and Style/1
        Cover 1/1
        Cover 2/2
        Preface/4
        Authors and Acknowledgements/6
        Contents/8
        Chapter 1: Introduction/10
                1.1 How to use this book/11
                1.2 To the new Ada programmer/11
                1.3 To the experienced Ada programmer/12
                1.4 To the software project manager/12
                1.5 to contracting agencies and standards organizations/13
        Chapter 2: Source Code Presentation/14
                2.1 Code formatting/14
                        2.1.1 Horizontal spacing/14
                        2.1.2 Indentation/15
                        2.1.3 Alignment of operators/18
                        2.1.4 Alignment of declarations/19
                        2.1.5 More on alignmeent/20
                        2.1.6 Blank lines/21
                        2.1.7 Pagination/22
                        2.1.8 Number of statements per line/23
                        2.1.9 Source code line length/24
                2.2 Summary/24
        Chapter 3: Readability/26
                3.1 Spelling/26
                        3.1.1 Use of underscores/26
                        3.1.2 Numbers/26
                        3.1.3 Capitalization/27
                        3.1.4 Abbreviations/28
                3.2 Naming conventions/29
                        3.2.1 Names/29
                        3.2.2 Type names/29
                        3.2.3 Object names/30
                        3.2.4 Program unit names/31
                        3.2.5 Constants and named numbers/32
                3.3 Comments/33
                        3.3.1 General comments/34
                        3.3.2 File headers/35
                        3.3.3 Program unit specification header/35
                        3.3.4 Program unit body header/38
                        3.3.5 Data comments/39
                        3.3.6 Statement comments/41
                        3.3.7 Marker comments/43
                3.4 Using types/44
                        3.4.1 Declaring types/44
                        3.4.2 Enumeration types/45
                3.5 Summary/46
        Chapter 4: Program Structure/50
                4.1 High level structure/50
                        4.1.1 Separate compilation capabilities/50
                        4.1.2 Subprograms/51
                        4.1.3 Functions/52
                        4.1.4 Packages/53
                        4.1.5 Cohesion/53
                        4.1.6 Data coupling/54
                        4.1.7 Tasks/54
                4.2 Visibility/55
                        4.2.1 Minimization of interfaces/55
                        4.2.2 Nested packages/56
                        4.2.3 Restricting visibility/56
                        4.2.4 Hiding tasks/57
                4.3 Exceptions/59
                        4.3.1 Using exceptions to help define an abstraction/59
                4.4 Summary/61
        Chapter 5: Programming Practices/64
                5.1 Optional parts of the syntax/64
                        5.1.1 Loop names/64
                        5.1.2 Block names/65
                        5.1.3 Exit statements/66
                        5.1.4 Naming end statemnts/66
                5.2 Parameter lists/67
                        5.2.1 Formal parameters/67
                        5.2.2 Named association/67
                        5.2.33 Default parameters/68
                        5.2.4 Mode indication/69
                5.3 Types/69
                        5.3.1 Derived types and subtypes/69
                        5.3.2 Anonymous types/71
                        5.3.3 Private types/71
                5.4 Data structures/72
                        5.4.1 Heeterogeneous data/72
                        5.4.2 Nested records/73
                        5.4.3 Dynamic data/74
                5.5 Expressions/75
                        5.5.1 Range values/75
                        5.5.2 Array attributes/76
                        5.5.3 Parenthetical expressions/76
                        5.5.4 Positive forms of logic/77
                        5.5.5 Short circuit forms of the logical operators/77
                        5.5.6 Accuracy of operations with real operands/78
                5.6 Statements/78
                        5.6.1 Nesting/78
                        5.6.2 Slices/80
                        5.6.3 Case statements/80
                        5.6.4 Loops/81
                        5.6.5 Exit statements/82
                        5.6.6 Recursion and iteration bounds/83
                        5.6.8 Return statements/84
                        5.6.9 Blocks/85
                        5.6.10 Aggregates/86
                5.7 Visibility/86
                        5.7.1 The use clause/87
                        5.7.2 The renames clause/88
                        5.7.3 Overloaded subprograms/88
                        5.7.4 Overloaded operators/89
                        5.7.5 Overloading the equality operator/89
                5.8 Using exceptions/89
                        5.8.1 Handling versus avoiding exceptions/90
                        5.8.2 Handlers for others/90
                        5.8.3 Propagation/91
                        5.8.4 Localizing the causes of an exception/91
                5.9 Erroneous Execution/92
                        5.9.1 Unchecked conversion/92
                        5.9.2 Unchecked deallocation/93
                        5.9.3 Dependeence on parameter passing mechanism/93
                        5.9.4 Multiple address clauses/94
                        5.9.5 Suppression of exception check/94
                        5.9.6 Initialization/94
                        5.9.7 Direct_IO and Sequential_IO/95
                        5.9.8 Incorrect order dependencies/96
                5.10 Summary/96
        Chapter 6: Concurrency/100
                6.1 Tasking/100
                        6.1.1 Tasks/100
                        6.1.2 Anonymous task types/101
                        6.1.3 Dynamic tasks/102
                        6.1.4 Prioritis/103
                        6.1.5 Delay statements/104
                6.2 Commmunication/105
                        6.2.1 Effecient task communications/105
                        6.2.2 Defensive task communication/106
                        6.2.3 Attributes 'Count, 'Callable, and 'Terminated/108
                        6.2.4 Shared variables/109
                        6.2.5 Tenative rendezvous constructs/111
                        6.2.6 Commmunication complexity/112
                6.3 Termination/113
                        6.1.1 Avoiding termination/113
                        6.3.2 Normal termination/114
                        6.3.3 The abort statement/115
                        6.3.4 Abnormal termination/115
                6.4 Summary/116
        Chapter 7: Portability/118
                7.1 Fundamentals/119
                        7.1.1 Global assumptions/119
                        7.1.2 Actual limits/120
                        7.1.3 Comments/120
                        7.1.4 Main subprogram/121
                        7.1.5 Encapsulating implementation dependencies/121
                        7.1.6 Implementation-added features/122
                7.2 Numeric types and expressions/122
                        7.2.1 Predefined numeric types/122
                        7.2.2 Ada model/123
                        7.2.3 Analysis/123
                        7.2.4 Accuracy Constraints/124
                        7.2.5 Comments/124
                        7.2.6 Precision of constants/124
                        7.2.7 Subexpression evaluation/124
                        7.2.8 Relational tests/124
                7.3 Storage control/125
                        7.3.1 Representation clause/125
                7.4 Tasking/126
                        7.4.1 Task activation order/126
                        7.4.2 Delay statements/126
                        7.4.3 Package Calendar, type Duration, and System.Tick/126
                        7.4.4 Select statement evaluation ordr/126
                        7.4.5 Task scheduling algorithm/127
                        7.4.6 Abort/127
                        7.4.7 Shared variables and pragma shared/127
                7.5 Exceptions/127
                        7.5.1 Predefined exceptions/127
                        7.5.2 Constraint_Error and Numeric_Error/128
                        7.5.3 Implementation-defined exceptions/128
                7.6 Representationi clauses and implementation dependent features/128
                        7.6.1 Representation clauses/129
                        7.6.2 Package System/129
                        7.6.3 Machine code inserts/129
                        7.6.4 Interfacing Foreign Languages/130
                        7.6.5 Implementation-defined pragmas and attributes/130
                        7.6.6 Unchecked deallocation/130
                        7.6.7 Unchecked conversion/131
                7.7 Input/output/131
                        7.7.1 Name and Form parameters/132
                        7.7.2 File closing/132
                        7.7.3 I/O on access types/132
                        7.7.4 Package Low_Level_IO/132
                7.8 Summmary/133
        Chapter 8: Reusability/136
                8.1 Understanding and clarity/137
                        8.1.1 Application-independent naming/137
                        8.1.2 Abbreviations/138
                        8.1.3 Generic formal parameters/139
                8.2 Robustness/139
                        8.2.1 Named numbers/139
                        8.2.2 Unconstrained arrays/140
                        8.2.3 Assumptions/140
                        8.2.4 Subtypes in generic specifications/141
                        8.2.5 Overloading in generic units/143
                        8.2.6 Hidden tasks/143
                        8.2.7 Exceptions/143
                8.3 Adaptability/145
                        8.3.1 Complete functionality/145
                        8.3.2 Generic units/146
                        8.3.3 Using generic units to encapsulate algorithms/146
                        8.3.4 Using generic units for abstract data types/148
                        8.3.5 Iterators/151
                        8.3.6 Private and limited private types/154
                8.4 Independence/156
                        8.4.1 Using generic parameters to reduce coupling/156
                        8.4.2 Coupling due to pragmas/157
                        8.4.3 Part families/158
                        8.4.4 Conditional compilation/158
                        8.4.5 Table-driven programming/159
                8.5 Summary/160
        Chapter 9: Performance/162
                9.1 Improving exception speed/162
                        9.1.1 Pragma inline/162
                        9.1.2 Blocks/163
                        9.1.3 Arrays/163
                        9.1.4 Mod and rem operators/164
                        9.1.5 Constraint checking/164
                9.2 Summmary/165
        Chapter 10: Complete Examples/166
                10.1 Menu-driven user interface/166
                10.2 Line-oriented portablee dining philosophers example/174
                10.3 Window-oriented portable dining philosophers example/179
        Appendix A: Map from Ada Language Referencee Manual to Guidelines/188
        References/194
        Bibliography/198
        Index/202

Then I ran another shell script, build-bookmarks.sh:

#! /usr/bin/env bash

jpdfbookmarks -f tmp/tmp/83style.pdf --apply 83style.bookmarks --out 83style.pdf

There is a PDF of the style guide for Ada 95 online, but the links to the other formats listed on the Ada 95 Documents page have bit rotted, alas.

Right, So, I've talked about how the LBL Software Tools Virtual Operating System organized its source files, using its archiver to collect all the source files, etc. for a program into an archive (sometimes with nested archives, because RECURSION IS NEAT) and then putting the archive under revision control using the TCS commands admin, delta, and get.

And that makes a lot of sense when what you are working on is one program or another closely related collection of information. But what if you are working on a collection of individual or nearly individual programs? Or what if your program is large enough that putting all its source in a single archive runs up against size limits in the SWTOOLS programs? Remember, they were ment to run on the 16 bit minicomputers of the day, as well as the 32 bit minicomputers that showed up soon after the SWTOOLS VOS was written, so there is a limit on the number of lines in a file that these can handle somewhere between 10,000 and 15,000 lines. What do you do then?

Well, today I wrote a set of commands to make it easy to work with a collection of source files, which each have a corresponding TCS history file in the subdirectory [.TCS]. I decided to have one DCL command procedure whose first parameter was the command to execute, so the common processing could be shared instead of duplicated between programs. But I had already written a program to compare a current source file inn the working directory with an older version in a TCS revision file. Hmm.

Anyway, I went on to write the tcs command as a front end for the normal TCS commands. Here's an example from running TCS HELP

$ tcs help
usage:
tcs [ help | -h | -help | -? ]
      Output this help message.

tcs admin FILE

      Initialize TCS file [.TCS]FILE from FILE.

tcs get [-oOUTFILE] [-h] [-rM.N] FILE

      Get a revision of FILE from TCS file [.TCS]FILE.

          -oOUTFILE writes the output to OUTFILE.
              If -o is not specifed the output goes to standard output.

          -h Output history information instead of a revision.

          -rM.N Output revision M.N.

tcs delta FILE

      Add a new version to TCS file [.TCS]FILE from FILE.

tcs outdated

      List all the source files that are newer than their corresponding
      TCS file in [.TCS]

tcs uncovered [FILESPEC] [IGNOREDTYPES]

      List all the files in the current directory that do not have
      corresponding files in [.TCS].

      If FILEPSEC is specified it should be a VMS wildcard that
      will be applied to the current directory for matching.

      If IGNOREDTYPES is specified it should be a single file type
      (without the ".") or a comma separated list of file types
      to be ignored.

      If one needs to specified IGNOREDTYPES but not FILESPEC just
      specify an empty string for FILESPEC.

And here is the current source code of TCS.SDCL:

!> TCS.SDCL -- TCS frontend.
##############################################################################
###
### tcs [ help | -h | -help | -? ]
### tcs admin FILE
### tcs get [-ooutfile] [-h] [-rM.N] FILE
### tcs delta FILE
### tcs outdated
### tcs uncovered [FILESPEC] [IGNOREDTYPES]
###
##############################################################################
    wso :== write sys$output
    wse :== write sys$error
    TRUE = 1 .eq. 1
    FALSE = 1 .ne. 1
    QUIET = %x10000000

    months_jan = "01"
    months_feb = "02"
    months_mar = "03"
    months_apr = "04"
    months_may = "05"
    months_jun = "06"
    months_jul = "07"
    months_aug = "08"
    months_sep = "09"
    months_oct = "10"
    months_nov = "11"
    months_dec = "12"

    debugging = f$type (tcs_debugging) .nes. ""
    verbose = FALSE

    command = p1

    if (command .eqs. "HELP" .or.
        command .eqs. "-H" .or.
        command .eqs. "-HELP" .or.
        command .eqs. "-?")
    {
        goto usage
    }

    if ((command .eqs. "") .or.
        .not. (command .eqs. "ADMIN" .or.
               command .eqs. "GET" .or.
               command .eqs. "DELTA" .or.
               command .eqs. "OUTDATED" .or.
               command .eqs. "UNCOVERED"))
    {
        wse "tcs: unrecognized TCS command: """, command, """"
        exit 2
    }

    param_idx = 2
    num_options = 0
    outfile = ""
    while (f$extract (0, 1, p'param_idx') .eqs. "-") {
         ## Remember, DCL upcases everything!
        if (f$extract (0, 2, p'param_idx') .eqs. "-O") {
            outfile = f$extract (2, f$length (p'param_idx'), p'param_idx')
        } else {
            num_options = num_options + 1
            options_'num_options' = p'param_idx'
        }
        param_idx = param_idx + 1
    }

    file = p'param_idx'                         # Can be blank
    dirname = f$search ("TCS.DIR")
    if (dirname .eqs. "") {             # No [.TCS] directory.
        create/dir [.TCS]
    }

    tcsfile = "[.tcs]" + file + "-TCS"  # Not used by some commands.

    if (debugging) {
        wso "command: ", command, " file: ", file, " tcsfile: ", tcsfile
        wso "outfile: """, outfile, """"
    }

    if (command .eqs. "ADMIN") {
        goto do_admin
    } else if (command .eqs. "GET") {
        goto do_get
    } else if (command .eqs. "DELTA") {
        goto do_delta
    } else if (command .eqs. "OUTDATED") {
        goto do_outdated
    } else if (command .eqs. "UNCOVERED") {
        goto do_uncovered
    }
    wso "tcs: This should be impossible, so somebody screwed up.  Exiting."
    exit 2 .or. QUIET


do_admin:
    result = f$search (tcsfile)
    if (result .nes. "") {
        wse "tcs: TCS file ", tcsfile, " already exists, exiting."
        exit 2
    }
    file = f$edit (file, "LOWERCASE")
    dclcmd = "admin ""-i''file'"" ''tcsfile'"
    wso "Executing ", dclcmd
    define/user sys$input sys$command
    'dclcmd'
    exit


do_get:
    if (outfile .eqs. "") {
        get 'options_1' 'options_2' 'options_3' 'options_4' 'tcsfile'
    } else {
        get 'options_1' 'options_2' 'options_3' 'options_4' 'tcsfile' >'outfile'
    }
    exit

do_delta:
    result = f$search (tcsfile)
    if (result .eqs. "") {
        wse "tcs: TCS file ", tcsfile, " does not exist, exiting."
        exit 2
    }
    define/user sys$input sys$command
    delta 'file' 'tcsfile'
    exit


do_outdated:
    filespec = "[.tcs]*.*-tcs"
    repeat {
        tcsfile = f$search (filespec)
        if (tcsfile .eqs. "") break
        tcsrdt = f$file (tcsfile, "RDT")
        tcs_day     = f$extract (00, 02, tcsrdt)
        tcs_monname = f$extract (03, 03, tcsrdt)
        tcs_year    = f$extract (07, 04, tcsrdt)
        tcs_rest    = f$extract (11, 12, tcsrdt)
        tcs_monnum  = months_'tcs_monname'
        tcs_cmpdate = tcs_year + tcs_monnum + tcs_day + tcs_rest
        if (debugging .and. verbose) wso "tcs_cmpdate: ", tcs_cmpdate
        dirname = f$parse (tcsfile,,, "DIRECTORY") - ".TCS]" + "]"
        filename = f$parse (tcsfile,,, "NAME")
        filetype = f$parse (tcsfile,,, "TYPE") - "-TCS"
        srcfile = filename + filetype
        srcrdt = f$file (srcfile, "RDT")
        src_day     = f$extract (00, 02, srcrdt)
        src_monname = f$extract (03, 03, srcrdt)
        src_year    = f$extract (07, 04, srcrdt)
        src_rest    = f$extract (11, 12, srcrdt)
        src_monnum  = months_'src_monname'
        src_cmpdate = src_year + src_monnum + src_day + src_rest
        if (debugging .and. verbose) wso "src_cmpdate: ", src_cmpdate
        if (src_cmpdate .gts. tcs_cmpdate) wso srcfile, " is newer than ", tcsfile
    }
    exit


do_uncovered:
    i = param_idx + 1
    ignoredtypes = p'i'
    if (ignoredtypes .nes. "") ignoredtypes = "," + ignoredtypes
    if (debugging) wse "ignoredtypes: ", ignoredtypes
    ignoredtypes_len = f$length (ignoredtypes)
    if (file .eqs. "") filespec = "*.*"
    else filespec = file
    if (debugging) wse "filespec: ", filespec
    old_result = ""
    repeat {
        result = f$search (filespec, 1)
        if (debugging) wso "result: ", result
        # No more results
        if (result .eqs. "") break
        # No wildcard specified
        if (result .eqs. old_result) break
        old_result = result
        filename = f$parse (result,,, "NAME")
        filetype = f$parse (result,,, "TYPE")
        file = filename + filetype
        # Ignore directories
        if (filetype .eqs. ".DIR") next
        # Skip the ignored file types.
        skip = "," + (filetype - ".")
        if (debugging) wse "skip: ", skip, " ignoredtypes: ", ignoredtypes
        if (f$locate (skip, ignoredtypes) .ne. ignoredtypes_len) {
            if (debugging) wse "Skipping ", file
            next
        }
        tcsfile = "[.TCS]" + file + "-TCS"
        if (f$search (tcsfile) .eqs. "")
            wso file, " does not have a ", tcsfile
    }
    exit


usage:
    copy sys$input sys$output
//usage:
//tcs [ help | -h | -help | -? ]
//      Output this help message.
//
//tcs admin FILE
//
//      Initialize TCS file [.TCS]FILE from FILE.
//
//tcs get [-oOUTFILE] [-h] [-rM.N] FILE
//
//      Get a revision of FILE from TCS file [.TCS]FILE.
//
//          -oOUTFILE writes the output to OUTFILE.
//              If -o is not specifed the output goes to standard output.
//
//          -h Output history information instead of a revision.
//
//          -rM.N Output revision M.N.
//
//tcs delta FILE
//
//      Add a new version to TCS file [.TCS]FILE from FILE.
//
//tcs outdated
//
//      List all the source files that are newer than their corresponding
//      TCS file in [.TCS]
//
//tcs uncovered [FILESPEC] [IGNOREDTYPES]
//
//      List all the files in the current directory that do not have
//      corresponding files in [.TCS].
//
//      If FILEPSEC is specified it should be a VMS wildcard that
//      will be applied to the current directory for matching.
//
//      If IGNOREDTYPES is specified it should be a single file type
//      (without the ".") or a comma separated list of file types
//      to be ignored.
//
//      If one needs to specified IGNOREDTYPES but not FILESPEC just
//      specify an empty string for FILESPEC.
    exit 2 .or. QUIET

I decided to leave my tcsdiff.sdcl program separate for the time being, since it was easy to convert to use with TCS files in [.TCS].

I found it amusing when I recently was working on some ratfor code soon after revising my SDCL (Structured DCL preprocessor) and I realized that the reason that the internal goto labels that I generate in SDCL start at 23000 because the original ratfor command started at 23000, which was carried over to the SWTOOLS VOS ratfor and the original sdcl written by Sohail Aslam of the University of Colorado at Colorado Springs, and from there to my version of SDCL.

The SWTOOLS VOS provides three shells, sh, hsh (which adds a history mechanism), and esh (which adds ed-style editing of the history). The release notes state that the shells need the privileges DETACH and CMEXEC, but under VMS 5.5-2 it turns out that they need the GRPNAM privilege as well.

Well, it's my first program using SWTOOLS VOS this time around.

So, I finished by first program using SWTOOLS. It is a simple directory lister, called l, that interprets all its arguments as as file specifications to search for using normal RMS wildcards, or used *.* if not arguments are specified. It only returns the files with the highest version number, does not include the device, directory, or version number in the output, and converts the filenames to lower case. It should only be used to list files in the current directory. I needed it because I do things like

l *.sdcl *.for | sedit 's/{?+}$/ar uv src.ar $1'

and I don't want any version numbers to end up in the names of the archive members, and so on.

Rafor is much better than Fortran 77. And Fortran has even more footguns than C when it comes to using separately compiled functions and subroutines, with no notices that I'd passed things with the wrong type until I actually ran the program and got a register dump because of an access violation.

I was not able to include things from SYS$LIBRARY:FORSYSDEF.TLB using the Fortran INCLUDE statement in ratfor, since it has its own include keyword , so I separated that part of the program into its own Fortran source file. Because that file wasn't run through ratfor I couldn't use the standard macro definitions, like STDERR, so when I wanted to output the filesnames, I just wrote a ratfor subroutine that would print them and called that from the Fortran subroutine. A little clunky, but it worked.

Annoying, the fc command (which compiles *.f files to objects) doesn't work when run under mmk, so I had to write a command procedure dommk that does mmk/noact/out=tmp.com and @tmp.com to do the build. (I think this was somehow due to having multiple levels of subprocesses: mmk's and rc's.)

Anyway, the program ended up 48 lines of ratfor in three files and 84 lines of Fortran. The C program I started with was 170 lines (in one file), but doesn't work with the SWTOOLS shell's notions of I/O redirection.

Last edited: 2024-07-19 12:44:44 EDT

Today I fixed a 41 year old bug in the SWTOOLS VOS sedit commmand!

At work part of my job is to maintain an emulated VAX/VMS 5.5-2 system for one of our clients. I have been using the SWTOOLS Virtual Operating System recently (Unix style I/O redirection! And pipes!), and whenever I tried to use the sedit command it would die with an integer overflow:

%SYSTEM-F-INTOVF, arithmetic trap, integer overflow at PC=0002D6C9, PSL=03C00022

Improperly handled condition, image exit forced.

      Signal arguments              Stack contents

      Number = 00000003                00000000
      Name   = 0000047C                08000020
               0002D6C9                000017C4
               03C00022                7FEF9784
                                       0002D479
                                       00001DC0
                                       00000000
                                       08000020
                                       7FEF97B4
                                       7FEF979C

      Register dump

      R0 = 0000000E  R1 = 0002BAF4  R2 = 0000000F  R3 = 7FF6A489
      R4 = 7FFE5E0C  R5 = 7FFE5EBC  R6 = 00000000  R7 = 00000001
      R8 = 7FFECA4C  R9 = 7FFECC54  R10= 7FFED7D4  R11= 00001E94
      AP = 7FEF9738  FP = 7FEF96F8  SP = 7FEF976C  PC = 0002D6C9
      PSL= 03C00022

Drats, drats, drats.

I use sed frequently on Unix, and it would be nice to have the SWTOOLS equivalent on VAX/VMS. What could I do but set the Wayback Machine for 1986 and dive in!

Those following along may want to read my post about how the Software Tools VOS organized its source files first.

The SWTOOLS VOS was written in Ratfor, which added structured control structures and other niceties such as macros, include files, and string constants to pre-1977 Fortran. I suspect that even as late as 1986, when the version of the SWTOOLS VOS was released, lots of installations were on machines that only *had* pre-1977 Fortran compilers.

Here's an example of Ratfor source, from sedit.r:

# copyf - copy file name to opened file fdo
subroutine copyf(name, fdo)
integer name(ARB)
integer fdo
integer fdi, i
integer open
character c, namstr(MAXLINE)
character getch

for (i=1; name(i)!=EOS; i=i+1)               #get name into string
     namstr(i) = name(i)
namstr(i) = EOS
fdi = open(namstr, READ)
if (fdi == ERR)
   call cant(namstr)
while (getch(c, fdi) != EOF)
   call putch(c, fdo)
call close(fdi)
return
end

You can tell it was inspired by Unix.

Here's the corresponding generated Fortran

      SUBROUTINE COPYF(NAME, FDO)
      INTEGER NAME(2048)
      INTEGER FDO
      INTEGER FDI, I
      INTEGER OPEN
      LOGICAL*1 C, NAMSTR(2048)
      LOGICAL*1 GETCH
      I=1
23190 IF (.NOT.(NAME(I).NE.0))GOTO 23192
      NAMSTR(I) = NAME(I)
23191 I=I+1
      GOTO 23190
23192 CONTINUE
      NAMSTR(I) = 0
      FDI = OPEN(NAMSTR, 1)
      IF (.NOT.(FDI .EQ. -3))GOTO 23193
      CALL CANT(NAMSTR)
23193 CONTINUE
23195 IF (.NOT.(GETCH(C, FDI) .NE. -1))GOTO 23196
      CALL PUTCH(C, FDO)
      GOTO 23195
23196 CONTINUE
      CALL CLOSE(FDI)
      RETURN
      END

Notice that the character variables got changed to LOGICAL*1? That turns out to be 1 byte variable...

So, to start, I needed to run sedit in the debugger. That's easy enough:

% cd ~tmp
% mkdir sedit
% cd sedit
/dua1/software/swtools/tmp/sedit/
% get -r1.5 ~src/sedit.tcs >sedit.w
% ar xv sedit.w
patdef
csedit
sedit.r
sedit.fmt
% rc -d -v sedit.r
~bin/ratp1.exe sedit.r | ~bin/ratp2.exe >sedit.f
~bin/fc.exe -v -d sedit.f
for/noop/object=sedit.obj/nolist/check=all/debug=all sedit.f
~bin/ld.exe -v -d sedit.obj
$ link/exe=dua1:[software.swtools.tmp.sedit]sedit.exe/debug/nomap sys$input/opti
ons
dua1:[software.swtools.tmp.sedit]sedit.obj,-
dua1:[software.swtools.bin]rlib.olb/incl=(tools$main),-
dua1:[software.swtools.bin]rlib.olb/libr
% echo Hello | sedit "s/H/J/"
%DEBUG-I-CANTCREATEMAIN, could not create the debugger subprocess
%DEBUG-I-CANTCREATEMAIN, could not create the debugger subprocess
-LIB-F-NOCLI, no CLI present to perform function
-LIB-F-NOCLI, no CLI present to perform function
%DEBUG-I-SHRPRC, debugger will share user process
%DEBUG-I-SHRPRC, debugger will share user process

         VAX DEBUG Version V5.5-023

%DEBUG-I-INITIAL, language is MACRO, module set to TOOLS$MAIN

DBG> go
%DEBUG-I-DYNMODSET, setting module DOCOM
%SYSTEM-F-INTOVF, arithmetic trap, integer overflow at PC=0002E345, PSL=03C00022
break on unhandled exception preceding DOCOM\%LINE 20
    20:       IF (.NOT.(CMD .EQ. 97))GOTO 23162
DBG> go
%DEBUG-I-DYNMODSET, setting module DOCOM
%SYSTEM-F-INTOVF, arithmetic trap, integer overflow at PC=0002E345, PSL=03C00022
break on unhandled exception preceding DOCOM\%LINE 20
    20:       IF (.NOT.(CMD .EQ. 97))GOTO 23162
DBG>

I guess we'll need a little more context.

DBG> type docom\1:20
module DOCOM
     1:       SUBROUTINE DOCOM(I, LINBUF, LINENO)
     2:       LOGICAL*1 LINBUF(2048)
     3:       INTEGER I, LINENO
     4:       LOGICAL*1 CMD
     5:       INTEGER K1, K2
     6:       INTEGER AQ
     7:       INTEGER IQ
     8:       INTEGER BUF
     9:       INTEGER LASTBF
    10:       INTEGER NLINES
    11:       INTEGER LINE1
    12:       INTEGER LINE2
    13:       INTEGER PAT
    14:       INTEGER PREVC
    15:       INTEGER NFLAG
    16:       INTEGER QFLAG
    17:       COMMON /CSEDIT/ AQ, IQ, BUF(20000), LASTBF, NLINES, LINE1, LINE2,
    18:      *PAT(132), PREVC, NFLAG, QFLAG
    19:       CMD = BUF(I+5)
    20:       IF (.NOT.(CMD .EQ. 97))GOTO 23162
DBG>

Ok, line 19 is where the the integer overflow happened. BUF is an array of INTEGERs, while CMD is a LOGICAL*1, which, if I look at the sedit.r source:

# docom - execute a single command at buf(i) on linbuf and lineno
   subroutine docom(i, linbuf, lineno)
   character linbuf(MAXLINE)
   integer i, lineno
   character cmd
   integer k1, k2
   include csedit

   cmd = buf(i+COMMAND)
   …

started as a character and got translated to a LOGICAL*1, the one byte logical data type. Normally that's ok, because we're just working with ASCII, so any character should fit in in one byte. Lets take a look:

DBG> ex buf[i+5]
DOCOM\BUF[19]:  00000173
DBG>

Oh dear. That's hexadecimal 173, which is decimal 371. No wonder we got an arithmetic trap, integer overflow.

If I look for occurrences of buf in sedit.r (using emacs 18.55.105) I see lots of lines like where buf is passed to subroutine addint, which is not documented in the manual pages, unfortunately, but is in the runtime library RLIB.OLB. On VAX/VMS the source for that is in ~vms/rlib.w:

# AddInt      Put int into intara if it fits, increment j
# works with an array of integers

integer function addint( int, intara, j, maxsiz)

integer         int, j, maxsiz, intara(maxsiz)

if( j > maxsiz )
  return(NO)

intara(j) = int
j = j + 1

return(YES)
end

Yes, that's just putting an integer in an array and incrementing the variable that stores where the next one goes.

Ok, lets look at all the addint calls.

Lines matching "\\baddint\\b(" in buffer sedit.r.
176:    if (addint(int, str, j, maxsiz) == NO)
223:   status = addint(nlines, buf, lastbf, MAXBUF)
224:   status = addint(0, buf, lastbf, MAXBUF)
225:   status = addint(line1, buf, lastbf, MAXBUF)
226:   status = addint(line2, buf, lastbf, MAXBUF)
229:      status = addint(NOTSTATE, buf, lastbf, MAXBUF)
235:      status = addint(OKSTATE, buf, lastbf, MAXBUF)
236:   status = addint(com, buf, lastbf, MAXBUF)
238:      status = addint(0, buf, lastbf, MAXBUF)
242:      status = addint(0, buf, lastbf, MAXBUF)
248:      status = addint(0, buf, lastbf, MAXBUF)
256:      status = addint(0, buf, lastbf, MAXBUF)
260:         status = addint(EOS, buf, lastbf, MAXBUF)
269:         status = addint(gflag, buf, lastbf, MAXBUF)
270:         status = addint(pflag, buf, lastbf, MAXBUF)
271:         status = addint(lastbf+2, buf, lastbf, MAXBUF)
273:         status = addint(lastbf+j+1, buf, lastbf, MAXBUF)
276:         status = addint(EOS, buf, lastbf, MAXBUF)
286:      status = addint(fdw, buf, lastbf, MAXBUF)
452:   dotext = addint(EOS, buf, lastbf, MAXBUF)
695:    if (addint(p(i), str, j, maxsiz) == NO)
713:    if (addint( s(i), str, j, maxsiz) == NO)

Some of the things they're adding to buf are clearly integers (nlines, and probably NOTSTATE and OKSTATE), but those EOS are the SWTOOLS VOS equivalent of the C '\0' that ends a string, so those particular ones definitely hold characters.

Well, if I want to debug that I'm going to have to rebuild the SWTOOLS VOS with debugging turned on. Investigating it turns out that I need to add /DEBUG to the macro and fortran commands in asmlib.com, asmprm.com, build.com, and compile.com in ~bin, and then execute ~bin:toolgen.com.

Once that is done I start stepping through various routines. Eventually I figure out that it buf(19) is the element that ends up with the 173 hex, and set a watch on it. And indeed it is getting passed a 173. Sigh.

Doing a SHOW STACK in the VMS Debugger shows that the addint() call that dies is in the subroutine compil(). Lets take a look:

DBG> type compil\50:65
module COMPIL
    50:       STATUS = ADDINT(LINE2, BUF, LASTBF, 20000)
    51:       COM = CLOWER(LIN(I))
    52:       IF (.NOT.(COM .EQ. 33))GOTO 23068
    53:       STATUS = ADDINT(1, BUF, LASTBF, 20000)
    54:       I = I+1
    55:       CALL SKIPBL(LIN, I)
    56:       COM = CLOWER(LIN(I))
    57:       GOTO 23069
    58: 23068 CONTINUE
    59:       STATUS = ADDINT(0, BUF, LASTBF, 20000)
    60: 23069 CONTINUE
    61:       STATUS = ADDINT(COM, BUF, LASTBF, 20000)
    62:       IF (.NOT.(COM .EQ. 97 .AND. FD .NE. 0))GOTO 23070
    63:       STATUS = ADDINT(0, BUF, LASTBF, 20000)
    64:       STATUS = DOTEXT(FD)
    65:       GOTO 23071
DBG>

Line 61 is the one that dies. Here addint() is being passed the variable COM. Lets take a look at the Ratfor source for its definition:

# compil - "compile" command in lin(i) from file fd, increment i
   subroutine compil(lin, fd)
   character lin(MAXLINE), com

Oh, look, com is a character, that gets translated by Ratfor to a LOGICAL*1, and it is a byte, while the integers that get passed in are longwords, which are 32 bytes long… Uh, doesn't Fortran pass everything by reference? So addint() gets passed the address of a byte, but interprets it as the address of a longword, so it picks up 3 extra bytes. For whatever reason, there is a 1 in the byte right next to the byte for com, so we get (hex, remember) 173 instead of 73, which is the ASCII for s, which the s in our sedit "s/H/J/"!

Ok, that should be easy to fix: introduce an integer temporary variable, assign com to it, and pass it instead.

Here's the VMS diff:

************
File DUA1:[SOFTWARE.SWTOOLS.TMP]SEDIT.R;6
  206      integer comint
  207      integer fd
******
File DUA1:[SOFTWARE.SWTOOLS.TMP]SEDIT.R;1
  206      integer fd
************
************
File DUA1:[SOFTWARE.SWTOOLS.TMP]SEDIT.R;6
  237      comint = com
  238      status = addint(comint, buf, lastbf, MAXBUF)
  239      if (com == APPENDCOM & fd != NO) {
******
File DUA1:[SOFTWARE.SWTOOLS.TMP]SEDIT.R;1
  236      status = addint(com, buf, lastbf, MAXBUF)
  237      if (com == APPENDCOM & fd != NO) {
************

Number of difference sections found: 2
Number of difference records found: 3

DIFFERENCES /IGNORE=()/MERGED=1/OUTPUT=DUA1:[SOFTWARE.SWTOOLS.TMP]SEDIT.DIFF;1-
    DUA1:[SOFTWARE.SWTOOLS.TMP]SEDIT.R;6-
    DUA1:[SOFTWARE.SWTOOLS.TMP]SEDIT.R;1

Recompile, lets see:

% echo Hello | sedit "s/H/J/"
Jello
%

That did it!

One of the things I've always found interesting about the LBL Software Tools VOS was how its source files were structured. I'll include here page 10 of the release notes from the release on the DECUS LT86 tape:

                            Release Notes


                        Source File Structure

The  source  code  for  `tool' is contained in a file [...SRC]tool.tcs
(if   the   tool   is   portable   across   operating   systems)    or
[...VMS]tool.tcs  (if  it  is  an VMS-specific tool).  This TCS source
file contains an edit history of all changes made to the source.   The
output  of  the  `get' utility operating on a `.tcs' file results in a
file (tool.w) which is all of the  environment  necessary  to  rebuild
the  tool,  provided  that the VOS is operational.  The tool.w file is
an archive containing:

  1. All of the files "included" by the ratfor source code.
  2. The ratfor source file, tool.r.
  3. The format input for the manual entry, tool.fmt.
  4. And optionally,  any  extra  definition  files  needed  to  build
     alternate versions of the tool (eg. sh => hsh).

As  an  example,  suppose  that  you  wish  to  change  the subroutine
"module" in "tool".  The suggested scenario is as follows:

   $ !Fetch the file tool.tcs from the appropriate directory in the container
   $ !file on tape into st_src
   $ hsh
   % get ~src/tool.tcs tool.w
   % ar xv tool.w
   % ar xv tool.r module
   % ed module
   (make changes and write file)
   % ar uv tool.r module
   % rc -v tool.r
   % (test out new tool.  repeat last three steps until satisfied.)
   % ed tool.fmt
   (modify writeup to reflect changes)
   % ar uv tool.w tool.r tool.fmt
   % cp tool.exe ~usr/tool.exe
   % delta tool.w ~src/tool.tcs
   (Identify in the comments the reason for the changes,
   and which modules changed.)
   % format tool.fmt >tool
   % ar uv ~man/s1 tool
   % asam <~man/s1 | sort >~man/i1

Placing tool.exe in ~usr  causes  the  shell  to  find  your  modified
version  of  "tool"  rather  than  the  distributed one.  The last two
commands  above  cause  the  manual  entry  for  `tool'  to  correctly
correspond to the utility itself.






                                 -10-

(It should be % get ~src/tool.tcs >tool.w with a “>” before tool.w in the above procedure. Otherwise the contents are echoed to the terminal instead of being written to tool.w.)

So, all the source files (source code and documentation) are stored in an archive file, which contains another archive file that has just the ratfor source, from which you extract the modules you want to work on, and at the end update the archives in the reverse order! This made organizing all the source much simpler, especially considering some of the porting targets for this software didn't have hierarchical directory structures, only flat directories. So when moving around parts of the system, like when you were preparing the distribution, you normally only dealt with the top level archives, the .TCS files, and only worked directly with the files that were contained within that archive and its child archives if you had to make a change to the source files. Very clever!

(Source 1)

(Source 2)

When I was in college in the 1980s the school I was at used Digital Equipment Corporation VAXes running VMS, and didn't have any Unix machines. I was quite interested in Unix and the Unix philosophy, but was frustrated by my lack of access to Unix machines. However, Brian W. Kernighan and P. J. Plauger wrote a couple of books about writing tools in the Unix style: Software Tools was in published in 1976 and used Fortran as its portable implementation language, while Software Tools in Pascal was published in 1981 and used Pascal.

Here is a quote repeated on each book's cover:

Good Programming is not learned from generalities, but by seeing how significant programs can be made clean, easy to read, easy to maintain and modify, human-engineered, efficient, and reliable, by the application of common sense and good programming practices. Careful study and imitation of good programs leads to better writing.

Both books worked through writing software tools that were simpler but still useful versions of many of the standard Unix tools.

I got Software Tools in Pascal because I knew Pascal better than Fortran and worked through implementing each of the programs on the college's VAX, which taught me a lot about programming and was significant influence on me. I later got Software Tools because I wanted to read the section on implementing the ratfor processor which that book used to add additional control structures unavailable in the Fortran of the day.

I was not the only person who was influenced by these books. Deborah K. Scherrer, Dennis E. Hall, and Joseph S. Sventek at Lawrence Berkeley National Laboratory with help from others greatly expanded the set of programs from the book into an entire Virtual Operating System (VOS), and founded the Software Tools Users Group in 1976 to distribute it, eventually leading to ports on over 50 operating systems.

Luckily for me VAX/VMS was one of those operating systems, and the port appeared on various tapes distributed by DECUS, the Digital Equipment Computer Users' Society. Luckily MPL Corporation, where I worked at the time, always got the DECUS tapes and had a Fortran compiler, so I could install it there. I found it a very useful and usable computing environment.

Anyway, I retain a fondness for that software, known variously as LBLTOOLS, LBL SWTOOLS, and SWTOOLS VOS, and have begun using the version from the DECUS VAX Languages & Tools SIG tape from 1986 again on the (emulated) VAX I maintain at work. This gave me the opportunity create a PDF with the documentation for that version, which I'm making available here for the curious.

“I really enjoyed that book. The first computer book I read where I thought my world was larger after reading it.” — C. Paul Bond

Last edited: 2024-10-21 15:59:04 EDT — Updated PDF with slight changes to structure and better bookmarks.

Fantastic Medieval Campaigns (FMC) by Marcia B. is a great retroclone and restatement of Original D&D: it's clearly written, well organized, contains a table of contents for the book and then a table of contents in each section, has a glossary and indices for monsters, spells, and tables, and uses the color backgrounds of the pages well to make finding the different sections easy. The art is charming and appropriate for a OD&D retroclone, and the layout is clean. It includes a retroclone of Chainmail, which is rare. I like it very much. And the PDF is free! I got the hardback color book and read it and want to run at least two campaigns with it, the first using its Chainmail retroclone, “Chain of Command”, and the next with the d20 based combat system.

But, but, but! The back cover text says “problematize our preconceptions of a text (or even a whole genre)” and mentions “falsehood”. And the contents of the last page of the text, which is labeled “This Page Intentionally Left Blank.”, are certainly not blank, and expresses opinions of D&D that must surely offend many D&D players. I'll quote it here:

Fantastic Medieval Campaigns is a recreation of what is at best a deeply reactionary work of art—if not a fascist one altogether. We recognize now that the authors, as well as some who were in their circle, thought quite badly of women, indigenous people, and others. However, we should let the text speak for itself because it speaks loudly. The book is a guide to fantastic war game campaigns, where the players take on the roles of sword-and-sorcery adventurers seeking greatness. They will begin in the Underworld simply slaying monsters and retrieving treasure in the form of gold, legal tender ready to be exchanged on the open market. As characters accumulate treasure, they acquire superhuman abilities and political power to boot. Heroes, Thaumaturgists, and Bishops emerge from their colonial katabasis conquering land by which to become Lords, Wizards, and Patriarchs. They will establish sanctuaries and, with their vast armies, turn the tide against the forces of evil chaos they have always ‘resisted' thus far. The setting in general is one where might makes right, where the violent extraction of resources is central to the protagonists activity, and where participation in these things is rewarded with not only political power bu the sort of physiological and supernatural power which colonizers and fascists imagined themselves to have. It is a mirror to the desires and fantasies of its original authors, a bunch of white, straight, cissexual men in the Midwest, just as it is a reflection of boys' pulp literature at the height of American culture about crushing one's enemies and driving them before oneself and hearing the lamentations of their women. All in all, this work was not written in a vacuum nor did it spring fully formed from the heads of its creators. You can use this book however you like or even attempt to play it with the mindset of a midcentury American man, but do not delude yourself with regards to its content or to the fantasy which it encodes. That being said, as the author, I offer up this work for analysis, critique, and reflection.

Well, that certainly put the coyote in the chicken house! It is definitely controversial in OSR circles. Honestly, though, I'm not sure that furor was worth following.

I just want to point out that, whatever the author's opinions of D&D, they wrote FMC so they could more easily understand the rules, so they could better play D&D with their friends, and according to a friend of theirs they spent over a year working on it.

Regardless of whether I agree with their views or not, FMC is a well written game and its author should be proud of it. It can be used to run some great games. If you don't agree with the author's views, just ignore them and play the game.

[I should have posted this a long time ago. Oh well. At least it's being posted now.]

Description of In the Labyrinth

In the Labyrinth (ITL) adds some elaborations to combat and magic, as well as all the things necessary to make The Fantasy Trip a complete roleplaying game. In particular, they add talents, non-magical abilities. Talents allow a character to try to do something, or makes something anybody can do easier. Talents are rated by the IQ necessary to learn them, and by how many points IQ points they cost to get at character creation. Talents cost twice as much (in IQ points at character creation and in XP after character creation) for wizards as they do regular “hero” characters. Regular heroes can learn spells, but they cost triple (in IQ points at character creation and in XP after character creation) what they cost wizards. ITL adds lots of spells, many of which have non-combat uses, as you'd expect from an RPG.

Finding out if your character succeeds is a matter of rolling dice equal to or lower than your stats. For easy things you roll 2 dice or even 1 die, normal things take 3 dice, while difficult things take 4, 5, even or more dice! Look at the chance to roll a 14 or less on 6d6! Yikes!

(See Retro-clone and Neo-clone for definitions.)

All of the retro-clones and neo-clones mentioned below are games with which I have some familiarity. Many of them I've played. The others I've read. All of them have something interesting to recommend them.

There was a time when Wizards of the Coast hadn't made old versions of D&D available easily, and the retro-clones were very important then. Even now some retro-clones or neo-clones have better presentation than the original rules (Old-School Essentials Classic Fantasy) or present a simpler version of classic rules (Labyrinth Lord: Revised Edition with Advanced Edition Companion for AD&D), or provide additional details and further development of a particular D&D version (Adventurer, Conqueror, King System).

And, of course, if you are playing with kids who might not have the money to buy PDFs of old versions of D&D, many of the retro-clones are available in PDF or online legally for free.