<STRONG>Advanced Features</STRONG><BR><P>Provides string, integer, floating-point, and safe stringwithout 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 theyacgi distribution. This CGI program accepts input submittedby the form yacsampl.html.<p><strong>IMPORTANT:</strong> after compiling yacgi, you willneed to place it in a location on your server system which isdesignated by your server administrator as an appropriate locationfor CGI scripts. Also, the URL of the action of the sample form inyacsampl.html must be changed to correctly indicate the locationof 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. Wedescribe the concepts as abstract data types.<ul><b><a href="#Relation">Name-Value Relation</a></b> ADTavailable 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 successfulcompletion, cgiOpen returns a pointer to the open relation. Inthe 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 suppliedName. Returns the first Value in therelation that has a given Name. Null is returned if no pairmeets 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 relationthat has a given Name. Null is returned if no pair meets thecondition.  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. Onsuccessful completion, cgiFirst returns 1. In the event oferror 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. Onsuccessful completion, cgiNext returns 1. In the event oferror it returns 0.<P><BR><STRONG><a name="cgiName">char *cgiName(CGI *cgi);</a></STRONG><BR>Returns a Name of the current pair. Ifthere 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. Ifthere 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 suppliedName.<BR>Returns the first Value in therelation 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 suppliedName.<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 itreturns <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 suppliedName.<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 wassuccessfully 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 Namewas submitted.<BR>In the last three cases, the Value pointed to by resultis 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 suppliedName.<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 wassuccessfully 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 Namewas submitted.<BR>In the last three cases, the Value pointed to by resultis 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 variableswhich are set by the server.<p>Instead of calling getenv() you can use cgiEnvGet functionthat always returns valid C strings (they are never null, althoughthey 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>