A CGI is any application that uses the Mac OS Common Gateway Interface standard to interact with an information server such as WebSTAR. The CGI standard defines arguments that allow the server to pass data to applications and receive data back from them.
You can develop a CGI to integrate with databases, process forms, and perform all sorts of other useful functions. CGIs can be developed and programmed in high-level scripting languages such as AppleScript, Frontier or MacPerl, or in low-level languages like C, Pascal or Java. Developing an application in a low-level language requires more effort but results in much better performance than an application developed in a scripting language.
The WebSTAR server itself does not process the data it sends to the CGI application nor the pages it returns to the client software. The server's job is to handle connections, use the proper method to return pages and files, and handle communications between the client and the CGI.
CGIs must perform all HTML formatting themselves. The WebSTAR web server expects your script or application to generate and return a proper HTTP header, and does no conversion of the return values from CGIs.
See the WebSTAR Development site at <http://dev.starnine.com/> for specs and more information related to Mac OS CGI development.
The WebSTAR server can interact with a CGI synchronously or asynchronously . If the name application ends with " .cgi ", the server passes an Apple Event to the application and waits for the CGI to return a result (synchronous operation). If the application name ends in " .acgi ", the server passes an Apple Event to the application and then continues processing other tasks until it receives a reply. Writing a CGI to be processed asynchronously is usually preferable.
While the Mac OS CGI ' handle CGI request ' parameter provides a cleaner format for writing AppleScript-based CGIs, it does not support the " Full Request " and " DIRE " parameters supported by the WebSTAR CGIs ' «event WWWωsdoc» ' format.
http://dev.starnine.com/
The WebSTAR server includes Apple Events and application properties to set all configuration parameters. For the most part, the syntax of the data sent by the AppleScript Set commands, or returned by the AppleScript Get commands is the same as the syntax for setting parameters.
Many of the application properties can be found in the Apple Event dictionary for the WebSTAR server, viewable in the Script Editor.
The WebSTAR server supports the four required Apple Events, plus a custom Apple Event suite for sending information to the WebSTAR server while it is running. The custom event suite provides the flexibility and power of WebSTAR CGIs.
The event suite for the WebSTAR server Apple Events is the same as the four-character creator code for the WebSTAR server application. The four-character Event Suite is WWWω--three uppercase Ws (WWW), followed by the omega character "ω" (option-Z on the keyboard).
WSAPI_ReadHTTPData circumvents the old 32K limit on POST args by allowing you to call it multiple times. The dataLen parameter is limited to 32K at a time. If more than 32K is expected from the client, you'll have to send this event multiple times to read all the data. Note that calling this function when data isn't pending will likely result in a timeout.
The WSAPI_GetIndexedParameter event gets information about WebSTAR using WebSTAR API parameters (see WebSTAR API Parameter Definitions ). Unlike the function of the same name in the WebSTAR API, the Plug-In parameter specifier is a character string instead of a 4 byte OSType character. Also, integer values are coerced to strings before being returned and non-integer, non-string parameters are not returned (e.g., FSSpecs, etc.).
For information about the equivalent API functions, use the WebSTAR Server Suite Installer to custom install "WebSTAR Development Resources", and see the WebSTAR API SDK.
The WebSTAR server application Get and Set events can use these properties:
If the WebSTAR server receives a query (such as "GET") from a browser requesting a file whose suffix mapping Action is "CGI" or "ACGI", the WebSTAR server attempts to launch the CGI application and communicate with it via Apple Events.
The WebSTAR server implements the Mac OS Common Gateway Interface standard in the sdoc Apple Event. The four-character Event Suite is "WWWω"--three uppercase Ws (WWW), followed by the omega character (option-Z on the keyboard). The four-character event code is sdoc . For example:
on «event WWWωsdoc»
The Apple Event keyword codes for the parameters passed by the WebSTAR server to CGI and ACGI applications are listed below. You can name the variables associated with these parameters whatever you like.
1024 |
Contains arguments following the dollar-sign ($) in a URL. For example, for this URL: <form action="ProcessForm.cgi$JimmyJones?14" method=post> the value "JimmyJones" is contained in this parameter. This keyword is also the direct parameter of the Apple Event (keyDirectObject). |
||
1024 |
Contains arguments following a question mark ("?") in a URL. For example, for this URL: |
||
32 |
|||
32 |
|||
256 |
Passes the domain name of the client (or the IP address if DNS look-ups are disabled). |
||
256 |
Passes the domain name of the server (or the server's IP address if DNS look-ups are disabled). |
||
16 |
|||
|
Passes the path of the CGI being executed. If the CGI is called as an ACTION, this parameter contains the file portion of the URL. |
|||
|
Passes the URL of the page from which this CGI was referenced. This information is useful for telling what sites are referencing your pages. It can also be useful in a script to add a "return" link to pages on-the-fly that would return users to whatever page they came from. |
|||
|
Passes the action being performed by the CGI. It will contain either the name of the user-defined action or one of these strings: CGI , ACGI , PREPROCESSOR , POSTPROCESSOR , ERROR , INDEX , or NOACCESS . |
|||
|
Passes the path to this CGI if it is executing as an action (in which case, the script name parameter contains the URL file path sent from the client). |
|||
|
Passes arguments sent from the WWW client as part of a POST request (such as form arguments). The actual form data (returned from running the CGI) is also placed in this parameter. |
|||
|
Passes the HTTP method being requested (such as GET , GET_CONDITIONAL , POST , etc.). For more information, see The Method Parameter . |
|||
|
Passes the IP address of the client as a string, even if NO_DNS is false. |
|||
|
Passes the complete, unmodified HTTP request as received from the WWW client. |
|||
|
Passes a unique long integer identifying the TCP/IP connection over which the server is communicating to the client. This number is used for sending the "Send Partial" Apple Event to the WebSTAR web server. |
|||
|
An FSSpec pointing to the root folder of the virtual host, or, if the URL is not for a virtual host, the WebSTAR root folder. |
This parameter passes the HTTP method being requested (such as GET, GET_CONDITIONAL, POST, etc.).
If the HTTP method is POST, the form data sent in the object body of the HTTP request is returned to the server in the post_args parameter. Otherwise, this parameter is empty.
If the HTTP method is GET, the form data overwrites the http_search_args parameter. If you are using a map-processing CGI, you might use the method=get argument to pass the name of a map information file that the CGI should use to process the map. The URL might look like this:
/cgi/MapServe.acgi$jonsmap.map
When a user clicks on the map, the client software changes this URL so that the map coordinates are added in the search. arguments. The full URL transmitted to the WebSTAR web server would look something like this:
/cgi/MapServe.acgi$jonsmap.map?223,1
When WebSTAR sends an Apple Event to CGIs, it includes a "DIRE" parameter. This enables CGIs to determine the correct root folder for the virtual host the request was made to.
For more information about how to develop CGI applications that work with the WebSTAR server, see:
http://dev.starnine.com/