Unix 128 v3.00 Notes 12 March 1991 Page 1 Contents: I. Building the Unix 128 System...................1 II. Distribution and Rights........................1 III. Introduction to the Unix 128 System............2 IV. Introduction to ftp............................3 V. Introduction to the nroff Package..............5 VI. Introduction to the as Assembler...............7 VII. Introduction to the emacs Text Editor..........9 VIII. Introduction to Telecommunications With tip....11 I. Building the Unix 128 System. 1. System requirements: a Commodore 128 computer, a 1571 disk drive, and an 80-column RGB monitor. 2. Most people will fetch this system via anonymous ftp to the Milton ftp site. If this is the case, you must get the two .lnx files (unix128v3a.lnx and unix128v3b.lnx), and download them in binary mode (as well as the lynx.c128 de-archiver, also found at Milton.) Save these files on one double-sided disk, and unarchive them. 3. It is necessary to write all the other necessary system files to disk by typing RUN "MAKE" from BASIC. This writes 8 SEQ files (.login äsystem init fileå, author äabout meå, nroff.hlp äa help file for nroff, accessable from emacs by typing ESC-x nroffå, nroff.tbl äthe printer table for nroffå, passwd äthe system password fileå, stdlib.i äassembler macroså, polish.ef and cyrillic.ef äpolish and russian fonts for emacs- ESC-X FONTå) to the disk. The last system file that needs to be written is the disk directory. To write this, you need to log in (if it asks you for a username/password use root/root.) and type % fsck. This does a filesystem consistency check and writes the filesystem to the disk. That's all there is to it... II. Distribution and Rights. 1. This set of programs is distributed without warranty or guarantee of any kind (in other words, if it transforms your 128 into a thermonuclear device and vaporizes your neighborhood upon execution, it's not my fault.) 2. This program set may be freely redistributed as long as it's intact with all documentation and code (excluding the sources, which no one needs). I wish for my name to stay with the package, and I retain all copyrights and patents to all the source code that I wrote. Don't even think of copying any of this stuff under your own name (or even worse- selling it...). The built-in wrongdoing-detection circuits will take control of the nearest Electric Knife and kill you. 3. Bug reports, gripes, $10 if you like this program may be sent to: Gregg Riedel 20 Ellbert Street Smithtown, NY 11787 (it's my home address, but it's a little more stable than my college address.) I will probably graduate SUNY-Binghamton around Spring '93 - I should retain my Consultant account until then: consp24 ` bingvaxu.cc.binghamton.edu Unix 128 v3.00 Notes 12 March 1991 Page 2 III. Introduction to the Unix 128 System: Unix 128 is not "real Unix" by definition. A "real Unix" system: 1. is multiprocessing- it can do more than one task "at the same time." This feature could be emulated (partially) in software on the 128, but it would be so slow and limited that it would cripple the system. 2. has true pipelining- input and output can be freely redirected. Unix 128 does not have true pipelining. However, you can freely redirect just about any output to a file or the printer (by ending a command line with lpr or >filename). I'll probably reserve true input redirection for a later release. 3. has a true heirarchial filesystem- Implementing a true heirarchial filesystem in which Unix controlled all aspects of disk i/o would mean not having compatibility with CBM DOS disks, which I wanted to retain. Functions Compatible with "Real" Unix: In addition to being a useful tool for development and for learning to move through a Unix environment, Unix 128 has some features useful for interaction with Unix mainframes: 1. tip: The tip modem package will interface through a modem to most remote "real Unix" systems. It provides (almost) VT-100 compatibility, VT-52 compatibility, and a raw mode for communication with other Commodore systems. 2. tar: tar is the tape archive that "real Unix" systems use to combine multiple files into one file to place on a backup tape. Unix 128's tar will both create and dissolve these tar files in a format compatible with "real Unix." Note: if you dissolve a tar created on "real Unix" that contains text files, these files will be in ASCII format, not PETSCII format (tHE cASES aRE rEVERSED). You can invoke 'dd' with the -s option to fix this problem (in English, type 'dd -s oldfile newfile') 3. uuencode/uudecode: This is a coder/decoder package that makes "real Unix" binaries into text files for mailing. The Unix 128 versions of these two programs should be compatible with "real Unix", with the exception of the ASCII/PETSCII problem mentioned above. 4. nroff: nroff will accept documents formatted for nroff or troff without the special macros for tables and equations ("standard" nroff). This is quite helpful when you'd like to edit a paper on a unix mainframe, but continue editing and print or preview the paper at home under Unix 128. Unix 128 v3.00 Notes 12 March 1991 Page 3 IV. Introduction to ftp ftp, the file transfer program, is a combination of a unique file transfer protocol and a set of terminal instructions designed to transmit and recieve files and other data between two Unix 128 sites. It is not compatible with the Internet ftp used between BSD, DEC, SUN and other large-scale Unix systems. It is not used for remote login to any system- use 'tip' for logins. The ftp command invokes one of two modes. The first mode (remote terminal mode) is used to originate a modem communications link to another Unix 128 system. The second mode (server mode) is used to answer incoming calls and act as a fileserver. To invoke remote terminal mode, type % ftp or % ftp phone-number. If a phone number is given, ftp will automatically dial that number and attempt to connect to another Unix 128 system (the system you dial must already be running in ftp server mode.) To invoke server mode, type % ftp -s. ftp will wait for the phone to ring, answer it, and begin the session. --- Remote Terminal Commands --- The following commands are available at the ftp> prompt: ? Get help (list the command summary) ascii Save incoming files as SEQ, don't convert PETSCII<->ASCII binary Save incoming files as PRG, don't convert PETSCII<->ASCII bye Hang up the phone, quit ftp and return to Unix 128 cd ädirå Change directory to ädirå close Hang up the phone but do not exit ftp. convert Binary conversion of PRG files to SEQ files. dir Read current remote directory get äfileå Get a file from the remote system. Select ascii, text, or binary first to assure the proper file type and conversion. hash Show a hash mark (#) for every 512 bytes transferred. This command toggles hash mark printing on and off. open änumberå Dial a phone numbr and attempt to connect to a remote system. send äfileå Send a file to the remote system. text Save incoming files as SEQ files, convert PETSCII<->ASCII (There is almost no need for this command. When in doubt, use ascii and convert later with 'dd -s') --- Server Commands --- The server allows 1 input: CTRL-C to break if someone is NOT connected. File transfers and directory requests are automatic. Important: the server doesn't know what type of file isn't incoming, so it saves everything as un-translated program (PRG) files. If you need to do a translation later, use the 'convert' command from the ftp> prompt. Unix 128 v3.00 Notes 12 March 1991 Page 4 --- The ftp Protocol --- ftp uses a special X-Modem derived protocol for file transfers. First, a request goes from the remote terminal to the server telling it to either send or receive a file. The file is sent in 128 byte blocks in the following format: ä 127 bytes of data å ä control byte å The control byte is one of three values. If it is 0, another block is coming. If it is Control-Y or Control-Z, then this is the last block and the last byte of valid data is the one that is not equal to the control byte (If the last valid byte is not Control-Z then the control byte will be Control-Z. If the last valid byte is Control-Z, Control-Y will be the control byte.) All data connections are done with 8 data bits, no parity, 1 stop bit, at 1200 baud. Unix 128 v3.00 Notes 12 March 1991 Page 5 V. Introduction to the nroff Package. nroff is a text formatting package that is "mostly" compatible with plain nroff and troff source files (no macros are included with this release for table (tbl) or equation (eqn) processing). nroff is not a "word processor" or "editor", but a pass-thru text formatter. You must enter text on any editor or word processor (emacs is fine) and then type % nroff -p file to print it or % nroff -v file to preview it. nroff provides the powerful features associated with many word processors. A short list of features includes: - n-line spacing (single space, double space ...) - line justification - centering - right alignment - multiple columns (1, 2, or 3 columns) - printer-dependent function macros for underline, reverse, italics, bold, super- and subscript and custom graphics - 3-part headers (left, center, and right aligned) - full control of page offset, line length, and page length --- Command Line Options --- nroff may be invoked with several command-line options in the format: % nroff (options) filename The options are: -i Interactive formatting setup first. -v Video preview only -p Print document only -S Use my own symbol table instead of 'nroff.tbl.' Example: -Smytable A command line might look like: % nroff -i -Smytable -p thisfile. The nroff command takes a single document filename. --- Formatting Commands --- All formatting commands must begin with a period (.) that is at the far left (first column) of the source document. The following list can be viewed from within emacs by typing ESC-X NROFF. The formatting commands are as follows: .bn N Bold the next N input lines.* .bp (N) Forced end-of-page (if N is given, it is the next page number.) .br Break (exit this file). .ce N Center the next N input lines. .cl N Break text into N (=1,2,3) columns .cs N Put N spaces between columns, if appropriate .de öxx yy Define macro öxx as the string yy. .dr Use draft mode.* .ec C Set the escape character to C (default=ö). .eo Ignore escape codes. .ex Exit this file. .fc Tell nroff to begin a new page to force changes made to be interpreted (column changes, header changes etc...) .ft fontname Use font 'fontname'. This is understood but ignored. .il N Italicize the next N input lines.* .in N Indent paragraphs N spaces (default=5). Unix 128 v3.00 Notes 12 March 1991 Page 6 .ll N Set line length to N characters. .lm N Set left margin to N characters (default=0). .ls N Set line spacing to N (1=single space, 2=double space etc.) .lt N Title is N characters long. .ne N Need N vertical spaces (i.e. skip N lines). .ni No indent .nq Use near-letter-quality mode.* .nx filename Load next file 'filename'. .pl N Set page length to N (paper is usually 66 lines, default=60). .pn N Next page is number N. .po N Set page offset to N (same as left margin). .ps N Pitch size in c.p.i. (Usually 10 or 12).* .ra N Right-align the next N input lines. .rm N Set right margin to N characters (default=79). .rv N Reverse (white-on-black) the next N input lines.* .ta N A tab is the tab character repeated N times (default=8). .tc C Tab character is C (default=" "). .tl 'l'c'r' Three part title (l=left, c=center, r=right). .ul N Underline the next N input lines.* * Requires a printer-dependent setting in 'nroff.tbl' --- Default Macros (nroff.tbl) --- öbs backslash ösu superscript on öca carat ösb subscript on öcb close curly brace ös0 super/subscript off öob open curly brace ödg degree symbol öpi pipe symbol (vertical bar) öin integral symbol ötl tilde ösg capital sigma ödt capital delta ösq square root symbol ög ä7 integers (0-255)åö custom graphics Unix 128 v3.00 Notes 12 March 1991 Page 7 VI. Introduction to the as Assembler Development Package as is the Unix 128 8510 assembler. It takes a single source file, processes the Unix 128 extensions, writes an object file (*.o) that contains only valid 8510 assembler opcodes / operands, then converts the object files and writes the binary machine language file 'a.out.' The first two bytes of 'a.out' contain the start address of the code (where it is loaded) and the rest of the file contains the single-byte opcodes and the bytes of data needed. The extensions to standard assembler are as follows: 1. The first line of any assembler source code must be the word 'start' followed by either a decimal number or a '$' and a hexidecimal number. This is the start address of the code which is written directly to 'a.out.' If a 'start' line is not found, an error will occur. 2. One or more lines may be given that begin with the word 'include' and a source filename that contains valid macro definitions (see 4). The purpose of this statement is similar to the C #include : to include macros of standard code. An include file, 'stdlib.i', is given with this package as an example. Example: include stdlib.i 3. A data section may be given, so that you may label common constants. A data section consists of the word 'data' on its own line, followed by one or more data lines, and followed by the word 'endd' (end-data) on its own line. A data line consists of a data label, the word 'equ', and a decimal value or a hexidecimal value preceeded by a '$' Example: data zero equ $00 two equ 2 endd Wherever the names 'zero' or 'two' are encountered, they are replaced with the appropriate data value. 4. Macros are units of code that are given a name. They are defined once, and expanded wherever the macro name is found. A macro definition begins with the word 'macro', a single space, and the macro name. One or more lines of valid 8510 source code are given on separate lines, and the word 'endm' (end-macro) is given to conclude the macro definition. Example: macro foo (start a macro named foo) lda #$00 endm (end of this macro) Whenever the name 'foo' is encountered in the source code, it is replaced with the line 'lda #$00'. Macros cannot be given parameters. Standard macros are usually used for system calls such as setting fast mode or clearing the screen. 5. Comments can be given on separate lines by beginning that line with a semicolon (;). Example: ;This is a comment Unix 128 v3.00 Notes 12 March 1991 Page 8 6. Any line may be given a name by which it can be referred. This removes the tedium of keeping track of addresses for jumps and branches. The name must be followed immediately by a colon (:). Example: line: ldx #zero sta $0400,x jmp line **WARNING** Be very careful not to use valid operand names for line labels, data labels or macro names. The preparser will replace all occurences of label names with the appropriate data. (For example, if you label a line with jsr:, every time you used jsr in your program it will be replaced by the address of the line to which the line label refers!) --- Command Line Options --- as can be invoked with several different options from the Unix 128 command line: % as -h :Prints a help screen. % as -d beg end :Disassembles memory from beg to end % as -v beg end :Views memory from beg to end % as filename :Parses 'filename' --> 'filename.o' --compiles--> 'a.out' --- Valid 8510 Mnemonics (op-codes) --- adc and asl bcc bcs beq bit bmi bne bpl brk bvc bvs clc cld cli clv cmp cpx cpy dec dex dey eor inc inx iny jmp jsr lda ldx ldy lsr nop ora pha php pla plp rol ror rti rts sbc sec sed sei sta stx sty tax tay tsx txa txs tya --- Valid Keywords --- start macro endm data endd include equ General Notes: 1. Use all lower case for keywords and op-codes, and use a single space between op-codes and operands. 2. There is a limit of 1500 lines of source code (255 characters per line) 3. There is a limit of 75 macros of 50 lines (255 char/line) each. 4. There is a limit of 100 unique line labels. 5. There is a limit of 100 data items in the data section. Unix 128 v3.00 Notes 12 March 1991 Page 9 VII. Introduction to the emacs Text Editor. Emacs is a powerful text editor for use under Unix 128. It is not a document formatter or 'word processor'- the most advanced text previewing feature is word-wrap. Text should be passed to nroff for formatting (line spacing, columns, justification etc.) Emacs allows up to 700 lines of text (of 80 characters / line). It loads and saves SEQ type files that are compatible with most other word processors. Emacs also features DiskEd, to enter CBM-DOS commands. It has help screens for itself as well as a command reference for writing nroff source files. It has multiple text editing features like setting and copying regions, 'killing' and 'yanking' lines of text, commands to move to the start and end of lines, up and down by screens, and commands to move to the start and end of text. Files can be inserted into the text. There is font support, and 2 partial fonts (one for special Polish characters and one for the Russian (cyrillic) alphabet) are included. --- Regions --- A region is defined as all the text in between the 'mark' and the current cursor position. A mark is set by typing (Commodore) (SPACE). Once a region is defined, you can: CONTROL-c : copy region as kill. This allows you to copy the region into the kill buffer to be copied back into the text with CONTROL-y (yank). Rot-13 region : Perform the rot-13 transformation on the region (which maps each letter 13 positions away; a-->m, b-->n, m-->a etc) --- Expanded Command Reference --- (C-key - Control+key E-key - Hit ESC then key) C-a Move the cursor to the beginning of the current line. C-b Move the cursor back one character (same as 'cursor left') C-c Copy the currently marked region into memory, to be retrieved with C-y (yank line) C-d Enter DiskEd, which allows CBM DOS commands to be executed. C-e Move the cursor to the end of the current line. C-f Move the cursor forward one character (='cursor right') C-g Quit prompt (general abort for commands) C-h Get Help!!! C-k Delete line from cursor to end of line, copying the line to memory. C-l Redraw the screen. C-n Move the cursor to the next line (='cursor down') C-p Move the cursor to the previous line (='cursor up') C-r Rot-13 a previously marked region C-v Move down by a full screen C-w Write this file as... C-y Yank a line from memory to the current cursor position. C-x c Clear text memory. C-x e Copy the keyboard macro defined with C-( and C-) C-x f Find phrase (maybe). C-x i Insert a file at the current cursor position. C-x p Print the contents of memory. C-x s Save file with current filename. C-x v View document with word-wrap. C-x C-c Quit to Unix 128. C-x C-f Load a file into memory, erasing current memory contents. Unix 128 v3.00 Notes 12 March 1991 Page 10 C-x ( Write keyboard macro C-x ) End keyboard macro C-x = Cursor information (what line, character etc) C-x + Insert a line at the cursor. E-< Move the cursor to the beginning of the file. E-> Move the cursor to the end of the file. E-v Move up by 1 full screen. E-x ? Show bound commands (nroff help, fonts etc.) Of course, the abbreviated command reference may be viewed at any time by typing C-h, without disturbing your document. Unix 128 v3.00 Notes 12 March 1991 Page 11 VIII. The tip Telecommunications Program. Tip is used to connect to mainframes or other Unix 128 systems using the telephone lines. It can use a wide variety of protocol and terminal settings and will be compatible with most systems. All of the features of tip can be accessed through the menu screen. To bring up the menu, press the ALT key on the upper left of the keyboard. This brings up the following menu items (use the cursor keys/äRETURNå to select): Baud Rate: the speed of communication (300 and 1200 are most common) Data Bits: 7 or 8 data bits are supported Parity: even, odd, space, mark or no parity are supported Stop Bits: 1 or 2 stop bits are allowed Duplex: full(no local echo) or half(local echo) duplex Terminal Type: -VT100: use VT100 emulation. This is not perfect emulation, but will provide most of the VT100 command set. If you're looking for 100% VT100/102 compatibility, get DesTerm 2.00 -VT52: use VT52 emulation. -Commodore: also called 'raw' mode, this doesn't interpret any of the control codes encountered. This is useful when talking to other Commodore systems. Dial: Enter a phone number and tip will dial it and attempt to connect to the host computer. One of the following codes will be returned: CONNECT = connected at 300 baud CONNECT 1200 = connected at 1200 baud BUSY = the host is busy VOICE = a human being answered the phone. Hang Up: Hang up the phone. Clear Display: This just clears the screen. Buffer: -Capture On: This will copy everything that comes across the screen (except menus etc.) to memory -Capture Off: This turns off the copy-to-memory feature. -Clear Buffer: Erase all buffer memory. -Save Buffer: Save the contents of the buffer in a disk file. -Print Buffer: Print the contents of the buffer on the printer. -View Buffer: Type the contents of the buffer on the screen (use the NO SCROLL key to pause / resume.) ASCII Upload: Enter a filename and tip will just type the file to the modem. To receive the file on a mainframe, you must first type: VAX/VMS: $ create filename (when done, type CTRL-Z) Unix: % cat > filename (when done, type CTRL-D) Quit to Unix: Returns to the Unix 128 shell prompt (%). You can leave tip without hanging up, do other work, and return to tip safely. Remember to hang up the phone when you're finished. (Terminal Mode): Return to terminal mode.