MacFormat 1996 January/macformat-033.iso/mac/Shareware City/Developers/CGIshell Folder/CGI shell docs.txt

Text File | 1995-09-24 | 8.5 KB | 300 lines | [TEXT/ALFA]

CGI shell, version 1.1


(c) Ronald T. Kneusel, Sept. 1995
[e-mail]

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


*****************************
*                           *
*      INTRODUCTION         *
*                           *
*****************************


DISCLAIMER


    This is a tool for programmers; Forth programmers in particular.  Therefore,
this documentation is intentionally sparse.  After all, real programmers don't
need no steenkin' documentation, right? :)



WHAT IS IT?


    CGI shell works with Chris Heilman's Pocket Forth programming language to
provide a skeleton for creating custom CGI applications for WebSTAR/MacHTTP.
The shell code handles AppleEvents, the interpretation of forms data, and
supplies a set of words for building a reply string.  Pocket Forth, version 6.4
is included in the release.


WHAT DO I NEED TO RUN IT?

    • A Mac running WebSTAR (commercial) or MacHTTP (shareware)
    • This code
    • A text editor (Teachtext or Simpletext will do)
    • Some Forth and HTML programming experience


A FIRST EXAMPLE

    This version of the shell gives you easy access to the direct argument,
the client's IP address, the client's browser type, and the field data.  A
minimal CGI using the shell is:


   \ Simple CGI

   --> CGIshell.4th    ( load the CGI code )

   message[ s1 You are: ]                 ( strings used in the reply )
   message[ s2 <br>Using: ]
   message[ s3 <br>And your favorite flavor is: ]

   message[ fname flavor]        ( name of the field )

   512 String>> out    ( return string goes here, 512 char max )
   out newstr          ( clear it )

   ,s sdoc  ,s WWWΩ  ae:   ( begin the AppleEvent reply handler )

      out startstring          ( add HTML header )

      s1 out strcpy            ( add 'You are: ' )
      out APPEND @Addr         ( add client's IP address )

      s2 out strcpy            ( add '<br>Using: ' )
      out APPEND @Browser      ( add browser type  )

      s3 out strcpy            ( add '<br>And your favorite flavor is: ' )
      out fname APPEND @Field  ( add flavor field data )

      out endstring            ( add HTML ending )

      out REPLY  bye           ( send the reply and quit )

   ;ae                    ( end reply handler )



This CGI will respond to an HTML form like this one:


   <h1> Simple CGI test </h1>
   <form method=post action="simple.cgi">
     What is your favorite ice cream flavor?
     <select name="flavor"
       <option>Vanilla <option>Chocolate <option>Strawberry
     </select>
     <input type=submit value="Send it">
   </form>


To create 'simple.cgi' load the Forth code above into a *copy* of Pocket Forth
and then enter  save bye  to save the dictionary.  Use a web browser to bring
up the HTML file, call it 'simple.html', and click 'send it'.  If all went well
you will receive a reply indicating who you are, what you are using, and
(presumably) your favorite type of ice cream.



*****************************
*                           *
*   Technical Description   *
*                           *
*****************************


MAIN USER LEVEL WORDS


    The most important words defined by the shell are @Direct, @Addr, @Browser,
and @Field.  These words fetch information sent by the web server to the CGI
application.


 @Direct  (e.g.  out APPEND @Direct )

    Direct returns the direct argument attached to the action component of the
    form definition.  If the HTML file contains:

        <form method=post action="my.cgi$3.141592">

    Then the phrase  out APPEND @Direct  will append the string 3.141592 to
    the string contained in  out  .  If NEW is specified in place of APPEND
    the direct argument replaces the previous contents of the string.  All
    strings are terminated with a '\0' character.


 @Addr  (e.g.   out APPEND @Addr )

    Addr returns the IP address string of the client.  If the address has a
    DNS entry its name will be returned.  If there was no DNS entry the reversed
    in-arpa numerical IP address is returned.  NEW and APPEND work as above.


 @Browser  (e.g.  out NEW @Browser )

    Browser returns a string indicating what type of web browser the client
    is using.  This can be useful for deciding when to return a graphically
    intensive page and when not to.  @Browser works as @Addr and @Direct.


 @Field  (e.g.  out f1 APPEND @Field )

    Field places the contents of the field whose name is in the string  f1
    into the string  out  .  NEW and APPEND work as before.  @Field will handle
    all translation of characters.


 REPLY   (e.g.  out REPLY )

    REPLY returns the string on the stack to the web server which then sends
    it down to the client.  This word must be called only from within a
    ae: ... ;ae pair.


SETTING UP THE APPLE EVENT HANDLER

  The heart of a CGI application is the AppleEvent handler that responds to the
  AppleEvent sent by the web server.  In Pocket Forth an AppleEvent handler is
  first defined and then saved to the dictionary.  When the application is then
  launched the handler is added to the list of handlers and the application
  will respond to the event whenever it is listening for events.  Pocket Forth
  listens to system events when waiting for input so it is unnecessary to
  be concerned about handling local events (i.e. mouse clicks, keypresses, etc.)
  In fact, Pocket Forth can be used normally while still listening for
  AppleEvents.  If you write the CGI to quit when finished you do not need to
  write any code for dealing with the server Mac.  This is unlike the C based
  Responder CGI shell.

  In Pocket Forth an Apple Event handler is defined using ae: and ;ae,

  ,s sdoc  ,s WWWΩ  ae:   \ begin the handler for the sdoc,WWWΩ event

     ...some code here...

  ;ae

  The general process, then, is:

  ,s sdoc  ,s WWWΩ  ae:

    <get data from the apple event using @Direct, @Field, etc.>

    <manipulate the data and create an output string>

    <reply to the event with  <output-string> REPLY>

    <quit or re-initialize the application>

  ;ae

  See the included examples for more information.


STRING SUPPORT WORDS

  The CGI shell provides a number of words for manipulating null terminated
strings.  These are summarized below:


   message[  ( compile: <name> <text>] )
             ( run: -- address )

             Create <name>, a null terminated string.  E.g.
               message[ s0 <h1>Result...</h1>]

   String>>  ( size -- (<name>) )

             Create a string, <name>, <size> bytes long.  E.g.
               512 String>> theReply

   strcpy    ( s1 s2 -- )

             Append s1 to s2.  Appending is useful for creating reply
             strings, use  strncpy  to avoid appending.

   length    ( s -- n )

             Return the length of string s.

   newstr    ( s -- )

             Zero the string s.  Equal to  0 s c!

   0type     ( s -- )

             Type the null terminated string s on the screen.  Useful for
             debugging.

   accept    ( s length -- )

             Identical to  expect  but adds a terminating '\0'.

   startstring  ( s -- )

             Add <HTML> to the string s.

   endstring ( s -- )

             Append </HTML> to the string s.


NUMERICAL CONVERSION

   Pocket Forth has complete support for floating point numbers making it useful
   for scientific applications.  These words will convert between floating point
   numbers and strings.


   f>str  ( f s -- )

          Put the floating point number f into the string using the current
          settings for FIX or SCI.

   str>f  ( s -- f )

          Make s into a floating point number on the stack.


NOTES

   The best way to learn to use the shell is to experiment.  See the 'Deflect'
example to learn how to force the client's browser to another URL.  When
developing a CGI keep the following in mind:


   *  turn off the processor cache if using an '040 based Mac.  Some code will
      compile with it on but often the application quits part way through. The
      compiled code seems to run just fine with the cache on.


   *  always use a fresh copy of the Pocket Forth application when re-compiling.


   *  remember to do  save bye  after loading the code.  Amazing how many times
      I forget to do that!


The software carries no warranty of any kind.  Caveat Emptor.

Ron Kneusel
8725 West Burdick Ave.
Milwaukee, WI  53227  USA
[phone]
[e-mail]

The latest version of CGIshell can always be found at:

http://kreeft.intmed.mcw.edu/pf.html
ftp://kreeft.intmed.mcw.edu/q/pub/forth/

September 1995, AMDG