1 March 2001

     SRE-http ver 1.3h Documentation: SRE-http's procedure library. 


SRE-http version 1.3 uses uses OS/2 "macrospace" to store many of
its procedures.  In addition, as a multi-threaded program, it uses the
environment, queues, and semaphores to transfer information between threads.
This document discusses both these aspects of SRE-http.

In the first section, we discuss procedures that competent REXX programmers 
may find useful when writing addons for SRE-http.
These procedures are stored in a "dynamic macrospace library file" called 
SREFPRC.RXL.  When SRE-http is first run (that is, when GoServe is 
started, and the first request arrives), SRE-http will load this 
library into macrospace.

The second section discusses SRE-http use of the environment, threads and
semaphores for inter-thread communication. 

Note that several of these procedures may not be needed on your site.  If so,
you can save a little bit of space by "removing them from macrospace".
For details, see the discussion of the REMOVE_PROCS variable in INITFILT.DOC.

Please note that SRE-http uses REXXLIB for various purposes. 
REXXLIB is found at 
     http://www.quercus-sys.com/rexxlib.htm.
Our licence with Quercus allows users of SRE-http to freely use REXXLIB 
(you do not need to  register it) as part of SRE-http.  
However, if you use REXXLIB for your own programs, you are supposed to 
pay for it (the license is only for use with programs we distribute). 
If you write "addons" for SRE-http that use REXXLIB, I'm not sure where 
that falls; but to be safe, I assume that you are supposed to register  
(the original cost was $25.00, though as of March 2001 it may be 
available for free).


-------         ----------          ---------          ------------
-------          SECTION 1: Using SRE-http's macrospace library.
-------         ----------          ---------          ------------

The following describes many of the procedures contained in the
SRE-http macrospace library.

If you are a serious REXX programmer, you may want to look at the source
code (contained in  various .SRF files) for further descriptions. Note
that there are some procedures placed into macrospace by SRE-http that
are not intended for general use; these are not described in this document.

Some preliminary notes:

1) What is  macrospace?
    Macrospace can be thought of as a system-wide dynamic link library.
    That is, procedures stored in macrospace are available 
    to all REXX programs, not just SRE-http.  Thus, if some other
    program "clears" macrospace, SRE-http may fail -- and
    vice versa!

2) Where's the source code?
     The source code for these procedures consists of a number of files with
     the extension .SRF; all stored in the SRE-http "library" directory
     (perhaps \GOSERVE\LIB).

3) What do we need to work with macrospace procedures?
     Nothing -- just call them the way you call any external OS/2
     procedure. Note that SRE-http uses procedures in REXXLIB.DLL 
     to "load" SREFPRC.RXL into macrospace.  For simple manipulations of
     macrospace, you can use MSPACE.CMD (look for it in the library
     directory).


4) A caution on using these procedures:

  There are four general cases where one might use these procedues:
    1) In an SRE-http addon (or a pre-filter, or mid-filter, procedure)
    2) In a CGI-BIN script
    3) In a post-filter procedure
    4) In a stand-alone program (that is NOT running in the same process as 
       SRE-http)

  Several of these procedures use GoServe to provide information,
  or use "request specific" information. These procedures will not
  work if called from one of the "higher numbered" cases. 

  For example, several of these procedures use the GoServe EXTRACT function,
  typically to determine the current serverport. Extract will NOT work in 
  a CGI-BIN script, or in a stand alone program.  

  Where appropriate, the "cases" where the procedure can/cannot be used
  are noted in the Restrictions: portion of the following descriptions.
 
 5) Another Caution
    In some cases, inappropriate use of these procedures can
    CRASH GOSERVE -- so do pay attention to the "restrictions"!
 
 6) On the use of "dynamic macrospace procedures".
    As of version 1.2N, SRE-http  uses "dynamic macrospace".
    Dynamic macrospace means that many of the procedures are not
    loaded until they are needed; which helps save space, and
    facilitates minor upgrades.

    There is one "gotcha" -- if you call one of 
    these procedures from an external program (that's not in the GoServe
    process), it is possible that you will get a "could not find
    SRE_LIBDIR error".  If this occurs, you just need to 
    SET SRE_LIBDIR=goserve_lib_directory (say, SET SRE_LIBDIR=D:\GOSERVE\LIB).

         Make sure you do this SET from the same OS/2 session you are runnning 
         this external procedure from,or put it in your config.sys file.

-------         ----------          ---------          ------------
            Description of general purpose macrospace procedures
-------         ----------          ---------          ------------

Calling Syntax:

File/url-resolution related procedures:
    status  =SREF_GOS(acmd,varname,dorange,hdrs)
   open_time=SREF_OPEN_READ(afile ,seconds_to_try_for , howopen )
afile_string=SREF_GRAB_FILE(afile,seconds_to_try_for)
newfiles=SREF_CONJUREF(basedir,basenames,extlist,minfree,mintime)
       newct=SREF_LOOKUP_COUNT(ctfile, needle, augment , substring , noadd)
    filename=SREF_DO_VIRTUAL(defdir,aurl,envstring,docheck,trans,homedir,hnick)
    mimetype=SREF_MEDIATYPE(filename,port)
      newurl=SREF_FIX_URL(local_url,servername,serverport)


String related procedures:
   newstring=SREF_REPLACESTRG(haystack,needle,replacement, type , exactmatch)
   newstring=SREF_WILDCARD(original, needle replacement,doexact)
   matchinfo=SREF_WILD_MATCH(needle,haystack,old_matchinfo,suppress_noslash)
      ablock=SREF_EXTRACT_BLOCK(haystack ,alabel ,delim1, delim2, delim3)
      newval=SREF_INSERT_BLOCK(haystack,alabel,add_string,after,delim1,delim2)
     astring=SREF_PACK64(packed_64_string)
stg_packd_64=SREF_MKPACK64(astring)
    md5_hash=SREF_MD5(astring,isfile)
     astring=SREF_UNCHUNK(chunked_string,trailers)
 stg_chunked=SREF_CHUNK(astring,trailers)
     astring=SREF_UNGZIP(gziped_string)
 stg_gzipped=SREF_GZIP(astring)
   img_elems=SREF_DIGITS(astring,digname,ndigits,frame,nobr,options)
       score=SREF_COMPWORD(needle,haystack)


Variable/time/version lookup procedures:
       value=SREF_VALUE(varname,newval,env,optinfo)
       value=SREF_QUEUE(queuename,action,aval,port)
        aval=SREF_CGIVARS(cgi_bin_variable)
     timestr=sref_gmt(offset,basetime,outtype,gmtoffset)

     juldate=SREF_JULDATE(mode, time_string)
 filter_name=SREF_VERSION(port)
    errmess=SREF_ERROR(amessage,do_pmprintf)

Internet info & retrieval procedures
     aresult=SREF_HOST(ipaddress)
        aval=SREF_BROWSER_INFO(field,browser,envstring)
       stuff=SREF_GET_URL(url,maxchar,verbose,headers)
       stuff=SREF_HOST_INFO(myaddr0,nhosts,envstring)
cookie_value=SREF_GET_COOKIE(cookie_name,nth)
         res=sref_dynamic_pwd(appname,newlocation,privset2,duration,respfile,clientaddr)


Daemon related procedures
       status=SREF_DMN_LAUNCH(daemon_name,file_name,optional_arg)
       status=SREF_DMN_EXIST(daemon_name)
        value=SREF_DMN_ASK(daemon_name,an_argument,max_wait)
 request_info=SREF_DMN_WAIT(daemon_name,max_wait)
  an_argument=SREF_DMN_VALUE(request_info)
       status=SREF_DMN_REPLY(request_info,reply_stuff)
       status=SREF_DMN_KILL(daemon_name)
 
Miscellaneous
     status=SREF_MAILIT(address_list,message,smtp_gateway,sender_address)
       rcode=SREF_MULTI_SEND(message,mime_type,howsend,file_flag,verbose)
         foo=SREF_EXPIRE_RESPONSE(aoffset,alength,atype,noauto)
         foo=PMPRINTF_SREF(astring,nofile,port)
       results=SREF_FIND_INDEX(target,qname,varname,nth,loc_only,timeout)


Short descriptions:

SREF_GOS: Send information to client in a http/1.1 compatible way.
SREF_OPEN_READ: Open a file, with waiting if the file is currently locked
SREF_GRAB_FILE: Open file (with waiting), and then read it in to a string variable
SREF_CONJUREF: Cleanup temporary directory, and then derive new filenames
SREF_SEARCH_FIXED: Binary (or wildcard) search of fixed-length record file
SREF_LOOKUP_COUNT: Lookup and increment an SRE counter file
SREF_DO_VIRTUAL: Map a URL to a virtual directory
SREF_MEDIATYPE: Determine mime type of a file
SREF_FIX_URL: Create fully qualified URL from local URL

SREF_REPLACESTRG: Replace occurences of needle, in haystack, with replacement
SREF_WILDCARD: Deterimine if needle is a "wildcard" match of haystack
SREF_EXTRACT_BLOCK:  Extract a delimited block of text from a string
SREF_INSERT_BLOCK: Insert block of text between delimiters
SREF_PACK64: Convert a "pack64" format string to original characters
SREF_MKPACK64: Convert a string to its "pack64" equivalent
SREF_MD5: Make an MD5 "digest" of a string, or of a file
SREF_UNCHUNK: Unchunk a "chunked" string
SREF_CHUNK: Create a chunked string
SREF_UNGZIP: Unzip a "gzip" compressed string 
SREF_GZIP: Create a "gzip" compressed string
SREF_DIGITS: Returns a list of IMG elements that point to digit .GIFs
SREF_COMPWORD: Matches a "needle" to a "haystack" -- return a 1-100 score.

SREF_VALUE: Value of a variable from an OS/2 or SRE-http "environment"
SREF_QUEUE: Read,write, and manipulate an SRE-http "queue"
SREF_CGIVARS: Get the value of one of the CGI-BIN environment variables
SREF_GMT: Compute a new GMT time, given an offset in fractional days
SREF_JULDATE: Return absolute fractional date (since 0/0/1)
SREF_VERSION: Return version of SRE-http
SREF_ERRROR: Read/record an error message

SREF_HOST: Return IP address given name (or vice versa)
SREF_BROWSER_INFO: Get spec-info on a browser
SREF_GET_URL: Go to a web server and GET a URL (the complete contents)
SREF_HOST_INFO: Return the "host nickname", given a servername
SREF_GET_COOKIE: Get value of a cookie
SREF_DYNAMIC_PWD: Prompt the client for a "dynamic password"

SREF_DMN_LAUNCH: Launch a daemon
SREF_DMN_EXIST: Check if daemon's queue and semaphore are open
SREF_DMN_ASK: Query the daemon for some information, wait for reply
SREF_DMN_WAIT: Daemon uses this to listen for queries
SREF_DMN_VALUE: Used by daemon to parse queries
SREF_DMN_REPLY: Used by daemon (to reply to SREF_DMN_ASK)
SREF_DMN_KILL: Kill a daemon's queue and semaphore

SREF_MULTI_SEND: Send a sequence of documents 
SREF_MAILIT: Send mail via an SMTP server
SREF_EXPIRE_RESPONSE: Modify the automatically generated expiry response header
PMPRINTF_SREF: A front-end (with error checking)for PMPRINTF
SREF_FIND_INDEX: Find a match in an SRE-Data file (requires SRE-Data addon)

      ---------------------------------------------------------
                     Longer Descriptions (alphabetically sorted)
      =========================================================


-------         ----------          ---------          ------------
PMPRINTF_SREF:  A pre-process for the REXXLIB PMPRINTF routine.

PMPRINTF_SREF is used throughout SRE-http as a means of reporting run-time
status information.  PMPRINTF_SREF typically calls the PMPRINTF procedure,
which will then display results in a PMPRINTF window.  PMPRINTF_SREF will
check for a few overflow conditions, thereby avoiding sys3175 errors.

In addition, PMPRINTF_SREF checks the SREF_PMPRINTF_LINE_LENGTH
and SREF_PMPRINTF_LOG_FILE environment variables.  These variables, set
in SREFMON.CMD, control the maximum line length to be displayed (longer lines will wrap),
and whether or not to log results to an SRE-http audit file

Usage:
  CALL  PMPRINTF_SREF(astring,nofile,port)
where
  astring : the string to write
  nofile : optional. If 1, then suppress writing to the PMPRINTF_LOG_FILE.
  port: optional, the port of the server


Restrictions: If called from a non-addon, you MUST include the port.



-------         ----------          ---------          ------------

SREF_BROWSER_INFO

Return information about a browser. 

Usage: 
  aval=sref_browser_info(field,browser,envstring)
where 
   field:  the field to get information on:
   browser:  optional: a "user-agent" identifying string.
         If this is not included, then the user-agent request header
         is used.
   envstring: only needed if called from non-addon (see restrictions)

Output: The result


The following fields are supported, with possible values noted. 
Note that if no information is available for an item. Or, a number
< 0 is returned to signify an error:
   -1 = BROWSERS.IDX file unreadabld
   -2 = Can not find entry for this user-agent
   -3 = No value for this field, for this user-agent
   -4 = BROWSERS.IDX file not found

  user_agent = User-agent of browser
  browser = Vendor of the Browser
  cookies =Cookie capable? YES or NO.
  security = Type of security. NO, SHTTP, or SSL.
  tables = Understands tables (YES NO)
  date = The date this table entry was entered or most recently 
          modified. YY/MM/DD
  redirectlimit = Maximum length of redirection string.
                 Integer between 255 and 8000
  maxlinklen = Maximum characters in url
                 Integer between 255 and 8000


Citation: This procedure uses browser.idx, which is based on information from:
http://website-1.openmarket.com:80/browsertest/prob/bt-maker.cgi?DataFile

Hint: Since browsers are coming and going, you may want to check the
      SRE-http home page for new versions of BROWSERS.IDX. Or,
      you can generate a new version of BROWSERS.IDX with 
      BROWSERS.CMD (run it from an OS/2 command prompt).

      BROWSERS.CMD can also be called as an SRE-http addon.  It
      will read BROWSERS.IDX and display information about your
      browser's capabilities.
      
Examples:
     tableok=sref_browser_info('TABLES')
     docook=sref_browser_info('COOKIES')
     security1=sref_browser_info('security','IBM WebExplorer DLL /v1.03')


Restrictions: if called from a non-addon, you must supply an "environment
string". This will have the form  SREF_nn_, where nn is the current
port (i.e.; nn=80).



-------         ----------          ---------          ------------

SREF_CGIVARS(Varname)

Usage: aval=sref_cgivars(cgi_bin_variable)

Returns: value of the CGI_BIN variable (if available)

Note that:SCRIPT_NAME, PATH_INFO, PATH_TRANSLATED, and REMOTE_IDENT,
PATH_INFO, PATH_TRANSLATED, and QUERY_STRING are not available. When
one of these variables is requested, a ' ' is returned

Note that this will NOT look in environment, but will determine the
values each time.  In other words, this not designed for use
in cgi-bin scripts (you should use x=value(varname,,'os2environment)
instead); it is designed for use in INTERPRET includes and in
directly called REXX server side programs).

Example:   aval=sref_cgivars('server_software')

Restrictions: should ONLY be called from an SRE-http addon. 

-------         ----------          ---------          ------------
SREF_CHUNK: Chunk a string

Usage: chunked_string=sref_chunk(astring,final,trailers)

Create a "chunked" string; which is suitable for http/1.1 transfer.

FINAL  should be 1 if this is the last of a sequence of chunked strings
(or if this is the "first of one").  

   *** Failure to include a "final" chunked sequence is an error! ***

The trailers argument is optional. When present (at it should only
be included when final=1) the value of trailer (typically crlf'ed
delimited set of trailers) is added to the end of the chunked
message.


Restrictions: none


-------         ----------          ---------          ------------
SREF_COMPWORD: Compare two words and return a score

Usage: 

    score=sref_compword(needle,haystack)

where:
   needle : the word to compare 
 haystack : the word to compare against

SREF_COMPWORD will compare the needle against the haystack and return a 
score that indicates how closely they match.  A score of 100 means "perfect
match", while a score of 0 means "no match". 

SREF_COMPWORD uses a simple pattern matching algorithim (based on 
looking for many possible substrings of the needle in the haystack).
The greater the number of substrings, and the closer they are
in letter position, the better the match.

Note that the definition of which word is the needle and which is the 
haystack is somewhat arbitrary. However, it can make a difference in
the score!


Examples: ascore=sref_compword("FORIM1","FORMULA")
          ascore=sref_compword("FORIM1","THEMR1")
          ascore=sref_compword("FORIM1","EXACT1")
     would yield scores of 0.170, 0.034, and 0.016  (respectively)
     In contrase:
          ascore=sref_compword("FORMULA","FORIM1")
          ascore=sref_compword("THEMR1","FORIM1")
          ascore=sref_compword("EXACT1","FORIM1")
     would yield scores of 0.124, 0.037, and 0.016  (respectively)


Restrictions: none


-------         ----------          ---------          ------------

SREF_CONJUREF : Create/delete temporary files
Usage: newfiles=sref_conjuref(basedir,basenames,extlist,minfree,mintime)

        basedir: directory to clean up (if > 10 files,
              remove all files > mintime hours old)
        basenames: list of (up to 4-char) file-stems to be used
                 (a random element will be added)
        extlist: list of up to 10 extension to be added to this file-stems

     So, if base= ZDOG,ZMOM and EXTLIST is FOO,CAT,001 then this will create
     ZDOGxxxx.FOO, ZMOMxxxx.CAT and ZMOMxxxx.001, where xxxx is some 4 digit
    random # (guaranteed to cause unique file names to be selected) 
    (note replication to generate as many names as longest list)

       minfree: Try to get this much space free by deleting files 
                from basedir (in kb)
       mintime: But don't delete anything less than this hours old

Return:   If newfiles=0, then could not create (say, minfree was violated)
          Else, comma delimited list of file names 
                that can be used as temporary files.

CAUTION: Be careful what you choose as your basedir (you could automatically
delete important stuff if your basedir is not strictly a "temporary files"
directory).

Restrictions: none

-------         ----------          ---------          ------------

SREF_DMN_LAUNCH, SREF_DMN_EXIST, SREF_DMN_ASK, SREF_DMN_WAIT,
SREF_DMN_VALUE, SREF_DMN_REPLY, SREF_DMN_KILL: A set of procedures to
use with daemons.

The several SREF_DMN_ procedures are used to launch, communicate with,
and kill deamons.  Daemons are semi-permanent threads running
under the GoServe process. Among other advantages, they offer a 
convenient means of storing data for quick retrieval, provide 
system monitoring capabilities, and allow one to perform 
non-time sensitive actions efficiently.  Section II of this
document discusses daemons in greater detail.

For a complete description of how to use these SREF_DMN_ procedures,
please see DAEMONS.DOC.
 

-------         ----------          ---------          ------------
SREF_DIGITS

Usage: 

    txtstring=SREF_DIGITS(amess,digit_name,nd,useframe,nobr,opts,imgdir)

where:
  txtstring :  a text string containing a sequence of <IMG elements, that
               point to the appropriate graphical digits

      amess : a string of characters, typically-but-not-always digits,
                  to display 
 digit_name : the name of the subdirectory containing the digit, 
              and/or character-image, .GIF files.  
              This subdirectory must be relative to the
              imgdir directory (as specified below).

              If digit_name is not specified, WHITBLAK is used.  

The remaining arguments are optional.

         nd : the number of characters to display. 
              If nd is longer then the number of characters in amess...
                a) if amess only contains digits, then 0's will be
                   used as a padding character 
                b) if amess contains non digit charcters, the "default"
                   character (specified in the "match file") is used
                   as a padding character
   useframe : if 1, then include a "left and right" frame
              around the characters (see the "frame" option above for details)
       nobr : if 0, then do NOT put a <NOBR> and </NOBR> around the
              IMG elements (that comprise the message)
     opts   : a string to be included in the IMG elements. 
              For example:
                ' ALIGN=CENTER VALIGN=TOP'
                ' VALIGN=MIDDLE WIDTH=12 HEIGHT=12 '
              In other words, opts can be a list of any IMG element
              modifers.
              Note that this "opts" list is included in all IMG elements,
              including "frame" elements.
     imgsel : the "counter_image_dir" selector.
              If not specified, a value of "DIGITS" is assumed.
     imgdir : Absolute path pointed to by the imgsel. If not specified, 
              the DIGITS subdirectory of the GoServe data directory
              is used.
        
  
For details on how to use SREF_DIGITS, see COUNTER.DOC


-------         ----------          ---------          ------------

SREF_DO_VIRTUAL: Convert a url into an fully qualified file name.

Usage: 
     filename=sref_do_virtual(defdir,aurl,envstring,docheck,trans,homedir,hnick)

where:
        defdir: Default drive&directory to use. If not supplied,
                the default data directory is used (see restrictions below)
        aurl :  A url (of the form /A1/A1/FILE.EXT) to
                convert to an fully qualified file name.
    envstring: An "environment variable prefix".  If
                not supplied, one will be built (based on
                the current http port, as supplied by GoServe) --
                but see restrictions below.
       docheck: If 1, then check to see if the file exists.
                If it doesn't, return 0.
        trans: A unique transaction number.  If not supplied,
               the current transaction number is used (as
               supplied by GoServe).
       homedir: The "home directory" replacement string for 
               the ~ character (may be host specific)
               If no homedir argument, the home_dir environment
               variable is used.
       hnick  : Host nickname -- used to identify the "host".  It is
                used to identify "host sensitive" virtual directory 
                entries.
 
     If docheck=0, or if docheck=1 and a file with the constructed name 
     exists. returns a  fully pathed file name based on the url and 
     either defdir or a match between aurl and the virtual file list.
     If docheck=1 and this match does not exist, returns a 0.

Examples:
    * newfile=sref_do_virtual(,'/herfiles/wedding1.jpg)
      If "herfiles" does not match a virtual directory, then
      newfile=ddir/herfiles/wedding1.jpg

   *  giants=sref_do_virtual('d:\teams','/stars/willymays.html')
      If no virtual directory match to "stars", then 
      giants=d:\teams\stars\willymays.html

     filename=sref_do_virtual(defdir,aurl,envstring,docheck,trans,homedir,hnick)

   *  mymad=sref_do_virtual('d:\journals','fun/mad.doc',,1,,,'SITE2A')
      First useentries for the SITE2A  host, and then "generic entries".
      If mad.doc does not exist, return a 0.

   * realdir=sref_do_virtual(,'WWW2/')
     The virtual directory corresponding to "selectors" under WWW2/
   

Caution: the virtual file list may contain http://xxx.yyy.zzz/abc entries.  
          These are understood by the main SRE-http routine, but NOT by 
          this procedure.
          If such a match occurs, SREF_DO_VIRTUAL will return a 0.

Caution2: as illustrated in the fourth example,
          if you wish to match a directory to a virtual directory
          (without matching any specific filename), you MUST end
          the "aurl" argument with a /.

Restrictions: if not called from an addon, you MUST supply ENVSTRING
(i.e.; if the server is running on port 80, then ENVSTRING='SREF_80_').
If called from a post-filter procedure or an stand alone program, you
must supply (in addition to envstring) the defdir, the trans (you can use
an arbitrary number), and the homedir. You do not need to supply
the host_nickname (if not supplied, host-specific entries will not
be used).



------         ----------          ---------          ------------
SREF_DYNAMIC_PWD

Usage:
  res=sref_dynamic_pwd(appname,newlocation,privset2,duration,respfile,clientaddr)
where
  appname: recommended. the "application" calling this. Used to identify 
           a "shared secret". If not specified, a value DYNPWD is used.
           Note that APPNAME is also used in responses.
  newlocation: recommended. The uri to invoke when client hits the submit
               button. Default value is "/"
  privset2 : REQUIRED. the space delimited list of "secret" privileges. 
             It should contain an entry of the form APPNAME:shared_secret
  duration: optional. duration of a timestamp, in days (and fractions of day)
             (default value is 1 day)
  respfile: optional.the "response file" containing the md5 procedure. If not
            specified, DYNPWD.RSP, in the datadir(), is used.
  clientaddr: client's numeric ip address. Optional, if missing, will get if
            with a GOSERVE extract 
and
  resp='' 
         if a valid password is found
or 
  resp='200 '||length(response) 
        if no valid password is found, 
        sref_dynamic_pwd asks the client to supply one -- this is the
        response code for this "response"

To enable dynamic passwords, you must write an "sre-http" addon that
calls the SREF_DYNAMIC_PWD procedure (SREF_DYNAMIC_PWD is loaded 
into macrospace when needed).  

For further details, please see DYNPWD.DOC.



------         ----------          ---------          ------------
SREF_ERROR: Read/record a request specific  error message.
Usage:
   errmess=sref_error(amessage,do_pmprintf)
where:
   amessage= Optional. If supplied, amessage will be recorded.
  do_pmprintf= Optional. If greater then or equal to 0, amessage will also 
                be written to the pmprintf window (using pmprintf_sref)

Return: The current error message for this request (possibly an empty string)

Each request has a "error-message" variable associated with it, which
is initialized to an empty string when the request arrives.  SREF_ERROR
can read from, or write to, this variable.  When no arguments are given
(i.e.; errmess=SREF_ERROR()), then the current value is returned; if there
have been no errors or warnings (that is, no calls to SREF_ERROR by SRE-http)
a null string is returned.

When amessage is specified, the current value of the error-message variable
is returned, and it is then set to be amessage.  In addition, amessage will
be written to the SRE-http error log (i.e.; D:\GOSERVE\DATA\ERROR.LOG).

Lastly, if do_pmprintf is greater then or equal to 0, amessage will be written
to the pmprintf window (pmprintf_sref is used).

Restriction: can only be called from an addon.

------         ----------          ---------          ------------

SREF_EXPIRE_RESPONSE: Build a response header that does not have an
immediate expiration.

 ***   USE OF SREF_EXPIRE_RESPONSE IS NO LONGER RECOMMENDED --   ***
 ***                    USE SREF_GOS instead!                    ***

Usage: foo=sref_expire_response(aoffset,alength,atype,noauto,pragvalue)
   aoffset is fraction of day to add to current date/time. This will
     be converted to gmt (assuming gmt variables have been set, as described
     in goserve.doc). If aoffset<0, then an "expires" header will Not
     be written.  Default is 0.04

   alength is the size of the document being sent. Default is 0
   atype is the mime type. Default is text/html
   noauto= Y or N: If Y, or if missing, then suppress auto - headers.
   pragvalue=value to use in a Pragma: header.
             If 0, suppress Pragma header.              
             If not specified, a Pragma: no-cache header is added.
           

Restriction: can ONLY be called from an addon.


------         ----------          ---------          ------------


SREF_EXTRACT_BLOCK : Extract a "labeled block" from a string.
Usage: ablock=sref_extract_block(haystack , alabel , delim1  , delim2  , delim3)

 Extract a block from haystack, defined by a Labeled block,
  where the label has the form delim1 label delim2 multi-line_string delim3  xxx
 Default values of delim1={,  2=}  3={
 Note that labels must have NO embedded spaces.
 

Example: if haystack= <!-- SELECT --> this is text to select <!-- END_SELECT -->
and label=SELECT, delim1='<!--', delim2='-->, and delim3='<!--', 
then ablock would be "this is text to select".  Note that the END_SELECT
is ignored.  


Restrictions: none 

-------         ----------          ---------          ------------
SREF_FIND_INDEX  : Query an SRE-data daemon for a match

Usage
   results=SREF_FIND_INDEX(target,qname,varname,nth,loc_only,timeout)
where:
   results = a 2 part response, seperated by a comma. The first part
            is the "record # of the matching record", or a 0 if no
            match, or less then 0 if an error. The second part is 
            what was matched (i.e.; the record containing the targeted 
            identifier); or a blank if no match (or error) occured.
  target = the string to search for>
  qname  = the "name" used when sredata was invoked 
  varname = (optional) Search by varname, not by "identifier"
            Or, invoke a special command
   nth    = (optional) return nth match
  loc_only = (optional) Return location, do not return a "value"
  timeout=   (optional)  max seconds to wait on daemon

SRE_FIND_INDEX is designed to work with the SRE-Data addon.


-------         ----------          ---------          ------------

SREF_FIX_URL  : Creates a proper HTTP URL.

Usage:  
   newurl=sref_fix_url(local_url,servername,serverport)

Servername and serverport are optional; if not supplied the 
current (canonical) servername and port are used (but see restrictions
for a proviso). Local_url can either be a (local) selector, or it can be 
a fully qualified URL.

The newurl will contain the http://, servername and port, and selector;
where the selector may be a substring of the local_url.

Note that SREF_FIX_URL will NOT add servername and serverport information
if the local_url already contains it

Also not that this may not work if the local_url contains periods
in subdirectory names.


Examples (assuming the server's address is foo.bar.net on port 80):

 *   newurl=sref_fix_url('dir1/prices.htm')
        will return http://foo.bar.net/dir1/prices.htm

 *   newurl=sref_fix_url('dir2/quality.shtml','joes.store.com')
        will return http://joes.store.com/dir2/quality.shtml

Restrictions: if called from a non-addon, you MUST provide the servername
and serverport. If are using a multi-host server and want to redirect
back to your own server, you SHOULD provide the appropriate servername
(it is risky to assume that the "canonical" servername is appropriate).



-------         ----------          ---------          ------------

SREF_GET_COOKIE:  Check for a cookie
Usage: cookie_value=sref_get_cookie(cookie_name,nth)

SREF_GET_COOKIE will check the request header for the "nth" cookie with
the name given in cookie_name. If found, its value will be returned.
If not found, an empty string will be returned.  Note that if nth is
not included, the first matching cookie is used.

For example, if the request header contains:
   cookie:  customer=wiley_coyote
then
   sref_get_cookie('customer') will return "wiley_coyote"
 
Alternatively:
   cookie:  customer=wiley_coyote ; item=bazooka ; customer=roadrunner 
then sref_get_cookie('customer',2) will return "roadrunner"

Note: cookie_name is case insensitive, but cookie_value is not

Restictions: can ONLY be called from an addon. In cgi-bin scripts, use 
value('http_cookie',,'os2environment') instead.

-------         ----------          ---------          ------------

SREF_GET_URL  : Retrieves a resource, given a  URL to an HTTP server.

Usage:  stuff=sref_get_url(url,maxchar,verbose,headers)

Will do socket calls to do an http/1.1 style  "GET" of  a URL from an 
http server.

Returns the resource sent by the server (without response headers).

Returns "0" (without the quotes) if any problem occurred (will also
write a message to the SRE-http error log)

URL : The "URL" to request.  You can specify a fully qualified URL (such as
      http://www.census.gov/index.htm), or a "local selector" (such as
      /files/listing.htm).  In the latter case, the local server (and port)
      is used).

MAXCHAR:  Will get first MAXCHAR characters; if MAXCHAR is missing, get 
           first 10 million (presumably you'll never ask for more then that!)

VERBOSE:  If 1, PMPRINTF some stuff
HEADERS:  Optional request headers to add. Each request header should be seperated by a
          CRLF ('0d0a'x). For example:
             headers='Referer:me@someplace'||'0d0a'x||'User-Agent: Mozilla 2.0 (emulating)'
                

CITATION: SREF_GET_URL is adapted from MOVEAUD.CMD, that comes with GoServe.

Restrictions: none


-------         ----------          ---------          ------------

SREF_GRAB_FILE: Read a file, and return it (and wait if it's currently locked)
Usage:   afile_string=sref_grab_file(afile,seconds_to_try_for)
               (see descriptions above)

Returns:
   If file exists/is accessible, returns the file (complete with all
CRLF's etc.). If file does not exist/ is not accessible, returns a 0.

Caution: If the file just contains a 0, then the afile_string will
         equal 0.  In these cases,the use of 0 as an "error" code
         is obviously misleading.

Restrictions:none

-------         ----------          ---------          ------------
SREF_GOS: Send information to a client in an http/1.1 compatible way

Usage: 

  status  =SREF_GOS(acmd,varname,dorange,hdrs)
where
   acmd = A content transfer command. ACMD has two modes: FILE and VAR
 varname= When a VAR type of acmd, the stuff to send
 dorange= If 1, then check for range requests
 hdrs   = CRLF delimited list of extra response headers. I.e.; the contents
          of an advanced-options file.

In most cases, you won't need to specify dorange and hdrs. However,
hdrs can be very useful when you want to fine tune the response headers;
for example, if you want to control the value of the cache-control response
header.

Basically, using SREF_GOS is like issuing a GoServe completion code --
but instead of issuing the completion code by itself, you use it as the
acmd argument.

For example, instead of:
   'FILE type text/html name d:\www\bar.htm'
you should use a FILE mode call of:
   stat=sref_gos('FILE type text/html name d:\www\bar.htm')

Similarly, instead of:
    'VAR type text/plain name make_stuff'
you should use a VAR mode call of:
    stat=sref_gos('VAR type text/plain name make_stuff',make_stuff)
(the 'name make_stuff' portion of the acmd argument is optional).

The following elements are permitted in both the FILE and VAR versions of
the acmd argument.  Note that most of these are the same as in the native
GoServe calls; with some additional meanings.

 NAME 
   Used in FILE mode calls -- the next word is the file to
   send to the client.
   Example: 'FILE type text/html NAME D:\WWW\FOO.HTM'

 TYPE   
   The mime type of the content (used to create content-type header)

 ENCRYPT enctype
   Instruct SREF_GOS to encrypt the response.
   Enctype should have the following structure:
      method:epwd
   where
      method = the encryption method. SRE-http provides SRE_A and SRE_B
               methods.
      epwd   = the "shared-secret" encryption password. This is typically
               found in a client's ?ENCRYPT:epwd "server privilege".
   For example:         
                ENCRYPT SRE_A:foorab

   Notes:
     * use of an ENCRYPT option in an SREF_GOS call will
       override the various "default" and "advanced option" encryption
       options. 
     * To disable encryption, use ENCRYPT 0:0
     * For further discussion of encryption, see ENCRYPT.DOC.

 ERASE      
   Temporary response -- set the max-age header to 0.
   Also: If FILE mode, then delete the NAMEd file after sending it. 
   If VAR, ERASE is the default (but nothing actually get's erased). 

 ETAG an_etag
   The ETAG to use. If not specified, SREF_GOS will compute one.
   Caution: if you specify an ETAG. delta-encoding will be suppressed
            (see DELTA.DOC for the details).

 MAXAGE nnn
    Set the max-age cache-control option; where max-age nn should be
    number of days (decimal values are allowed). Or, you
    can specify Hours, Minutes, or Seconds.
    For example:
        MAXAGE .04  
        MAXAGE 0.04D
        MAXAGE  1H
        MAXAGE 45M
        MAXAGE 1800S

    Note that if ERASE is used, then MAXAGE nnn is ignored

 NOERASE
   Non-temporary response. This is ignored in FILE mode, but suppresses
   the max-age=0 if used with VAR.

 NOCACHE  
   Suppress public caching (private caching is allowed)

 NOCACHE* 
   Suppress all caching (public, private, and sreproxy caching is NOT done).

 NOIF
   If NOIF appears, then SRE-http will not check the various If-
   conditions (such as If-Modified-Since)

 CACHE  
   Enables public caching.

 CACHE*
   Enables public caching, and enables the GoServe cache.

 RESPONSE    
   Change the http response code. If not specified, SREF_GOS determines
   the response (typically, 200 Ok).
   The word following RESPONSE should be the response line -- 
   which should consist of a number and a short description.  
   The number and the description should be seperated by url-encoded
   spaces (%20).
   Example: 
      'FILE type text/html NAME D:\WWW\FOO.HTM RESPONSE 201%20Content%20Created'

 CLOSE
   Force an immediate close of the connection 
   (normally, http/1.1 clients are  maintained).
   Example: 'FILE close type text/html NAME D:\WWW\ERROR.HTM'

Notes:
  * By using SREF_GOS, you can ensure that appropriate http/1.1 
    style headers are added to the response.  
  * Furthermore, SREPROXY only knows about responses returned via SREF_GOS.
 

SREF_GOS and cache control.

   The Cache-control response header  is used to instruct
   caches (both on proxy servers, and on client's machine) when
   and how to cache a response.

   SREF_GOS uses a somewhat convoluted set of rules to construct a
   "Cache-control" response header. These rules consider:
      i) Whether VAR or FILE is used
     ii) Whether  ERASE, NOERASE, CACHE, CACHE*, NOCACHE, or NOCACHE* is specified
    iii) The value of the PROXY_CACHE parameter

  In some cases these SREF_GOS rules, and the kind of controls you may have using
  the above factors, may be unsatisfactory.  For example, clients may
  be over-refreshing.  If this should occur, use of the hdrs argument (the 4th
  argument) can be helpful.

  HDRS should be CRLF ('0d0a'x) delimited list of statements of the form
    'HEADER ADD name: value '.
   or
    'HEADER DROP NAME:'

  In particular, you may wish to use:
     'HEADER ADD Cache-Control: cache_tokens'
  where cache_tokens are a list of cache-control tokens (as described in RFC2616).

  For example:
    hdr='HEADER ADD Cache-control: private,max-age=200'
    foo=sref_gos('FILE type text/html ERASE name d:\temp\foo.1 ',,,hdr)


Restrictions: can only be called from SRE-http addons.

-------         ----------          ---------          ------------

SREF_GZIP: Create a "gzip" compressed string

  usage: string_gzipped=sref_gzip(astring)

The inverse of SREF_UNGZIP.

Typically, string_gzipped with be written to a .GZ file.

Restrictions: uses the rxGZlib.dll library that comes with SRE-http -- make sure
             that rxGZlib.dll is in a LIBPATHed directory.
      

-------         ----------          ---------          ------------


SREF_HOST: A "host lookup"
Usage:  aresult=sref_host(ipaddress)
        IPaddress can be numeric or character (with appropriate periods)
Aresult is a sentence noting the ipaddress and the name associated with it.

Restrictions: none



-------         ----------          ---------          ------------

SREF_HOST_INFO: Return "host specific" information.

SREF_HOST_INFO uses the server's ip address, and any HOST: header, to
find a matching entry in the HOSTS. variables.

Usage  stuff=sref_host_info(myaddr0,nhosts,envstring)

   where: myaddr0 = the ip address of the server (to whom the request was sent)
          nhosts = the number of hosts defined in the HOSTS. variables
       envstring = environment variable preface
and stuff will contain
  0 = No match in HOSTS variables
     or
  parse var stuff servername ',' nickname ',' ddir 
    where
      servername : the servername for this request (possibly pulled from
                   a HOST: request header)
      nickname : SRE-http nickname for this servername 
      ddir     : Default data directory

If myaddr0,nhosts, and envstring are not specified, sref_host_info will
figure them out.

Restrictions: can  ONLY be called from an ADDON (uses the GoServe REQFIELD function)

-------         ----------          ---------          ------------


SREF_INSERT_BLOCK : Insert a block into a string, at a "labeled" location.
Usage: 
  newhaystack=sref_insert_block(haystack,alabel,add_string,after,delim1,delim2)

   Insert a add_string into haystack, right  after or before aLabel.
     where the alabel has the form delim1 label delim2
   Insertion is immediately after delim2, or before delim1
   (if after=1, then after)
   Default values of delim1={,  2=}
   Note that labels must have NO embedded spaces.

Returns the added to (or not added to) haystack

Restrictions:none


-------         ----------          ---------          ------------


SREF_JULDATE  : Returns julian date (since  1/1/0000) and fractional time

Usage: 
   juldate=sref_juldate(mode, time_string)
where:
      mode: F: Date/time is: yy/mm/dd/hh/mm/ss mode 
               as returned by sysfiletree(afile,'stem','FT')
            T: Date/time is: yyyymmdd hr : mm : sec
               as returned by: adate=date('S')|| ' '||time()
  time_string: The time string (using one of the above modes)
               If time_string not specified, use current date & time.

Typical return: 729152.125451 ; with the fraction accurate to about 
                a second.

Caution: we recommend using a rexx statement of "numeric digits 11"
before calling (otherwise, accuracy will be only good to a minute).
Example:
   numeric digits 11
   adate=word(sysfiletree(afile,'stem','FT'),1)
  jdate=juldate(adate,'F')


Restrictions: none


-------         ----------          ---------          ------------

SREF_LOOKUP_COUNT : Augment a SRE-http "counter file"
usage: 
   newcount=sref_lookup_count(ctfile, needle, augment , substring , noadd)
where:
       ctfile: Name of the "counter file" to examine 
               Should contain entries that have the format:
               Aurl  ACount  optional_info
       needle: The target of the search. Typically a URL.
      augment:  YES: augment the count
                ADD: augment the count, or if needle can not be found,
                    add new entry with count=1
    substring: EXACT: Exact match only
                   *: Use wildcard match if no exact match
                          ABBREV: Use abbreviation match if no exact match
        noadd:     1: just return matching filename and message
                      (do NOT lookup count or augment)
                   2: set optional_info equal to the current date,
                      and augment the value of acount

Returns a space delimited list containing STATUS COUNT optional_info
     If status=0, then some failure, 1 then success,
     2 then no match, but we added it (only possible if AUGMENT =  ADD)


Restrictions: none


-------         ----------          ---------          ------------

SREF_MAILIT :  Use REXX socket calls to send e-mail
Usage: 
    status=sref_mailit(address_list,message,smtp_gateway,sender_address)

where:
    address_list: A space delimited list of addresses
         message: A message string, that may contain CRLFs
                 (and may be rather long)
    smtp_gateway: The IP address of your SMTP server
  sender_address: The sender's address (optional)
                 If sender's address  is not given, it will be generated using
                GoServe's servername() function.

  Status: 0 if failure to connect, 1 if success

  Examples:
       status=mailit("BOB@HIS.NET" , "This is my message ", "MAIL.MY.ORG" )
       status= mailit("BOB@HIS.NET JILL@HER.COM " , "This is my message ", ,
                    "MAIL.MY.ORG", "HARRY@MY.ORG")

  Note on recipient addresses:
     The message will be sent to each address.  Since the addresses are
     sent and then the message, this allows for fairly rapid mailing to multiple
     individuals.
 

Notes:
   *  The POSTMAIL.80 "post-filter" uses a local version of SREF_MAILIT
   *  POSTMAIL.80 contains a useful discussion of some of the limitations of
      the OS/2 SENDMAIL 
   *  CITATION: SREF_MAILIT is a modification of a routine written by Dave Briccetti.  
                                                                                 

Restrictions: if NOT called from an addon, you MUST specify the sender_address.


-------         ----------          ---------          ------------

SREF_MAKE_BLOCK  : Replaces substrings with other substrings.
Usage: newhaystack=sref_make_block(needle, haystack, delim1 , delim2, check_case)

      Replace all occurences of NEEDLE in HAYSTACK with delim1 needle delim2.
      If delim1 and delim2 not given, then { AND } are used.
      Example: make_block('boys',' there are wild boys out there','<b>',' </b>')
           returns 'there are wild <b>boys </b> out  there'
           (note that spaces are all retained).
      IF check_case=1, then cases must match (between needle and haystack)

Restrictions: none 

-------         ----------          ---------          ------------

SREF_WILD_MATCH : Performs a wildcard match, with "is this better" check

usage:
    matchinfo=sref_wild_match(needle,haystack,old_matchinfo,suppress_noslash)
where:
    needle : the string to search for
  haystack : the string to search in, it can contain * wildcard characters
 old_matchinfo: matchinfo from prior calls to sref_wild_match using same needle
 suppress_noslash: if 1, then suppress the trailing-| "noslash" feature

SREF_WILD_MATCH returns information on the quality of the match, information
which can be used in subsequent calls to SREF_WILD_MATCH to treat "worse"
wildcard matches as non-matches. Thus, you can use a a series of calls to 
SREF_WILD_MATCH to find the "best match" of a needle against a set of 
haystacks that may contain wildcards.

Returns (note that all comparisions are case insensitive):
        Situation                          Returns
        ------------                       ----------
  If needle is exact match to haystack      -1

  If needle does not match haystack          0
  (even with wild card checking) 

  If needle wildcard matches haystack,       match information
   and old_matchinfo='' (or if           (a list of numbers signifying
   old_matchinfo is not specified            matching characters in needle)   

  If needle wildcard matches haystack,       match information
     and old_matchinfo<>''    
     and the current match is a "better"
     match then the "old_matchinfo" match 
 
  Same as above, but if the current          0
   match is NOT a better match          
 
Basically,
  -1 means "exact match",
   0 means "no match" or "not better match" (if old_matchinfo not specified, 
       0 always means "no match"), 
   and everything else means "wild card match" (that's better then prior
       "best" wildcard match).

Example of usage:
   /* Example of  use of sref_wild_match */
   a.1='This is *'
   a.2='This is a *'
   a.3='This is a funny * story'
   a.4='* is * '
   a.5='Th* fun*'
   a.6='This is funny *'

  say "Enter string : " ; parse pull ans
  old_matchinfo=''; isit=0
  do mm=1 to 6
     haystack=a.mm
     resu=sref_wild_match(ans,haystack,old_matchinfo)
     if resu=-1 then do
       isit=mm
       leave
     end
     if resu=0 then iterate
     isit=mm
     old_matchinfo=resu
  end
  matchingvar=isit

Thus, if you entered ..... then MATCHINGVAR would be equal to:
    That is silly                  4
    This is a man                  2
    This is not mine               1
    This is a funny but sad story  3  
    This is funny today            6
    That may be                    0  (no match)
    This is a *                    2  (exact match)

Caution: You MUST set old_matchinfo='' before the first call in a series of calls
       
SPECIAL FEATURE:
  If haystack ends with a |, then no "slash" is allowed in the
  final wildcarded portion of the needle.  That is, the portion of the needle
  "covered" by the final asterisk in the haystack can NOT contain a / or a \. 
  If it does, it's a NO MATCH.  

  Note that this feature is suppressed when suppress_noslash=1

 Examples:
    using a needle of: 
       animal/cats/food.1
  The follwing haystacks yield:
       animal/*candy  --  no match
       anim*/*.1      --  match
       animal/*.1|    --  no match (* covers cats/food, which contains a /)
       anim*/food*|   --  match (final * covers ".1")
       */cats*|       --  no match (final * covers "/food.1")

  The primary purpose of this feature is to "limit" wildcard matches to a 
  single subdirectory (that is, to prevent matches to items in deeper 
  portions of the directory tree)
  
Hint: if you don't care about "best matches", use 
            ismatch=sref_wild_match(needle,haystack)
      and treat any non-0 value of ismatch as signifying a match.

Restrictions: none

-------         ----------          ---------          ------------

SREF_MEDIATYPE :  Returns mime type of a file
    Usage: mimetype=sref_mediatype(filename,port)

filename: name of file to deduce mime type of
port: optional, used when caleld from non-addons

Uses the extension of filename to determine the mime type.
For example, AA.HTM would yield "text/html".

SREF_MEDIATYPE will check the MEDIATYP.RXX file (of custom media types),
that is located in the GoServe working directory.

Restrictions:
  if called from something other then an SRE-http addon, you MUST
  include a port. If called from a stand-alone, the mediatyp.rxx file
  will not be available.
  

-------         ----------          ---------          ------------

SREF_MD5 : Create a "MD5" digest

  usage    md5_digest=sref_md5(astring,isfile)

where:
   astring: the string to "digest", or a fully qualified file name
   isfile: If 1, then atring is a filename (the contents of the
           file will be md5'ized; not the filename itself.

MD5 is used in various cryptograhic settings. SRE-http uses MD5 to 
return content-md5 response headers (which provides an integrity check),
and in digest authentication (which sends an md5 encrypted password).

Restrictions: uses srxfunc.dll.


-------         ----------          ---------          ------------

SREF_MKPACK64 : Create a "base64" string.
 
   usage:  string_packed_64=sref_mkpack64(astring)

The inverse of SREF_PACK64.

Note that  astring=sref_pack64(sref_mkpack64(astring))

Caution: this is NOT very efficient for long string (say, greater
          then 3000 bytes).

Restrictions: none
 



-------         ----------          ---------          ------------
-------         ----------          ---------          ------------
-------         ----------          ---------          ------------



-------         ----------          ---------          ------------
SREF_MULTI_SEND : Facilitates creation of "multi-part" documents.

SREF_MULTI_SEND is used to create multi-part document. It can also
be used to "send pieces" of a document as it becomes available.

  usage:
    rcode=sref_multi_send(message,mime_type,howsend,file_flag,verbose,wname,optheaders)
where:
   message:  either contains the "message" to be send (either a text string or
             binary value); OR it contains a fully qualified file name.
   mime_type : A mime type; such as text/html or image/gif
   howsend : A flag that tells SRE-http "where in the multi-send process
             we are".  There are basically four values (with 
             possible modifiers):
              '1' == Single part document to "send in pieces" (requires
                     a modifier)
              'S' == Start the multipart send (i.e.; the first image)
              'M' == A middle piece -- more will follow
              'E' == End piece -- send this "message" and close the connection.
               
             In addition, you can "build" a long message, and display 
             each portion as soon as they are added.  To do this, use the
             following HowSend codes:
                '1S' and '1E' -- Start and end a "sent in pieces" single part
                                 document
                'SS' and 'SE' -- Start and end the first "part"
                'MS' and 'ME' -- Start and end the middle "part(s)"
                'ES' and 'EE' -- Start and end the final "part"
                'A'  and '1A' -- Add stuff (between 1S-1E; SS-SE ; MS-ME; or ES-EE)
   fileflag: If equal to 1, then "message" is to be treated as a
              fully-qualified file name (Optional)
   verbose : If > 2, some status info will be displayed (optional)
   wname    : Name to use when writing to GoServe audit file (for future 
             implementation)
   optheaders: optional response headers (crlf delimited)

The return code (rcode) is the RC from the 'SEND' command: you can
check for negative values which  indicate a broken connection.

For further details on SREF_MULTI_SEND, see MULTSEND.DOC


Advanced users note:
   To force "connection close", you need to modify the howsend argument of
   1, S, SE, E, EE, and 1E by adding a ' 1'.   That is, use
   1 1 and 1E 1 (or S 1 and E 1).
   Examples:
        foo=sref_multi_send('hello','text/plain','1 1',0)
        foo=sref_multi_send('stuff here',,'1A',0)
        foo=sref_multi_send('goodbye',,'1A 1',0)
   or
        foo=sref_multi_send('pic1.gif','image/gif','S 1',0)
        foo=sref_multi_send('pic2.gif','image/gif','A',0)
        foo=sref_multi_send('pic3.gif','image/gif','E 1',0)

Restriction: this can ONLY be called by an addon (it makes heavy use
             of the GoServe API).



-------         ----------          ---------          ------------

SREF_GMT: Compute a new GMT time, given a date,time,and offset


 Usage:  newtime=sref_gmt(offset,basetime,outtype,gmtoffset)
   where:
        offset  -- offest in days, hours, seconds, or minutes
        basetime -- in several formats
        outtype --- format of output
        gmtoffsett   --- size of gmt offset

   Returns
        Time (including GMT offset and "user supplied" offset) in desired format

 More Details:

   Offset: Add an offset to the "current time". Format can be:
      days : use a real number. i.e.;  1.3  (1.3 days), or 0.05 (1/20 day)
                (or you can add a d; say, 1.3d)
      hours:  use an integer followed by an h. i.e.; 1h.
      minutes: an integer followed by an m.  i.e.;  60m
      seconds: an integer followed by a s. i.e.; 3600s

      Default is 0 (no offset)

  Basetime: The time to add the offset to. The format can be (SRE_GMT
            will recognize the format)
      julian     ---  728882.887731  
                                (days since 0/0/00 . fraction of day)
      internet ---  Sat, 12 Aug 1996 21:18:20 GMT
  old internet ---  Saturday, 12-Aug-96 21:18:20 GMT
   ansi c      ---  Sat Aug 12 21:18:20 1996   
  sysfiletree  ---  96/08/12/21/18 or 96/09/12/21/18/22

  The Default is the current time

Outtype
   I       --- internet
   J       --- julian   
   C       --- cookie -- similar to internet, but use 12-Aug-1994 
                    (suitable for expires field of set-cookie)
   F       --- sysfiletree  

   Default is I

GMT_OFFSET
   If 0, do NOT offset (do NOT add the GMT to I or C outtype)
   If >0, then use this as the GMT offset (in SECONDS)
   Default: use the TZ environment variable (via the GoServe gmtoffset function)

Examples:
  say sref_gmt()
  say sref_gmt(,728882.88773)
  say sref_gmt(.12,'Sat, 12 Aug 1996 21:18:20 GMT','J')
  say sref_gmt('18000s','Saturday, 12-Aug-96 21:18:20 GMT')
  say sref_gmt('300m','Sat Aug 12 21:18:20 1996 ')
  say sref_gmt('5h','96/08/12/21/18','C',0)
  say sref_gmt(,,'F',0)
yields ....
   the current I style date/time-- say Wed, 24 Feb 1999 00:04:36 GMT
   Tue, 13 Aug 1996 02:18:19 GMT
   728883.216064
   Tue, 13 Aug 1996 07:18:19 GMT
   Tue, 13 Aug 1996 07:18:19 GMT
   Tue, 13-Aug-1996 02:17:59
   98/03/26/22/55

Restrictons: can ONLY be called from an addon.


-------         ----------          ---------          ------------

SREF_OPEN_READ: Open a file for read/write (and wait if it's currently locked)
SREF_OPEN_READ simulates a "write protected semaphore" -- it delays 
returning until the file is no longer locked by a writing process.

Usage: open_time=sref_open_read(afile ,seconds_to_try_for , howopen )
        afile: file to open
     seconds_to_try_for : seconds to try for
        howopen: BOTH= open as read/write
                 WRITE= open as write
                 NEW = open as write, must not already exist
                 READ = open as read (the default)
Returns:
 -2 : Timed out
 -1 : File does not exist, or does exist (if howopen=WRITE)
 >0 : Seconds it took (minimum value of 0.01) to open

Restrictions: none


-------         ----------          ---------          ------------
SREF_PACK64 : Convert a "base64" string.
 
   usage:  astring=sref_pack64(packed_64_string)
 
This is a rexx version of the GoServe pack64 function.  Quoting
from GoServe.doc:
   Takes a single string, expressed according to the MIME "Base64"
   specification (in RFC 1521), as an argument and returns the decoded
   (packed) string.  Each four bytes in 'string' is packed to three bytes
   in the result (except possibly for the last four bytes); 'string' must
   be a multiple of 4 bytes.  If any deviation from these specifications
   (or from the RFC 1521 "Base64" character set) is found, the null string
   is returned.

  PACK64 is useful for processing the incoming user/password data encoded
  for the HTTP 'basic access authentication scheme' -- see the HTTP
  documentation for details.

We provide this function, as well as SREF_MKPACK64 for CGI-BIN and
other "non-goserve" processes.

Caution: this is NOT very efficient for long string (say, greater
          then 3000 bytes) -- use the GoServe PACK64 if you can!


Restrictions: none

-------         ----------          ---------          ------------

SREF_REPLACESTRG: Replace substrings
Usage: 
    newstring=sref_replacestrg(haystack,needle,replacement, type , exactmatch)
where:
        haystack: The string to search in
        needle: The string to search for
     replacement: Replace occurences of "needle" with "replacement"
          type: 
                FORWARD: Replace first occurence
               BACKWARD: Start from end, replace "last" occurence.
                    ALL: Replace all occurences
    exactmatch:  if YES, then cases must match (NO=case is ignored).
             Note that the case of the "replacement" is retained, as
             well as the non-replaced portion of the haystack, regardless
             of the value of exactmatch.

Returns:
     The haystack,with the replacements (if no replacements, return the
     original value of haystack)

Restrictions:none

-------         ----------          ---------          ------------
SREF_SEARCH_FIXED: Search a fixed-length record file for a match
Usage:
  match_record=sref_search_fixed(string,filename,numrec,reclen,recoff,idat,idlen,type)
where:
  string : The string to look for
  filename: A fixed-length record file to look in
  numrec:  # records in filename
  reclen: length of each record (must include possible crlf's at end of line)
  recoff: number of header records (offset from start of file) --- they will
          be skipped when searching
  idat:  Character (in a record) that identifier variable (to be searched) 
         1 is the first character
  idlen: length, in characters, of identifier
  type: Type of search
        1 = Exact match (no space stripping, case sensitive)
        2 = Wildcard match (string can have * wildcards)
        2 n = Same as 2, but return nth match (i.e.; 2 and 2 1 are the same)
        otherwise: strip spaces, case insensitive match.

  Wildcard matches are attempted "one record at a time" -- it's much slower
  then the binary searches used for exact and non-exact matches.
 
  Note that if you use one of the binary match types, be sure the sort order
  is appropriate (i.e.; if exact is used, then pay attention to case)

Returns:
  If a match is found, the matching record is returned.
  If no match is found, a '' is returned.
    
Restrictions: none


-------         ----------          ---------          ------------
       
SREF_VERSION  : Returns string listing the SRE-http version
Usage:
   filter_name=sref_version(port)
or  
  filter_number=sref_version(port,1)

where port is optional.

When a second argument of 1 is used, then a "numeric" version number is returned.
Otherwise, a descriptive string is returned.

Sample descriptive string return: SRE-http Ver 1.3c.0299.a 
Or, as a  numeric return: 130301.2 
    ver 1.3, subversion 3 , build  number 1; 
    the .2 signfies that SREPROXY is being used

The numeric return provides a convenient way of comparing the revision to
some 'minimal value'.

The (~proxy), or (std), refer to the "proxy" (SREPROXY) or standard (SREFILTR)
versions of SRE-http.

Restrictons: if called from a non-addon, you should include the 
port of the server (if not included, a default value of 80 is used).




-------         ----------          ---------          ------------

SREF_VALUE: Get value from the OS/2, or SRE-http, environment.


SREF_VALUE is a general purpose "value of a variable" procedure.

SREF_VALUE is able to extract and set variables that 
reside in  four different "environments". These four
environments are:

   i) OS2 : the  os/2 environment variables
  ii) INI : the SRE-http initialization parameters
 iii) REQ : request specific variables 
  iv) USE : semi-permanent user defined variables


Calling syntax:
     value=SREF_VALUE(varname,newval,env,optinfo,port,prefix)
where:
    varname : the name of the variable to look up
    newval: a new value for this variable. If not specified, or if set
            equal to a zero-length string (i.e.; newval="")
            a new value will NOT be set
     env: The "environment" to look in; either OS2,INI, REQ, or USE.
  optinfo: Optional: information: used if env=REQ  or env=USE.
  port : Optional: the port (that goserve is running under)
  prefix: Optional: the "sre" prefix (typically, SREF_80_)

If prefix is specified, port is ignored.
If sref_value is called from a GoServe thread, port and prefix are
unnecessary.

In any case, the current value of the variable will be returned; and if NEWVAL
is specified, the variable's value will then be changed to this NEWVAL.

ENV specific notes:

  * For all values of ENV, setting VARNAME='*' will cause a space 
    delimited list of "currently available variables" to be returned.

  * env=OS2 is equivalent to the use of OS/2's value function, with 
    the added bonus of the * "list variables" option. Note that when *
    is used with env=OS2, INI variables will be detected and NOT displayed.

    Note: in a multi-host environment, you can obtain a "host" specific
          value of a variable by including a .HOST_NICKNAME to the
          VARNAME (seperated by a space). 
          For example,
             if you've defined a HOST with a host nickname of "SITE2",
             and want the "host specific version of THE_REALM", 
             then enter VARANAME='THE_REALM SITE2'.  
          Note that if there is no "host-specific" value, the "generic"
          value will be used.  
 
  * env=INI is equivalent to using OS/2's value function on variables that
    begin with SREF_nn, where nn is the "current port" (port 80 if 
    no current port can be determined).

  * When using SREF_VALUE in a stand-alone process (not under GoServe/SRE),
    to use the REQ "environment" you MUST first issue a
          call sref_value('!INI',,'REQ',,,'SREF_80_')  
    (assuming that GoServe/SRE is running on port 80).

  * When using env=REQ, and calling from a post-filter procedure, or from a 
    stand alone program, OPTINFO should contain the appropriate request id (as
    assigned by GoServe).
    SRE-http provides this name to post-filter procedures. For stand-alones,
    you'll have to figure it out (sorry, we do not provide a mechanism for 
    doing this figuring out).

  * env=USE is the only way (short of writing your own code) of reading/writing
    "user defined, semi-permanent" variables.

    These variables are constant (unless explicitily modified) across
    requests -- they belong to the GoServe process (and NOT to
    a specific request). 

    Although specific to a GoServe process, these variables can be
    accessed from any other process. To do this, you must set the
    OPTINFO variable to be the "port number" (i.e.; miscinfo=8080) 
    of the GoServe process (if OPTINFO is not specifed, a port number 
    of 80 is assumed).
  
  * env=USE and env=REQ both use the SRE-http "variable storage daemon". 
   This daemon can handle any kind of string, of any (reasonable) length. 

    Thus, using SREF_VALUE('USE',...)is much more flexible than 
    using the REXX VALUE(,,'os2environment') function; since the OS/2 
    environment does  NOT like  binary strings, and gets  flakey when a string
    of any size (say, greater then 1024 bytes) appears.

    Of course, this also means that to use USE and REQ, GoServe/SRE
    MUST be running in some currently active process.


Note: SRE-http comes with a simple demo of SREF_VALUE --TESTVALU.SHT
      and TESTVALU.CMD.
    
Restrictions: can be called from anywhere, given the above concerns.

-------         ----------          ---------          ------------
SREF_QUEUE

SRE-http supports a flexible form of "queue". The primary purpose of these 
SRE-http queues is to store and retrieve information in a globally accessible, 
semi-permanent location. In many ways, they are functionally similar to REXX 
queues, but are much more easily manipulated.

SREF_QUEUE is called as:
    
      retvalue=SREF_QUEUE(QueueName,action,value,port)

where:
      queuename: The name of a queue; it can be any REXX-style, variable name
      value: Either the value to be added to the queue, or instructions on
             how to read from the queue
      action: Type of action (PUT, QUEUE, POP, READ, etc.)
      port: Optional:: required if SREF_QUEUE is not called from an addon. 
            If called from an external process (such as a CGI-BIN script),
            this should be the port that SRE-http is running under (typically,
            80).


For details on how to use SREF_QUEUE, see SREFQUE.DOC

Restrictions: same as sref_value -- can be called from anywhere, but you
might need to supply the port.

-------         ----------          ---------          ------------

SREF_UNGZIP: Uncompress a "gzip" string

  usage: astring=sref_gzip(gzipped_string)

The inverse of SREF_GZIP.

Typically, gzipped_string will be the contents of a .GZ (or .Z) compressed file.

Restrictions: uses the rxGZlib.dll library that comes with SRE-http -- make sure
             that rxGZlib.dll is in a LIBPATHed directory.
      
-------         ----------          ---------          ------------

SREF_WILDCARD  : Do a wildcard match (with substitution)

Usage:  
    newstring=sref_wildcard(needle,haystack replacement,doexact)
where:
      needle: String to search for
    haystack: String to compare needle to
 replacement: Return this string, after (possibly) inserting
              wildcarded portions of needle into wildcarded portions
              of replacement
             (note there is no comma between haystack and replacement)
   doexact: Exact match flag. If doexact=1, then do NOT do wildcard matching.

returns:  
   code , match
where
   code: 0= none, 1=exact match, 2=replacement match

See if  needle matches haystack.  Haystack can contain *, which are
used as wildcard characters (as with matching file names in OS/2).
If a match occurs, the replacement is returned, possibly with
"substitution" matches  -- i.e.; the part of needle "covered by" the
* in the haystack is placed into the replacement (at the position of the
* in the replacement)

Example:  newstring=sref_wildcard('1234567','12*67 abcde*f',0)
          yields:  newstring= 2 ,abcde345f

Note: Needle and replacement should not contain "real" * characters.


Restrictions: none



-------         ----------          ---------          ------------
-------     SECTION 2: Inter-thread communications in SRE-http
-------         ----------          ---------          ------------


In order to improve throughput, SRE-http has been written as a multi-threaded
program.  The goal is to reduce the size of SREFILTR.80, the GoServe "filter".
The multi-threaded nature of GoServe makes this important: since every
"request" that arrives run's in a seperate thread. If you
only get 1 request at a time, that may not be much of a problem.  However,
when many requests arrive simultaneously, the multiplicity of
"large threads" can bog the machine down.  Since image rich documents will
generate many requests, such occurences of "many simultaneous
requests" may actually be fairly typical (even for a lightly visited site)!

For this and other reasons, SRE-http uses a number of "daemons".
As with "loading the library of macrospace procedures", these daemons are
launched when SRE-http is first run.  Note that unlike the "request
specific threads" launched by GoServe, the daemons stay active as long as
GoServe is running.  In contrast, "request specific threads" are
constantly being generated and killed, as GoServe recieves and responds 
to tcp/ip requests.

Note that launching a thread simply means running a REXX program 
simultaneously. However, in contrast to running programs in different
processes (say, with the DETACH command), REXX threads share a single 
environment.

This "shared environment" feature motivates SRE-http's extensive use of
the environment to store configuration information.  Basically, one of 
SRE-http's daemons  (the SREFMON.CMD thread) loads the 
variables set in INITFILT.80 (as well as variables set in
REPSTRGS.IN) into the environment (SREFMON.CMD also keeps track
of these files, and re-initializes the environment should you change them
"on-the-fly").

If you need the values of these variables, you can use the SREF_VALUE
comamnd to retrieve them. For  example, to retrieve the value of the
CHECKLOG variable, you can use
    check_log=sref_value('CHECKLOG',,'INI')


Technical Note:
    For historical reasons, SRE-http stores these "initialization" 
    variables with a prefix of SREF_port_. For example, if you 
    are running on port 80 (the default http port), and you want the
    value of the CHECKLOG variable, you could extract it using: 
        avalue=VALUE('SREF_80_CHECKLOG',,'os2environment')

Although used by SRE-http, the limitations of the enviroment preclude
its use for many important purposes. Instead, a number of special
"SRE-http daemons" are used. These include:

    USERCHK.RXX:  Used to lookup usernames stored in the USERS.IN file.
    ALIASCHK.RXX: Used for alias matching, it uses the ALIASES.IN file.
    ACCESCHK.RXX: Used for finding access rights and permissions, it
                  uses ACCESS.IN
    VIRTCHK.RXX:  Used for virtual directory lookup, it uses VIRTUAL.IN.
    VARSTORE.RXX: Used for storing semi-permanent variables, clientnames,
                  and recent requests.

These daemons store their data files in memory.  For example, USERCHK 
does not re-read USERS.IN everytime it needs to look up a username/password
combination.  Instead, it examines a "copy" of USERS.IN that is read 
into memory.

In addition to providing semi-permanent data storage, daemons are also
useful in providing non-time sensitive processing. For example: 
    POSTFCHK.RXX: Used for "recording requests" and for "a custom written
                  post-filter".  Uses RECRDALL.IN.
    PMPRINTF.RXX: Used as a front-end to the PMPRINTF procedure.

In addition to these core SRE-http functions, daemon's can be used
in addons.  For example, the SRE-Data addon (a simple web-aware database
addon) uses a daemon to search databases.  Similarly, the SRE_BLNC addon
uses a daemon to provide load balancing.

Ambitious programmers interested in writing addon's that are partially
run as daemons can make good use of a simple set of "SREF_DMN_" 
procedures supplied with SRE-http. These procedures greatly 
facilitate the use of daemons, relieving the need for the programmer 
to deal with most of the myriad details.  The DAEMONS.DOC file
describes these procedures in detail.


-------         ----------          ---------          ------------
-------     SECTION 3: A short discussion of OS/2 SendMail
-------         ----------          ---------          ------------