-- FileLookup.mesa
-- M. D. Schroeder, September 7, 1982 11:54 am

DIRECTORY
  Rope: TYPE USING [ROPE],
  System: TYPE USING [GreenwichMeanTime];

FileLookup: CEDAR DEFINITIONS = BEGIN

Result: TYPE = {noResponse, noSuchPort, noSuchName, ok};

LookupFile: PROC [server, file: Rope.ROPE ]
    RETURNS [result: Result, version: CARDINAL,
      create: System.GreenwichMeanTime, count: LONG CARDINAL];

-- This procedure uses the LookupFile packet exchange protocol to obtain the
-- version number, create time, and byte length of a file on a remote file server.
-- The file name may be specified complete with version number, with "!h", with "!l",
-- or with no version.  The file names can be specified either with the "<..>..>.." syntax
-- or with the ".../.../..." syntax (be sure that the name does not start with a '/).

-- If the result is "ok" then the requested file exists with the returned
-- version number, create time, and byte length.  "noSuchName" means that either
-- the server name was nonsense or that the file does not exist on that server.
-- "noSuchPort" means that the server responded with a no-such-port error packet
-- when prodded on the LookupFile socket.  "noResponse" means that either the NLS
-- didn't respond to the server name lookup, the LookupFile packet didn't get to the
-- server, or the server did not respond to it.

-- LookupFile caches the state of the server as derived from previous lookup attempts.
-- If the cached state for a server is either "noResponse" or "noSuchPort" then
-- LookupFile immediately returns that result without attempting any communication.
-- Such negative cache entries are flushed after five minutes.  Positive cache entries
-- contain the Pup address of the server, eliminating the need to do a NLS lookup
-- on the server name.

-- The longest that you should have to wait for a response is ~ 4*(2 + 0.5*MIN[8,hopCount])
-- seconds.  This is the time it will take to decided that a server isn't going to respond in the
-- case of an uncached down server.  Most answers are determined much more quickly.


END...