home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / comms / nlistmgr_1 / NM0,80Docs < prev    next >
Text File  |  1994-07-26  |  11KB  |  304 lines
  1. NListMgr 0.80 documentation (draft)
  2. (C) Steven Haslam July 1994
  3.  
  4. NListMgr provides routines to load the domains file, pass the domains file
  5. information (decoded) onto clients and to lookup and scan FTN nodelists.
  6.  
  7. NListMgr is loaded in the normal way. It may be given the pathname of a
  8. directory on its load command-line, which it will assume contains the domains
  9. file, named "Domains". It will then proceed to load the file.
  10.  
  11. (Under RiscOS 3, NListMgr will "canonicalise" the filename given before using
  12. it. This means that system variables and paths will be expanded and
  13. references according to the CSD, CSL or URD will be converted to complete
  14. pathnames; so you can therefore get away with entering "RMLoad %.NListMgr
  15. ^.Nodelist". This facility is not available under RiscOS 2)
  16.  
  17. To load the file at any other time, use the command "NListMgr_Load". Using
  18. this command without parameters will use the name given last.
  19.  
  20. If NListMgr is loaded without parameters, it will look for the nodelist
  21. directory using the system variable NListMgr$NodeListDir.
  22.  
  23. SWI NListMgr_GetSystInfo (&CCF00)
  24.  
  25. \E    R0 = pointer to ExtAddr struct
  26. \X    R0 = pointer to OldSystInfo struct, or 0 if not found
  27.  
  28. This SWI uses old-style structures. Its use is deprecated, it calls
  29. NListMgr_Lookup, which you should use in preference.
  30.  
  31. SWI NListMgr_ListSysts (&CCF01)
  32.  
  33. \E    R0 = pointer to ExtAddr struct (not necessarily complete)
  34.     R1 = input reason code
  35.     R2 = buffer pointer
  36.     R3 = buffer size
  37. \X    R0 = number of entries written
  38.     R1 = output reason code
  39.     
  40. This SWI uses old-style structures. Its use is deprecated, it calls
  41. NListMgr_Scan, which you should use in preference.
  42.  
  43. SWI NListMgr_DomainsFile (&CCF02)
  44.  
  45. \X    R0 = pointer to filename of domains file (0-terminated)
  46.  
  47. This SWI returns a pointer to the domains file. Its use is deprecated, you
  48. should use NListMgr_DomainsTable to read the decoded information.
  49.  
  50. SWI NListMgr_SystFlag (&CCF05)
  51.  
  52. \E    R0 = pointer to ExtAddr struct
  53.     R1 = pointer to wildcarded flag name
  54. \X    R0 = non-zero if flag found
  55.     R1 = pointer to actual flag found.
  56.  
  57. This SWI uses old-style structures. Its use is deprecated, it calls
  58. NListMgr_Flags, which you should use in preference.
  59.  
  60. SWI NListMgr_Lookup (&CCF06)
  61.  
  62. \E    any of
  63.         R0=domain number, R1=zone, R2=net, R3=node, R4=point
  64.         R0=ptr to address structure (>=&8000)
  65.     R1=reason code
  66. \X    R1=0 on entry
  67.         R0=pointer to SystInfo struct, or 0 if not found
  68.     else if R1=1
  69.         R0=non-zero if found, zero otherwise
  70.     else error returned
  71.  
  72. This SWI searches the nodelist for a system according to address.
  73.  
  74. An "address structure" is five words, being:
  75.  
  76. Offset    Meaning
  77. +0    Domain number
  78. +4    Zone number
  79. +8    Net number
  80. +12    Node number
  81. +16    Point number
  82.  
  83. The "domain number" is an index, starting from 0, into the domains table (or
  84. line number, starting from 0, of the domains file).
  85.  
  86. The structure returned by this call is as follows:
  87.  
  88. Offset    Meaning
  89. +0    Pointer to name of system
  90. +4    Pointer to site of system
  91. +8    Pointer to operator of system
  92. +12    Pointer to phone number of system
  93. +16    Pointer to password for system
  94. +20    Mail status: 0 = never accepts mail, 1 = mail during ZMH, 2 = mail
  95. 24hrs a day
  96. +24    "Maximum connect rate", in bps (usually 9600 for V32b &c.)
  97. +28    Cost band
  98. +32    Pointer to gateway flags of system (or 0)
  99. +36    Pointer to capability flags of system (or 0)
  100. +40    Pointer to user flags of system (or 0)
  101.  
  102. All strings referenced above are 0-terminated. They are pointers straight
  103. into NListMgr's data cache, and should therefore be copied if being kept for
  104. a long time; "long time" meaning, in this context, over calls to NListMgr,
  105. possibly by other tasks.
  106.  
  107. NListMgr first searches the data cache, so multiple lookups to the same
  108. system in a short time, if the system is found, will be fairly quick.
  109.  
  110. NListMgr then searches the index cache, the extent of which is user-defined;
  111. commonly, only nodes that are password-protected or have been edited.
  112.  
  113. NListMgr finally searches the index file, using the zone cache information to
  114. speed up searching.
  115.  
  116. If R1 is 1 on entry, then if the system is found, the data is not loaded
  117. into the data cache: this improves timing if the data is not going to be
  118. required, but if the data is then requested, and the system is in only the
  119. main index file, then a complete lookup will be performed again.
  120.  
  121. SWI NListMgr_Scan (&CCF07)
  122.  
  123. \E    R0 = pointer to address structure (not necessarily complete)
  124.     R1 = input reason code
  125.     R2 = pointer to buffer
  126.     R3 = buffer size
  127. \X    R0 = number of entries written to buffer
  128.     R1 = output reason code
  129.     
  130. This call scans the nodelist, and enumerates the contents into a client
  131. buffer. This call allows a client to read the nodelist in terms of its
  132. structure, i.e. read all the zones in a domain, then all the regions in a
  133. zone and so on.
  134.  
  135. The input reason codes are:
  136.  
  137. Code    Meaning
  138. 0    Produce a list of zones, one integer per zone
  139. 1    Produce a list of regions, one integer per region
  140. 2    Produce a list of hosts, one integer per host
  141. 3    Produce a list of systems, two integers per system
  142. 4    Produce a list of pointers, one integer per point
  143.  
  144. When listing systems, the output is in { node, point } pairs, one integer
  145. each.
  146.  
  147. The output reason codes are 0 for a success, 1 for an overflowed buffer, or 2
  148. for any other error.
  149.  
  150. Listing the zones in a domain is fast because it uses the zone cache; all
  151. other types require the main index to be scanned.
  152.  
  153. At the time of writing (17-Jul-1994 00:47:15) all input reason codes except 0
  154. (listZones) are unimplemented, and return an error.
  155.  
  156. SWI NListMgr_Flags (&CCF08)
  157.  
  158. \E    R0 = pointer to address structure
  159.     R1 = pointer to wildcarded flag name
  160.     R2 = buffer to store actual flag name, or 0
  161.     R3 = size of buffer
  162. \X    R0 = non-zero if flag found
  163.     If R2!=0 on entry, the buffer at R2 is updated if a match is found
  164.  
  165. This call may be used to see if a system has a flag set, or has a flag
  166. matching a certain format. The same format is used for wildcards as is used
  167. by filing systems: # matches any character, * matches 0 or more characters,
  168. case is ignored; "*" will match any string.
  169.  
  170. Note that it is possible to call NListMgr_Lookup and check the flags
  171. yourself: if the above is not quite want you want to do, coding your own
  172. check is advisable.
  173.  
  174. SWI NListMgr_DomainsTable (&CCF09)
  175.  
  176. \E    R0 = pointer to table buffer, or 0 to get size
  177.     R1 = size of buffer pointed to by R0 if R0!=0
  178.     R2 = pointer to data buffer if R0!=0
  179.     R3 = size of data buffer if R0!=0
  180.     R4 = flags:
  181.         bit 0 set => terminate strings with CR, not NUL
  182.         bit 1 set => return one domain only, see R5
  183.         all other bits should be clear
  184.     R5 = number of domain to return (if bit 1 of R4 set)
  185.  \X    R0 preserved
  186.     R1 = size required for table buffer if R0=0 on entry, else preserved
  187.     R2 preserved
  188.     R3 = size required for data buffer if R0=0 on entry, else preserved
  189.     R4 = number of domains
  190.  
  191. When called with R0!=0, this command fills two buffers. The "table buffer" is
  192. a table of data structures giving information on each domain; this contains
  193. string pointers into the data buffer, which has no other significance.
  194.  
  195. Each entry in the domain table is 5 words long:
  196.  
  197. Offset    Meaning
  198. +0    Pointer to domain name
  199. +4    Pointer to domain I/O string
  200. +8    Pointer to domain nodelist directory string
  201. +12    Integer containing technology type
  202. +16    Pointer to other information that was in the domains file
  203.  
  204. Indices into this table, with the first element numbered as 0, are identical
  205. to "domain numbers" in address structures.
  206.  
  207. Setting bit 0 of R4 on entry causes the strings in the data buffer to be
  208. terminated with CR characters (ASCII code 13) not NUL (ASCII code 0): this is
  209. to assist BASIC programmers.
  210.  
  211. Setting bit 1 of R4 on entry reads the information for one domain only,
  212. the number of which is specified in R5; this means that programs need not
  213. store the entire table all the time.
  214.  
  215. *NListMgr_Load [<fsp>]
  216.  
  217. This command will cause NListMgr to reload the domains file, reload nodelist
  218. indices and flush the data cache. If no nodelist directory is given, the
  219. previos one is used.
  220.  
  221. *NListMgr_Domains
  222.  
  223. This command will list the current domains table
  224.  
  225. *NListMgr_CacheStatus
  226.  
  227. This command will give the sizes of the caches, and also list the systems in
  228. the data cache, with their cache ages.
  229.  
  230. <NListMgr$NodeListDir>
  231.  
  232. This system variable is used as a default for the nodelist directory, if none
  233. has been given on the command line: it is normally set by the !NListMgr
  234. application.
  235.  
  236. <NListMgr$DataCacheSize>
  237.  
  238. This system variable may be set by the user to change the cache size from the
  239. default (4 systems). This must be greater than or equal to 1: disabling the
  240. data cache entirely is not permitted.
  241.  
  242. This system variable is read every time the cache is re-initialised: i.e. on
  243. module loading, and on execution of the NListMgr_Load command.
  244.  
  245. <NListMgr$FileCacheSize>
  246.  
  247. This system variable may be set by the user to change the size of the file
  248. cache used when (if) the entire index file is being read: the index file is
  249. read in chunks of this size.
  250.  
  251. Setting NListMgr$FileCacheSize to 0 disables file cacheing, recommended only
  252. if you index-cache all systems.
  253.  
  254. Further notes:
  255.  
  256. The SWIs which use old-style structures are compatible with same-numbered
  257. SWIs in previous version of the module. They are "wrappings" for the new
  258. SWIs, which use the address structures and information structures stored in
  259. the data cache. You are advised to use the new SWIs where possible; but the
  260. old SWIs have been provided for the express purpose of backward-compatiblity.
  261.  
  262. Lists produced by NListMgr_Scan are not "tidied": they may contain duplicate
  263. numbers, and are not sorted. Duplicates may arise where systems or nodelists
  264. have been joined at compilation: if 1:374/777, then 2:250/116, then 3:713/601
  265. are added onto a region 25 nodelist (zone 2), 4 zones will be listed: zones
  266. 2, 1, 2 and 3.
  267.  
  268. It is [will be] possible for NListMgr_Scan to return no entries even where
  269. systems are present: for example, the addition of a single node in zone 1
  270. will produce no regions or hosts in zone 1. A method of listing all the
  271. systems in zone 1 in this case has yet to be defined.
  272.  
  273. In the above case, the zone will always be listed, even if no ZC system was
  274. compiled.
  275.  
  276. SWIs &CCF03 and &CCF04 are undefined, and return an error.
  277.  
  278. Proper loading of the module:
  279.  
  280. The NListMgr module should be loaded, if necessary using the RMEnsure command
  281. to check if it is already in memory. Programs should execute the command
  282. "/NListMgr:Ensure" to load NListMgr if it is not already loaded. Obviously,
  283. this requires the setting of NListMgr$Path, which should contain a file
  284. called "Ensure" that loads the module; this is normally set to the !NListMgr
  285. applcation, although this is not necessary.
  286.  
  287. A recommended set of commands to load NListmgr 0.80 is:
  288.  
  289. If "<NListMgr$Path_Message>"="" THEN Set NListMgr$Path_Message Please open a
  290. directory display containing the !NListMgr application, or load the NListMgr
  291. module.
  292. RMEnsure NListMgr 0.80 /NListMgr:Ensure
  293. RMEnsure NListMgr 0.80 NListMgr 0.80 or later is required to run XXXXXXX
  294.  
  295. Under RISC-OS 3, this will print a more informative message if !NListMgr has
  296. not been "seen" by the Filer.
  297.  
  298. -----------------------------------------------------------------------------
  299. Steven Haslam, 112 Keighley Road, Colne, Lancashire, BB8 0PH, ENGLAND
  300.             VOICEphone: (+44)-(0)282-866835
  301. -----------------------------------------------------------------------------
  302. Revised    26-Jul-1994    NListMgr_DomainsTable returning only one domain
  303.             NListMgr$FileCacheSize
  304.