-- STPSubr.Mesa
-- last edit February 4, 1983 2:14 pm
-- last edit May 22, 1983 2:49 pm, Russ Atkinson
 -- change short STRING to LONG STRING
-- definitions file for commonly used STP procedures
-- implemented in STPSubrImpl.Mesa
 
DIRECTORY
File: TYPE USING [Capability, Permissions, read],
UnsafeSTP: TYPE USING [ErrorCode, Type, -- FileType, -- Handle],
Stream: TYPE USING [Handle],
Subr: TYPE USING[TTYProcs],
System: TYPE USING [gmtEpoch];
 
STPSubr: DEFINITIONS = {
 
 RetrieveProcType: TYPE = PROC[fileName: LONG STRING, stp: UnsafeSTP.Handle,
   remoteStream: Stream.Handle] RETURNS[skipRest: BOOL];
 
 -- in all the procedures below that take h as a parameter,
 -- if h = NIL then it uses Exec.w for prompting for input
 
 -- this is an attempt to handle the confusing aspects of remote enumerates
 -- and retrieves
 -- you call EnumerateForRetrieve and I call enumProc with each file that matches
 -- you never need to catch credentialsErrors out of EnumerateForRetrieve;
 -- you might want to catch noSuchFile
 EnumerateForRetrieve: PROC[host, filePattern: LONG STRING,
  enumProc: RetrieveProcType, h: Subr.TTYProcs,
  onlyOne: BOOL ← TRUE];
 
 -- filename can be local or remote
 -- if possible you should call StopSTP at the end of your program
 -- set fileType if this is Subr.Write
 -- set createtime if this is Subr.Write to a remote stream
 GeneralOpen: PROC[filename: LONG STRING, h: Subr.TTYProcs,
  access: File.Permissions ← File.read,
  fileType: UnsafeSTP.Type← unknown,
  createtime: LONG CARDINAL ← LOOPHOLE[System.gmtEpoch]]
  RETURNS[sh: Stream.Handle, stphandle: UnsafeSTP.Handle];
 -- close the stream, simply call Space.Delete[sh]
 
 -- just like GeneralOpen but filename can be a pattern,
 -- you pass it a proc
 PatternGeneralOpen: PROC[filepattern: LONG STRING, proc: RetrieveProcType,
  h: Subr.TTYProcs];
 
 
 StpState: TYPE = LONG POINTER TO StpStateRecord;
 StpStateRecord: TYPE = RECORD[
  checkForOverwrite: BOOL ← TRUE
  ];
 
 -- raises Subr.FileError if can't find file on local or remote
 -- if host or directory are NIL, then just like Subr.NewStream[];
 -- if wantExplicitVersion is true, wantcreatetime = 0, and version > 0,
 -- then gets that version
 -- otherwise gets !H when wantcreatetime = 0
 CachedOpen: PROC[host, directory, shortname: LONG STRING,
  version: CARDINAL, wantcreatetime: LONG CARDINAL,
  h: Subr.TTYProcs,
  stpState: StpState, wantExplicitVersion: BOOL, onlyOne: BOOL ← TRUE,
  tryDollars: BOOL ← FALSE] RETURNS[sh: Stream.Handle, cap: File.Capability];
 
 -- just like CachedOpen but avoids FileStream.Create
 CachedRetrieve: PROC[host, directory, shortname: LONG STRING,
  version: CARDINAL, wantcreatetime: LONG CARDINAL, h: Subr.TTYProcs,
  stpState: StpState, wantExplicitVersion: BOOL, onlyOne: BOOL ← TRUE,
  tryDollars: BOOL ← FALSE] RETURNS[cap: File.Capability];
 
 Connect: PROC[host: LONG STRING, h: Subr.TTYProcs,  
  onlyOne: BOOL ← FALSE] RETURNS[stphandle: UnsafeSTP.Handle];
 
 -- always returns NIL
 ForceClosed: PROC[stphandle: UnsafeSTP.Handle] RETURNS[UnsafeSTP.Handle];
 
 StopSTP: PROC;
 
 
 -- these procedures can be called without using the Connect[] stphandles
 
 -- used by SModelImpl
 Store: PROC[stphandle: UnsafeSTP.Handle, remoteName: LONG STRING,
  localCap: File.Capability, createDate: LONG CARDINAL,
  h: Subr.TTYProcs] RETURNS[nbytes: LONG CARDINAL];
 
 -- takes contents of remotesh and writes them onto file localfilename
 -- returns cap, a File.Capability for the file it wrote onto WITH Write permission
 -- may raise UnsafeSTP.Error
 WriteStreamToDisk: PROC[remotesh: Stream.Handle, localfilename: LONG STRING,
  byteLengthHint: LONG CARDINAL, h: Subr.TTYProcs]
  RETURNS[cap: File.Capability, nbytes: LONG CARDINAL];
 
 HandleSTPError: PROC[stphandle: UnsafeSTP.Handle, stpError: UnsafeSTP.ErrorCode,
  message: LONG STRING, h: Subr.TTYProcs]
  RETURNS[retryit: BOOL];
 
 AddUserName: PROC[sto: LONG STRING, spat: LONG STRING, h: Subr.TTYProcs];
 
 MakeSTPHandle: PROC[host: LONG STRING, h: Subr.TTYProcs]
  RETURNS[stphandle: UnsafeSTP.Handle];
 
 -- when called, sets useCIFS to shouldUseCIFS in STPSubrImpl.Mesa
 SetUseOfCIFS: PROC[shouldUseCIFS: BOOL];  
 
 SetNumberOfConnectTries: PROC[nTries: CARDINAL];
 
 }.