This is a very informal document at the moment; hopefully it will be replaced by a more comprehensive one sometime in the not-too-distant future. Getting to Inquir: To get to Inquir database services, you must connect to port 1 on mintaka.lcs.mit.edu. This is the tcpmux port. There are five services available at that point relevant to Inquir. To summon any of these services you must send the text-string name to the port, followed by a NETASCII NEWLINE (in C, for instance, this might look like fprintf(tcpmuxport, "inquir-lookup\r\n");) After the service has been summoned, a line will be returned with the first character a + or a - indicating, respectively, success or failure in summoning the service. The rest of the line contains a text explanation of the success or failure. At this point, you may be expected to send or receive text, depending on the service. inquir-config When inquir-config is summoned, it returns (ASCII) a set of configuration information. These are structured like LISP lists, but are sufficiently structured that any program should be able to parse them. [We should have a complete doc on each form and what the args are. We should restrict the format more than required by the E-Lisp so that the above statement is true. Perhaps this should come under the database entry format below, with a forward reference here -MAP] inquir-lookup when inquir-lookup is summoned, it waits for a username to be sent followed by a NETASCII NEWLINE. If the username is found, it returns the inquir-record of that user (see below for inquir-record format.) Otherwise it returns the string 'Unknown UNAME "FOO"' where foo is the username requested (note that leading spaces and capitalization are ignored by inquir when dealing with usernames.) inquir-new-uid when inquir-new-uid is summoned, it returns an ascii number which is guaranteed to be an unused UID in the inquir range (12000-14999). If you use it (i.e. save it with inquir-update in the UID field of an INQUIR record) you will register it as used, otherwise it will eventually get distributed to another caller. inquir-update when inquir-update is summoned, it waits for an inquir record to be entered, then closes the connection. At this time, it provides no diagnostics feedback as to success or failure of update. The user specified in the SUNAME field has his record updated (or created, if he doesn't exist) in all fields specified (his record, if it exists, will be deleted if no UNAME field is specified, though) as long as his OWNER field is blank. (A non-blank OWNER field in the original record for the user requires inquir-update-krb to update.) inquir-update-krb This wants the length (bytes of an int) of an authenticator, followed by an authenticator (service and instance "inquir", and krb_realmofhost("inquir"), checksum 0) followed by the length of a private message built with a schedule and key built from the same info as your authenticator followed by the private message itself. (See the code in /common/inquir/vaxbin/inquir.c for an example.) Note that this update will succeed if the user attempting the update is listed on the OWNER line of the record being updated, or if the record's OWNER line is blank or non-extant. Inquir record format: (much of the following text is stolen from a document by sra) The update request is parsed into its component "items", which are identified by their names. These items form the data for the new database entry. Items are indicated by their item-name, a colon, and the value of the item. An item is terminated by end-of-line, unless continuation is being used, in which case a "newline" sequence is concatenated into the value at all but the final line break. Whitespace occuring before the colon is completely ignored, so the item "U N A M E :foo" is identical to the item "UNAME:foo"; for ease of reading, we shall use the latter form in this document. Items with a null item-name are continuations of the previous item. Lines with no colon character at all are completely ignored (don't ask). The very first item, which needs no value, is called BEGIN. Everything until the first "BEGIN:" is ignored. The very last item, which needs no value, is called END. Note that, as a change from earlier versions, after the END: inquir-update and inquir-update-krb now close the connection without parsing further updates (i.e. one update per connect only.) The values of the UNAME and SUNAME items are case-insensitive. Between them they specify the action to be taken by the update message. The database entries are keyed on their UNAME fields. The SUNAME item is special in that it does not specify a field in the database entry; rather, the SUNAME item specifies the UNAME of the database entry to modify. The old entry for the indicated SUNAME is read in, and the items from the update request file are merged into it. The new items have precedence; only items specifically mentioned in the request are changed. If the UNAME is null, SUNAME's entry is deleted. If the UNAME differs from the SUNAME, SUNAME is changing his name to UNAME. That is, SUNAME's entry is deleted and a new ENTRY is created for UNAME. The NETAD field should be a fully qualified RFC822 format address, but this is not presently enforced by the database software. If this field is garbage, mail routing will do strange things. The OWNER item a) If the field is blank, the entry is not owned by anyone and can be updated by anybody at all. If the principle is "invalid" (obsolete or some such) it is treated as if it were blank. b) If the field contains a valid principle, the principle is checked against the principle trying to make an update, and rejected if necessary. This requires use of inquir-update-krb. The UID item The UID item must either be absent, or a unique UID. If you attempt to update a record with a UID duplicate of another record's UID, the update will fail. The NETAD item Changing the NETAD item changes your email forwarding @lcs.mit.edu to wherever you point the NETAD item. A sample update field BEGIN : SUNAME :NICK WRKPH :6524 NAME :Nicholas Papadakis WRKTE :x3-6524 RELAT :Research Staff HOMTE :(617) 661-4938 ALTER :NICK 11-Jan-89 09:56:21-EST (600533781) REMAR : SUPER :TJG BIRTH :19 July WRKAD :NE43-254 OWNER : UID :11183 NETAD :nick@ghoti.lcs.mit.edu HOMAD :897 Main St. Cambridge (above Tosci's) NICK :nic PROJE :Lispm maintenance UNAME :NICK GROUP :CRS END : A looked-up field will resemble this, but with no BEGIN/END pair bracketing it. Note that these fields are the standard fields; other fields may be used, but won't necessarily be seen in the EMACS front end or other front-ends that may be constructed. Remember that record length is limited... This is a very hastily written document; if you have questions or would like to volunteer to write a better one, please email bug-inquir@lcs.mit.edu.