WebScript Abstract

Description
WebScript is a simple script language used to automate http connections to a server. WebScript is a CGI application.

Why it is useful
WebScript can be used to automate any http connection. It was designed for use with a state-full http server.
With WebScript, organizations can give users access to specific Web material without requiring that the user log in. For example, an organization has 30 databases available over the net to member (via some authentication method). To make one of those databases available to the public all they would need to do is write a WebScript Script to login, select the public database and return the query page to the user. (see Example 3) In this way, all of the other databases as well as the login and password are hidden from the user. WebScript can also be used to fulfill the basic authentication used by web clients. (see Example 5)

Notes
WebScript has been ported to all platforms listed below.

Installation
  1. Get the source or get a binary for:
  2. If necessary, edit the Makefile to change the install location. The supplied Makefile will install files to /usr/local/bin, which requires root access to your server. If you don't have root access or if you would like to install to a different location, change /usr/local/bin to the desired install directory.
  3. Compile it. A Makefile is supplied (run make).
  4. Run make install to install WebScript to /usr/local/bin.
  5. Configure your web server to identify .scr files as cgi scripts and, if desired, to limit access to the scripts. See your web server documentation for details on how to do this. If your server uses the NSCA conf file format, you may refer to the NCSA HTTP documentation.

    If your configuration files follow the NCSA standard, adding this line to your httpd.conf will allow script (.scr) files to be executed as CGI scripts:
      AddType application/x-httpd-cgi .scr
    This example httpd.conf configuration block specifies that the directory containing the .scr files is a CGI directory, and that access to that directory is restricted to computers at your institution. For the example, we have used my-webscripts-dir as the location of the .scr files and OCLC's IP range; these values should be replaced with the appropriate values for your institution:
    <Directory /my-webscripts-dir>
     Options ExecCGI
      <Limit GET>
       order deny,allow
       deny from all
       allow from 132.174. 
      </Limit>
    </Directory>
  6. Start writing scripts (or use the sample fs.scr). In order to be accessed by your users, scripts must be copied to the location specified in your httpd.conf Directory directive (see step 4) and have their file permissions set to be executable.

Language Description
Commands appear one per line and the script is terminated at end of file.
Double quotes, carriage returns, newlines and back slashes are represented as '\"', '\r', '\n' and '\\' respectively.

HOST "host:port"
Opens a socket and connects to the host and port given in the argument. This socket stays open until the next HOST call or the end of the script. Port defaults to 80 if not specified. Remember that http servers close the connection after sending a document. For this reason it is necessary to call HOST again to establish a new connection before sending a another message. (see Example 3)
WAIT "n"
Sleep for n seconds.
SET "var=string"
Set the variable var equal to string.
Variable are referenced as $var$. (see Example 1)
All environment variables are available to set or display. Command line variables will override script and environment variables.
DISPLAY "string"
Send the string given by string to the user.
If string is blank then the last read buffer is displayed to the user.
Nothing is read from the socket and into the buffer until a RECEIVE or SCAN is issued. (See Example 2)
SEND "string"
Send the string given by string to the current host.

Note: If the string is being sent to an HTTP server, that server will perform an HTTP decoding on the string it receives. For this reason, it is necessary to escape some characters with their percent encoding. For example, if your password has a % sign in it you will need to replace it with %25.

RECEIVE "n", "start"
Scan the input for start. Timeout after n seconds. The Start may be empty, which will cause RECEIVE to retrieve the whole message.
SCAN "n", "start", "end", var
Scan the input for start and end. Place the text the comes between start and end into the variable var. Timeout after n seconds. SCAN is case insensitive.
ABSOLUTE "string"
Insert the specified string before each partial/relative URL specified in a SRC, HREF, or ACTION. This is an alternative to BASE and does what BASE should. (See Example 6 and compare to Example 5).
BASE "string"
Insert a BASE tag with HREF="string" if one isn't present (structure is preserved if the document is structured correctly). (See Example 4) on how to get around the need for a BASE tag (in case you are working with an old browser that doesn't support the BASE tag).
ENCODE "string", var
Encode string and place the results into the variable var. This is used to send authentication. (See Example 5)
ONERROR "string"
Specifies the string to return to the user if an error is encountered. Can be reset to default with an empty string.
ONERROR SWITCH
CASE "number: string"
CASE "number: string"...
DEFAULT: "string"
....
Specifies the string to return to the user if an error is encountered. The number in the CASE specified the HTTP return code from the server (if any), or the internal error code and message (default behaviour). Any CASE or the DEFAULT can be reset to default with an empty string. If ONERROR SWITCH is used, there must be a corresponding DEFAULT and it must be the last statement case of the ONERROR.
EXIT
Terminate script at this point.

Examples
Example 1
#!/usr/local/bin/webscript
DISPLAY "Content-type: text/html\n\n" DISPLAY "<HTML> <HEAD>" DISPLAY "<TITLE> Search Results</TITLE>" DISPLAY "</HEAD>" DISPLAY "<BODY>" SET "string1=This is a test\r\n\r\n" DISPLAY "String1 = $string1$" SET "string2=$string1$" DISPLAY "String2 = $string2$" DISPLAY "\r\n"
DISPLAY "</BODY>" DISPLAY "</HTML>"
Example 2
#!/usr/local/bin/webscript
# Open a socket to host
HOST     "www.ncsa.uiuc.edu:80"
# Send a GET command
SEND     "GET / HTTP/1.0\r\n\r\n"
# Read response (even though we don't want to scan for anything
SCAN     5, "", "", null
# Display response to user
DISPLAY  ""
    
Example 3
#!/usr/local/bin/webscript
#
# Real Example
#
# The server at www.ref.oclc.org:2000 is a state-full server that constructs
# the response URL with embedded session information.  We are going to capture that
# session information and use it to take the user directly to the query screen for
# a specific database.
#
# Define some variables to use later.
SET     "host=www.ref.oclc.org:2000"
SET     "user=Vince"
SET     "password=Smile"
SET     "journal=APLO"
#
# Define who we are going to communicate with and open a socket to them 
# for future writes (remember that httpd closes the socket after serving
# a request).
HOST    "$host$"
#
# Send a string to the host
SEND    "GET /html/ejo_pswd.htm HTTP/1.0\r\n\r\n"
SCAN    60, "<FORM METHOD=POST ACTION=\"", "\">", string
#DISPLAY "$string$\n"
#
HOST    "$host$"
SEND    "POST $string$ HTTP/1.0\r\nContent-type: application/x-www-form-urlencoded\r\nContent-length: 100\r\n\r\nautho=$user$&password=$password$\r\n"
ONERROR "Location: http://$host$/html/ejo_pswd.htm\r\n\r\n"
SCAN    60, "<FORM method=POST ACTION=\"", "\">", string2
ONERROR ""
#DISPLAY "$string2$\n"
#
HOST    "$host$"
SEND    "POST $string2$ HTTP/1.0\r\nContent-type: application/x-www-form-urlencoded\r\nContent-length: 100\r\n\r\ndbname=$journal$\r\n"
SCAN    60, "", "", string3
#DISPLAY "$string3$\n"
BASE    "http://$host$/"
#DISPLAY "$string3$\n\n"
#
# Display the buffer to the user
DISPLAY ""
    
Example 4
#!/usr/local/bin/webscript
#
# Real Example
#
# The server at www.ref.oclc.org:2000 is a state-full server that constructs
# the response URL with embedded session information.  We are going to capture that
# session information and use it to take the user directly to the query screen for
# a specific database.
#
# Define some variables to use later.
SET     "host=www.ref.oclc.org:2000"
SET     "user=Vince"
SET     "password=Smile"
SET     "journal=APLO"
#
# Define who we are going to communicate with and open a socket to them 
# for future writes (remember that httpd closes the socket after serving
# a request).
HOST    "$host$"
#
# Send a string to the host
SEND    "GET /html/ejo_pswd.htm HTTP/1.0\r\n\r\n"
SCAN    60, "<FORM METHOD=POST ACTION=\"", "\">", string
#DISPLAY "$string$\n"
#
HOST    "$host$"
SEND    "POST $string$ HTTP/1.0\r\nContent-type: application/x-www-form-urlencoded\r\nContent-length: 100\r\n\r\nautho=$user$&password=$password$\r\n"
ONERROR "Location: http://$host$/html/ejo_pswd.htm\r\n\r\n"
SCAN    60, "<FORM method=POST ACTION=\"", "\">", string2
ONERROR ""
#DISPLAY "$string2$\n"
#
# Return a redirect to the browser and let it submit the request to the
# the server.  This is useful for browsers that don't support the BASE
# tag.
DISPLAY "Location: http://$host$$string2$:dbname=$journal$\r\n\r\n"
    
Example 5
#!/usr/local/bin/webscript
#
# Define some variables to use later.
SET     "host=www.oclc.org"
SET     "user=vince"
SET     "password=smile"
#
HOST    "$host$"
#
# UUEncode the password string
ENCODE  "$user$:$password$", enc_pwd
#
# Send the get (including authorization)
SEND    "GET /~tkac/secure/ HTTP/1.0\r\nAuthorization: Basic $enc_pwd$\r\n\r\n"
SCAN    60, "", "", string
BASE    "http://$host$/~tkac/secure/"
#
# Send the contents of the received buffer to stdout
DISPLAY ""
    
Example 6
#!/usr/local/bin/webscript
#
# Define some variables to use later.
SET        "host=www.oclc.org"
SET        "user=vince"
SET        "password=smile"
#
HOST       "$host$"
#
# UUEncode the password string
ENCODE     "$user$:$password$", enc_pwd
#
# Send the get (including authorization)
SEND       "GET /~tkac/secure/ HTTP/1.0\r\nAuthorization: Basic $enc_pwd$\r\n\r\n"
SCAN       60, "", "", string
ABSOLUTE   "http://$host$/~tkac/secure/"
#
# Send the contents of the received buffer to stdout
DISPLAY ""
    
Bugs and Problems
Please report any bugs to me.

License
See the license agreement (and read it).

Required Software
NCSA httpd 1.3 or any CGI 1.1 compliant server.

Curator
Douglas L. Baden
Reference Services Development
Online Computer Library Center
6565 Frantz Road
Columbus, Ohio 43017-3395

email: baden@oclc.org
phone: (614) 764-4385