Copyright Xerox Corporation 1979Inter-Office MemorandumToCommunication ProtocolsDateJuly 1, 1978FromEd TaftLocationPalo AltoSubjectThe Pup Network Directory andOrganizationPARC/CSLthe PUPNM JSYSXEROX Filed on: [Maxc1]PupDirectory.bravoThis is a revision of a memo of the same title dated June 27, 1975. Only minor changes have beenmade. The principal motivation for this revision is to re-issue the memo in Bravo and Press formats.In a separate memo, Naming and Addressing Conventions for Pup, we proposed the establishment ofa network directory associating names and addresses of entities such as networks, hosts, and processesat Parc. This memo documents the format of the directory that has been implemented, theprocedures for maintaining it, and a Tenex JSYS called PUPNM for performing name/addressconversions using it.The design that has evolved has benefitted from contributions by Bob Metcalfe, Dave Boggs, andPeter Deutsch.Contents of the Network DirectoryEach entry in the directory consists of a list of names, a list of addresses, and a list of attributes.A name is a string consisting of alphanumerics plus the characters '-' and '/' (others may beadmitted by popular demand). Both upper and lower case alphabetics may be used; two namesdiffering only in the case of their letters are considered identical. If more than one name appears inan entry's name list, all the names are synonyms and may be used interchangeably.An address is a triple consisting of a network number, a host number, and a socket number, asdefined in the Pup specifications. In the case that all three of these numbers are nonzero, theaddress completely specifies a Pup port. However, if one or more of the numbers is zero (i.e.unspecified), the address represents a subset of all possible ports.The classes of addresses that we expect to find useful in practice are the following:1.Network addresses, in which only the network number is specified.2.Host addresses, in which the network and host numbers are specified.3.Port addresses, in which all three numbers are specified.4.Well-known sockets, addresses in which only the socket number is specified.The addresses in a directory entry's address list describe alternative ways of accessing the entityassociated with the entry (or multiple, identical instances of that entity). Accordingly, we requireЪН &ОpТXН]Оg~qТiНІОcrН]pТXН-єrН7BpНІО\ rН]pН-єrН7BpНІОVrН]pН-єrН7BpН]ОT НЭОO─spНЇОI⌠П(НыОCиТ▄Т█ПOНыОBDТ─ПLТ│НыО?_Т▀Т▄tП)pП"НыО=зТ┌tpТ┐ПAНыОНыО ТцП#tpТдП"НыО┤ТПDНыО╒ПUНоОҐНёПAНоОьНёПDНоОСНёП9НоОНёПKНыО )ТаПKТбНыОєТ╛ТґПV 8Эс>/d The Pup Network Directory and the PUPNM JSYS2that all addresses in an address list have corresponding patterns of specified and unspecifiedelements.An attribute is merely a pair consisting of an attribute name and an attribute value. The attributename is composed according to the same rules as the names in a directory entry's name list, whilethe attribute value may be an arbitrary string.In addition to the attribute list associated with an entire directory entry, individual addresses in theentry's address list may have attribute lists associated with them.Structure of the Network DirectoryThe network directory is currently maintained on Maxc1 as the highest-numbered version of the filePup-Network.Directory. It is distributed automatically by the PUPSRV program to allother Name Lookup servers, using the Pup Network Directory Update protocol, described in aseparate memo.The file is constructed in a manner intended to facilitate interpretation by Altos and Novas. It iswritten in 16-bit bytes (packed in the standard PDP-10 format, i.e. two bytes left-justified in each36-bit word). All pointers in this file are 16 bits wide and refer to 16-bit bytes relative to the start ofthe file. All strings are BCPL-style, i.e. an 8-bit byte count followed by that number of 8-bit bytes.As a concession to Maxc, all blocks and tables start at Maxc word boundaries, i.e. pointers to themare always even. Unused bytes are always zero.We now present the format of the various blocks and tables in the directory, in the order in whichthey actually appear in the file. The individual items in these objects are 16-bit bytes except wherenoted.Header Block0Number of name blocks1Pointer to name lookup table2Number of address blocks3Pointer to address lookup table4Number of words occupied by entry blocks5Pointer to first entry block6Version number of this fileName Lookup Table(Ordered by name using the ASCII collating sequence, except that lower-case letters collatewith the corresponding capital letters)Pointer to name blockPointer to name block ...Pointer to name blockAddress Lookup Table(Ordered by value of network, host, and socket numbers)Pointer to address blockPointer to address block ...ЪНЇОfПpТП,НGОНыОbТЛТМПVНыО`≥НыО]ЄТ°tpТ²ПUНыО\/Т°П,Т²П5НыОZ╙ТП/НыОWеТ∙П,Т√П<НыОV@ТПCНыОQЁuП"НыОNнpТ┴П6Т┼П,НыОMIТиП%ТйП7НыОKдТкПZНыОJ?Т НыОGZТёП/ТєП5НыОEуТ╗ПdНыОDPТ│tpПAТ┌НыОBкТ▌Т▐tpПQНыОAFТ√tptpП-Т≈НыО?аТП/НыО<эТ■П3Т∙П/НыО;WТ▐П!Т░ПEНыО9рНоО5EtТНеО2`pН≥НеО0шН≥НеО/VН≥НеО-яН≥НеО,LН≥П(НеО*гН≥НеО)BН≥НоО$╣tНоО!пpТ∙П[НоО KТП'НеОfНеОАНеО\НеОвНоОJtНоОepП7НеО─НеОШНеОvЪ╗Ї/?/\шThe Pup Network Directory and the PUPNM JSYS3Pointer to address blockEntry Block(One per network directory entry)Pointer to first name block in listPointer to first address block in listNumber of attributesPointer to first attribute name blockPointer to first attribute value block ...Pointer to last attribute name blockPointer to last attribute value blockName BlockPointer to next name in entry's list (zero marks end)Pointer to owning entry blockName stringAddress BlockPointer to next address in entry's list (zero marks end)Pointer to owning entry blockNetwork (8 bits), Host (8 bits)Socket (32 bits)Number of attributesPointer to first attribute name blockPointer to first attribute value block ...Pointer to last attribute name blockPointer to last attribute value blockAttribute BlockAttribute name or value stringSyntax of Port NamesA port name expression is composed of name strings and address constants joined by the operator'+'.A name is one of the name strings defined in the network directory. Its value is the associated listof addresses.An address constant is in the form # # where the numbers are specified in octal. An element of this constant may be left unspecified bysupplying zero or by leaving it out entirely. Leading '#'s may be omitted. For example,"0#0#3", "##3", and "3" all denote an address constant with network and host numbersunspecified and socket number 3, while "3##" denotes network number 3.НЇОfПpТП,НGОНеОbНоО]▒t НоОZ╛pП!НеОWгП#НеОVBП&НеОTҐНеОS8П%НеОQЁП&НеОP.НеОN╘П$НеОM$П%НоОH≈t НеОE╡pП5НеОD-НеОB╗ НоО>tНеО;6pП8НеО9╠НеО8,НеО6їНеО5"НеО3²П%НеО2П&НеО0⌠НеО/П$НеО-┴П%НоО(ЭtНеО&pНыО!┼uНыО╔pТєtpП(Т╔П!НыО НыО;Т■tpП#Т∙П<НыОІТНыОяtpНоОЛП2НыОТ÷ПJТ═НыО┌ТМП?ТННыОЩТКПCТЛНыОxТПFйЇ1>/\ыгThe Pup Network Directory and the PUPNM JSYS4Names and address constants may be combined by means of the '+' operator, which is roughlyspeaking an intersection operator. Its effect is to make an expression whose value is more specific(i.e. contains fewer unspecified elements) than either of its operands. For example, the value of"3##+##123" is "3##123". If a particular element is specified in both operands but withconflicting values, the intersection is empty.When either of the operands is a name whose value is a list of addresses, the resulting value is alsopotentially a list. For example, the value of "Maxc1" in the network directory is the list 1#1#,2#1#, 3#200#, 4#40#. Hence the value of the expression "Maxc1+123" is the list 1#1#123,2#1#123, 3#200#123, 4#40#123. However, the value of the expression "3##+Maxc1" (or"Parc-Net3+Maxc1") is a single address, 3#200#, since the intersections of the given addressconstant with the other addresses in the list are empty.The PUPNM JSYSTo permit easy conversion between names and addresses in Tenex, we have implemented a ratherelaborate JSYS called PUPNM. We shall first summarize its calling sequence before covering someof its more grandiose features.Accepts in1:Source/destination designator (must be string pointer if source).2:B0 off: Convert address pointed to by RH 2 to name string ondestination designated by 1 (unless B4 on; see below).B0 on: Lookup name string designated by 1, return correspondingaddress(es) in table pointed to by RH 2.B1:For B0 off: output a string in the complete form"network+host+socket" if B1 off; omit fields where possible ifB1 on. For B0 on: Allow recognition if B1 on.B2(only if B0 off): If off, give error if address not found innetwork directory; if on, output an address constant using octalnumbers.B3(only if B0 off): Return network directory address block pointerin 3.B4Lookup attribute name string designated by 4 and output thecorresponding attribute value string to 1 (B0 must be off, and B4on suppresses outputting of the name string to 1 and forces B2off).B9-17: Address table length (words, ignored unless B0 on).RH:Location of table in which addresses are passed or returned.4:String pointer to attribute name (if B4 on).PUPNMReturns+1:Unsuccessful, error # in 1.+2:Successful:1:Updated where relevant (string pointer).2:Updated only if B0 on in call:НЇОfПpТП,НGОНыОbТЇПRТ╦НыО`≥Т°ПVТ² НыО_ТЄП6Т╣П,НыО]▐Т╨ПAТ╩НыО\ ТП.НыОY%Т▐ПeНыОW═Т╗Т╘ПTНыОVТ▒П7Т▓П!НыОT√Т╣ПSНыОSТяП/ТрП-НыОQ▄ТП8НыОLЪu НыОJpТёП8ТєП$НыОH∙Т█ПKТ▌НыОGТНоОD+Т─ Н═Н ТП/Н═ОAFН ТИП)ТЙН!О?аТП6Н О<эТуП(ТжН!О;WТП(Н О8rН!Т─Т│П%Н!О6МТ≤П&Т≥Н!О5hТП/Н О2┐Н!ТФТГП,Н!О0ЧТ÷П5Т═Н!О/yН О,■Н!Т■П3Т∙ Н!О+ТН О(*Н!ТтП,ТуН!О&╔Т▌П$Т▐Н!О% ТґТўП#Н!О#⌡Н О ІТП;Н ОяН!ТИП/ТЙН═ОЛН ТП,Н*PОНоО"Н═Н!Н═О=Н! Н═ОXН П(Н═ОsН Ъ HЇ,>/[ч)The Pup Network Directory and the PUPNM JSYS5LH:Number of words returned in address table.RH:Unchanged3:Only if B3 of 2 on in call:Zero if the address passed to PUPNM did not exactly match someaddress in the network directory. If a match was found:LH:Version number of network directory.RH:Index in file (16-bit bytes) of first word of the matching addressblock.4:Updated where relevant.Addresses are passed or returned in a table pointed to by RH 2. Each address is stored in twowords, with the network and host numbers in the left and right halves of the first word and thesocket number right-justified in the second.PUPNM performs one of two functions, controlled by B0 of 2 in the call. If B0 is off, PUPNMlooks up the address given in the two words pointed to by RH 2, and outputs a string correspondingto that address (unless B4 is on; see below). This conversion is controlled by the other bits in LH2. If B2 is off and the supplied address does not exactly match some address in the networkdirectory, an error occurs; if B2 is on, however, PUPNM will construct an expression whose valueis that address, possibly including octal address constants. For example, the address 3#377#0 willyield an error if B2 is off, but will generate the string "Parc-Net3+377#" if B2 is on.If B1 is off, the generated string will be an expression with a separate term for each nonzeroelement in the address. For example, the address 3#200#3 will yield the string "Parc-Net3+Maxc1+FTP". If B2 is on, a term will be omitted if its value is implicitly determined byone or more of the other terms. Hence the address 3#200#3 will yield the string "Maxc1+FTP"since one of the values of "Maxc1" is 3#200#.If B3 is on and the supplied address exactly matches some address in the network directory,PUPNM returns in RH 3 the byte number in the directory at which that address block starts. Thispermits a user program to perform any further processing desired, such as obtaining attributes oralternative addresses for the same directory entry. In order to read the network directory, a program mustopen the file in thawed mode. PUPNM returns in LH 3 the version number of the file Pup-Network.Directory that the index is valid in (which might be different from the highest-numberedversion if a new version of the directory is in the process of being created when PUPNM isexecuted).If B4 is on and the supplied address exactly matches some address in the network directory,PUPNM looks up the attribute name designated by the string pointer in 4. If the entry has such anattribute, the corresponding attribute value is output to the designator in 1; if no such attributeexists, an error occurs. B4 on suppresses the normal outputting of the name string corresponding tothe address and forces B2 to be off.PUPNM's second function, invoked when B0 is on, is to translate a port name expression(constructed as described in the preceding section) into an address or a list of addresses. For thisoperation, the source must be a string (i.e. JFNs, terminal designators, etc., are not permitted)terminated by a null, space, rubout, or any control character. '!' also terminates the string when PUPNM iscalled from monitor mode. PUPNM returns the value of that expression as a list of addresses stored inthe table pointed to by 2. B9-17 of 2 in the call specify the length of the table in words; PUPNMreturns in LH 2 the number of words actually stored (i.e. two times the number of addresses in thelist). If the address list is longer than will fit in the table, LH 2 contains the number of words thatwould have been stored if the table had been long enough.If B1 of 2 is on in the call, recognition may be performed on a name string if it is terminated byНЇОfПpТП,НGОН ОbН!П*Н О_9Н!Н═О\TН Н ОYoТуТжП!Н!ОWЙТП8Н ОUН!П$Н ОR Н!Т°Т²П-Н!ОP⌡Н═ОMІН ТНыОJяТ╠ПPТ╡ НыОILТўТ╞ПDНыОGгТП,НыОDБТіПAТїНыОC]Т┌ПMТ┐НыОAьТ▐ПeНыО@SТгП@ТхНыО>нТ∙П"Т√П?НыО=IТ⌠ПcНыО;дТПWНыО8ъТмТнПMНыО7ZТП>ТНыО5уТіТїПDНыО4PТ■П&Т∙П6НыО2кТП-НыО/ФТчПDТъНыО.aТ▌Т▐ПKНыО,эТґП!ТўП@НыО+WТіП5rТїНыО)рТ═pПAНыО(MТёП`НыО&хТу ТжПPНыО%C НыО"^ТчПDТъНыО ыТ├П!Т┤ПAНыОTТ╠ПKТ╡НыОоТ┬Т┴ПTНыОJТП$НыОeТЪТП>НыОЮТ║П[Т╒ НыО[Тп ТяПSНыОжТ┼П>rТ▀ НыОQТ⌠pТ■П1НыОлТ▀Т▄ПOНыОGТ▐П^Т░НыОбТ▐ПhНыО =ТП9НыО XТ·Т÷ПO╛Ї >/]ЫWThe Pup Network Directory and the PUPNM JSYS6null. If such a string is a unique initial substring of some name in the network directory, theremainder of that name is appended to the source string and the string pointer in 1 updatedappropriately. An ambiguity causes the error return to be taken with a distinct error code.The possible errors returned by PUPNM (aside from the usual errors for bad JFNs and the like) areas follows:PUPNX1Name or address not found. B0 and B2 were off and the supplied addressdid not exactly match some address in the network directory, or B0 was onand some name in the source expression was not found.PUPNX2Name ambiguous. Recognition was invoked (B0 and B1 on), and the lastname in the source string (terminated by null) was an initial substring ofmore than one name in the network directory.PUPNX3Syntax error or illegal address. B0 was off and an address was suppliedwith network, host, or socket number out of bounds, or B0 was on and thesource string was not a legal expression.PUPNX4Inconsistent values in name expression. Two terms joined by '+' yieldedan empty intersection.PUPNX5Syntax error in attribute name string.PUPNX6Attribute name not found.PUPNM JSYS and error code assignments are:PUPNMJSYS 443PUPNX1602030PUPNX2602031PUPNX3602032PUPNX4602033PUPNX5602034PUPNX6602035Network Directory MaintenanceThe file Pup-Network.Directory is created by first preparing a text file containing theinformation to be kept in the directory. This file is Pup-Network.Txt, and it should beconsulted for details on the required format.The text file is compiled into a directory by means of the program MakDir (MakDir.Sav,source in MakDir.Mac). MakDir first requests an input filename (default Pup-Network.Txt onthe connected directory) and compiles it into internal storage. If errors are detected, appropriatemessages are printed and the program quits upon reaching the end of the input file. If no errors aredetected, MakDir then requests an output file (default input-filename.Directory on the connecteddirectory) onto which it writes the compiled results.When compiling the directory that is actually to be installed in the system and distributed to otherName Lookup servers, it is essential that MakDir be run while connected to . Creating aPup-Network.Directory file on another directory and then copying it to will cause theversion number contained within the file to be inconsistent with the file's version number in, which will in turn cause the distribution process to malfunction.When Tenex is started up, it maps in the highest-numbered version of Pup-Network.Directory. To permit installing a new version of the directory without restarting Tenex, afunction has been added to the (privileged) OPRFN JSYS. Executing OPRFN with the stringНЇОfПpТП,НGОНыОbТцП`НыО`≥ТуТжПEНыО_ТЙТКП@НыО\/Т┐П5Т└П,НыОZ╙Т НоОWеН═Т■П*Т∙Н═ОV@Т⌠П<Т■Н═ОT╩ТП5НоОQжН═ТіТїП%Н═ОPQТЁТЄП8Н═ОNлТП,НоОKГН═Т╧П(Т╨Н═ОJbТ▓П=Т⌠ Н═ОHщТП)НоОEЬН═Т╚П<Т╛Н═ОDsТНоОA▌Н═П&НоО>╘Н═НыО;дП*НоО8ъН═НоО5ЗН═НюО4uН═НюО2ПН═НюО1kН═НюО/ФН═НюО.aН═НыО)тuНыО&ОpТуПKТжНыО%jТ╟П(Т╠П8НыО#ЕТП-НыО!Т²ПIТ·НыО{Т│П`НыОЖТ╟Т╠ПLНыОqТ─П8Т│П-НыОЛТЇТ╦ПPНыОgТП5НыО┌Т≤П-Т≥П7НыОЩТ≤Т≥tpП<НыОxТаП@ТбНыОСТЮП#ТАП:НыОnТПKНыО ┴ТNТOП5НыОТ П.Т⌡П5НыО ТхТиП:$Ї 8>/]р>The Pup Network Directory and the PUPNM JSYS7SIXBIT /PUPDIR/ in 1 causes Tenex again to map in the highest-numbered version of thedirectory. This OPRFN is invoked by the privileged Exec command "Initialize PupDirectory".Another program, TypDir, interprets a network directory and outputs a formatted dump showing itsinternal structure. This is handy to have while debugging programs that read the directory itself.TypDir requests an input filename (default Pup-Network.Directory on the connected directory) andan output filename (default input-filename.Lst on the connected directory), and produces a text filewhose format should be self-explanatory.НЇОfПpТП,НGОНыОbТФТГПFНыО`≥ТнП[НыО]ЄТ▀П7Т▄П)НыО\/Т╙ПHТ╚НыОZ╙Т√П*Т≈П6НыОY%Т∙ПdНыОW═ТП(Ъ▄ЇWY?/╠D TIMESROMAN TIMESROMAN TIMESROMANLOGO TIMESROMAN TIMESROMAN СЗ9в ╘#б+╪.ЪЪj/1/⌠ШїЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪPUPDIRECTORY.bravoTaftSeptember 3, 1979 5:43 PM