You copied the Doc URL to your clipboard.

3.8.2. CGI routine return values

The CGI routine return values (a bitmask and a string) are complex. Once the browser has sent a form to the server, it is expecting an HTML page in response. This form reply page can be anything from a simple thanks for filling in our form type of message, to the most complex page in the system. The ARM Webserver provides a simple generic form response page that you can use without having to write any code or include any additional HTML pages. This allows you to have many forms and still keep memory usage down. However, some CGI routines may need more control over the content of their form replies than the generic reply page provides. These have the options of building and sending their own HTML text replies, or passing the name of a reply file back to the webserver code.

The return value is a bitmask of the following bit values:

FP_OK    /* form processing was OK if set, else system error */
FP_FILE  /* filetext points to a file reply */
FP_TEXT  /* filetext points to an error or status text */
FP_ERRHD /* insert an error header line in the reply page */
FP_OKHD  /* insert an “OK” header line in the reply page */
FP_DONE  /* CGI routine did everything */

The hp parameter is passed to the CGI function so it can use hp->sock to write its own form reply. In this case, it should return the predefined value FP_DONE. This overrides all the other return bit values and causes the ARM Webserver to simply close the connection and free resources.

If FP_DONE is not the sole bit returned, then FP_OK should be set. This bit indicates that the CGI routine did not experience any catastrophic failure. If this bit is not set, an HTTP server error packet is returned, and the end user at the browser will not know exactly what has gone wrong. The FP_OK bit does not imply that the form data was correct or parsable. Bad form data is indicated by returning the FP_ERRHD bit (see below).

Another way to ensure that the CGI routine controls its reply is to modify it to set the passed filetext parameter to a file name, set the FP_FILE bit in the return value, and return. The ARM Webserver will send the named file to the browser as a reply.

Most forms do not require such detail. Generally, the webserver CGI routines will return a bit mask consisting of:

  • FP_OK

  • possibly FP_TEXT

  • either FP_ERRHD or FP_OKHD.

If FP_ERRHD is set, a generic form error reply page is prepared. If FP_OKHD is set, a generic form OK page is prepared. If neither is set, a very plain form reply page is prepared, which implies neither error nor success. If FP_TEXT is set, then filetext is assumed to point to a string that is inserted in the reply page. This text can be inserted regardless of the state of FP_ERRHD and FP_OKHD.

Was this page helpful? Yes No