KLH UUO package documentation This file attempts to describe the features currently available with KSC;NUUOS > and how to use them intelligently. There are several main sections which can be selected, and each is documented in a separate page. This is a list of all the various programs which make use of KLH's UUOs or MACROS; the idea is to facilitate upgrades by being able to determine how heavily used a certain feature is, or what programs would need modifications if something in the package were changed. Note that use of UUOs automatically implies use of MACROS. Use UUOS: (currently MC:KSC;NUOS >) MC: KSC;COMSAT > ; ITS Mailer satellite MC: KSC;QMAIL > ; ITS Mail user interface MC: KSC;FTPS > ; ITS FTP server MC: KSC;FTPU > ; ITS FTP user interface MC: KLH;NCR > ; Statistics cruncher MC: KLH;80TRAN > ; cross loader/dumper MC: KLH;PARJCL > ; JCL parsing package MC: KLH;.TIMER > ; ITS/TNX Execution timing package [SRI-KL]VOID ; 20X database hacker Use MACROS: (currently MC:KSC;MACROS >) MC: SYSENG;CRTSTY > ; ITS CRT support package Bare Bones - UUO dispatcher and UUO definitions The UUO dispatcher and UUO definition macros alone are available in a "bare bones" configuration. This may be useful for quick hacks which need such code, but normally of course other features are selected. The idea here is to explain how UUOs are defined, so that once the package is .INSRT'd, the user can define additional idiosyncratic UUOs most efficiently. The UUO opcode range is from 0-77 octal; there are also a few random opcodes outside this range for which no hardware function exists, which trap as UUOs. The opcodes from 1 to 37 inclusive are fastest as they trap directly to locations 40-41 in the user's address space; those from 40-47 are ITS system calls, and those from 50-77 also trap to ITS, but the system simulates the action of 1-37 for these, incurring so much overhead that it is generally faster to use subroutine calls instead. Because sometimes one might want to define more than 31. UUOs, the trick of decoding certain UUO's by their AC or E field is allowed for. In general, if a UUO doesn't need one of these fields, it should be defined using one of the alternate macros below in preference to the standard UUODEF. This will help avoid a shortage of opcodes. UUODEF ,
This is the standard way to define a full-fledged UUO which needs both its AC and effective address fields. UUODFE ,
This defines a UUO which needs only its effective address field, and ignores the AC field. Currently this becomes a flavor of the U.CALL UUO; is defined as U.CALL , where is a unique number from 0-17 assigned by the macro. UUODFA ,
This defines a UUO which needs only its AC field. These are thus distinguished by their effective address, and the number of such UUOs is effectively infinite. is defined to be U.OPER where is a unique number from 0-UOPMAX. (UOPMAX is currently 20.) UUODFN ,
These UUOs require neither their AC nor E fields and this macro is actually the same as UUODFA. Byte Pointer UUOs These UUOs are primarily for use with 7-bit (ASCII) byte pointers, but DECBPT is completely general. Because of their utility and small size, the routines are always included unless only the "bare bones" package is being assembled. MD7BPT AC, This is actually a macro which decrements a 7-bit byte pointer in AC. Only 2 of its 3 instructions are normally executed, and this is recommended if the BP is already in an AC. The comma following AC is necessary. Don't try to skip over this, use a jump instead. D7BPT [byte ptr] Decrements the 7-bit byte ptr at E. This is mainly useful for convenience/compactness; MD7BPT is faster. DECBPT [byte ptr] General-purpose byte ptr decrement. Works for ANY size byte. Of course, if only 7-bit pointers are used, (M)D7BPT is recommended instead. PTSKIP AC,[byte ptr] Skips (adjusts) 7-bit byte ptr at E by # of chars specified in AC. Works for both positive and negative skip values; this is a general form of the preceding pointer decrement UUO's. PTRDIF AC,[byte ptr] Pointer difference. Takes two 7-bit byte ptrs, one from E and the other from AC, and returns in AC the difference in char positions (E ptr)-(AC ptr). Can return positive or negative values. Using indexing or indirection in the byte pointers will win! SPECIAL FEATURE: If the LH is completely zero, 440700 (beginning of word) is assumed. Output UUOs and macros These UUO's are probably the most versatile and heavily used of the entire package. It is very easy to direct output of various forms to a variety of destinations, and the FWRITE macro provides a very compact way of using the UUOs. The general form of these UUO's is: OUTUUO , where is the number of a "UUO channel" and is the argument to be output, in some form. is also known as a "soft" channel, as opposed to a "hard" channel which has actually been OPEN'd as an ITS I/O channel; the distinction is important, because it is possible to use the same channel number simultaneously as separate hard and soft channels. Soft channels come in several flavors, only one of which is identical to its hard counterpart. These flavors are selected by "opening" the channel: OUTOPN CH,[,,] Set up a UUO channel for output. Note that , which selects the desired flavor, is actually a value in the AC field of the word, allowing to be formed with indexing and indirection. As a special case, OUTOPN CH, is the same as OUTOPN CH,[$UCIOT,,]. Types of UUO channels: OUTOPN CH,[$UCIOT,,] This is the only type which corresponds to a "hard" channel. Output uses .IOT and SIOT on the "hard" channel of the same number. This does NOT perform an actual .OPEN of the channel, which must be done elsewhere by the user. OUTOPN CH,[$UCBPT,,[byte ptr]] Output on this channel will perform IDPB's starting with the given byte pointer, which need not be 7-bit. OUTOPN CH,[$UCXCT,,[instr]] Output on this channel will perform an XCT of the given instruction, once per byte; the byte will be furnished in acc U1. OUTOPN CH,[$UCUAR,,] Output on this channel will deposit 7-bit characters into the specified "UUO area", with the feature that this area will be automatically expanded to as large a size as necessary to hold the output; it will never overflow, hence this is ideal for buffers. OUTOPN CH,[SETZ $UCUAR,,] is similar but the area is cleared and reset. See the section on "UUO areas" for more detailed information. OUTOPN CH,[$UCTRN,,[channel #]] Translates into another UUO channel. Any output on this type of channel will act just as if output was being done on the specified . Linked translates will work (A to B to C) but things are not apt to win if the "target" channel is changed out from under by OUTOPN'ing it. -------------------------------------------------------------------- OUTPTV CH, Read pointer value of channel. Returns to the count of chars that have been output on the channel since it was opened. For channels opened into an area, this is the # of chars between start of area and current Write BP. For translated channels, the count is that of the target channel. Actual Ouput UUOs Here are listed the UUOs which actually perform output on a UUO channel. The descriptions, though short, should be clear enough. OUTI CH, Output Immediate. The effective address E itself is the byte to be output. OUTZ CH, Output ASCIZ string. E points to the beginning of an ASCIZ string. OUTC CH,[#,,] Output ASCNT string. c(E) holds the address of an ASCII string in RH, with char count in LH. OUTPC CH,[#,,[byte ptr]] Output Pointer Count string. c(E) LH has byte count, RH is address of a byte pointer, which may use any size byte. OUTPZ CH,[byte ptr] Output Pointer Zero-end string. c(E) holds a byte pointer, also using any size byte, to a string terminated by a null byte. OUT6W CH, Output 6bit Word. Takes c(E) as 6 sixbit characters and outputs as 6 ASCII chars. OUT6F CH, Output 6bit Filename. Like OUT6W but won't output trailing blanks; if the word is 0, nothing is output. OUT6Q CH, Output 6bit Quoted filename. Like OUT6F but inserts a ^Q before all punctuation chars. OUT10. CH, Output Decimal with point. Outputs c(E) as a signed decimal value, with point. OUN10 is an obsolete synonym. OUT10 CH, Output Decimal Like OUT10. but without trailing point. OUN9 is an obsolete synonym. OUT8 CH, Output Octal Outputs c(E) as a signed octal value. OUTRH CH, Output Right Half Outputs RH of c(E) as 6 octal digits. CRLF CH, Output CRLF Outputs a CR and LF. OUTFLT CH, Output Floating value. Outputs c(E) as a signed, floating decimal value. There are currently no formatting options available, but the output generally looks reasonable. Algorithm was taken directly from MACLISP. Individualized output UUOs It isn't hard to take advantage of the output-UUO structuring to define your own output UUOs, or develop "hi-speed" subroutines. The basic macro to use is: STDOUT Standard Output macro. Byte to output must be in acc U1, and channel number to output on must be in U2. This macro takes up 3 instructions, so don't try skipping over it. Don't depend on its length being constant either. It's a good idea to begin all output UUO's with: UIOINIT UUO I/O Initialization macro Currently all this does is load the AC field of the UUO into acc U2. Possibly this could someday change. For better efficiency, any time a byte count is available, the following sequence should be used instead of many STDOUT's: ; U2 - channel number ; U3 - byte pointer to read from ; U4 - byte count JUMPG U4,@USCOPT(U2) ; Jump to output and return. JRST UUORET This procedure is particularly effective for hard channels, because SIOT can then be used; however, it is always more efficient for strings of 4 or more bytes. Use of FWRITE macro Most output sequences are done by means of the FWRITE macro. The easiest way to explain it is to demonstrate it: FWRITE CH,[[This is example ],N10,EXNUM,[ of file ],6F,FN1,[.]] This particular invocation results in OUTC CH,[ASCNT [This is example ]] OUN10 CH,EXNUM OUTC CH,[ASCNT [ of file ]] OUT6F CH,FN1 OUTC CH,[ASCNT [.]] More generally, one thinks of it as FWRITE ,[,,...]. Each may be either a literal string of text, as in "[ of file ]", or a , pair such as "N10,EXNUM". Literal strings are simply output using OUTC, as above, and paired items use the to determine how the is to be output. In this case, N10 means to output the decimal value of the argument. must be no more than 3 chars long, and the must be either a value or an address of some kind; indexing and indirection will work fine. A list of all currently defined s follows the definition of FWRITE in KSC;MACROS >. The hack which makes this thing work is the concatenation of with "%%." to produce a macro name such as "%%.N10" which is given the channel and as macro args, and which is responsible for producing the right code. Thus, it is easy to define one's own FWRITE item types simply by defining a macro of the form DEFINE %%. C,ARG ... assemble code to output ARG on channel C ... TERMIN UUO-Area UUOs - Storage Management Read the file KSC;?AREAS >. ; UAROPN AC,[,, ? [,,]] ; Creates an area, using ARPT-indicated ; ARBLK for storage of area variables. contains the ; minimum initial allocation desired, the desired increment ; modulus when expanding ($ADFIM used if =0), and the ; are exactly those defined for $ARTYP. If the given ARPT is ; zero, or E of the call itself is zero, then a unique ARBLK ; will be created dynamically. If AC is specified, the ARPT ; will be returned in it; it is an error to request ARBLK creation ; and not specify an AC! ; --> NOTE: ARPT is accessed indirectly, and the type bits do not ; infringe on the I or @ fields, so all addressing modes work. ; UARCLS Close area, free up its core. ; UARTYP [type,,] Changes area to specified type, and ; tries to be clever about converting from wds to chars... ; (Flushes ^C's, ^L's and ^@'s from last word in that case) ; Only bits specified in UXFGTB can be changed with this UUO. ; UAREXP AC, Expands indicated area according to ; contents of AC - if c(AC) positive, adds c(AC) words; if ; negative, deletes -c(AC) words. Both operations apply to high end. ; OUTAR CH, Outputs char-mode area on CH. ; These UUOs implement a PDL mechanism for areas. UXPDLP ; points to a list of blocks, each of which is $ARSIZ+1 words long. ; The first word is a pointer to the next block and the remaining ; words store the ARBLK for some area. When UXPDLP is 0, the ; PDL is empty; else it points to the first ARBLK on the stack. ; UARPUSH - Push the given ARBLK words on the stack, and "close" ; the actual ARBLK it was copied from. ; UARPOP - Pop UUO area from stack into specified ARBLK. ; If any active area existed in the ARBLK, it is closed!! ; UARFLS - Flushes the UUO area stack. Closes all areas found on it! Low level storage management - CORSER If you are interested in calling the dynamic storage allocation primitives directly, there are 4 available routines which are completely supported by the CORSER package. These are rarely necessary owing to the ease of manipulating UUO areas, but are documented here for reference. The internal block structure and algorithm details are well described in the source file, KSC;CORSER >. MOVE U1,[-<# pages>,,<1st page #>] PUSHJ P,CORINI Core Management Initialization. This routine must be called before any of the others, but note that the UARINIT UUO does this as part of its setup. Given a "page AOBJN" in ac U1 to the area of memory it is to manage, important variables are initialized and the entire area is freed. (thus this can be used to reset all storage whenever necessary). MOVE U1,[<# words desired>] PUSHJ P,CORGET Core Getter - Get block. This routine returns in U2 the address of a block of core that will contain at least the requested number of words. The actual length will be returned in U1. Be sure to keep track of the block, and call CORREL when you are through with it; otherwise core pollution will eventually build up to toxic levels. MOVE U1,[<# more words desired>] MOVE U2,[
] PUSHJ P,COREXP Core Expansion - Expand block. This routine will expand the specified block by at least the requested number of words. The new total length will be returned in U1, and the new block address in U2. Note that the block may or may not have been shifted in core. In either case, all data in the block will be preserved exactly; the effect is simply that of adding more room at the end. MOVE U1,[
] PUSHJ P,CORREL Core Release - Free up block. The indicated block will be freed, and data in it will no longer be accessible. In fact, attempting to do so might result in a MPV, since CORREL actually frees pages when possible. ------- Other: There are a number of tuning variables which can give the user a fair chance at optimizing the core allocation algorithms, but they aren't documented here; nor are the metering assembly conditionals which can provide feedback on the success of this tuning. (You see, they never got written.) The current defaults appear to work quite well, however. String UUOs ; Strings are represented by a 2 descriptor words in the following ;SAIL-type format: ; : ,,<# chars> ; (ILDB gets 1st char) ; For constant strings, whose descriptors can be stored anywhere, ; should be 0. Variable string descriptors are stored in a table ;beginning at STRNGS and containing NSTRS string variables. ;The macro STRNAM creates an entry in this area at assemble ;time with the label , and will be some unique index ;when the string is not null. Initializing the string hackery with ;a STRINIT UUO has the side effect of setting all variable strings null. ;(NOTE: References to a variable string should be by address of its descriptors, i.e. ; its name, since it is possible for the byte pointer to change ; unexpectedly due to expansion or shifting of the core area containing ; the strings, as well as to GC'ing of the stringspace!!) ;BCONC is used to begin forming a string; output operations on ;channel STRC will then be accumulated into a string which is ;formally stored by ECONC. ; The string variable table must be declared, anytime after ; all STRNAM's have been processed, as ; STRNGS: SBLOCK ; ; NSTRS==<.-STRNGS>/2 STRINIT ; Initializes string stuff ; BCONC starts composing new string, beginning with given one ; (if E zero, null string used.) ; ECONC makes describe the string concatenated thus far MAKSTR, CONC macros. List UUOs see KSC;?LISTS > Miscellaneous ECALL - but don't use. Display UUOs? (DUUOS >)