@device(imprint10) @make(report) @definefont(Userfont, 1=, 2=, 3=, 4=, 5=) @modify(CopyrightNotice, Fixed -1 inch, Flushright) @Style(Font computermodernroman11) @Style(spacing 1,indent 0) @Style(leftmargin 1.0inch) @Style(Linewidth 6.5inches) @modify(hd2, leftmargin -3, font userfont, facecode 4) @pagefooting(left = "Revision A: July 1, 1985", Right = "L. B. Merims") @blankspace(1.5 inch) @begin(flushright, font userfont, facecode 1) You Get...Software @end(flushright) @begin(flushright, font userfont, facecode 3) AT System 2.00 Release Notes @end(flushright) @blankspace(.75 inch) @begin(flushright, font userfont, facecode 4) L. B. Merims MIT Project Athena Revision A July 1, 1985 @end(flushright) @copyrightnotice(Massachusetts Institute of Technology) @newpage @begin(majorheading, font userfont, facecode 2, flushright) You Get . . . Software @end(majorheading) @begin(heading, font userfont, facecode 4, flushright) AT System Release 2.00 @end(heading) @section(Introduction) This document lists the software that comes with an AT workstation along with special notes about each program's use that are not covered in the standard documentation. It is intended for people who are developing software. You get three kinds of software with the AT workstation: the IBM DOS system; a number of applications packages and libraries (some from IBM, some from other companies); and a series of commands written here at Athena to make life on your AT more pleasant. For the DOS system and the applications software, you should consult the manuals listed below under each heading for details. The Athena written commands are documented in alphabetical one-page-per-command reference style in the back of the document. @section(Documentation) DOS documentation is divided into three sets: a @i(Standard) set that contains all the manuals for the standard software, a @i(Technical) set containing rarer technical reference manuals, and @i(Optional) manuals that come with optional software. All projects get some number of Standard sets based upon discussions with the project manager and our best estimate of your needs. Each project gets one Technical set. Optional manuals are distributed with optional software. Talk to your assigned Student Applications Programmer if you need additional sets. It is not possible to purchase most of these manuals; the manual came when Athena purchased a software license, one license per CPU. To replace a lost manual, we have to buy a new software license. The "cost" of a set of manuals thus runs into several thousand dollars. We are keeping inventory on manual allocations. Be careful with the manuals you have. Athena may not replace stolen or mislaid manuals. We will supply a limited number of locking manual racks to projects upon request. (You will have to get your manuals punched to fit the racks, however.) @section(System) @subsection(IBM PC-DOS Version 3.00) The system is pre-installed on the hard disk drive, drive C:. Athena has installed DOS in a Unix-like directory structure. See the @i(AT System Model) document in this set for details. All DOS commands work as documented in the @i(Disk Operating System Version 3.00) manual except: @begin(itemize) The ATTRIB command that sets file protection to "read only, no write," has been moved to the \etc directory to prevent its casual use. (We have changed most system files to "read only" so they don't get accidentally deleted.) To use ATTRIB, type: @example[\etc\attrib @i(options)] The FORMAT command has been changed so that you can only format the A: floppy disk drive. This is to prevent people from accidentally formatting the hard disk drive C: and destroying the system. The GRAPHICS command works, but it is not what we plan to use to produce graphical output. At the moment, there are no Athena-supplied hardcopy printers. (A shipment has just come in.) The printers will be attached to one of the XT's (or an AT, in a pinch) in your cluster. The question then becomes, do you have a network link to that XT? If you don't, you will have to get graphics hardcopy output by copying your graphic output to a floppy disk, carrying it to the XT, then running the Athena-supplied PRNTMETA command @i(on the XT). (See the Reference section of this document for a description of PRNTMETA.) If you do have a network link to the XT, then you will be able to print the file with the @i(lpr) command in a later system release. The PRINT command works, but we do not plan to use it to produce hardcopy text output. Again, at the moment there are no Athena-supplied hardcopy printers. When there are, you will print hardcopy output on either the local printer, or any printer in the network, using the Athena-written @i(lpr) command. See the Reference section of this document for details on the @i(lpr) command. @end(itemize) @paragraph(Documentation) @begin(description) @b(DOS Version 3.00 Manual)@\@multiple{Included in the standard documentation set. This is actually four documents: a @i(Quick Reference) card, an introductory @i(Users Guide), an @i(Applications Set-Up Guide) that you should ignore, and the DOS 3.0 @i(Reference) manual. The @i(Reference) manual contains system concepts, reference pages for all commands, error messages. It is reasonably simple and short for anyone who knows one operating system already. Do not miss the "DOS Editing Keys" section of the @i(Quick Reference) card. It shows how to do command editing not covered elsewhere. (For example, try the --> key after typing a command.) } @b(DOS Technical Reference Manual)@\In the Technical documentation set. Internal DOS operation. @end(description) @section(Editor) @subsection(Epsilon Emacs Version 2.03, Lugaru Software Ltd.) This is an "Emacs-like" full screen editor. "Emacs-like" means it uses various combinations of CTRL-c and ESC-c (or ALT-c) sequences as commands, like the many editors originally inspired by the MIT Project Mac Emacs editor. Epsilon is @i(very like) the CCA Emacs editor that runs on Athena Unix systems. Very like, though, is @p(not) the same. Although many of the key bindings are the same for most of the common functions, some common bindings are different. Moreover, there are some fundamental differences in behavior: @begin(itemize) Epsilon does not make a backup~ copy of the file you are editing. When you exit, Epsilon does not ask you if you want to save the file as CCA Emacs does. Instead, it asks you if you really want to exit. You are expected to have saved the file with the C-X C-S command explicitly before exiting. To exit Epsilon Emacs: @itemize[ Save the file with: C-X C-S Exit with: C-X C-Z ] Epsilon does not insert external files into the current buffer in the same way as CCA Emacs--it overwrites the current buffer. You can only insert external files by "staging" them through another buffer. This is a complicated process of juggling files and current buffers where it is easy to foul-up and overwrite the wrong thing. @end(itemize) These are the major differences with potentially serious consequences that we have uncovered so far. In the main, things work the same. Epsilon does have some major advantages over CCA Emacs. It is @i(much) faster, and it uses the PC's labeled function keys (such as PAGE DOWN) to good effect. You will have to be a little careful, though. Let us know if you find any other traps such as those listed above so that we may repair them or give fair warning. There are actually @p(two versions) of Epsilon Emacs on the ATs, invoked by two @p(different commands). They have somewhat different key bindings. @paragraph(epsilon command) The command: @format[ epsilon @i(filename) ] invokes an Epsilon that behaves exactly as documented in your @i(Epsilon Reference Manual). This is the safest--and recommended--way to use Epsilon Emacs. @paragraph(emacs command) A second version is invoked with the command: @format[ emacs @i(filename) ] This calls up an Epsilon whose key bindings are @i(the logical OR of a subset of the CCA Emacs and all of the Epsilon Emacs keybindings), in so far as it was possible. Now what does that mean? It means that we took the Athena @i(Emacs Quick Reference) card (for CCA bindings) and went through it, comparing each binding on the card to the Epsilon binding for the same function: @itemize{ If the bindings were the same (as most were, e.g., C-F for forward character) then we left them alone. If the bindings were different, then is the CCA binding already used by Epsilon for another purpose? @itemize{Yes. Then change the Epsilon key sequence to the CCA sequence and find a new binding for the Epsilon command. The only Epsilon bindings that had to be changed and no longer work as documented in the Epsilon manual are: @begin(VERBATIM, font smallbodyfont) C-C is now used as a prefix instead of as . is invoked with C-\. C-L now redisplays the window rather than centering the window around the cursor. Centering the window may be done with C-C C-L, or N5. A-@@ is now rather than . is done with C-@@. C-X C-D now performs rather than . is now done by C-X K. C-X 2 still splits the screen into two windows, but a new buffer is opened in the second window, like in CCA EMACS. @end(verbatim) No. Leave the Epsilon binding as is, and just add a CCA binding so that now two bindings execute the same command. } Where there are Epsilon bindings with no CCA conflict, e.g., the PgDn key, they are left in effect. } Many CCA Emacs commands (there are over 400 of them) are not on the @i(Emacs Quick Reference) card and hence were not examined or adjusted for consistency. This is why if you type the C-X C-C binding in Epsilon, you will exit; but if you type C-X C-C on Unix under CCA Emacs, you will capitalize everything in your current buffer. Also, there was nothing we could do when there were incoherencies in function as well as key binding. C-C C-C, the CCA Emacs exit command, always asks you if you want to save the file. Epsilon @i(has no equivalent function). (Epsilon's macro facility is too limited to allow construction of an equivalent command.) If you type C-C C-C to exit you will only be asked if you want to leave. You must save the file explicitly first with C-X C-S. All this makes using the Emacs command to run Epsilon sound like driving in Boston. It isn't really that bad. In the main, things work well. You can easily work for a long time and not notice any difference except for the most obvious such as the exit function. It is interesting how difficult it is to be absolutely loyal to coherence. We would be interested in your feedback as to whether "close" is good enough, or a complete miss. @paragraph(Documentation) @begin(description) @b(Epsilon Reference Manual)@\In all documentation sets. @b(CCA Emacs Compatibility Bindings Wall Chart) @\This is tucked into your @i(Epsilon) manual. It shows all bindings for the "or'd" set you get with the @i(emacs) command. @end(description) @subsection(EDLIN) This is a line editor that comes with DOS 3.0. It is @i(not supported) by Project Athena. You can use it if you like, but you should not code anything that depends upon it or require students to learn it. It is documented in chapter 8 of the DOS 3.0 manual. @section(Text Formatters/Word Processors) There are no text formatters such as Scribe on the AT workstations. You can satisfy the major text formatting needs by using a combination of Epsilon Emacs text formatting commands to fill, justify, and center text, and the Athena-written @i(pr) command to divide the text into pages with numbers and optional headers. @i(pr) is modeled after the Unix @i(pr) command. @paragraph(Documentation) @begin(description) @b(Section 6.13, Epsilon Reference Manual)@\In all documentation sets. Describes Epsilon's text formatting commands. @b(pr page)@\In the Reference section of this writeup. @end(description) @section(Languages) @subsection (C: Lattice C Version 2.1) Lattice C is an implementation of the standard C language as defined in Kernighan and Ritchie's @i(The C Programming Language), with extensions. It is a two-pass compiler, supported by its own math library (file \lib\lcm) and a library of utility functions (file \lib\lc). You must explicitly link to the mathematics library if you make any even vaguely mathematical code (such as declaring something to be float or double). (The Lattice C math library takes advantage of the math coprocessor hardware in your AT workstation). Also, always put the math library first in any link list of libraries. It must come before the regular lc library. Lattice C can also call the GKS graphics library. It cannot call the NAG library. The Athena @i(DOS Portability Guide) included in this packet discusses how you should use Lattice C in order to make your programs portable back to the Unix environment. To make using C on the AT workstation more like using C under Unix, Athena has written a @i(cc) command that compiles and links in one operations in a style as close as possible to the way the Unix @i(cc) command works. It has similar options. See the entry for @i(cc) in the Reference section of this writeup for more information. When the @i(cc) command cannot do what you want, you will have to revert to the "native" @i(lc1) (pass one), @i(lc2) (pass two), and DOS @i(link) commands described in the @i(Lattice C) and @i(DOS 3.0) manuals, respectively. @b(NOTE:) Currently (June 13, 1985, system release 2.00) you cannot use the @i(cc) command if your program links to GKS. We plan to fix this shortly. Ask your assigned Student Applications Programmer for updates. @paragraph(Documentation) @begin(description) @b(Lattice C Compiler)@\In all documentation sets. Describes the implementation, the libraries, the compilation and runtime system, error messages, and the system library implementation. Ignore the "Getting Started" section; it is irrelevant for Athena. @b(cc page)@\In the Reference section of this writeup. @b(DOS Portability Guide)@\Describes what to look out for if you want your code to be portable to Unix. In this Athena packet. @end(description) @subsection[Fortran: IBM Professional Fortran (Ryan-McFarland) Version 1.00] Professional Fortran is an Ansi Fortran 77 compiler with extensions. It can call both the NAG library of mathematical routines, and the GKS graphics library, if you explicitly link to these libraries. Its own libraries are kept in the files \lib\profort, \lib\profdbg, and \usr\lib\profort.err. The compiler takes advantage of the math coprocessor in the AT workstation. Professional Fortran comes with its own source code level debugger. Professional Fortran can generate compiler listings. To make using Fortran on the AT workstation more like using Fortran under Unix, Athena has written an @i(f77) command that compiles and links in one operation in a style as close as possible to the way the Unix @i(f77) command works. It has similar options, plus a few extra (such as a switch to produce various compiler listing information). See the entry for @i(f77) in the Reference section of this writeup for more information. When the @i(f77) command cannot do what you want--perhaps it does not have an option that the @i(profort) command has--you will have to use the "native" @i(profort) and DOS @i(link) commands described in the @i(Professional Fortran Installation and Use) manual, and the @i(DOS 3.0) manuals. The Athena @i(DOS Portability Guide) included in this packets discusses how you should use Professional Fortran in order to make your programs most portable back to the Unix environment. @paragraph(Documentation) @begin(description) @b(Professional Fortran Installation and Use)@\Included in all documentation sets. How to compile, link, run and debug Professional Fortran (although you might prefer the @i(f77) command for the first two of these functions). Error messages, arithemetic considerations, extensions, and a section on portability and conversion. Ignore the "Quick Start" chapter on installation; it is irrelevant. @b(Professional Fortran Reference)@\Included in all documentation sets. The reference manual for the language and its functions. @b(f77 page)@\In the Reference section of this writeup. @b(DOS Portability Guide)@\In this packet. How to write Professional Fortran code that will convert back to Unix @i(f77) code. @end(description) @subsection(Pascal: IBM Pascal Version 2.00) IBM Pascal is a standard Pascal compiler, as defined in the Jensen and Wirth book @i(Pascal Users Manual and Report, Second Edition), with numerous enhancements. Non-standard behavior is noted in the documentation. IBM Pascal is a three-pass compiler. Note that it is a compiler, not an interpreter. Although Pascal does have its own libraries (\lib\8087only.lib, \lib\ieeemath.lib, \lib\regmath.lib, \lib\pascal.lib, etc.) it cannot call either the NAG library or the GKS graphics library. To make using Pascal on the AT more like using the Pascal compiler under Unix, Athena has written a @i(pc) command that compiles and links in one step in a style as similar as possible to the way the Unix @i(pc) command works. See the entry for @i(pc) in the Reference section of this writeup for more information. If the @i(pc) command cannot do what you want to do, you may have to use the "native" Pascal compile commands, @i(pas1, pas2, pas3) (for the three compile passes), and the DOS @i(link) command. We have not yet studied the problem of writing compatible Unix and DOS Pascal code. @paragraph(Documentation) @begin(description) @b(Pascal Compiler, Volume 1)@\In all documentation sets. Compiling, linking, and running Pascal programs. Data types, constants, variables, expressions and statements, procedures and functions, and appendicies on advanced file topics, runtime structure, the library manager, numeric precision, and pascal limits. Ignore the chapter on installation; it is irrelevant except for background information. @b(Pascal Compiler, Volume 2)@\In all documentation sets. Pascal language reference manual. @b(pc page)@\In the Reference section of this writeup. @end(description) @subsection(Lisp) The AT workstation does not come with a Lisp compiler or interpreter. Talk to your assigned Student Applications Programmer if you think you may need a Lisp. @subsection(Assembler) The IBM Macro Assembler is an optional software product. It is not included in the standard AT workstation system. Because assembly language programming is not portable to other systems, we discourage its use in any but the most critical circumstances. Talk to your assigned Student Applications Programmer if you think you need this product. @section(Debuggers) There are two kinds of debuggers: @p(source code) debuggers, and @p(object code) debuggers. Both are used to do runtime debugging of programs. An object code debugger will tell you that your program has died at a particular hexidecimal address and offset, what the error code was, and what the value of the system registers were at the time of the fault. The debugger gives you tools to examine a system dump to determine the problem. A source code debugger will tell you that your program has died at a particular line number in the source code, what the error code was, and you can use the debugger to examine the contents of program variables, by name. Both will let you step through a program and trace its history: one will step through machine instructions, the other through source program statements. People prefer using source code debuggers in most cases. Your AT comes with @i(four) debuggers. Two are part of the standard system, two are optional. @subsection(DEBUG DOS Version 3.00) This is an object code debugger that comes with the DOS 3.00 system. It is documented in Chapter 10 of the @i(DOS 3.00) manual. We don't recommend its use in view of the better alternatives. @subsection(Professional Fortran Interactive Symbolic Debug) This is a source code debugger that comes with the IBM Professional Fortran compiler. It is documented in Chapter 3 of the @i(Professional Fortran Installation and Use) manual. To use the debugger, you must compile your program with the @i(-g) option with the @i(f77) command, or the @i(/T) option on the @i(profort) command. This debugger only works with Fortran. @subsection(Atron Software Source Probe, Version 1.10) This is a nice source code debugger than works with C, Pascal, and the non-standard Macro Assembler. We have not tested it to see that it works with Professional Fortran. @b(It is an optional software product.) To acquire it, contact your assigned Student Applications Programmer. We recommend that most development projects acquire this tool. Compiling with the @i(cc) and @i(pc) commands' respective debugging options should be adequate to setup for the @i(swsource) command. The Software Source Probe is documented in the Atron @i(Software Source Probe) manual. If you acquire the product, you will also get the manual. @subsection(IBM Professional Debug Facility, Version 1.00) This is an object code debugger. It is superior to the DEBUG facility that comes with DOS for Macro Assembly language debugging. @b(It is an optional software product.) Contact your assigned Student Applications Programmer if you want this product. The debugger comes with a hardware interrupt button circuit card that will have to be inserted into your PC. The debugger is documented in the @i(IBM Profesion Debug Facility) manual. If you acquire this product, you will also get the manual. @section(Development Tools) @subsection(Make: Lattice "Make" Utility, Version 2.10) The @i(make) utility is recognized as one of the Unix system's best ideas. "Real" application programs are usually a congregation of files; a main file, many subroutine files, perhaps some C data definition header files, plus several libraries. To make the application, all these pieces are compiled and linked together. Any one of the files will be modified many times as the application is developed. It becomes quite a bookkeeping chore to remember which files have to be recompiled and relinked when other files that they depend upon change. The @i(make) utility lets you create a file that is a script of DOS commands to compile and link a whole application. You can specify dependencies so that no more is remade than needs to be. When you change something, you need only type the make command and the application will be recreated in its updated form. The Lattice @i(lmk) utility implements the Unix @i(make) idea under DOS. There are some differences in approach made necessary by the differences between the two systems, but you can certainly use your @i(lmk) make files as models for your later Unix @i(make) files. Lattice @i(lmk) is part of the standard software distribution. @paragraph(Documentation) @begin(description) @b(Lattice LMK Functional Description Manual)@\This is part of the standard documentation set. It is one of two manuals contained in the dark blue binder incorrectly labeled "Lattice C Compiler." (The other is the @i(curses) manual.) The manual is organized as a tutorial, with a brief reference manual at the back. @end(description) @subsection(Lattice Text Management Utilities, Version 1.00) @b(This is optional software.) It is not part of the standard Athena AT workstation software distribution. The Lattice company has created DOS versions of some of the most popular Unix text manipulation utilities: grep (which looks for text strings in files), diff (which compares the contents of files, looking for differences), wc (which counts the words or lines in a file), ed (a line editor), extract (which removes lines from files), and build (which takes extracted lines and puts them in new files). These utilities are permanent fixtures in any Unix programmer's bag of tricks. It is said that the original Unix spelling checker program @i(spell) was nothing more than these utilities artfully joined together with Unix pipes. Since DOS supports pipes, too, the utilities are equally useful on the AT workstation. Talk to your assigned Student Applications Programmer if you are interested in acquiring the Text Management Utilities. @paragraph(Documentation) @begin(description) @b(Text Management Utilities)@\Optional document that comes with the optional software. Four manuals combined in one packet that describe grep, diff and wc, ed, and extract and build. @end(description) @section(Graphics Libraries: IBM GKS Graphical Kernel System, Version 1.00) GKS is a library of graphics subroutines that supports interactive, color, two-dimensional vector graphics. The International Standards Organization (ISO) has adopted GKS as its standard graphics interface. Athena has selected GKS as its standard graphics system. (We are studying several VAX/Unix GKS implementations.) GKS is implemented as a two sets of equivalent language "bindings," that is, one set of routines to call from Fortran, and one set to call from C. You cannot call GKS from Pascal. As you read through the @i(GKS Programmer's Guide) Introduction and Chapter 1, you will have some questions about which pieces of GKS we have, and how we've configured it on your AT: @begin(itemize) We have the VDI. We have a limited number of Graphics Development Toolkits. It is not part of the standard distribution. (The main use for the Toolkit is to develop device drivers.) Talk to your Student Application Programmer if you are interested in this package. We have GKS. This is what we are distributing as part of the standard software on the AT. (The BASIC language bindings will not be distributed.) We do not have the Plotting System Library. It is not available. We have only a few experimental copies of the Graphical File System. It is not generally available. We do not have the Terminal Emulator. It is not available. @end(itemize) @subsection(Installation Details) @begin(itemize) GKS is already installed on your system. Your AUTOEXEC.BAT and CONFIG.SYS files have been modified for GKS. INIT_VDI.EXE is in \etc\init_vdi.exe. You have a working version of the linker. VDI.SYS, and the VDIDY004.SYS, VDIDY006.SYS, VDIPRGRA.SYS, VDIDYPGD.SYS, and VDIMTFIL.SYS device drivers that come with your AT are in \dev. All of the sample and demonstration programs, including the binary for ROOMDEMO, are in \usr\src\gks. All of the libraries for GKS and Professional Fortran and Lattice C bindings are in \lib. The CONFIG.SYS file is setup for graphics as follows: @begin(format,leftmargin +0, font smallbodyfont) DISPLAY=\DEV\VDIDY006.SYS /G:CRT (PC 640x200 two-color high-res) DISPLAY=\DEV\VDIDY004.SYS /G:CRT (PC 320x200 four-color med-res) DISPLAY=\DEV\VDIDYPGD.SYS /G:CRT (The PGA, variable DISPLAY) DISPLAY=\DEV\VDIMTFIL.SYS /G:FILE (The metafile, variable METAFIL) DISPLAY=\DEV\VDIPRGRA.SYS /G:PRINT (The printer, variable PRINTER) @end(format) Any logical name not shown above (DISPLAY, METAFIL, PRINTER) is unset. GKS keeps track of these logical names in an internal table. They can be overridden if you explicitly set them as DOS environment variables with the SET command. Again, you do not have to install or initialize the system, it is already done. @end(itemize) There are some details about the way you must link to the GKS library from Professional Fortran and Lattice C that are not covered in the manuals. @paragraph[Professional Fortran] @begin(itemize) You can compile and link Fortran programs that call GKS in one step with the Athena-supplied @i(f77) command. You would use this order for the elements: @begin(format, leftmargin +0) f77 @i(options) pfgks.obj @i(yourprogram) -lpfgks -lgks @end(format) The \lib\pfgks.obj is an object file that must be linked with your program. The "-lpfgks -lgks" links first the Professional Fortran-specific version of the GKS library, then the main GKS library. If you have other libraries, they should go before the GKS libraries. (@i(f77) links to profort.lib automatically.) According to page 11 of the @i(GKS Language Bindings, Volume 3 (Fortran)) book, it appears that you cannot use the Professional Fortran source code debugger if you are also calling GKS. We @i(think) this is what it says. We will investigate this. If you find out first, tell us. @end(itemize) @paragraph{Lattice C} @begin(itemize) You can @i(not) currently use the Athena-supplied @i(cc) command to compile and link your C programs that call GKS. The reason is that the @i(cc) command as currently constructed allows variable names to be up to 32 characters in length, following the Unix model. GKS, however, was compiled with the variable-name length option set to a limit of 8 characters. We will do two things to fix this in a later bug-fix release. 1) For the near-term we will create an include file that you will have to put in any source program that calls GKS that will allow the longer variable names. 2) We will contact the GKS people and try to get them to send us a new version that was compiled with long variable names turned on. You must use the "native" @i(lc) or @I(lc1) and @i(lc2) commands to compile, and the DOS @i(link) command to link your programs as follows: @begin(format, leftmargin +0) lc1 @i(sourcefile).c -ml -s -b lc2 @i(sourcefile).q link \lib\c @i(objectfiles, outfile),, \lib\cgks \lib\lcm \lib\lc \lib\gks @end(format) The documentaion that describes linking with GKS (pp. 8-9 of the @i[GKS Language Bindings, Volume 2]) contains some errors. The correct form of the @i(link) command is shown above. First, the @i(order) of the libraries is important: first the cgks library, then the C math library (this may not be required, but most common math operations and floating point variables require explicit linking to the math library), then the standard C library, then the main gks library. If you have libraries of your own, put them before these libraries. Second, the correct name of the C object module is c.obj, not lc.obj as the manual shows. @end(itemize) @subsection(Documentation) @begin(description) @b(Graphical Kernal System Programmer's Guide)@\In all documentation sets. How to run the demonstration program. GKS concepts and routines. How to design an application. Appendices describing Error Codes, Device Drivers, and GKS Data Structures. @b(GKS Language Bindings Volume 2: C)@\In all documentation sets. Details of C use. Reference manual of C routines. @b(GKS Language Bindings Volume 1: Fortran)@\In all documentation sets. Details of Fortran use. Reference manual of Fortran routines. @b(Device-Independent Graphics, with Examples from IBM Personal Computers)@\by Robert F. Sproul, W.R. Sutherland, Michael K. Ullner, McGraw-Hill 1985, $35, ISBN 0-07-060504. We've been told that it is difficult to figure out how to program graphics under GKS using just the above-listed manuals. This book is a "how to do graphics programming, using the GKS standard, with specific examples in Fortran and C on the IBM Personal Computer with GKS and the Professional Graphics Adapter"--in short, just exactly what you would want and exactly what we have. Athena has a few of these books on hand. We will loan @i(one) to each AT project using GKS upon request to your assigned Student Applications Programmer. @end(description) @section(Math Library: NAG PC50 Library, Release 1) The NAG Fortran PC50 Library is a collection of 50 Fortran subroutines and functions that solve some of the commonest problems that occur in numerical computation. It is a subset of the complete NAG library of over 400 routines that runs on Athena Unix systems. You can call NAG routines from Professional Fortran only; you cannot call them from C or Pascal. Included are routines for such things as zeros of polynomials, roots of equations, summing series, quadrature, solving differential equations, minimizing and maximizing functions, matrix opertions, eigenvalues, etc. To link to the NAG library using the Athena-supplied @i(f77) command: @begin(format, leftmargin +0) f77 @i(options) @i(yourprogram) -lnag @end(format) The NAG library is in the file \lib\nag.lib. @subsection(Documentation) @begin(Description) @b(The NAG Fortran PC50 Library)@\In all documentation sets. Introductory discussion, then detailed descriptions of each routine, including examples, grouped by function. @end(description) @section(Window Screen Management: Lattice Curses Library, Version 1.01) Operating system user interfaces tend to look like the kind of computer terminal that was in predominant use at the time the system was originally conceived. The first herd of interactive timesharing systems all presumed a hardcopy teletype terminal, running fairly slowly. This is the classic "dumb ascii" terminal. Their user interfaces tend to be line-at-a-time @i(command) oriented systems. Unix falls into this category. (So, too, does DOS, but for different reasons.) Later on, it became pretty safe to assume that the user was on a CRT display of some intelligence, running at 1200 baud or better. User interfaces came to take-on a full-screen, menu-oriented character. The programmer could also put dot-and-dash pictures up on the screen, make separate text regions, and let the user move around the screen with the cursor arrow keys. From this comes screen editors, menu-driven programs like the Unix @i(ispell) program, and games like @i(rogue). The problem is that each make of terminal has different escape codes to control it. If you wanted one program to run on n-different terminals (as it would have to in the Athena environment), you would have to code n-different versions of your program. The Berkeley Unix people came up with the @i(curses) library to help solve this problem. Curses is a set of library calls that control screen terminal I/O. Curses itself will reference a database of terminal capabilities to interpret how to perform a particular logical act (like "move cursor") on a particular physical terminal. One screen-oriented program will work on any terminal in the curses database. More to the point, a screen-oriented program that you write on your AT workstation under Lattice @i(curses) should port easily to Berkeley Unix @i(curses).@foot[A "third generation" would be the high-resolution, high-speed, bit-mapped terminal such as the MacIntosh, the PGA, or the VAXstation-100. One of Athena's main software development projects is to develop higher-level tools to program these devices.] You can call @i(curses) from Lattice C only, not from Fortran or Pascal. Include a @i(-lcurses) option on your @i(cc) command, or add the word @i(curses) to your DOS LINK command. Curses is kept in \lib\curses. @subsection(Documentation) @begin(description) @b(Lattice Curses Screen Management Library, Curses Reference Guide, Revision 1.0)@\In all documentation sets. It is in the dark blue "Lattice C" binder with the make utility documentation. @end(description) @section(Spreadsheet: Access Technology 20/20, Version 1.00) A spreadsheet system lets you create two-dimensional tables of data. Any one of the cells can be a function of the other cells. The functions supplied range from simple things like addition and multiplication through linear regression analysis. You can create dependencies among the cells so that if one--say your January income--changes, all dependent cells--taxes, net total, gross total--change too. 2020 can create the usual pie, bar, and x-y graphs from the data tables. 2020 is Athena's standard spreadsheet system. However, a 2020 "model" (data file) created under DOS is not compatible with the 2020 model file format used on Unix. You cannot ship model files between the two systems. @b(Note:) There is a bug that causes one option of the 20/20 tutorial program to fail. This will be fixed in a bug-fix release. @subsection(Documentation) @begin(description) @b(2020 Users Manual), @b(Essential 2020)@\Only a few distributed, most not available yet. Will be in all standard documentation sets. At the printers, estimate July 8 availability. @end(description) @section[Communications: MIT-LCS PC/Internet Protocol (PC/IP)] Most Athena workstations will eventually be connected to some network. There are two scenarios: @begin(enumerate) All AT's in a cluster are first connected together with a local ethernet cable. There are only AT's on the local cable. This local cable is eventually gatewayed onto the main MIT campus spine network, giving the AT's access to the other Athena machinees, including the Unix hosts and their facilities. The AT's in a cluster are connected to a local ethernet cable that is already part of the main MIT campus spine network. @end(enumerate) You should know which case you are because how much you can do with remote login, mail, printing, and other network services depends upon which machines you can get to. All network protocol handling will be done with the Personal Computer/Internet Protocol (PC/IP) package developed at MIT's Lab for Computer Science. PC/IP is a collection of programs that makes your AT into a host on the national Internet, of which MIT is a part. There are fourteen PC/IP commands. We will discuss only three of them here. @subsection(Bug) The \dev\netdev.sys file describes the AT host to the network. All the \dev\netdev.sys files in Athena AT system release 2.00 @b(are wrong). They will not work properly. (Two people trying to @i(telnet) will hang because all the AT's think they're the same network address.) When the AT is put on the network, call the Athena Service Hotline at 3-1410 to arrange to have the \dev\netdev.sys file configured properly. @subsection(Remote Login and Mail: telnet) The @i(telnet) command lets you login to another host on your local subnetwork. You will not be able to "login" to other AT's. The local subnetwork is the physical cable connecting the local network, exclusive of gateways. To know who is on your local subnet and who isn't you should ask your Student Applications Programmer, since this is not intuitive. We are looking for a way to be able to remove the local subnet restriction and let you login to any other machine on the campus network for which you have an account, but this will come later. The AT workstations will never be mail hosts themselves. To send and receive mail, you will have to have an account on one of the Athena Unix machines, login to that machine with the @i(telnet) command, and use the Unix system and its @i(mh) mail system to do your correspondence. Your AT will act as an intelligent terminal. You will have to manually set your terminal type when you @i(telnet) into an Athena Unix host as follows: @format{ setenv TERM h19pc unsetenv TERMCAP } The capitalization (or lack of it) is important. If you don't set your terminal type, screen programs such as emacs will not work correctly. The @i(telnet) command is described in the @i(PC/IP User's Guide) described below. @subsection(File Transfer: tftp) @i(Tftp) (trivial file transfer protocol) will transfer files between any two hosts on the network. It is @i(not) restricted to the local subnet the way that @i(telnet) is. You can use it to transfer files between AT's, and between an Athena Unix host and the AT. There are a lot of ins and outs about how this works: @begin(itemize) First, are you on a network at all? Is there a cord coming out of the back of your AT and disappearing off somewhere? (If you are not connected to the network, the usual response to any PC/IP network command is "Name servers not responding." This could mean other things, though, such as the network being temporarily down.) Is your network only a local AT network? Or does it have contact with Unix machines? (Try using the @i(telnet) program to login to your Athena Unix account.) Has the \dev\netdev.sys file that identifies the host to the network been set up properly? Call 3-1410 to arrange to have this customized properly. @multiple{ You must know the network address of any AT involved in a file transfer. Network addresses can be in several forms: an octal form where the elements of the address are separated with commas that looks like 22,107,0,52; a decimal form with the elements separated by dots such as 18.77.0.110, and as a regular network name like athena, hera, nessus, et al. Eventually, all AT's will be labeled. Until then, to find out an AT's network address: @begin(itemize) If you can use the telnet command to a remote host, you can find out that AT's DECIMAL and OCTAL addresses with F10 I. You can get an AT to tell you its OCTAL address, without the need to login and reference anything else, with the \etc\custom command as follows. @begin(enumerate) Type:@example[ \etc\custom \dev\netdev] You will see a menu of options. Type @b(s) for "set". You will see a screen-full of options. At the very top of the screen in the left corner will be a caption "My network address." Below that you will see a number like 22,107,0,52. This number is the @i(octal) representation of that AT's network address. @b(DO NOT CHANGE THIS NUMBER.) Write it down, including all the commas. Exit with ESC. Exit the entire program with @b(q). Be careful not to change anything. @end(enumerate) @end(itemize) There is no way to get at AT to tell you its network address in the DECIMAL or NAME form--the two forms that always work. } @end(itemize) @subsection(Unix to AT File Transfer) To transfer files between an Athena Unix machine and an AT workstation, you have two choices: @begin(enumerate) @begin(multiple) The best way is to get onto the AT you want to transfer files to/from amd login to the Unix system you want to exchange files with using the @i(telnet) command. Once logged in, use the @i(tftp) command to effect the transfer. The general form of the @i(tftp) command for Ascii files is: @example{ tftp put @i(localfile) @i(foreign-host) @i(foreignfile) get } Be sure to enclose any DOS file specifications in single quotes, e.g., '\usr\tmp\myfile'. The \ character is significant to the Unix shell and the shell will eat it up unless you enclose it in quotes. It is also best to give a full path specification because the transfer will go to whatever the AT's current directory is otherwise. The foreign-host name must be given as a decimal address or a simple name. The octal address will not work. The AT will give a little "whoop" and ask you if it's OK to do the transfer. Reply @b(F10 y) for yes, or @b(F10 n) for no. Logout from Unix when you're done. @end(multiple) You can be on any Unix system through any kind of terminal and transfer to a particular AT, @i(but)-- @begin(enumerate) If the other AT is logged in through PC/IP @i(telnet), whatever user is on that machine (assuming it's even turned on) will be asked whether he/she wants to accept the requested transfer. If the other AT is not logged in through @i(telnet), the request will time out unless a user on the AT has first enabled the AT to receive unsolicited network @i(tftp) file transfer requests by typing @i(tftp server) on the AT. (That user, for the sake of his/her files' integrity, must also turn off @i(tftp server) by exiting or typing @b(-) or the AT will be available for network file raiding.) @end(enumerate) @end(enumerate) @subsection(AT to AT File Transfer) To transfer files between AT's, you must know the network address of the machine on the other end. (See the explanation of how to find this out above.) That other machine must also have first been placed in "receive mode" by the person on the other end typing @i(tftp serve). (Otherwise your transfer will just time out.) Use the local @i(tftp) command to do the transfer. For more information, see the discussions on the @i(tftp) command in the @i(PC/IP User's Guide.) @subsection(Network Administration: The @i(custom) Command) The PC/IP @i(custom) command is used to see and set the values in the \dev\netdev.sys file that describes your AT workstation to the network (such as its network address). The @i(custom) command has been moved to \etc to prevent its casual use. The \dev\netdev.sys file that comes with the AT 2.00 system release is wrong and will not work properly. Project Athena will set all AT workstation netdev.sys files correctly when we hook your system to the network. @b(Do Not Do This Yourself) unless you are the site administrator for your cluster, understand full-well what you are doing, and are working in concert with Athena operations. It is very easy to get the netdev.sys file wrong and have your AT drop off the network. Contact Athena operations (3-1410) if you think you are having network configuration difficulties. @subsection(Documentation) @begin(description) @b(PC/IP User's Guide)@\In all documentation sets. This document is not proprietary and can be copied at will. The document is really addressed to the programmer who must install and maintain PC/IP. The parts of most interest are the discussions of the @i(telnet) and @i(tftp) commands. @end(description) @section(Reference) The following pages show, in alphabetical order, the commands that were written at Athena to supplement the DOS environment. Some of these commands were written to deliberately emulate the behavior of Unix commands. These are documented in Unix "man page" format. The others are documented in @i(DOS Reference Manual) style. @newpage @subsection(ATHENA) @subsection(CC) @subsection(F77) @subsection(LPR) @subsection(PC) @subsection(PRNTMETA) @subsection(SAFE)