home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / srefprc.doc < prev    next >
Text File  |  2001-03-27  |  76KB  |  1,872 lines
  1. 1 March 2001
  2.  
  3.      SRE-http ver 1.3h Documentation: SRE-http's procedure library. 
  4.  
  5.  
  6. SRE-http version 1.3 uses uses OS/2 "macrospace" to store many of
  7. its procedures.  In addition, as a multi-threaded program, it uses the
  8. environment, queues, and semaphores to transfer information between threads.
  9. This document discusses both these aspects of SRE-http.
  10.  
  11. In the first section, we discuss procedures that competent REXX programmers 
  12. may find useful when writing addons for SRE-http.
  13. These procedures are stored in a "dynamic macrospace library file" called 
  14. SREFPRC.RXL.  When SRE-http is first run (that is, when GoServe is 
  15. started, and the first request arrives), SRE-http will load this 
  16. library into macrospace.
  17.  
  18. The second section discusses SRE-http use of the environment, threads and
  19. semaphores for inter-thread communication. 
  20.  
  21. Note that several of these procedures may not be needed on your site.  If so,
  22. you can save a little bit of space by "removing them from macrospace".
  23. For details, see the discussion of the REMOVE_PROCS variable in INITFILT.DOC.
  24.  
  25. Please note that SRE-http uses REXXLIB for various purposes. 
  26. REXXLIB is found at 
  27.      http://www.quercus-sys.com/rexxlib.htm.
  28. Our licence with Quercus allows users of SRE-http to freely use REXXLIB 
  29. (you do not need to  register it) as part of SRE-http.  
  30. However, if you use REXXLIB for your own programs, you are supposed to 
  31. pay for it (the license is only for use with programs we distribute). 
  32. If you write "addons" for SRE-http that use REXXLIB, I'm not sure where 
  33. that falls; but to be safe, I assume that you are supposed to register  
  34. (the original cost was $25.00, though as of March 2001 it may be 
  35. available for free).
  36.  
  37.  
  38. -------         ----------          ---------          ------------
  39. -------          SECTION 1: Using SRE-http's macrospace library.
  40. -------         ----------          ---------          ------------
  41.  
  42. The following describes many of the procedures contained in the
  43. SRE-http macrospace library.
  44.  
  45. If you are a serious REXX programmer, you may want to look at the source
  46. code (contained in  various .SRF files) for further descriptions. Note
  47. that there are some procedures placed into macrospace by SRE-http that
  48. are not intended for general use; these are not described in this document.
  49.  
  50. Some preliminary notes:
  51.  
  52. 1) What is  macrospace?
  53.     Macrospace can be thought of as a system-wide dynamic link library.
  54.     That is, procedures stored in macrospace are available 
  55.     to all REXX programs, not just SRE-http.  Thus, if some other
  56.     program "clears" macrospace, SRE-http may fail -- and
  57.     vice versa!
  58.  
  59. 2) Where's the source code?
  60.      The source code for these procedures consists of a number of files with
  61.      the extension .SRF; all stored in the SRE-http "library" directory
  62.      (perhaps \GOSERVE\LIB).
  63.  
  64. 3) What do we need to work with macrospace procedures?
  65.      Nothing -- just call them the way you call any external OS/2
  66.      procedure. Note that SRE-http uses procedures in REXXLIB.DLL 
  67.      to "load" SREFPRC.RXL into macrospace.  For simple manipulations of
  68.      macrospace, you can use MSPACE.CMD (look for it in the library
  69.      directory).
  70.  
  71.  
  72. 4) A caution on using these procedures:
  73.  
  74.   There are four general cases where one might use these procedues:
  75.     1) In an SRE-http addon (or a pre-filter, or mid-filter, procedure)
  76.     2) In a CGI-BIN script
  77.     3) In a post-filter procedure
  78.     4) In a stand-alone program (that is NOT running in the same process as 
  79.        SRE-http)
  80.  
  81.   Several of these procedures use GoServe to provide information,
  82.   or use "request specific" information. These procedures will not
  83.   work if called from one of the "higher numbered" cases. 
  84.  
  85.   For example, several of these procedures use the GoServe EXTRACT function,
  86.   typically to determine the current serverport. Extract will NOT work in 
  87.   a CGI-BIN script, or in a stand alone program.  
  88.  
  89.   Where appropriate, the "cases" where the procedure can/cannot be used
  90.   are noted in the Restrictions: portion of the following descriptions.
  91.  
  92.  5) Another Caution
  93.     In some cases, inappropriate use of these procedures can
  94.     CRASH GOSERVE -- so do pay attention to the "restrictions"!
  95.  
  96.  6) On the use of "dynamic macrospace procedures".
  97.     As of version 1.2N, SRE-http  uses "dynamic macrospace".
  98.     Dynamic macrospace means that many of the procedures are not
  99.     loaded until they are needed; which helps save space, and
  100.     facilitates minor upgrades.
  101.  
  102.     There is one "gotcha" -- if you call one of 
  103.     these procedures from an external program (that's not in the GoServe
  104.     process), it is possible that you will get a "could not find
  105.     SRE_LIBDIR error".  If this occurs, you just need to 
  106.     SET SRE_LIBDIR=goserve_lib_directory (say, SET SRE_LIBDIR=D:\GOSERVE\LIB).
  107.  
  108.          Make sure you do this SET from the same OS/2 session you are runnning 
  109.          this external procedure from,or put it in your config.sys file.
  110.  
  111. -------         ----------          ---------          ------------
  112.             Description of general purpose macrospace procedures
  113. -------         ----------          ---------          ------------
  114.  
  115. Calling Syntax:
  116.  
  117. File/url-resolution related procedures:
  118.     status  =SREF_GOS(acmd,varname,dorange,hdrs)
  119.    open_time=SREF_OPEN_READ(afile ,seconds_to_try_for , howopen )
  120. afile_string=SREF_GRAB_FILE(afile,seconds_to_try_for)
  121. newfiles=SREF_CONJUREF(basedir,basenames,extlist,minfree,mintime)
  122.        newct=SREF_LOOKUP_COUNT(ctfile, needle, augment , substring , noadd)
  123.     filename=SREF_DO_VIRTUAL(defdir,aurl,envstring,docheck,trans,homedir,hnick)
  124.     mimetype=SREF_MEDIATYPE(filename,port)
  125.       newurl=SREF_FIX_URL(local_url,servername,serverport)
  126.  
  127.  
  128. String related procedures:
  129.    newstring=SREF_REPLACESTRG(haystack,needle,replacement, type , exactmatch)
  130.    newstring=SREF_WILDCARD(original, needle replacement,doexact)
  131.    matchinfo=SREF_WILD_MATCH(needle,haystack,old_matchinfo,suppress_noslash)
  132.       ablock=SREF_EXTRACT_BLOCK(haystack ,alabel ,delim1, delim2, delim3)
  133.       newval=SREF_INSERT_BLOCK(haystack,alabel,add_string,after,delim1,delim2)
  134.      astring=SREF_PACK64(packed_64_string)
  135. stg_packd_64=SREF_MKPACK64(astring)
  136.     md5_hash=SREF_MD5(astring,isfile)
  137.      astring=SREF_UNCHUNK(chunked_string,trailers)
  138.  stg_chunked=SREF_CHUNK(astring,trailers)
  139.      astring=SREF_UNGZIP(gziped_string)
  140.  stg_gzipped=SREF_GZIP(astring)
  141.    img_elems=SREF_DIGITS(astring,digname,ndigits,frame,nobr,options)
  142.        score=SREF_COMPWORD(needle,haystack)
  143.  
  144.  
  145. Variable/time/version lookup procedures:
  146.        value=SREF_VALUE(varname,newval,env,optinfo)
  147.        value=SREF_QUEUE(queuename,action,aval,port)
  148.         aval=SREF_CGIVARS(cgi_bin_variable)
  149.      timestr=sref_gmt(offset,basetime,outtype,gmtoffset)
  150.  
  151.      juldate=SREF_JULDATE(mode, time_string)
  152.  filter_name=SREF_VERSION(port)
  153.     errmess=SREF_ERROR(amessage,do_pmprintf)
  154.  
  155. Internet info & retrieval procedures
  156.      aresult=SREF_HOST(ipaddress)
  157.         aval=SREF_BROWSER_INFO(field,browser,envstring)
  158.        stuff=SREF_GET_URL(url,maxchar,verbose,headers)
  159.        stuff=SREF_HOST_INFO(myaddr0,nhosts,envstring)
  160. cookie_value=SREF_GET_COOKIE(cookie_name,nth)
  161.          res=sref_dynamic_pwd(appname,newlocation,privset2,duration,respfile,clientaddr)
  162.  
  163.  
  164. Daemon related procedures
  165.        status=SREF_DMN_LAUNCH(daemon_name,file_name,optional_arg)
  166.        status=SREF_DMN_EXIST(daemon_name)
  167.         value=SREF_DMN_ASK(daemon_name,an_argument,max_wait)
  168.  request_info=SREF_DMN_WAIT(daemon_name,max_wait)
  169.   an_argument=SREF_DMN_VALUE(request_info)
  170.        status=SREF_DMN_REPLY(request_info,reply_stuff)
  171.        status=SREF_DMN_KILL(daemon_name)
  172.  
  173. Miscellaneous
  174.      status=SREF_MAILIT(address_list,message,smtp_gateway,sender_address)
  175.        rcode=SREF_MULTI_SEND(message,mime_type,howsend,file_flag,verbose)
  176.          foo=SREF_EXPIRE_RESPONSE(aoffset,alength,atype,noauto)
  177.          foo=PMPRINTF_SREF(astring,nofile,port)
  178.        results=SREF_FIND_INDEX(target,qname,varname,nth,loc_only,timeout)
  179.  
  180.  
  181. Short descriptions:
  182.  
  183. SREF_GOS: Send information to client in a http/1.1 compatible way.
  184. SREF_OPEN_READ: Open a file, with waiting if the file is currently locked
  185. SREF_GRAB_FILE: Open file (with waiting), and then read it in to a string variable
  186. SREF_CONJUREF: Cleanup temporary directory, and then derive new filenames
  187. SREF_SEARCH_FIXED: Binary (or wildcard) search of fixed-length record file
  188. SREF_LOOKUP_COUNT: Lookup and increment an SRE counter file
  189. SREF_DO_VIRTUAL: Map a URL to a virtual directory
  190. SREF_MEDIATYPE: Determine mime type of a file
  191. SREF_FIX_URL: Create fully qualified URL from local URL
  192.  
  193. SREF_REPLACESTRG: Replace occurences of needle, in haystack, with replacement
  194. SREF_WILDCARD: Deterimine if needle is a "wildcard" match of haystack
  195. SREF_EXTRACT_BLOCK:  Extract a delimited block of text from a string
  196. SREF_INSERT_BLOCK: Insert block of text between delimiters
  197. SREF_PACK64: Convert a "pack64" format string to original characters
  198. SREF_MKPACK64: Convert a string to its "pack64" equivalent
  199. SREF_MD5: Make an MD5 "digest" of a string, or of a file
  200. SREF_UNCHUNK: Unchunk a "chunked" string
  201. SREF_CHUNK: Create a chunked string
  202. SREF_UNGZIP: Unzip a "gzip" compressed string 
  203. SREF_GZIP: Create a "gzip" compressed string
  204. SREF_DIGITS: Returns a list of IMG elements that point to digit .GIFs
  205. SREF_COMPWORD: Matches a "needle" to a "haystack" -- return a 1-100 score.
  206.  
  207. SREF_VALUE: Value of a variable from an OS/2 or SRE-http "environment"
  208. SREF_QUEUE: Read,write, and manipulate an SRE-http "queue"
  209. SREF_CGIVARS: Get the value of one of the CGI-BIN environment variables
  210. SREF_GMT: Compute a new GMT time, given an offset in fractional days
  211. SREF_JULDATE: Return absolute fractional date (since 0/0/1)
  212. SREF_VERSION: Return version of SRE-http
  213. SREF_ERRROR: Read/record an error message
  214.  
  215. SREF_HOST: Return IP address given name (or vice versa)
  216. SREF_BROWSER_INFO: Get spec-info on a browser
  217. SREF_GET_URL: Go to a web server and GET a URL (the complete contents)
  218. SREF_HOST_INFO: Return the "host nickname", given a servername
  219. SREF_GET_COOKIE: Get value of a cookie
  220. SREF_DYNAMIC_PWD: Prompt the client for a "dynamic password"
  221.  
  222. SREF_DMN_LAUNCH: Launch a daemon
  223. SREF_DMN_EXIST: Check if daemon's queue and semaphore are open
  224. SREF_DMN_ASK: Query the daemon for some information, wait for reply
  225. SREF_DMN_WAIT: Daemon uses this to listen for queries
  226. SREF_DMN_VALUE: Used by daemon to parse queries
  227. SREF_DMN_REPLY: Used by daemon (to reply to SREF_DMN_ASK)
  228. SREF_DMN_KILL: Kill a daemon's queue and semaphore
  229.  
  230. SREF_MULTI_SEND: Send a sequence of documents 
  231. SREF_MAILIT: Send mail via an SMTP server
  232. SREF_EXPIRE_RESPONSE: Modify the automatically generated expiry response header
  233. PMPRINTF_SREF: A front-end (with error checking)for PMPRINTF
  234. SREF_FIND_INDEX: Find a match in an SRE-Data file (requires SRE-Data addon)
  235.  
  236.       ---------------------------------------------------------
  237.                      Longer Descriptions (alphabetically sorted)
  238.       =========================================================
  239.  
  240.  
  241. -------         ----------          ---------          ------------
  242. PMPRINTF_SREF:  A pre-process for the REXXLIB PMPRINTF routine.
  243.  
  244. PMPRINTF_SREF is used throughout SRE-http as a means of reporting run-time
  245. status information.  PMPRINTF_SREF typically calls the PMPRINTF procedure,
  246. which will then display results in a PMPRINTF window.  PMPRINTF_SREF will
  247. check for a few overflow conditions, thereby avoiding sys3175 errors.
  248.  
  249. In addition, PMPRINTF_SREF checks the SREF_PMPRINTF_LINE_LENGTH
  250. and SREF_PMPRINTF_LOG_FILE environment variables.  These variables, set
  251. in SREFMON.CMD, control the maximum line length to be displayed (longer lines will wrap),
  252. and whether or not to log results to an SRE-http audit file
  253.  
  254. Usage:
  255.   CALL  PMPRINTF_SREF(astring,nofile,port)
  256. where
  257.   astring : the string to write
  258.   nofile : optional. If 1, then suppress writing to the PMPRINTF_LOG_FILE.
  259.   port: optional, the port of the server
  260.  
  261.  
  262. Restrictions: If called from a non-addon, you MUST include the port.
  263.  
  264.  
  265.  
  266. -------         ----------          ---------          ------------
  267.  
  268. SREF_BROWSER_INFO
  269.  
  270. Return information about a browser. 
  271.  
  272. Usage: 
  273.   aval=sref_browser_info(field,browser,envstring)
  274. where 
  275.    field:  the field to get information on:
  276.    browser:  optional: a "user-agent" identifying string.
  277.          If this is not included, then the user-agent request header
  278.          is used.
  279.    envstring: only needed if called from non-addon (see restrictions)
  280.  
  281. Output: The result
  282.  
  283.  
  284. The following fields are supported, with possible values noted. 
  285. Note that if no information is available for an item. Or, a number
  286. < 0 is returned to signify an error:
  287.    -1 = BROWSERS.IDX file unreadabld
  288.    -2 = Can not find entry for this user-agent
  289.    -3 = No value for this field, for this user-agent
  290.    -4 = BROWSERS.IDX file not found
  291.  
  292.   user_agent = User-agent of browser
  293.   browser = Vendor of the Browser
  294.   cookies =Cookie capable? YES or NO.
  295.   security = Type of security. NO, SHTTP, or SSL.
  296.   tables = Understands tables (YES NO)
  297.   date = The date this table entry was entered or most recently 
  298.           modified. YY/MM/DD
  299.   redirectlimit = Maximum length of redirection string.
  300.                  Integer between 255 and 8000
  301.   maxlinklen = Maximum characters in url
  302.                  Integer between 255 and 8000
  303.  
  304.  
  305. Citation: This procedure uses browser.idx, which is based on information from:
  306. http://website-1.openmarket.com:80/browsertest/prob/bt-maker.cgi?DataFile
  307.  
  308. Hint: Since browsers are coming and going, you may want to check the
  309.       SRE-http home page for new versions of BROWSERS.IDX. Or,
  310.       you can generate a new version of BROWSERS.IDX with 
  311.       BROWSERS.CMD (run it from an OS/2 command prompt).
  312.  
  313.       BROWSERS.CMD can also be called as an SRE-http addon.  It
  314.       will read BROWSERS.IDX and display information about your
  315.       browser's capabilities.
  316.       
  317. Examples:
  318.      tableok=sref_browser_info('TABLES')
  319.      docook=sref_browser_info('COOKIES')
  320.      security1=sref_browser_info('security','IBM WebExplorer DLL /v1.03')
  321.  
  322.  
  323. Restrictions: if called from a non-addon, you must supply an "environment
  324. string". This will have the form  SREF_nn_, where nn is the current
  325. port (i.e.; nn=80).
  326.  
  327.  
  328.  
  329. -------         ----------          ---------          ------------
  330.  
  331. SREF_CGIVARS(Varname)
  332.  
  333. Usage: aval=sref_cgivars(cgi_bin_variable)
  334.  
  335. Returns: value of the CGI_BIN variable (if available)
  336.  
  337. Note that:SCRIPT_NAME, PATH_INFO, PATH_TRANSLATED, and REMOTE_IDENT,
  338. PATH_INFO, PATH_TRANSLATED, and QUERY_STRING are not available. When
  339. one of these variables is requested, a ' ' is returned
  340.  
  341. Note that this will NOT look in environment, but will determine the
  342. values each time.  In other words, this not designed for use
  343. in cgi-bin scripts (you should use x=value(varname,,'os2environment)
  344. instead); it is designed for use in INTERPRET includes and in
  345. directly called REXX server side programs).
  346.  
  347. Example:   aval=sref_cgivars('server_software')
  348.  
  349. Restrictions: should ONLY be called from an SRE-http addon. 
  350.  
  351. -------         ----------          ---------          ------------
  352. SREF_CHUNK: Chunk a string
  353.  
  354. Usage: chunked_string=sref_chunk(astring,final,trailers)
  355.  
  356. Create a "chunked" string; which is suitable for http/1.1 transfer.
  357.  
  358. FINAL  should be 1 if this is the last of a sequence of chunked strings
  359. (or if this is the "first of one").  
  360.  
  361.    *** Failure to include a "final" chunked sequence is an error! ***
  362.  
  363. The trailers argument is optional. When present (at it should only
  364. be included when final=1) the value of trailer (typically crlf'ed
  365. delimited set of trailers) is added to the end of the chunked
  366. message.
  367.  
  368.  
  369. Restrictions: none
  370.  
  371.  
  372. -------         ----------          ---------          ------------
  373. SREF_COMPWORD: Compare two words and return a score
  374.  
  375. Usage: 
  376.  
  377.     score=sref_compword(needle,haystack)
  378.  
  379. where:
  380.    needle : the word to compare 
  381.  haystack : the word to compare against
  382.  
  383. SREF_COMPWORD will compare the needle against the haystack and return a 
  384. score that indicates how closely they match.  A score of 100 means "perfect
  385. match", while a score of 0 means "no match". 
  386.  
  387. SREF_COMPWORD uses a simple pattern matching algorithim (based on 
  388. looking for many possible substrings of the needle in the haystack).
  389. The greater the number of substrings, and the closer they are
  390. in letter position, the better the match.
  391.  
  392. Note that the definition of which word is the needle and which is the 
  393. haystack is somewhat arbitrary. However, it can make a difference in
  394. the score!
  395.  
  396.  
  397. Examples: ascore=sref_compword("FORIM1","FORMULA")
  398.           ascore=sref_compword("FORIM1","THEMR1")
  399.           ascore=sref_compword("FORIM1","EXACT1")
  400.      would yield scores of 0.170, 0.034, and 0.016  (respectively)
  401.      In contrase:
  402.           ascore=sref_compword("FORMULA","FORIM1")
  403.           ascore=sref_compword("THEMR1","FORIM1")
  404.           ascore=sref_compword("EXACT1","FORIM1")
  405.      would yield scores of 0.124, 0.037, and 0.016  (respectively)
  406.  
  407.  
  408. Restrictions: none
  409.  
  410.  
  411. -------         ----------          ---------          ------------
  412.  
  413. SREF_CONJUREF : Create/delete temporary files
  414. Usage: newfiles=sref_conjuref(basedir,basenames,extlist,minfree,mintime)
  415.  
  416.         basedir: directory to clean up (if > 10 files,
  417.               remove all files > mintime hours old)
  418.         basenames: list of (up to 4-char) file-stems to be used
  419.                  (a random element will be added)
  420.         extlist: list of up to 10 extension to be added to this file-stems
  421.  
  422.      So, if base= ZDOG,ZMOM and EXTLIST is FOO,CAT,001 then this will create
  423.      ZDOGxxxx.FOO, ZMOMxxxx.CAT and ZMOMxxxx.001, where xxxx is some 4 digit
  424.     random # (guaranteed to cause unique file names to be selected) 
  425.     (note replication to generate as many names as longest list)
  426.  
  427.        minfree: Try to get this much space free by deleting files 
  428.                 from basedir (in kb)
  429.        mintime: But don't delete anything less than this hours old
  430.  
  431. Return:   If newfiles=0, then could not create (say, minfree was violated)
  432.           Else, comma delimited list of file names 
  433.                 that can be used as temporary files.
  434.  
  435. CAUTION: Be careful what you choose as your basedir (you could automatically
  436. delete important stuff if your basedir is not strictly a "temporary files"
  437. directory).
  438.  
  439. Restrictions: none
  440.  
  441. -------         ----------          ---------          ------------
  442.  
  443. SREF_DMN_LAUNCH, SREF_DMN_EXIST, SREF_DMN_ASK, SREF_DMN_WAIT,
  444. SREF_DMN_VALUE, SREF_DMN_REPLY, SREF_DMN_KILL: A set of procedures to
  445. use with daemons.
  446.  
  447. The several SREF_DMN_ procedures are used to launch, communicate with,
  448. and kill deamons.  Daemons are semi-permanent threads running
  449. under the GoServe process. Among other advantages, they offer a 
  450. convenient means of storing data for quick retrieval, provide 
  451. system monitoring capabilities, and allow one to perform 
  452. non-time sensitive actions efficiently.  Section II of this
  453. document discusses daemons in greater detail.
  454.  
  455. For a complete description of how to use these SREF_DMN_ procedures,
  456. please see DAEMONS.DOC.
  457.  
  458.  
  459. -------         ----------          ---------          ------------
  460. SREF_DIGITS
  461.  
  462. Usage: 
  463.  
  464.     txtstring=SREF_DIGITS(amess,digit_name,nd,useframe,nobr,opts,imgdir)
  465.  
  466. where:
  467.   txtstring :  a text string containing a sequence of <IMG elements, that
  468.                point to the appropriate graphical digits
  469.  
  470.       amess : a string of characters, typically-but-not-always digits,
  471.                   to display 
  472.  digit_name : the name of the subdirectory containing the digit, 
  473.               and/or character-image, .GIF files.  
  474.               This subdirectory must be relative to the
  475.               imgdir directory (as specified below).
  476.  
  477.               If digit_name is not specified, WHITBLAK is used.  
  478.  
  479. The remaining arguments are optional.
  480.  
  481.          nd : the number of characters to display. 
  482.               If nd is longer then the number of characters in amess...
  483.                 a) if amess only contains digits, then 0's will be
  484.                    used as a padding character 
  485.                 b) if amess contains non digit charcters, the "default"
  486.                    character (specified in the "match file") is used
  487.                    as a padding character
  488.    useframe : if 1, then include a "left and right" frame
  489.               around the characters (see the "frame" option above for details)
  490.        nobr : if 0, then do NOT put a <NOBR> and </NOBR> around the
  491.               IMG elements (that comprise the message)
  492.      opts   : a string to be included in the IMG elements. 
  493.               For example:
  494.                 ' ALIGN=CENTER VALIGN=TOP'
  495.                 ' VALIGN=MIDDLE WIDTH=12 HEIGHT=12 '
  496.               In other words, opts can be a list of any IMG element
  497.               modifers.
  498.               Note that this "opts" list is included in all IMG elements,
  499.               including "frame" elements.
  500.      imgsel : the "counter_image_dir" selector.
  501.               If not specified, a value of "DIGITS" is assumed.
  502.      imgdir : Absolute path pointed to by the imgsel. If not specified, 
  503.               the DIGITS subdirectory of the GoServe data directory
  504.               is used.
  505.         
  506.   
  507. For details on how to use SREF_DIGITS, see COUNTER.DOC
  508.  
  509.  
  510. -------         ----------          ---------          ------------
  511.  
  512. SREF_DO_VIRTUAL: Convert a url into an fully qualified file name.
  513.  
  514. Usage: 
  515.      filename=sref_do_virtual(defdir,aurl,envstring,docheck,trans,homedir,hnick)
  516.  
  517. where:
  518.         defdir: Default drive&directory to use. If not supplied,
  519.                 the default data directory is used (see restrictions below)
  520.         aurl :  A url (of the form /A1/A1/FILE.EXT) to
  521.                 convert to an fully qualified file name.
  522.     envstring: An "environment variable prefix".  If
  523.                 not supplied, one will be built (based on
  524.                 the current http port, as supplied by GoServe) --
  525.                 but see restrictions below.
  526.        docheck: If 1, then check to see if the file exists.
  527.                 If it doesn't, return 0.
  528.         trans: A unique transaction number.  If not supplied,
  529.                the current transaction number is used (as
  530.                supplied by GoServe).
  531.        homedir: The "home directory" replacement string for 
  532.                the ~ character (may be host specific)
  533.                If no homedir argument, the home_dir environment
  534.                variable is used.
  535.        hnick  : Host nickname -- used to identify the "host".  It is
  536.                 used to identify "host sensitive" virtual directory 
  537.                 entries.
  538.  
  539.      If docheck=0, or if docheck=1 and a file with the constructed name 
  540.      exists. returns a  fully pathed file name based on the url and 
  541.      either defdir or a match between aurl and the virtual file list.
  542.      If docheck=1 and this match does not exist, returns a 0.
  543.  
  544. Examples:
  545.     * newfile=sref_do_virtual(,'/herfiles/wedding1.jpg)
  546.       If "herfiles" does not match a virtual directory, then
  547.       newfile=ddir/herfiles/wedding1.jpg
  548.  
  549.    *  giants=sref_do_virtual('d:\teams','/stars/willymays.html')
  550.       If no virtual directory match to "stars", then 
  551.       giants=d:\teams\stars\willymays.html
  552.  
  553.      filename=sref_do_virtual(defdir,aurl,envstring,docheck,trans,homedir,hnick)
  554.  
  555.    *  mymad=sref_do_virtual('d:\journals','fun/mad.doc',,1,,,'SITE2A')
  556.       First useentries for the SITE2A  host, and then "generic entries".
  557.       If mad.doc does not exist, return a 0.
  558.  
  559.    * realdir=sref_do_virtual(,'WWW2/')
  560.      The virtual directory corresponding to "selectors" under WWW2/
  561.    
  562.  
  563. Caution: the virtual file list may contain http://xxx.yyy.zzz/abc entries.  
  564.           These are understood by the main SRE-http routine, but NOT by 
  565.           this procedure.
  566.           If such a match occurs, SREF_DO_VIRTUAL will return a 0.
  567.  
  568. Caution2: as illustrated in the fourth example,
  569.           if you wish to match a directory to a virtual directory
  570.           (without matching any specific filename), you MUST end
  571.           the "aurl" argument with a /.
  572.  
  573. Restrictions: if not called from an addon, you MUST supply ENVSTRING
  574. (i.e.; if the server is running on port 80, then ENVSTRING='SREF_80_').
  575. If called from a post-filter procedure or an stand alone program, you
  576. must supply (in addition to envstring) the defdir, the trans (you can use
  577. an arbitrary number), and the homedir. You do not need to supply
  578. the host_nickname (if not supplied, host-specific entries will not
  579. be used).
  580.  
  581.  
  582.  
  583. ------         ----------          ---------          ------------
  584. SREF_DYNAMIC_PWD
  585.  
  586. Usage:
  587.   res=sref_dynamic_pwd(appname,newlocation,privset2,duration,respfile,clientaddr)
  588. where
  589.   appname: recommended. the "application" calling this. Used to identify 
  590.            a "shared secret". If not specified, a value DYNPWD is used.
  591.            Note that APPNAME is also used in responses.
  592.   newlocation: recommended. The uri to invoke when client hits the submit
  593.                button. Default value is "/"
  594.   privset2 : REQUIRED. the space delimited list of "secret" privileges. 
  595.              It should contain an entry of the form APPNAME:shared_secret
  596.   duration: optional. duration of a timestamp, in days (and fractions of day)
  597.              (default value is 1 day)
  598.   respfile: optional.the "response file" containing the md5 procedure. If not
  599.             specified, DYNPWD.RSP, in the datadir(), is used.
  600.   clientaddr: client's numeric ip address. Optional, if missing, will get if
  601.             with a GOSERVE extract 
  602. and
  603.   resp='' 
  604.          if a valid password is found
  605. or 
  606.   resp='200 '||length(response) 
  607.         if no valid password is found, 
  608.         sref_dynamic_pwd asks the client to supply one -- this is the
  609.         response code for this "response"
  610.  
  611. To enable dynamic passwords, you must write an "sre-http" addon that
  612. calls the SREF_DYNAMIC_PWD procedure (SREF_DYNAMIC_PWD is loaded 
  613. into macrospace when needed).  
  614.  
  615. For further details, please see DYNPWD.DOC.
  616.  
  617.  
  618.  
  619. ------         ----------          ---------          ------------
  620. SREF_ERROR: Read/record a request specific  error message.
  621. Usage:
  622.    errmess=sref_error(amessage,do_pmprintf)
  623. where:
  624.    amessage= Optional. If supplied, amessage will be recorded.
  625.   do_pmprintf= Optional. If greater then or equal to 0, amessage will also 
  626.                 be written to the pmprintf window (using pmprintf_sref)
  627.  
  628. Return: The current error message for this request (possibly an empty string)
  629.  
  630. Each request has a "error-message" variable associated with it, which
  631. is initialized to an empty string when the request arrives.  SREF_ERROR
  632. can read from, or write to, this variable.  When no arguments are given
  633. (i.e.; errmess=SREF_ERROR()), then the current value is returned; if there
  634. have been no errors or warnings (that is, no calls to SREF_ERROR by SRE-http)
  635. a null string is returned.
  636.  
  637. When amessage is specified, the current value of the error-message variable
  638. is returned, and it is then set to be amessage.  In addition, amessage will
  639. be written to the SRE-http error log (i.e.; D:\GOSERVE\DATA\ERROR.LOG).
  640.  
  641. Lastly, if do_pmprintf is greater then or equal to 0, amessage will be written
  642. to the pmprintf window (pmprintf_sref is used).
  643.  
  644. Restriction: can only be called from an addon.
  645.  
  646. ------         ----------          ---------          ------------
  647.  
  648. SREF_EXPIRE_RESPONSE: Build a response header that does not have an
  649. immediate expiration.
  650.  
  651.  ***   USE OF SREF_EXPIRE_RESPONSE IS NO LONGER RECOMMENDED --   ***
  652.  ***                    USE SREF_GOS instead!                    ***
  653.  
  654. Usage: foo=sref_expire_response(aoffset,alength,atype,noauto,pragvalue)
  655.    aoffset is fraction of day to add to current date/time. This will
  656.      be converted to gmt (assuming gmt variables have been set, as described
  657.      in goserve.doc). If aoffset<0, then an "expires" header will Not
  658.      be written.  Default is 0.04
  659.  
  660.    alength is the size of the document being sent. Default is 0
  661.    atype is the mime type. Default is text/html
  662.    noauto= Y or N: If Y, or if missing, then suppress auto - headers.
  663.    pragvalue=value to use in a Pragma: header.
  664.              If 0, suppress Pragma header.              
  665.              If not specified, a Pragma: no-cache header is added.
  666.            
  667.  
  668. Restriction: can ONLY be called from an addon.
  669.  
  670.  
  671. ------         ----------          ---------          ------------
  672.  
  673.  
  674. SREF_EXTRACT_BLOCK : Extract a "labeled block" from a string.
  675. Usage: ablock=sref_extract_block(haystack , alabel , delim1  , delim2  , delim3)
  676.  
  677.  Extract a block from haystack, defined by a Labeled block,
  678.   where the label has the form delim1 label delim2 multi-line_string delim3  xxx
  679.  Default values of delim1={,  2=}  3={
  680.  Note that labels must have NO embedded spaces.
  681.  
  682.  
  683. Example: if haystack= <!-- SELECT --> this is text to select <!-- END_SELECT -->
  684. and label=SELECT, delim1='<!--', delim2='-->, and delim3='<!--', 
  685. then ablock would be "this is text to select".  Note that the END_SELECT
  686. is ignored.  
  687.  
  688.  
  689. Restrictions: none 
  690.  
  691. -------         ----------          ---------          ------------
  692. SREF_FIND_INDEX  : Query an SRE-data daemon for a match
  693.  
  694. Usage
  695.    results=SREF_FIND_INDEX(target,qname,varname,nth,loc_only,timeout)
  696. where:
  697.    results = a 2 part response, seperated by a comma. The first part
  698.             is the "record # of the matching record", or a 0 if no
  699.             match, or less then 0 if an error. The second part is 
  700.             what was matched (i.e.; the record containing the targeted 
  701.             identifier); or a blank if no match (or error) occured.
  702.   target = the string to search for>
  703.   qname  = the "name" used when sredata was invoked 
  704.   varname = (optional) Search by varname, not by "identifier"
  705.             Or, invoke a special command
  706.    nth    = (optional) return nth match
  707.   loc_only = (optional) Return location, do not return a "value"
  708.   timeout=   (optional)  max seconds to wait on daemon
  709.  
  710. SRE_FIND_INDEX is designed to work with the SRE-Data addon.
  711.  
  712.  
  713. -------         ----------          ---------          ------------
  714.  
  715. SREF_FIX_URL  : Creates a proper HTTP URL.
  716.  
  717. Usage:  
  718.    newurl=sref_fix_url(local_url,servername,serverport)
  719.  
  720. Servername and serverport are optional; if not supplied the 
  721. current (canonical) servername and port are used (but see restrictions
  722. for a proviso). Local_url can either be a (local) selector, or it can be 
  723. a fully qualified URL.
  724.  
  725. The newurl will contain the http://, servername and port, and selector;
  726. where the selector may be a substring of the local_url.
  727.  
  728. Note that SREF_FIX_URL will NOT add servername and serverport information
  729. if the local_url already contains it
  730.  
  731. Also not that this may not work if the local_url contains periods
  732. in subdirectory names.
  733.  
  734.  
  735. Examples (assuming the server's address is foo.bar.net on port 80):
  736.  
  737.  *   newurl=sref_fix_url('dir1/prices.htm')
  738.         will return http://foo.bar.net/dir1/prices.htm
  739.  
  740.  *   newurl=sref_fix_url('dir2/quality.shtml','joes.store.com')
  741.         will return http://joes.store.com/dir2/quality.shtml
  742.  
  743. Restrictions: if called from a non-addon, you MUST provide the servername
  744. and serverport. If are using a multi-host server and want to redirect
  745. back to your own server, you SHOULD provide the appropriate servername
  746. (it is risky to assume that the "canonical" servername is appropriate).
  747.  
  748.  
  749.  
  750. -------         ----------          ---------          ------------
  751.  
  752. SREF_GET_COOKIE:  Check for a cookie
  753. Usage: cookie_value=sref_get_cookie(cookie_name,nth)
  754.  
  755. SREF_GET_COOKIE will check the request header for the "nth" cookie with
  756. the name given in cookie_name. If found, its value will be returned.
  757. If not found, an empty string will be returned.  Note that if nth is
  758. not included, the first matching cookie is used.
  759.  
  760. For example, if the request header contains:
  761.    cookie:  customer=wiley_coyote
  762. then
  763.    sref_get_cookie('customer') will return "wiley_coyote"
  764.  
  765. Alternatively:
  766.    cookie:  customer=wiley_coyote ; item=bazooka ; customer=roadrunner 
  767. then sref_get_cookie('customer',2) will return "roadrunner"
  768.  
  769. Note: cookie_name is case insensitive, but cookie_value is not
  770.  
  771. Restictions: can ONLY be called from an addon. In cgi-bin scripts, use 
  772. value('http_cookie',,'os2environment') instead.
  773.  
  774. -------         ----------          ---------          ------------
  775.  
  776. SREF_GET_URL  : Retrieves a resource, given a  URL to an HTTP server.
  777.  
  778. Usage:  stuff=sref_get_url(url,maxchar,verbose,headers)
  779.  
  780. Will do socket calls to do an http/1.1 style  "GET" of  a URL from an 
  781. http server.
  782.  
  783. Returns the resource sent by the server (without response headers).
  784.  
  785. Returns "0" (without the quotes) if any problem occurred (will also
  786. write a message to the SRE-http error log)
  787.  
  788. URL : The "URL" to request.  You can specify a fully qualified URL (such as
  789.       http://www.census.gov/index.htm), or a "local selector" (such as
  790.       /files/listing.htm).  In the latter case, the local server (and port)
  791.       is used).
  792.  
  793. MAXCHAR:  Will get first MAXCHAR characters; if MAXCHAR is missing, get 
  794.            first 10 million (presumably you'll never ask for more then that!)
  795.  
  796. VERBOSE:  If 1, PMPRINTF some stuff
  797. HEADERS:  Optional request headers to add. Each request header should be seperated by a
  798.           CRLF ('0d0a'x). For example:
  799.              headers='Referer:me@someplace'||'0d0a'x||'User-Agent: Mozilla 2.0 (emulating)'
  800.                 
  801.  
  802. CITATION: SREF_GET_URL is adapted from MOVEAUD.CMD, that comes with GoServe.
  803.  
  804. Restrictions: none
  805.  
  806.  
  807. -------         ----------          ---------          ------------
  808.  
  809. SREF_GRAB_FILE: Read a file, and return it (and wait if it's currently locked)
  810. Usage:   afile_string=sref_grab_file(afile,seconds_to_try_for)
  811.                (see descriptions above)
  812.  
  813. Returns:
  814.    If file exists/is accessible, returns the file (complete with all
  815. CRLF's etc.). If file does not exist/ is not accessible, returns a 0.
  816.  
  817. Caution: If the file just contains a 0, then the afile_string will
  818.          equal 0.  In these cases,the use of 0 as an "error" code
  819.          is obviously misleading.
  820.  
  821. Restrictions:none
  822.  
  823. -------         ----------          ---------          ------------
  824. SREF_GOS: Send information to a client in an http/1.1 compatible way
  825.  
  826. Usage: 
  827.  
  828.   status  =SREF_GOS(acmd,varname,dorange,hdrs)
  829. where
  830.    acmd = A content transfer command. ACMD has two modes: FILE and VAR
  831.  varname= When a VAR type of acmd, the stuff to send
  832.  dorange= If 1, then check for range requests
  833.  hdrs   = CRLF delimited list of extra response headers. I.e.; the contents
  834.           of an advanced-options file.
  835.  
  836. In most cases, you won't need to specify dorange and hdrs. However,
  837. hdrs can be very useful when you want to fine tune the response headers;
  838. for example, if you want to control the value of the cache-control response
  839. header.
  840.  
  841. Basically, using SREF_GOS is like issuing a GoServe completion code --
  842. but instead of issuing the completion code by itself, you use it as the
  843. acmd argument.
  844.  
  845. For example, instead of:
  846.    'FILE type text/html name d:\www\bar.htm'
  847. you should use a FILE mode call of:
  848.    stat=sref_gos('FILE type text/html name d:\www\bar.htm')
  849.  
  850. Similarly, instead of:
  851.     'VAR type text/plain name make_stuff'
  852. you should use a VAR mode call of:
  853.     stat=sref_gos('VAR type text/plain name make_stuff',make_stuff)
  854. (the 'name make_stuff' portion of the acmd argument is optional).
  855.  
  856. The following elements are permitted in both the FILE and VAR versions of
  857. the acmd argument.  Note that most of these are the same as in the native
  858. GoServe calls; with some additional meanings.
  859.  
  860.  NAME 
  861.    Used in FILE mode calls -- the next word is the file to
  862.    send to the client.
  863.    Example: 'FILE type text/html NAME D:\WWW\FOO.HTM'
  864.  
  865.  TYPE   
  866.    The mime type of the content (used to create content-type header)
  867.  
  868.  ENCRYPT enctype
  869.    Instruct SREF_GOS to encrypt the response.
  870.    Enctype should have the following structure:
  871.       method:epwd
  872.    where
  873.       method = the encryption method. SRE-http provides SRE_A and SRE_B
  874.                methods.
  875.       epwd   = the "shared-secret" encryption password. This is typically
  876.                found in a client's ?ENCRYPT:epwd "server privilege".
  877.    For example:         
  878.                 ENCRYPT SRE_A:foorab
  879.  
  880.    Notes:
  881.      * use of an ENCRYPT option in an SREF_GOS call will
  882.        override the various "default" and "advanced option" encryption
  883.        options. 
  884.      * To disable encryption, use ENCRYPT 0:0
  885.      * For further discussion of encryption, see ENCRYPT.DOC.
  886.  
  887.  ERASE      
  888.    Temporary response -- set the max-age header to 0.
  889.    Also: If FILE mode, then delete the NAMEd file after sending it. 
  890.    If VAR, ERASE is the default (but nothing actually get's erased). 
  891.  
  892.  ETAG an_etag
  893.    The ETAG to use. If not specified, SREF_GOS will compute one.
  894.    Caution: if you specify an ETAG. delta-encoding will be suppressed
  895.             (see DELTA.DOC for the details).
  896.  
  897.  MAXAGE nnn
  898.     Set the max-age cache-control option; where max-age nn should be
  899.     number of days (decimal values are allowed). Or, you
  900.     can specify Hours, Minutes, or Seconds.
  901.     For example:
  902.         MAXAGE .04  
  903.         MAXAGE 0.04D
  904.         MAXAGE  1H
  905.         MAXAGE 45M
  906.         MAXAGE 1800S
  907.  
  908.     Note that if ERASE is used, then MAXAGE nnn is ignored
  909.  
  910.  NOERASE
  911.    Non-temporary response. This is ignored in FILE mode, but suppresses
  912.    the max-age=0 if used with VAR.
  913.  
  914.  NOCACHE  
  915.    Suppress public caching (private caching is allowed)
  916.  
  917.  NOCACHE* 
  918.    Suppress all caching (public, private, and sreproxy caching is NOT done).
  919.  
  920.  NOIF
  921.    If NOIF appears, then SRE-http will not check the various If-
  922.    conditions (such as If-Modified-Since)
  923.  
  924.  CACHE  
  925.    Enables public caching.
  926.  
  927.  CACHE*
  928.    Enables public caching, and enables the GoServe cache.
  929.  
  930.  RESPONSE    
  931.    Change the http response code. If not specified, SREF_GOS determines
  932.    the response (typically, 200 Ok).
  933.    The word following RESPONSE should be the response line -- 
  934.    which should consist of a number and a short description.  
  935.    The number and the description should be seperated by url-encoded
  936.    spaces (%20).
  937.    Example: 
  938.       'FILE type text/html NAME D:\WWW\FOO.HTM RESPONSE 201%20Content%20Created'
  939.  
  940.  CLOSE
  941.    Force an immediate close of the connection 
  942.    (normally, http/1.1 clients are  maintained).
  943.    Example: 'FILE close type text/html NAME D:\WWW\ERROR.HTM'
  944.  
  945. Notes:
  946.   * By using SREF_GOS, you can ensure that appropriate http/1.1 
  947.     style headers are added to the response.  
  948.   * Furthermore, SREPROXY only knows about responses returned via SREF_GOS.
  949.  
  950.  
  951. SREF_GOS and cache control.
  952.  
  953.    The Cache-control response header  is used to instruct
  954.    caches (both on proxy servers, and on client's machine) when
  955.    and how to cache a response.
  956.  
  957.    SREF_GOS uses a somewhat convoluted set of rules to construct a
  958.    "Cache-control" response header. These rules consider:
  959.       i) Whether VAR or FILE is used
  960.      ii) Whether  ERASE, NOERASE, CACHE, CACHE*, NOCACHE, or NOCACHE* is specified
  961.     iii) The value of the PROXY_CACHE parameter
  962.  
  963.   In some cases these SREF_GOS rules, and the kind of controls you may have using
  964.   the above factors, may be unsatisfactory.  For example, clients may
  965.   be over-refreshing.  If this should occur, use of the hdrs argument (the 4th
  966.   argument) can be helpful.
  967.  
  968.   HDRS should be CRLF ('0d0a'x) delimited list of statements of the form
  969.     'HEADER ADD name: value '.
  970.    or
  971.     'HEADER DROP NAME:'
  972.  
  973.   In particular, you may wish to use:
  974.      'HEADER ADD Cache-Control: cache_tokens'
  975.   where cache_tokens are a list of cache-control tokens (as described in RFC2616).
  976.  
  977.   For example:
  978.     hdr='HEADER ADD Cache-control: private,max-age=200'
  979.     foo=sref_gos('FILE type text/html ERASE name d:\temp\foo.1 ',,,hdr)
  980.  
  981.  
  982. Restrictions: can only be called from SRE-http addons.
  983.  
  984. -------         ----------          ---------          ------------
  985.  
  986. SREF_GZIP: Create a "gzip" compressed string
  987.  
  988.   usage: string_gzipped=sref_gzip(astring)
  989.  
  990. The inverse of SREF_UNGZIP.
  991.  
  992. Typically, string_gzipped with be written to a .GZ file.
  993.  
  994. Restrictions: uses the rxGZlib.dll library that comes with SRE-http -- make sure
  995.              that rxGZlib.dll is in a LIBPATHed directory.
  996.       
  997.  
  998. -------         ----------          ---------          ------------
  999.  
  1000.  
  1001. SREF_HOST: A "host lookup"
  1002. Usage:  aresult=sref_host(ipaddress)
  1003.         IPaddress can be numeric or character (with appropriate periods)
  1004. Aresult is a sentence noting the ipaddress and the name associated with it.
  1005.  
  1006. Restrictions: none
  1007.  
  1008.  
  1009.  
  1010. -------         ----------          ---------          ------------
  1011.  
  1012. SREF_HOST_INFO: Return "host specific" information.
  1013.  
  1014. SREF_HOST_INFO uses the server's ip address, and any HOST: header, to
  1015. find a matching entry in the HOSTS. variables.
  1016.  
  1017. Usage  stuff=sref_host_info(myaddr0,nhosts,envstring)
  1018.  
  1019.    where: myaddr0 = the ip address of the server (to whom the request was sent)
  1020.           nhosts = the number of hosts defined in the HOSTS. variables
  1021.        envstring = environment variable preface
  1022. and stuff will contain
  1023.   0 = No match in HOSTS variables
  1024.      or
  1025.   parse var stuff servername ',' nickname ',' ddir 
  1026.     where
  1027.       servername : the servername for this request (possibly pulled from
  1028.                    a HOST: request header)
  1029.       nickname : SRE-http nickname for this servername 
  1030.       ddir     : Default data directory
  1031.  
  1032. If myaddr0,nhosts, and envstring are not specified, sref_host_info will
  1033. figure them out.
  1034.  
  1035. Restrictions: can  ONLY be called from an ADDON (uses the GoServe REQFIELD function)
  1036.  
  1037. -------         ----------          ---------          ------------
  1038.  
  1039.  
  1040. SREF_INSERT_BLOCK : Insert a block into a string, at a "labeled" location.
  1041. Usage: 
  1042.   newhaystack=sref_insert_block(haystack,alabel,add_string,after,delim1,delim2)
  1043.  
  1044.    Insert a add_string into haystack, right  after or before aLabel.
  1045.      where the alabel has the form delim1 label delim2
  1046.    Insertion is immediately after delim2, or before delim1
  1047.    (if after=1, then after)
  1048.    Default values of delim1={,  2=}
  1049.    Note that labels must have NO embedded spaces.
  1050.  
  1051. Returns the added to (or not added to) haystack
  1052.  
  1053. Restrictions:none
  1054.  
  1055.  
  1056. -------         ----------          ---------          ------------
  1057.  
  1058.  
  1059. SREF_JULDATE  : Returns julian date (since  1/1/0000) and fractional time
  1060.  
  1061. Usage: 
  1062.    juldate=sref_juldate(mode, time_string)
  1063. where:
  1064.       mode: F: Date/time is: yy/mm/dd/hh/mm/ss mode 
  1065.                as returned by sysfiletree(afile,'stem','FT')
  1066.             T: Date/time is: yyyymmdd hr : mm : sec
  1067.                as returned by: adate=date('S')|| ' '||time()
  1068.   time_string: The time string (using one of the above modes)
  1069.                If time_string not specified, use current date & time.
  1070.  
  1071. Typical return: 729152.125451 ; with the fraction accurate to about 
  1072.                 a second.
  1073.  
  1074. Caution: we recommend using a rexx statement of "numeric digits 11"
  1075. before calling (otherwise, accuracy will be only good to a minute).
  1076. Example:
  1077.    numeric digits 11
  1078.    adate=word(sysfiletree(afile,'stem','FT'),1)
  1079.   jdate=juldate(adate,'F')
  1080.  
  1081.  
  1082. Restrictions: none
  1083.  
  1084.  
  1085. -------         ----------          ---------          ------------
  1086.  
  1087. SREF_LOOKUP_COUNT : Augment a SRE-http "counter file"
  1088. usage: 
  1089.    newcount=sref_lookup_count(ctfile, needle, augment , substring , noadd)
  1090. where:
  1091.        ctfile: Name of the "counter file" to examine 
  1092.                Should contain entries that have the format:
  1093.                Aurl  ACount  optional_info
  1094.        needle: The target of the search. Typically a URL.
  1095.       augment:  YES: augment the count
  1096.                 ADD: augment the count, or if needle can not be found,
  1097.                     add new entry with count=1
  1098.     substring: EXACT: Exact match only
  1099.                    *: Use wildcard match if no exact match
  1100.                           ABBREV: Use abbreviation match if no exact match
  1101.         noadd:     1: just return matching filename and message
  1102.                       (do NOT lookup count or augment)
  1103.                    2: set optional_info equal to the current date,
  1104.                       and augment the value of acount
  1105.  
  1106. Returns a space delimited list containing STATUS COUNT optional_info
  1107.      If status=0, then some failure, 1 then success,
  1108.      2 then no match, but we added it (only possible if AUGMENT =  ADD)
  1109.  
  1110.  
  1111. Restrictions: none
  1112.  
  1113.  
  1114. -------         ----------          ---------          ------------
  1115.  
  1116. SREF_MAILIT :  Use REXX socket calls to send e-mail
  1117. Usage: 
  1118.     status=sref_mailit(address_list,message,smtp_gateway,sender_address)
  1119.  
  1120. where:
  1121.     address_list: A space delimited list of addresses
  1122.          message: A message string, that may contain CRLFs
  1123.                  (and may be rather long)
  1124.     smtp_gateway: The IP address of your SMTP server
  1125.   sender_address: The sender's address (optional)
  1126.                  If sender's address  is not given, it will be generated using
  1127.                 GoServe's servername() function.
  1128.  
  1129.   Status: 0 if failure to connect, 1 if success
  1130.  
  1131.   Examples:
  1132.        status=mailit("BOB@HIS.NET" , "This is my message ", "MAIL.MY.ORG" )
  1133.        status= mailit("BOB@HIS.NET JILL@HER.COM " , "This is my message ", ,
  1134.                     "MAIL.MY.ORG", "HARRY@MY.ORG")
  1135.  
  1136.   Note on recipient addresses:
  1137.      The message will be sent to each address.  Since the addresses are
  1138.      sent and then the message, this allows for fairly rapid mailing to multiple
  1139.      individuals.
  1140.  
  1141.  
  1142. Notes:
  1143.    *  The POSTMAIL.80 "post-filter" uses a local version of SREF_MAILIT
  1144.    *  POSTMAIL.80 contains a useful discussion of some of the limitations of
  1145.       the OS/2 SENDMAIL 
  1146.    *  CITATION: SREF_MAILIT is a modification of a routine written by Dave Briccetti.  
  1147.                                                                                  
  1148.  
  1149. Restrictions: if NOT called from an addon, you MUST specify the sender_address.
  1150.  
  1151.  
  1152. -------         ----------          ---------          ------------
  1153.  
  1154. SREF_MAKE_BLOCK  : Replaces substrings with other substrings.
  1155. Usage: newhaystack=sref_make_block(needle, haystack, delim1 , delim2, check_case)
  1156.  
  1157.       Replace all occurences of NEEDLE in HAYSTACK with delim1 needle delim2.
  1158.       If delim1 and delim2 not given, then { AND } are used.
  1159.       Example: make_block('boys',' there are wild boys out there','<b>',' </b>')
  1160.            returns 'there are wild <b>boys </b> out  there'
  1161.            (note that spaces are all retained).
  1162.       IF check_case=1, then cases must match (between needle and haystack)
  1163.  
  1164. Restrictions: none 
  1165.  
  1166. -------         ----------          ---------          ------------
  1167.  
  1168. SREF_WILD_MATCH : Performs a wildcard match, with "is this better" check
  1169.  
  1170. usage:
  1171.     matchinfo=sref_wild_match(needle,haystack,old_matchinfo,suppress_noslash)
  1172. where:
  1173.     needle : the string to search for
  1174.   haystack : the string to search in, it can contain * wildcard characters
  1175.  old_matchinfo: matchinfo from prior calls to sref_wild_match using same needle
  1176.  suppress_noslash: if 1, then suppress the trailing-| "noslash" feature
  1177.  
  1178. SREF_WILD_MATCH returns information on the quality of the match, information
  1179. which can be used in subsequent calls to SREF_WILD_MATCH to treat "worse"
  1180. wildcard matches as non-matches. Thus, you can use a a series of calls to 
  1181. SREF_WILD_MATCH to find the "best match" of a needle against a set of 
  1182. haystacks that may contain wildcards.
  1183.  
  1184. Returns (note that all comparisions are case insensitive):
  1185.         Situation                          Returns
  1186.         ------------                       ----------
  1187.   If needle is exact match to haystack      -1
  1188.  
  1189.   If needle does not match haystack          0
  1190.   (even with wild card checking) 
  1191.  
  1192.   If needle wildcard matches haystack,       match information
  1193.    and old_matchinfo='' (or if           (a list of numbers signifying
  1194.    old_matchinfo is not specified            matching characters in needle)   
  1195.  
  1196.   If needle wildcard matches haystack,       match information
  1197.      and old_matchinfo<>''    
  1198.      and the current match is a "better"
  1199.      match then the "old_matchinfo" match 
  1200.  
  1201.   Same as above, but if the current          0
  1202.    match is NOT a better match          
  1203.  
  1204. Basically,
  1205.   -1 means "exact match",
  1206.    0 means "no match" or "not better match" (if old_matchinfo not specified, 
  1207.        0 always means "no match"), 
  1208.    and everything else means "wild card match" (that's better then prior
  1209.        "best" wildcard match).
  1210.  
  1211. Example of usage:
  1212.    /* Example of  use of sref_wild_match */
  1213.    a.1='This is *'
  1214.    a.2='This is a *'
  1215.    a.3='This is a funny * story'
  1216.    a.4='* is * '
  1217.    a.5='Th* fun*'
  1218.    a.6='This is funny *'
  1219.  
  1220.   say "Enter string : " ; parse pull ans
  1221.   old_matchinfo=''; isit=0
  1222.   do mm=1 to 6
  1223.      haystack=a.mm
  1224.      resu=sref_wild_match(ans,haystack,old_matchinfo)
  1225.      if resu=-1 then do
  1226.        isit=mm
  1227.        leave
  1228.      end
  1229.      if resu=0 then iterate
  1230.      isit=mm
  1231.      old_matchinfo=resu
  1232.   end
  1233.   matchingvar=isit
  1234.  
  1235. Thus, if you entered ..... then MATCHINGVAR would be equal to:
  1236.     That is silly                  4
  1237.     This is a man                  2
  1238.     This is not mine               1
  1239.     This is a funny but sad story  3  
  1240.     This is funny today            6
  1241.     That may be                    0  (no match)
  1242.     This is a *                    2  (exact match)
  1243.  
  1244. Caution: You MUST set old_matchinfo='' before the first call in a series of calls
  1245.        
  1246. SPECIAL FEATURE:
  1247.   If haystack ends with a |, then no "slash" is allowed in the
  1248.   final wildcarded portion of the needle.  That is, the portion of the needle
  1249.   "covered" by the final asterisk in the haystack can NOT contain a / or a \. 
  1250.   If it does, it's a NO MATCH.  
  1251.  
  1252.   Note that this feature is suppressed when suppress_noslash=1
  1253.  
  1254.  Examples:
  1255.     using a needle of: 
  1256.        animal/cats/food.1
  1257.   The follwing haystacks yield:
  1258.        animal/*candy  --  no match
  1259.        anim*/*.1      --  match
  1260.        animal/*.1|    --  no match (* covers cats/food, which contains a /)
  1261.        anim*/food*|   --  match (final * covers ".1")
  1262.        */cats*|       --  no match (final * covers "/food.1")
  1263.  
  1264.   The primary purpose of this feature is to "limit" wildcard matches to a 
  1265.   single subdirectory (that is, to prevent matches to items in deeper 
  1266.   portions of the directory tree)
  1267.   
  1268. Hint: if you don't care about "best matches", use 
  1269.             ismatch=sref_wild_match(needle,haystack)
  1270.       and treat any non-0 value of ismatch as signifying a match.
  1271.  
  1272. Restrictions: none
  1273.  
  1274. -------         ----------          ---------          ------------
  1275.  
  1276. SREF_MEDIATYPE :  Returns mime type of a file
  1277.     Usage: mimetype=sref_mediatype(filename,port)
  1278.  
  1279. filename: name of file to deduce mime type of
  1280. port: optional, used when caleld from non-addons
  1281.  
  1282. Uses the extension of filename to determine the mime type.
  1283. For example, AA.HTM would yield "text/html".
  1284.  
  1285. SREF_MEDIATYPE will check the MEDIATYP.RXX file (of custom media types),
  1286. that is located in the GoServe working directory.
  1287.  
  1288. Restrictions:
  1289.   if called from something other then an SRE-http addon, you MUST
  1290.   include a port. If called from a stand-alone, the mediatyp.rxx file
  1291.   will not be available.
  1292.   
  1293.  
  1294. -------         ----------          ---------          ------------
  1295.  
  1296. SREF_MD5 : Create a "MD5" digest
  1297.  
  1298.   usage    md5_digest=sref_md5(astring,isfile)
  1299.  
  1300. where:
  1301.    astring: the string to "digest", or a fully qualified file name
  1302.    isfile: If 1, then atring is a filename (the contents of the
  1303.            file will be md5'ized; not the filename itself.
  1304.  
  1305. MD5 is used in various cryptograhic settings. SRE-http uses MD5 to 
  1306. return content-md5 response headers (which provides an integrity check),
  1307. and in digest authentication (which sends an md5 encrypted password).
  1308.  
  1309. Restrictions: uses srxfunc.dll.
  1310.  
  1311.  
  1312. -------         ----------          ---------          ------------
  1313.  
  1314. SREF_MKPACK64 : Create a "base64" string.
  1315.  
  1316.    usage:  string_packed_64=sref_mkpack64(astring)
  1317.  
  1318. The inverse of SREF_PACK64.
  1319.  
  1320. Note that  astring=sref_pack64(sref_mkpack64(astring))
  1321.  
  1322. Caution: this is NOT very efficient for long string (say, greater
  1323.           then 3000 bytes).
  1324.  
  1325. Restrictions: none
  1326.  
  1327.  
  1328.  
  1329.  
  1330. -------         ----------          ---------          ------------
  1331. -------         ----------          ---------          ------------
  1332. -------         ----------          ---------          ------------
  1333.  
  1334.  
  1335.  
  1336. -------         ----------          ---------          ------------
  1337. SREF_MULTI_SEND : Facilitates creation of "multi-part" documents.
  1338.  
  1339. SREF_MULTI_SEND is used to create multi-part document. It can also
  1340. be used to "send pieces" of a document as it becomes available.
  1341.  
  1342.   usage:
  1343.     rcode=sref_multi_send(message,mime_type,howsend,file_flag,verbose,wname,optheaders)
  1344. where:
  1345.    message:  either contains the "message" to be send (either a text string or
  1346.              binary value); OR it contains a fully qualified file name.
  1347.    mime_type : A mime type; such as text/html or image/gif
  1348.    howsend : A flag that tells SRE-http "where in the multi-send process
  1349.              we are".  There are basically four values (with 
  1350.              possible modifiers):
  1351.               '1' == Single part document to "send in pieces" (requires
  1352.                      a modifier)
  1353.               'S' == Start the multipart send (i.e.; the first image)
  1354.               'M' == A middle piece -- more will follow
  1355.               'E' == End piece -- send this "message" and close the connection.
  1356.                
  1357.              In addition, you can "build" a long message, and display 
  1358.              each portion as soon as they are added.  To do this, use the
  1359.              following HowSend codes:
  1360.                 '1S' and '1E' -- Start and end a "sent in pieces" single part
  1361.                                  document
  1362.                 'SS' and 'SE' -- Start and end the first "part"
  1363.                 'MS' and 'ME' -- Start and end the middle "part(s)"
  1364.                 'ES' and 'EE' -- Start and end the final "part"
  1365.                 'A'  and '1A' -- Add stuff (between 1S-1E; SS-SE ; MS-ME; or ES-EE)
  1366.    fileflag: If equal to 1, then "message" is to be treated as a
  1367.               fully-qualified file name (Optional)
  1368.    verbose : If > 2, some status info will be displayed (optional)
  1369.    wname    : Name to use when writing to GoServe audit file (for future 
  1370.              implementation)
  1371.    optheaders: optional response headers (crlf delimited)
  1372.  
  1373. The return code (rcode) is the RC from the 'SEND' command: you can
  1374. check for negative values which  indicate a broken connection.
  1375.  
  1376. For further details on SREF_MULTI_SEND, see MULTSEND.DOC
  1377.  
  1378.  
  1379. Advanced users note:
  1380.    To force "connection close", you need to modify the howsend argument of
  1381.    1, S, SE, E, EE, and 1E by adding a ' 1'.   That is, use
  1382.    1 1 and 1E 1 (or S 1 and E 1).
  1383.    Examples:
  1384.         foo=sref_multi_send('hello','text/plain','1 1',0)
  1385.         foo=sref_multi_send('stuff here',,'1A',0)
  1386.         foo=sref_multi_send('goodbye',,'1A 1',0)
  1387.    or
  1388.         foo=sref_multi_send('pic1.gif','image/gif','S 1',0)
  1389.         foo=sref_multi_send('pic2.gif','image/gif','A',0)
  1390.         foo=sref_multi_send('pic3.gif','image/gif','E 1',0)
  1391.  
  1392. Restriction: this can ONLY be called by an addon (it makes heavy use
  1393.              of the GoServe API).
  1394.  
  1395.  
  1396.  
  1397. -------         ----------          ---------          ------------
  1398.  
  1399. SREF_GMT: Compute a new GMT time, given a date,time,and offset
  1400.  
  1401.  
  1402.  Usage:  newtime=sref_gmt(offset,basetime,outtype,gmtoffset)
  1403.    where:
  1404.         offset  -- offest in days, hours, seconds, or minutes
  1405.         basetime -- in several formats
  1406.         outtype --- format of output
  1407.         gmtoffsett   --- size of gmt offset
  1408.  
  1409.    Returns
  1410.         Time (including GMT offset and "user supplied" offset) in desired format
  1411.  
  1412.  More Details:
  1413.  
  1414.    Offset: Add an offset to the "current time". Format can be:
  1415.       days : use a real number. i.e.;  1.3  (1.3 days), or 0.05 (1/20 day)
  1416.                 (or you can add a d; say, 1.3d)
  1417.       hours:  use an integer followed by an h. i.e.; 1h.
  1418.       minutes: an integer followed by an m.  i.e.;  60m
  1419.       seconds: an integer followed by a s. i.e.; 3600s
  1420.  
  1421.       Default is 0 (no offset)
  1422.  
  1423.   Basetime: The time to add the offset to. The format can be (SRE_GMT
  1424.             will recognize the format)
  1425.       julian     ---  728882.887731  
  1426.                                 (days since 0/0/00 . fraction of day)
  1427.       internet ---  Sat, 12 Aug 1996 21:18:20 GMT
  1428.   old internet ---  Saturday, 12-Aug-96 21:18:20 GMT
  1429.    ansi c      ---  Sat Aug 12 21:18:20 1996   
  1430.   sysfiletree  ---  96/08/12/21/18 or 96/09/12/21/18/22
  1431.  
  1432.   The Default is the current time
  1433.  
  1434. Outtype
  1435.    I       --- internet
  1436.    J       --- julian   
  1437.    C       --- cookie -- similar to internet, but use 12-Aug-1994 
  1438.                     (suitable for expires field of set-cookie)
  1439.    F       --- sysfiletree  
  1440.  
  1441.    Default is I
  1442.  
  1443. GMT_OFFSET
  1444.    If 0, do NOT offset (do NOT add the GMT to I or C outtype)
  1445.    If >0, then use this as the GMT offset (in SECONDS)
  1446.    Default: use the TZ environment variable (via the GoServe gmtoffset function)
  1447.  
  1448. Examples:
  1449.   say sref_gmt()
  1450.   say sref_gmt(,728882.88773)
  1451.   say sref_gmt(.12,'Sat, 12 Aug 1996 21:18:20 GMT','J')
  1452.   say sref_gmt('18000s','Saturday, 12-Aug-96 21:18:20 GMT')
  1453.   say sref_gmt('300m','Sat Aug 12 21:18:20 1996 ')
  1454.   say sref_gmt('5h','96/08/12/21/18','C',0)
  1455.   say sref_gmt(,,'F',0)
  1456. yields ....
  1457.    the current I style date/time-- say Wed, 24 Feb 1999 00:04:36 GMT
  1458.    Tue, 13 Aug 1996 02:18:19 GMT
  1459.    728883.216064
  1460.    Tue, 13 Aug 1996 07:18:19 GMT
  1461.    Tue, 13 Aug 1996 07:18:19 GMT
  1462.    Tue, 13-Aug-1996 02:17:59
  1463.    98/03/26/22/55
  1464.  
  1465. Restrictons: can ONLY be called from an addon.
  1466.  
  1467.  
  1468. -------         ----------          ---------          ------------
  1469.  
  1470. SREF_OPEN_READ: Open a file for read/write (and wait if it's currently locked)
  1471. SREF_OPEN_READ simulates a "write protected semaphore" -- it delays 
  1472. returning until the file is no longer locked by a writing process.
  1473.  
  1474. Usage: open_time=sref_open_read(afile ,seconds_to_try_for , howopen )
  1475.         afile: file to open
  1476.      seconds_to_try_for : seconds to try for
  1477.         howopen: BOTH= open as read/write
  1478.                  WRITE= open as write
  1479.                  NEW = open as write, must not already exist
  1480.                  READ = open as read (the default)
  1481. Returns:
  1482.  -2 : Timed out
  1483.  -1 : File does not exist, or does exist (if howopen=WRITE)
  1484.  >0 : Seconds it took (minimum value of 0.01) to open
  1485.  
  1486. Restrictions: none
  1487.  
  1488.  
  1489. -------         ----------          ---------          ------------
  1490. SREF_PACK64 : Convert a "base64" string.
  1491.  
  1492.    usage:  astring=sref_pack64(packed_64_string)
  1493.  
  1494. This is a rexx version of the GoServe pack64 function.  Quoting
  1495. from GoServe.doc:
  1496.    Takes a single string, expressed according to the MIME "Base64"
  1497.    specification (in RFC 1521), as an argument and returns the decoded
  1498.    (packed) string.  Each four bytes in 'string' is packed to three bytes
  1499.    in the result (except possibly for the last four bytes); 'string' must
  1500.    be a multiple of 4 bytes.  If any deviation from these specifications
  1501.    (or from the RFC 1521 "Base64" character set) is found, the null string
  1502.    is returned.
  1503.  
  1504.   PACK64 is useful for processing the incoming user/password data encoded
  1505.   for the HTTP 'basic access authentication scheme' -- see the HTTP
  1506.   documentation for details.
  1507.  
  1508. We provide this function, as well as SREF_MKPACK64 for CGI-BIN and
  1509. other "non-goserve" processes.
  1510.  
  1511. Caution: this is NOT very efficient for long string (say, greater
  1512.           then 3000 bytes) -- use the GoServe PACK64 if you can!
  1513.  
  1514.  
  1515. Restrictions: none
  1516.  
  1517. -------         ----------          ---------          ------------
  1518.  
  1519. SREF_REPLACESTRG: Replace substrings
  1520. Usage: 
  1521.     newstring=sref_replacestrg(haystack,needle,replacement, type , exactmatch)
  1522. where:
  1523.         haystack: The string to search in
  1524.         needle: The string to search for
  1525.      replacement: Replace occurences of "needle" with "replacement"
  1526.           type: 
  1527.                 FORWARD: Replace first occurence
  1528.                BACKWARD: Start from end, replace "last" occurence.
  1529.                     ALL: Replace all occurences
  1530.     exactmatch:  if YES, then cases must match (NO=case is ignored).
  1531.              Note that the case of the "replacement" is retained, as
  1532.              well as the non-replaced portion of the haystack, regardless
  1533.              of the value of exactmatch.
  1534.  
  1535. Returns:
  1536.      The haystack,with the replacements (if no replacements, return the
  1537.      original value of haystack)
  1538.  
  1539. Restrictions:none
  1540.  
  1541. -------         ----------          ---------          ------------
  1542. SREF_SEARCH_FIXED: Search a fixed-length record file for a match
  1543. Usage:
  1544.   match_record=sref_search_fixed(string,filename,numrec,reclen,recoff,idat,idlen,type)
  1545. where:
  1546.   string : The string to look for
  1547.   filename: A fixed-length record file to look in
  1548.   numrec:  # records in filename
  1549.   reclen: length of each record (must include possible crlf's at end of line)
  1550.   recoff: number of header records (offset from start of file) --- they will
  1551.           be skipped when searching
  1552.   idat:  Character (in a record) that identifier variable (to be searched) 
  1553.          1 is the first character
  1554.   idlen: length, in characters, of identifier
  1555.   type: Type of search
  1556.         1 = Exact match (no space stripping, case sensitive)
  1557.         2 = Wildcard match (string can have * wildcards)
  1558.         2 n = Same as 2, but return nth match (i.e.; 2 and 2 1 are the same)
  1559.         otherwise: strip spaces, case insensitive match.
  1560.  
  1561.   Wildcard matches are attempted "one record at a time" -- it's much slower
  1562.   then the binary searches used for exact and non-exact matches.
  1563.  
  1564.   Note that if you use one of the binary match types, be sure the sort order
  1565.   is appropriate (i.e.; if exact is used, then pay attention to case)
  1566.  
  1567. Returns:
  1568.   If a match is found, the matching record is returned.
  1569.   If no match is found, a '' is returned.
  1570.     
  1571. Restrictions: none
  1572.  
  1573.  
  1574. -------         ----------          ---------          ------------
  1575.        
  1576. SREF_VERSION  : Returns string listing the SRE-http version
  1577. Usage:
  1578.    filter_name=sref_version(port)
  1579. or  
  1580.   filter_number=sref_version(port,1)
  1581.  
  1582. where port is optional.
  1583.  
  1584. When a second argument of 1 is used, then a "numeric" version number is returned.
  1585. Otherwise, a descriptive string is returned.
  1586.  
  1587. Sample descriptive string return: SRE-http Ver 1.3c.0299.a 
  1588. Or, as a  numeric return: 130301.2 
  1589.     ver 1.3, subversion 3 , build  number 1; 
  1590.     the .2 signfies that SREPROXY is being used
  1591.  
  1592. The numeric return provides a convenient way of comparing the revision to
  1593. some 'minimal value'.
  1594.  
  1595. The (~proxy), or (std), refer to the "proxy" (SREPROXY) or standard (SREFILTR)
  1596. versions of SRE-http.
  1597.  
  1598. Restrictons: if called from a non-addon, you should include the 
  1599. port of the server (if not included, a default value of 80 is used).
  1600.  
  1601.  
  1602.  
  1603.  
  1604. -------         ----------          ---------          ------------
  1605.  
  1606. SREF_VALUE: Get value from the OS/2, or SRE-http, environment.
  1607.  
  1608.  
  1609. SREF_VALUE is a general purpose "value of a variable" procedure.
  1610.  
  1611. SREF_VALUE is able to extract and set variables that 
  1612. reside in  four different "environments". These four
  1613. environments are:
  1614.  
  1615.    i) OS2 : the  os/2 environment variables
  1616.   ii) INI : the SRE-http initialization parameters
  1617.  iii) REQ : request specific variables 
  1618.   iv) USE : semi-permanent user defined variables
  1619.  
  1620.  
  1621. Calling syntax:
  1622.      value=SREF_VALUE(varname,newval,env,optinfo,port,prefix)
  1623. where:
  1624.     varname : the name of the variable to look up
  1625.     newval: a new value for this variable. If not specified, or if set
  1626.             equal to a zero-length string (i.e.; newval="")
  1627.             a new value will NOT be set
  1628.      env: The "environment" to look in; either OS2,INI, REQ, or USE.
  1629.   optinfo: Optional: information: used if env=REQ  or env=USE.
  1630.   port : Optional: the port (that goserve is running under)
  1631.   prefix: Optional: the "sre" prefix (typically, SREF_80_)
  1632.  
  1633. If prefix is specified, port is ignored.
  1634. If sref_value is called from a GoServe thread, port and prefix are
  1635. unnecessary.
  1636.  
  1637. In any case, the current value of the variable will be returned; and if NEWVAL
  1638. is specified, the variable's value will then be changed to this NEWVAL.
  1639.  
  1640. ENV specific notes:
  1641.  
  1642.   * For all values of ENV, setting VARNAME='*' will cause a space 
  1643.     delimited list of "currently available variables" to be returned.
  1644.  
  1645.   * env=OS2 is equivalent to the use of OS/2's value function, with 
  1646.     the added bonus of the * "list variables" option. Note that when *
  1647.     is used with env=OS2, INI variables will be detected and NOT displayed.
  1648.  
  1649.     Note: in a multi-host environment, you can obtain a "host" specific
  1650.           value of a variable by including a .HOST_NICKNAME to the
  1651.           VARNAME (seperated by a space). 
  1652.           For example,
  1653.              if you've defined a HOST with a host nickname of "SITE2",
  1654.              and want the "host specific version of THE_REALM", 
  1655.              then enter VARANAME='THE_REALM SITE2'.  
  1656.           Note that if there is no "host-specific" value, the "generic"
  1657.           value will be used.  
  1658.  
  1659.   * env=INI is equivalent to using OS/2's value function on variables that
  1660.     begin with SREF_nn, where nn is the "current port" (port 80 if 
  1661.     no current port can be determined).
  1662.  
  1663.   * When using SREF_VALUE in a stand-alone process (not under GoServe/SRE),
  1664.     to use the REQ "environment" you MUST first issue a
  1665.           call sref_value('!INI',,'REQ',,,'SREF_80_')  
  1666.     (assuming that GoServe/SRE is running on port 80).
  1667.  
  1668.   * When using env=REQ, and calling from a post-filter procedure, or from a 
  1669.     stand alone program, OPTINFO should contain the appropriate request id (as
  1670.     assigned by GoServe).
  1671.     SRE-http provides this name to post-filter procedures. For stand-alones,
  1672.     you'll have to figure it out (sorry, we do not provide a mechanism for 
  1673.     doing this figuring out).
  1674.  
  1675.   * env=USE is the only way (short of writing your own code) of reading/writing
  1676.     "user defined, semi-permanent" variables.
  1677.  
  1678.     These variables are constant (unless explicitily modified) across
  1679.     requests -- they belong to the GoServe process (and NOT to
  1680.     a specific request). 
  1681.  
  1682.     Although specific to a GoServe process, these variables can be
  1683.     accessed from any other process. To do this, you must set the
  1684.     OPTINFO variable to be the "port number" (i.e.; miscinfo=8080) 
  1685.     of the GoServe process (if OPTINFO is not specifed, a port number 
  1686.     of 80 is assumed).
  1687.   
  1688.   * env=USE and env=REQ both use the SRE-http "variable storage daemon". 
  1689.    This daemon can handle any kind of string, of any (reasonable) length. 
  1690.  
  1691.     Thus, using SREF_VALUE('USE',...)is much more flexible than 
  1692.     using the REXX VALUE(,,'os2environment') function; since the OS/2 
  1693.     environment does  NOT like  binary strings, and gets  flakey when a string
  1694.     of any size (say, greater then 1024 bytes) appears.
  1695.  
  1696.     Of course, this also means that to use USE and REQ, GoServe/SRE
  1697.     MUST be running in some currently active process.
  1698.  
  1699.  
  1700. Note: SRE-http comes with a simple demo of SREF_VALUE --TESTVALU.SHT
  1701.       and TESTVALU.CMD.
  1702.     
  1703. Restrictions: can be called from anywhere, given the above concerns.
  1704.  
  1705. -------         ----------          ---------          ------------
  1706. SREF_QUEUE
  1707.  
  1708. SRE-http supports a flexible form of "queue". The primary purpose of these 
  1709. SRE-http queues is to store and retrieve information in a globally accessible, 
  1710. semi-permanent location. In many ways, they are functionally similar to REXX 
  1711. queues, but are much more easily manipulated.
  1712.  
  1713. SREF_QUEUE is called as:
  1714.     
  1715.       retvalue=SREF_QUEUE(QueueName,action,value,port)
  1716.  
  1717. where:
  1718.       queuename: The name of a queue; it can be any REXX-style, variable name
  1719.       value: Either the value to be added to the queue, or instructions on
  1720.              how to read from the queue
  1721.       action: Type of action (PUT, QUEUE, POP, READ, etc.)
  1722.       port: Optional:: required if SREF_QUEUE is not called from an addon. 
  1723.             If called from an external process (such as a CGI-BIN script),
  1724.             this should be the port that SRE-http is running under (typically,
  1725.             80).
  1726.  
  1727.  
  1728. For details on how to use SREF_QUEUE, see SREFQUE.DOC
  1729.  
  1730. Restrictions: same as sref_value -- can be called from anywhere, but you
  1731. might need to supply the port.
  1732.  
  1733. -------         ----------          ---------          ------------
  1734.  
  1735. SREF_UNGZIP: Uncompress a "gzip" string
  1736.  
  1737.   usage: astring=sref_gzip(gzipped_string)
  1738.  
  1739. The inverse of SREF_GZIP.
  1740.  
  1741. Typically, gzipped_string will be the contents of a .GZ (or .Z) compressed file.
  1742.  
  1743. Restrictions: uses the rxGZlib.dll library that comes with SRE-http -- make sure
  1744.              that rxGZlib.dll is in a LIBPATHed directory.
  1745.       
  1746. -------         ----------          ---------          ------------
  1747.  
  1748. SREF_WILDCARD  : Do a wildcard match (with substitution)
  1749.  
  1750. Usage:  
  1751.     newstring=sref_wildcard(needle,haystack replacement,doexact)
  1752. where:
  1753.       needle: String to search for
  1754.     haystack: String to compare needle to
  1755.  replacement: Return this string, after (possibly) inserting
  1756.               wildcarded portions of needle into wildcarded portions
  1757.               of replacement
  1758.              (note there is no comma between haystack and replacement)
  1759.    doexact: Exact match flag. If doexact=1, then do NOT do wildcard matching.
  1760.  
  1761. returns:  
  1762.    code , match
  1763. where
  1764.    code: 0= none, 1=exact match, 2=replacement match
  1765.  
  1766. See if  needle matches haystack.  Haystack can contain *, which are
  1767. used as wildcard characters (as with matching file names in OS/2).
  1768. If a match occurs, the replacement is returned, possibly with
  1769. "substitution" matches  -- i.e.; the part of needle "covered by" the
  1770. * in the haystack is placed into the replacement (at the position of the
  1771. * in the replacement)
  1772.  
  1773. Example:  newstring=sref_wildcard('1234567','12*67 abcde*f',0)
  1774.           yields:  newstring= 2 ,abcde345f
  1775.  
  1776. Note: Needle and replacement should not contain "real" * characters.
  1777.  
  1778.  
  1779. Restrictions: none
  1780.  
  1781.  
  1782.  
  1783. -------         ----------          ---------          ------------
  1784. -------     SECTION 2: Inter-thread communications in SRE-http
  1785. -------         ----------          ---------          ------------
  1786.  
  1787.  
  1788. In order to improve throughput, SRE-http has been written as a multi-threaded
  1789. program.  The goal is to reduce the size of SREFILTR.80, the GoServe "filter".
  1790. The multi-threaded nature of GoServe makes this important: since every
  1791. "request" that arrives run's in a seperate thread. If you
  1792. only get 1 request at a time, that may not be much of a problem.  However,
  1793. when many requests arrive simultaneously, the multiplicity of
  1794. "large threads" can bog the machine down.  Since image rich documents will
  1795. generate many requests, such occurences of "many simultaneous
  1796. requests" may actually be fairly typical (even for a lightly visited site)!
  1797.  
  1798. For this and other reasons, SRE-http uses a number of "daemons".
  1799. As with "loading the library of macrospace procedures", these daemons are
  1800. launched when SRE-http is first run.  Note that unlike the "request
  1801. specific threads" launched by GoServe, the daemons stay active as long as
  1802. GoServe is running.  In contrast, "request specific threads" are
  1803. constantly being generated and killed, as GoServe recieves and responds 
  1804. to tcp/ip requests.
  1805.  
  1806. Note that launching a thread simply means running a REXX program 
  1807. simultaneously. However, in contrast to running programs in different
  1808. processes (say, with the DETACH command), REXX threads share a single 
  1809. environment.
  1810.  
  1811. This "shared environment" feature motivates SRE-http's extensive use of
  1812. the environment to store configuration information.  Basically, one of 
  1813. SRE-http's daemons  (the SREFMON.CMD thread) loads the 
  1814. variables set in INITFILT.80 (as well as variables set in
  1815. REPSTRGS.IN) into the environment (SREFMON.CMD also keeps track
  1816. of these files, and re-initializes the environment should you change them
  1817. "on-the-fly").
  1818.  
  1819. If you need the values of these variables, you can use the SREF_VALUE
  1820. comamnd to retrieve them. For  example, to retrieve the value of the
  1821. CHECKLOG variable, you can use
  1822.     check_log=sref_value('CHECKLOG',,'INI')
  1823.  
  1824.  
  1825. Technical Note:
  1826.     For historical reasons, SRE-http stores these "initialization" 
  1827.     variables with a prefix of SREF_port_. For example, if you 
  1828.     are running on port 80 (the default http port), and you want the
  1829.     value of the CHECKLOG variable, you could extract it using: 
  1830.         avalue=VALUE('SREF_80_CHECKLOG',,'os2environment')
  1831.  
  1832. Although used by SRE-http, the limitations of the enviroment preclude
  1833. its use for many important purposes. Instead, a number of special
  1834. "SRE-http daemons" are used. These include:
  1835.  
  1836.     USERCHK.RXX:  Used to lookup usernames stored in the USERS.IN file.
  1837.     ALIASCHK.RXX: Used for alias matching, it uses the ALIASES.IN file.
  1838.     ACCESCHK.RXX: Used for finding access rights and permissions, it
  1839.                   uses ACCESS.IN
  1840.     VIRTCHK.RXX:  Used for virtual directory lookup, it uses VIRTUAL.IN.
  1841.     VARSTORE.RXX: Used for storing semi-permanent variables, clientnames,
  1842.                   and recent requests.
  1843.  
  1844. These daemons store their data files in memory.  For example, USERCHK 
  1845. does not re-read USERS.IN everytime it needs to look up a username/password
  1846. combination.  Instead, it examines a "copy" of USERS.IN that is read 
  1847. into memory.
  1848.  
  1849. In addition to providing semi-permanent data storage, daemons are also
  1850. useful in providing non-time sensitive processing. For example: 
  1851.     POSTFCHK.RXX: Used for "recording requests" and for "a custom written
  1852.                   post-filter".  Uses RECRDALL.IN.
  1853.     PMPRINTF.RXX: Used as a front-end to the PMPRINTF procedure.
  1854.  
  1855. In addition to these core SRE-http functions, daemon's can be used
  1856. in addons.  For example, the SRE-Data addon (a simple web-aware database
  1857. addon) uses a daemon to search databases.  Similarly, the SRE_BLNC addon
  1858. uses a daemon to provide load balancing.
  1859.  
  1860. Ambitious programmers interested in writing addon's that are partially
  1861. run as daemons can make good use of a simple set of "SREF_DMN_" 
  1862. procedures supplied with SRE-http. These procedures greatly 
  1863. facilitate the use of daemons, relieving the need for the programmer 
  1864. to deal with most of the myriad details.  The DAEMONS.DOC file
  1865. describes these procedures in detail.
  1866.  
  1867.  
  1868. -------         ----------          ---------          ------------
  1869. -------     SECTION 3: A short discussion of OS/2 SendMail
  1870. -------         ----------          ---------          ------------
  1871.  
  1872.