DOWDIR PAD Protocol version 2.0 Bob Graham, 22-Oct-1986 The protocol for communicating with a DOWDIR server is fairly simple request/response exchange. To perform any DOWDIR function, a PAD (user interface) must: 1) create a packet containing the function code followed by input values needed for the function 2) create a DECnet link to the server if one is not already available 3) send the packet to the server 4) wait for a response packet 5) unpack the values in the response packet and (for most functions) display them In the VMS version of the DOWDIR PAD, step 1 is taken care of by repeated calls to the routine DDPAD_WRITE_ITEM. Steps 2-4 are supported by a single call to DDPAD_REQUEST. Step 5 is performed by repeated calls to DDPAD_READ_ITEM. DDPAD_WRITE_ITEM and DDPAD_READ_ITEM are basically shell routines to make accessing the 'functional' routines PACK and UNPACK easier to use. DDPAD_REQUEST also has an internal functional routine GET_LINK, which attempts to create a DECnet link to one of a list of available servers. PACKET FORMAT: The same format is used for both the request and response packets. The packets are variable length with a minimum of 4 bytes and a maximum of 4096 bytes long. The first 2 bytes of the packet contains the function code, as an INTEGER*2 variable. The rest of the packet is made up of TYPE-LENGTH-VALUE (TLV) fields. TLV fields follow each other in the packet with no intervening data. In a TLV field, the first byte contains the field type, the second byte contains the length of the value, and the rest of the field contains the value, if any. All values are ASCII text strings with leading and trailing spaces removed. The function code and TLV type codes are defined in the module $DOWDIRDEF in DOWDIRPAD.TLB. This module is INCLUDEd in every routine which needs to use these values. In the VMS version of the DOWDIR PAD, the function codes are prefixed with DDF_, while the type codes are prefixed with DDP_. The currently defined function codes for use by a PAD are: ddf_display = 1 ; look up entries via last name ddf_getrec = 2 ; retrieve a single entry via master number ddf_update = 3 ; update a single entry via master number ddf_close = 4 ; close the DECnet link (optional) ddf_delete = 5 ; delete a single entry via master number The other function codes that are defined are for use only in server to server communications and should not be used by PADs. The currently defined type codes for PADs are: ddp_success = 0 ; a return value, indicates success ddp_lastname = 1 ; entry's last name field ddp_commonname = 2 ; entry's common (first) name ddp_initials = 3 ; entry's initials ddp_phone = 4 ; phone number string ddp_building = 5 ; building identification ddp_mailadr = 6 ; users' electronic mail address ddp_department = 7 ; department string ddp_location = 8 ; location string ddp_masterno = 9 ; master number string ddp_comment = 14 ; comment field ddp_error = 255 ; a return value, text contains error message The other type codes that are defined in $DOWDIRDEF are for use only in server to server communications and should not be used by PADs. In general, the TLV fields in a request packet can be in any order. This is also basically true in the response packets with the exception that the LASTNAME field is always the first item returned for an entry. Thus it can be used to tell when one entry ends and another begins in the response to a LOOKUP function where more than one entry can be returned. The server indicates errors in processing a request by responding with a packet whose first (and only) TLV has a type code of DDP_ERROR (255). The text value of the field is the error message to be displayed. The DDP_SUCCESS is a type code used for response packets when there isn't a legitimate value to be returned, such as for a DELETE function. The length of a DDP_SUCCESS value should always zero. MAKING A REQUEST: Once a request packet has been created, it needs to be sent to the server. The PAD must then wait for a response packet to be returned (or an error returned from the DECnet software). If a DECnet logical link to a server already exists, then the request is sent on that link. If not, or sending the request returns an error that the link is down, then a new link must be created. A full function PAD must be able to connect to one of a list of servers, in case the primary server is unavailable. The information needed for each server is the node name that the server is on and the object number used by the server on that node. So far, all the servers on the network use object number 233, but PADs should be designed so that different object numbers can be used by different nodes. In the VMS version of the PAD, the list is a /SYSTEM logical name. For the RSX and IBM/INTERLINK version, the list is encoded into a BLOCK DATA common. What ever mechanism is used for keeping the list of server, it make it reasonably easy for whoever is installing the PAD to change the list. The servers should be listed in order of increasing 'distance' from the PAD. Thus, the server that gives the best response time (ie. least hops, fastest circuits, etc) should be the first in the list. It would be possible to write a PAD that would only attempt to connect to a single server, but I would not recommend it. All of the DOWDIR PADs which have been distributed have had the ability to connect to more than one server. The connection to the server should be made using the non-transparent interface to DECnet. This is so that the PAD can send some values in the 'optional connect data' to the server. If no optional data is sent, the server will respond using a slightly different protocol than is documented here. Three words (INTEGER*2) need to be sent to the server in the optional connect data. The first word is the protocol version number and should be a 2. The second word is used for server to server links, for PAD's it must be zero. The third word is the size in bytes of the packet buffer in the PAD. The server will not send response packets larger than this value. If the third word is omitted from the optional connect data, then the server will use a maximum response packet size of 4096. The current server doesn't return any useful data in the 'optional accept/reject data' and later versions probably won't either. Thus new PAD's do not need to be designed to look at that data. Once a logical link has been created, requests are made using the normal DECnet SEND function. Response packets are read using the normal DECnet READ function. The link can be closed with the normal DISCONNECT function when the PAD exits, however, the server is written to handle links that disconnect abnormally. DOWDIR SERVER FUNCTIONS: The server expects to receive particular TLV fields for each different type of request. If you don't send the proper fields the results are unpredictable. Server response packets currently return the fields listed here, however as future versions of the server may return different fields. Thus a PAD should be written to ignore unexpected fields. For the DISPLAY function, the LASTNAME field is required, and the COMMONNAME, INITIALS and LOCATION fields are allowed as options. A successful response packet will contain all the entry fields. The GETREC and DELETE functions require the MASTERNO field. GETREC returns all the entry fields, while DELETE currently returns DDP_SUCCESS. The UPDATE function requires the MASTERNO field and the entry fields that are to be changed. A successful response packet will contain all the entry fields with their updated values. NOTE: these are not necessarily the same as the values sent in the request packet. The server does do some validation of field entries, so a good PAD should always display the data returned in the response to the user to verify exactly what was updated.