yacgi.html

C libs that handle common CGI operations.

<STRONG>Advanced Features</STRONG><BR>
<P>
Provides string, integer, floating-point, and safe string
without shell metacharacters functions to retrieve form data.
<P>
<PRE>
#include &lt;stdio.h&gt;
#include &lt;stdlib.h&gt;
#include "yacgi.h"

main(int argc, char *argv[])
{
    CGI *cgi;
    int more;
    char *string;
    int flag;
    long i;
    double r;
    char c[31];


    printf("Content-type: text/html%c%c",10,10);
    /*-----------------------------------------------------------
     *              Opening Relation
     *-----------------------------------------------------------*/
    cgi = cgiOpen();
    if(!cgi)
    {
       printf("&lt;H3&gt;%s&lt;/H3&gt;%c",cgiStateMsg(),10);
       exit(1);
    }
    /*-------------------------------------------------------------
     *              Advanced Features: Input String, Integer, Real,
     *              Safe String
     *-----------------------------------------------------------*/
    printf("&lt;CENTER&gt;&lt;H2&gt;Advanced Features&lt;/H2&gt;&lt;/CENTER&gt;");

    printf("&lt;p&gt;&lt;b&gt;%s&lt;/b&gt;&lt;br&gt;%c","String",10);
    flag = cgiValueString(cgi, "String", c, 30);
    if(flag == CGI_OK || CGI_VAL_TRUNCATED )
        printf("&lt;code&gt;%s&lt;/code&gt;&lt;br&gt;%c",c,10);
    else
        printf("&lt;code&gt;%s&lt;/code&gt;&lt;br&gt;%c",cgiStateMsg(),10);

    printf("&lt;p&gt;&lt;b&gt;%s&lt;/b&gt;&lt;br&gt;%c","Integer",10);
    flag = cgiValueInteger(cgi, "Integer", &i, 1);
    if(flag == CGI_OK )
        printf("&lt;code&gt;%ld&lt;/code&gt;&lt;br&gt;%c",i,10);
    else
        printf("&lt;code&gt;%s&lt;/code&gt;&lt;br&gt;%c",cgiStateMsg(),10);

    printf("&lt;p&gt;&lt;b&gt;%s&lt;/b&gt;&lt;br&gt;%c","Real",10);
    flag = cgiValueReal(cgi, "Real", &r, 1);
    if(flag == CGI_OK )
        printf("&lt;code&gt;%lf&lt;/code&gt;&lt;br&gt;%c",r,10);
    else
        printf("&lt;code&gt;%s&lt;/code&gt;&lt;br&gt;%c",cgiStateMsg(),10);


    printf("&lt;p&gt;&lt;b&gt;%s&lt;/b&gt;&lt;br&gt;%c","SafeString",10);
    string = cgiValueFirst(cgi, "SafeString");
    if(string)
        printf("&lt;code&gt;%s&lt;/code&gt;&lt;br&gt;%c",cgiSafeStr(string),10);
    /*------------------------------------------------------
     *                 Closing Relation.
     *------------------------------------------------------*/
    cgiClose(cgi);
    return(0);
}
</PRE>
<P>

The sample application 'yacsampl.c' is provided as part of the
yacgi distribution. This CGI program accepts input submitted
by the form yacsampl.html.
<p>
<strong>IMPORTANT:</strong> after compiling yacgi, you will
need to place it in a location on your server system which is
designated by your server administrator as an appropriate location
for CGI scripts. Also, the URL of the action of the sample form in
yacsampl.html must be changed to correctly indicate the location
of yacsampl on your web server.
<p>
<hr>
<h2><a name="reference">yacgi reference</a></h2>
There are very few basic concepts that you need to know. We
describe the concepts as abstract data types.
<ul>
<b><a href="#Relation">Name-Value Relation</a></b> ADT
available via functions:<br>
<ul>
<a href="#cgiOpen">    cgiOpen()</a><br>
<a href="#cgiClose">     cgiClose()</a><br>
<a href="#cgiValueFirst"> cgiValueFirst()</a><br>
<a href="#cgiValueNext"> cgiValueNext()</a><br>
<a href="#cgiFirst">     cgiFirst()</a><br>
<a href="#cgiNext">      cgiNext()</a><br>
<a href="#cgiName">      cgiName()</a><br>
<a href="#cgiValue">     cgiValue()</a><br>
and advanced functions:<br>
<a href="#cgiSafeValue">    cgiSafeValue() </a><br>
<a href="#cgiValueString">  cgiValueString()</a><br>
<a href="#cgiValueInteger"> cgiValueInteger()</a><br>
<a href="#cgiValueReal">    cgiValueReal()</a><br>
<p>
</ul>
<b><a href="#State">State of Relation</a></b> ADT available via functions:<br>
<ul>
<a href="#cgiStateClear">  cgiStateClear()</a><br>
<a href="#cgiStateGet">  cgiStateGet()</a><br>
<a href="#cgiStateSet">    cgiStateSet()</a><br>
<a href="#cgiStateMsg">    cgiStateMsg()</a><br>
</ul>
<p>
<b><a href="#Environment">CGI Environment</a></b> ADT available via functions:<br>
<ul>
<a href="#cgiEnvGet">  cgiEnvGet()</a><br>
</ul>
</ul>
<p>
<p>
<ul>
<hr>
<b><a name="Relation">Name-Value Relation</a></b> is accessed via the following operations,
that can change <a href="#State">State of Relation</a>.
<hr>
<CITE>Open/Close functions:</CITE>
<BR>
<BR><STRONG><a name="cgiOpen">CGI   *cgiOpen();</a></STRONG><BR>
Opens a Name-Value binary relation with the given name. On successful
completion, cgiOpen returns a pointer to the open relation. In
the event of error, it returns null.
<P>
<BR><STRONG><a name="cgiClose">void   cgiClose(CGI *cgi);</a></STRONG><BR>
Closes the relation.
<P>
<CITE>Evaluate functions:</CITE>
<BR>
<BR><STRONG><a name="cgiValueFirst">char *cgiValueFirst(CGI *cgi, char *Name);</a>
</STRONG><BR>
Evaluates the first Value in the relation by the supplied
Name. Returns the first Value in the
relation that has a given Name. Null is returned if no pair
meets the condition. In the event of error it returns 0.
<P>
<BR><STRONG><a name="cgiValueNext">char *cgiValueNext(CGI *cgi, char *Name);</a>
</STRONG><BR>
Evaluates the next Value in the relation by the supplied Name.
Returns the next Value in the relation
that has a given Name. Null is returned if no pair meets the
condition.  In the event of error it returns 0.
<P>
<CITE>Iterate functions:</CITE>
<BR>
<BR><STRONG><a name="cgiFirst">int cgiFirst(CGI *cgi);</a></STRONG><BR>
Moves the current position to the first stored pair. On
successful completion, cgiFirst returns 1. In the event of
error it returns 0.
<P>
<BR><STRONG><a name="cgiNext">int cgiNext(CGI *cgi);</a></STRONG><BR>
Moves the current position to the next stored pair. On
successful completion, cgiNext returns 1. In the event of
error it returns 0.
<P>

<BR><STRONG><a name="cgiName">char *cgiName(CGI *cgi);</a></STRONG><BR>
Returns a Name of the current pair. If
there is an error or if the relation is empty it returns 0.
<P>
<BR><STRONG><a name="cgiValue">char  *cgiValue(CGI *cgi);</a></STRONG><BR>
Returns a Value of the current pair. If
there is an error or if the relation is empty it returns 0.
<P>
<CITE>Advanced features:</CITE>
<BR>
<BR><STRONG><a name="cgiSafeValue">char *cgiSafeValue(CGI *cgi, char *Name);</a>
</STRONG><BR>
Evaluates the first Value in the relation by the supplied
Name.
<BR>Returns the first Value in the
relation that has a given Name and ESCAPES the shell metacharacters.
<BR>Null is returned if no pair meets the condition.
In the event of error it returns 0.
<P>
<BR><STRONG><a name="cgiValueString">int cgiValueString(CGI *cgi, char *name,
char *result, int max);</a></STRONG><BR>
Evaluates the first Value in the relation by the supplied
Name.<BR>The string will be copied into the buffer specified by result,
up to but not exceeding max-1 bytes.<BR><BR>
The function returns <a href="#State">CGI_OK</a> if the Value was successfully retrieved.
<BR>
If the string was retrieved but was truncated to fit the buffer it
returns <a href="#State">CGI_VAL_TRUNCATED</a>,<BR>
<a href="#State">CGI_VAL_EMPTY</a> if the string was retrieved but was empty, and
<BR><a href="#State">CGI_VAL_NOTFOUND</a> if no such Name was submitted.
<P>
<BR><STRONG><a name="cgiValueInteger">int cgiValueInteger(CGI *cgi,
char *name, long *result, long defval);</a> </STRONG><BR>
Evaluates the first Value in the relation by the supplied
Name.<BR>
The value pointed to by result will be set to the value submitted.
<BR>
The function returns <a href="#State">CGI_OK</a>if the Value was
successfully retrieved,<BR>
<a href="#State">CGI_VAL_EMPTY</a>if the Value submitted is an empty string,<BR>
<a href="#State">CGI_VAL_BADTYPE</a> if the Value submitted is not an integer,<BR>
and <a href="#State">CGI_VAL_NOTFOUND</a> if no such Name
was submitted.<BR>
In the last three cases, the Value pointed to by result
is set to the specified default.
<P>
<BR><STRONG><a name="cgiValueReal">int cgiValueReal(CGI *cgi, char *name,
double *result, double defval);</a></STRONG><BR>
Evaluates the first Value in the relation by the supplied
Name.<BR> The value pointed to by result will be set to the value submitted.
<BR>
The function returns <a href="#State">CGI_OK</a>if the Value was
successfully retrieved,
<a href="#State">CGI_VAL_EMPTY</a>if the Value submitted is an empty string,<BR>
<a href="#State">CGI_VAL_BADTYPE</a> if the Value submitted is not a real number,<BR>
and <a href="#State">CGI_VAL_NOTFOUND</a> if no such Name
was submitted.<BR>
In the last three cases, the Value pointed to by result
is set to the specified default.
<P>
<hr>
<b><a name="State">State of Relation</a></b> can be one of the following
<hr>
<p>
<CENTER><TABLE BORDER=1 CELLSPACING=1 CELLPADDING=1>
<TR>
<TD> CGI_OK  </TD>
<TD> The function successfully performed </TD>
</TR>
<TR>
<TD> CGI_MEMORY                  </TD>
<TD> Out-of-memory error         </TD>
</TR>
<TR>
<TD> CGI_CONTENTTYPE             </TD>
<TD> MIME content type error     </TD>
</TR>
<TR>
<TD> CGI_REQUESTMETHOD           </TD>
<TD> Request metod error         </TD>
</TR>
<TR>
<TD> CGI_IO                      </TD>
<TD> I/O error                   </TD>
</TR>
<TR>
<TD> CGI_VAL_TRUNCATED           </TD>
<TD> Value was cut short         </TD>
</TR>
<TR>
<TD> CGI_VAL_INVALID             </TD>
<TD> Value was not a legal type  </TD>
</TR>
<TR>
<TD> CGI_VAL_EMPTY               </TD>
<TD> Value contained no data     </TD>
</TR>
<TR>
<TD> CGI_VAL_NOTFOUND </TD>
<TD> No value was submitted      </TD>
</TR>
<TR>
<TD> CGI_LASTERROR               </TD>
</TR>
</TABLE></CENTER>
<P>
<b>State of Relation</b> is accessed via the following operations:
<P>
<BR><STRONG><a name="cgiStateClear">void cgiStateClear();</a></STRONG><BR>
Resets state of Name-Value Relation to CGI_OK
<p>
<BR><STRONG><a name="cgiStateGet">int  cgiStateGet();</a></STRONG><BR>
Returns current state of Name-Value Relation
<p>
<BR><STRONG><a name="cgiStateSet">int  cgiStateSet(int val);</a></STRONG><BR>
Resets state of Name-Value Relation to the given value
<p>
<BR><STRONG><a name="cgiStateMsg">char *cgiStateMsg();</a></STRONG><BR>
Returns state of Name-Value Relation string
<p>
<hr>
<b><a name="Environment">CGI Environment</a></b> ADT available via functions:<br>
<hr>
<BR><STRONG><a name="cgiEnvGet">char *cgiEnvGet(char *var);</a></STRONG><BR>
Obtains the current value of the CGI environment, var
<p>
The CGI standard specifies a number of environment variables
which are set by the server.
<p>
Instead of calling getenv() you can use cgiEnvGet function
that always returns valid C strings (they are never null, although
they may point to an empty string).
</ul>
<CENTER><A HREF="index.html"> HOME </A></CENTER><p>
<FONT SIZE="-1">Copyright &copy 1997 Andrew Girow. All Rights Reserved.</FONT>
<HR SIZE=3>
<FONT SIZE="-1">Last updated: July 21, 1997</FONT>
</BODY>
</HTML>