DCE C Library Documentation

DCE C Library Documentation

This document is not intended to be an explanation on how to write C language cgi scripts. It is only meant to list the available functions in the WSU implementation of the C library of cgi related functions. I won't even be describing typical C functions. I'll leave it to you to find that documentation. This library was written to be compatible with gcc so it can be moved easily to multiple platforms.

Simple Test Program
test_pgm.h
test_pgm.c
Alphabetical List of Functions
Alphabetical List of Macros and Variables
Valid Probe Types
Sample Makefile
Registering a new DCE service

Simple Program

About the simplest possible cgi C program that will contact MVS would consist of the following *.h and *.c files. The *.h file would contain include information that gets included into the *.c file. The include file you create must be of the format "probename_c.h". The "probename_c.h" file is required. Even if empty, you still must have a "probename_c.h" file. When you register the serice, you will have a "probename.h" include file created for you. Do not modify the "probename.h" file at all.

We'll call these test_pgm_c.h and test_pgm.c in this document. You can view test_pgm_c.h and test_pgm.c below.

You can view the usage of the various functions in the alphabetical list of functions. If you want to change some of the default variables that are set, you can go to the alphabetical list of macros and variables.

test_pgm_c.h

/*

test_pgm_c.h These are extra defs needed specifically for test_pgm.c Created: (drg) 6/10/97 Modified: 9/19/97: (drg) fixed initialization

*/

#define PROBE_NAME "test_pgm" #define PROBE_TYPE SIC #define BACKGROUND "/AIS/ATMS/graphics/simpgray.gif" #ifdef PROD # define PRODUCTION TRUE #else # define PRODUCTION FALSE #endif

/* Miscellaneous macros */

#if PRODUCTION == TRUE
# define RETURN_LINK "https://www.it.wsu.edu/AIS/SIC/sicintro.htm"
#else
# define RETURN_LINK "https://www.develop.it.wsu.edu/AIS/SIC/sicintro.htm"
#endif

#define RETURN_LABEL "Student Information Center Menu" #define WEB_CENTER "Student Information Center"

char* logout_link;

The "PROBE_NAME" should be the name of the C program. You can override this with something else, but it is not advisable.

The "PROBE_TYPE" macro must be one of the valid probe types. You can check below for the valid Probe Types.

If you have a particular background you want to be used on all pages of this probe, you can set it with the "BACKGROUND" macro.

The Makefile used to compile the probe is setup to run with the "PROD" parameter on or off, depending on whether you specified "dev" or "prod" when you called the Makefile. If PROD has been set, the the "PRODUCTION" macro is set to TRUE. Otherwise it is FALSE. The PRODUCTION macro is used to set things such as the return host address, etc. You can view a Sample Makefile at the end of this document.

Depending on whether PRODUCTION is true or false, the value of RETURN_LINK is established to return to one server or another.

RETURN_LABEL is set to be the same irregardless of whether you are in production or development. RETURN_LABEL could be put in the previous #if for RETURN_LINK and set differently depending on whether the production or development system is being used.

The WEB_CENTER macro is used in different titles. It can be set here along with the other values.

The last line for "logout_link" is necessary to setup that particular global variable.

You must put an include statement near the top of your C program. The include for "probename.h" is created for you automatically. Never modify the "probename.h" file. The "probename.h" file assumes that you have a "probename_c.h" file in your directory. If you aren't going to have an include of your own, you still must create an empty "probename_c.h" file.

At the top of your C program, you must have one line that indicates that this is your main routine. This is the MAIN_CLIENT_CODE statement as listed below.

test_pgm.c

/* 

	test_pgm.c

	test probe.
 
	Created: 5/30/97 (drg)
	Modified:
		10/22/97 (drg) modified to print correctly

*/


/* 
	the test_pgm.h include must be loaded before WSU_lib.h
*/

#define MAIN_CLIENT_CODE
#include "test_pgm.h"

#include "WSU_lib.h"
#include "WSU_probe.h"


/* Function prototypes (if any) */

void printterms(char**,int);
void print_summary(char**);



/* Main routine for probe */
void main()
{
/*		These variable names are not important and can be changed from 
		program to program. 	*/
		
  	char* this_state;
  	int   i;

  	INIT_Probe_Vars();
  	
/*	   These are not needed, but can be uncommented for debugging purposes
	   If you use these, change the IP numbers to reflect your own client IP name
	   and number
	   
putenv("QUERY_STRING=USER=rford&PW=password&state=phase2&Session=Spring 1997");
putenv("HTTP_COOKIE=KEY=ticket4sam; path=/; kinit=done; path=/;");
putenv("REMOTE_ADDR=134.121.111.111");
putenv("REMOTE_HOST=134.121.111.111");
putenv("HTTP_USER_AGENT=Mozilla/2.0");
*/
  	INIT_Probe();

	logout_link = (char*)malloc(100);
	bzero(logout_link,sizeof(logout_link));
  	sprintf(logout_link,"https://%s/AIS/html/logout.htm",this_server);

	this_state = (char*)malloc(50);
	bzero(this_state,sizeof(this_state));
	
/*		If the state has not yet ben set, set it to "phase1"   */
  	if (!FormValue("state")) {
		strncpy(this_state,"phase1",6);
  	} else {
		this_state=(char*)FormValue("state"); 
  	}

  	if (strncmp(this_state,"phase1",6) == 0) {
		sumsel();
  	} else if (strncmp(this_state,"phase2",6) == 0) {
		sumrpt();
	} else {
	   HTML_Error("Problem with posted value",99,"There is a
		problem with the phase value. It must always be set 
		and for some reason this time it isn't.");
	}

	
	return;

} /* end main() */

/* 	sumsel lets them select which reporting period they want to query */

void sumsel() {
	HBAG bag;
	char **parmlist;
	int  number_of_parms;

/*		"ADAB1234" is the Adabas glue/action routine name as it is known on MVS */
	bag = (HBAG)InitBag("ADAB1234");
/*		fill the  bag with the student's wsu number which was set in INIT_Probe */
	FillStrings(bag,1,wsu_number_string);
/*		this statement sends the filled "bag" to MVS and returns the 
                        buffer into the parmlist array with number_of_parms
		elements in the array. If any error occured on the 
		MVS side, then we go to the error routine at this point */
	parmlist = (char**)CallServer(bag, &number_of_parms);

/*		since everything is ok, print out all of the terms returned from MVS */
	print_header("Financial Aid - Select Award Period");

print_WSU_identity(); printterms(parmlist, number_of_parms); exitMain(); return; } /* end of sumsel */

/* Print out the list of terms. */

void printterms(char **parmlist, int num) { int i;

        printf("<h3 align=center>Summary of Financial Aid</h3> \
                     <form method=POST action=%s><b>Select Award Period:\            </b> <SELECT NAME=\"Session\">\n",probe_name);         for (i = 0; i < num; ++i)              printf("<OPTION>%s\n",parmlist[i]);              printf("<OPTION></SELECT><p><center> \
                   <INPUT type=submit value=\"Show Summary of \           Aid\"> </center>\n");        PostStartTime(); /* added for performance monitoring reasons*/
              printf("<input type=hidden name=state value=\"phase2\">\                      </form><p><br> Go to <a href=\"/AIS/SIC/sicintro.htm\"> \
                      Student Information Center Menu</a><br><br>\n");        return; }

/* sumrpt will report the financial aid for the selected term */

void sumrpt() { HBAG bag; char** parmlist; int number_of_parms; char* session;

bag = (HBAG)InitBag("ADAB5678"); session = (char*)FormValue("Session"); /* this time we are adding 2 elements to the bag to be sent to MVS */ FillStrings(bag,2,wsu_number_string,session); parmlist = (char**)CallServer(bag,&number_of_parms); print_header("Financial Aid - SUmmary"); print_summary(parmlist); exitMain(); return; }

/* print out the financial aid summary */

void print_summary(char **parms) { int aid_cnt,i; int number_of_fields; char *as_of_date; char *award_total; char *credited_total; char** fields; aid_cnt = atoi(parms[0]); as_of_date = parms[1]; award_total = parms[2]; credited_total = parms[3]; printf(" <CENTER> <table border> <caption align=center>\ <h3>Summary of Financial Aid </h3> <align=center>\ %s</caption><p> <tr> <th>Type of Aid <th> Awarded \ Amount <th>Stafford or Plus Loans Less Fees <th> \ Credited to account as of %s</tr>\n", FormValue("Session"),as_of_date); if (aid_cnt > 0) { for (i = 4; i <= aid_cnt+3; ++i) { fields = split(":",parms[i],&number_of_fields); printf("<tr><td align=left> %s </td> <td \ align=right> %s </td> <td align=right>\ %s </td> <td align=right> %s </td></tr>\n",
fields[0],fields[1],fields[2],fields[3]); } printf("<tr><td align=left><b>Totals for this \ award period</b></td> <td align=right><b>%s\ </b></td> <td align=right>&nbsp</td> \ <td align=right><b>%s</b></td> </table>\ </center><br>\n", award_total,credited_total); } else { printf("<tr><td align=center colspan=4> \ <b>*** No Aid for this Award Period ***</b>\ </td></tr> </table></center><br>\n"); } printf ("<p><b>If you have not already registered \ for classes, please do so on \ <a href=\"/AIS/REG/cgi-bin/reg_info.cgi\"> \ METRO </a> as soon as you are eligible to \ avoid delays in the delivery of your financial \ aid.</b><p>"); printf("</center>Please contact the \ <a href=\"http://%s/cgi-bin/Logout.cgi?script=http://www.wsu.edu/FINAID/contact.htm \"> Office of Student Financial Aid</a> if you \ have questions about the above information. \ <p>For information regarding your balance/checks,\ see <a href=\"/AIS/SIC/cgi-bin/balances_checks.cgi\"> \ Student Balances/Checks</a>.\n", this_server); printf("<p>Select another <a href=%s>\n",probe_name); printf("Award Period?</a><br><br> Go to \ <a href=\"/AIS/SIC/sicintro.htm\"> Student \ Information Center Menu</a><br><br>\n"); return; } /* END print_summary() */

Alphabetical List of Functions

alltrim (removes all leading and trailing blanks from a string)
CallServer (sends the bag to MVS)
CallTimeKeeper (used to add time of day to the performance log)
close_client (closes the html stream)
connect_port (open a socket to the requested port on the requested host)
Debug (used only in debugging to print out values of variables)
dir_list (returns a list of all files in a directory)
display_WSU_banner (prints the WSU standard identity)
escape_url (opposite of unescape_url)
exists (checks to see if a file exists)
ExitMain (ends the probe)
FillBag (adds strings and integers to the bag)
FillStrings (adds strings to the bag)
FormValue (array/function holding the POST and GET html form query values)
getenv (returns one of the environment variables)
get_groups (will return a list of groups for NID)
Get_Key (will return a cookie)
get_wsu_number (returns the wsu number in a string)
GetTime (return the current time of day in milliseconds)
HTML_Error (prints an html error message before loggin the client out)
INIT_Probe (this gets the probe started, calls authentication, etc.)
INIT_Probe_Vars (sets all kinds of variables)
InitBag (begins filling a bag to be sent to MVS)
in_group (see if the person is in that group)
itoa (converts and integer to a string)
Logout_FULL (gets rid of the kerberos tickets and user temporary files)
Logout_Public (similar to the above, but used for non specific authentications)
lowercase (converts a string of alpha characters to all lowercase)
ModFormValue (changes the value of an element in FormValue)
Non_Browser_Authentication (used if the probe is not driven by the web)
parseQuery (grabs the POST and GET form values and puts them into FormValue)
plustospace (converts plus signs to spaces)
PostStartTime (adds the time of day and processing cpu time into the html stream)
print_header (prints the html header)
print_meta_refresh_header (print html header and automatically redirects to another url)
putenv (sets one of the environment variables)
query_ups (query the User Profile Server)
Reauth (will let developers ask for reauth on the fly)
reverse (reverse a string)
spacetoplus (converts spaces to a plus sign)
split (similar to the perl function of the same name)
squish (replaces tabs and newlines with spaces and removes multiple occurances of spaces)
string_index (returns the index of a string in a string)
substr (returns a substring)
translate (translates all occurances of one character into another)
unescape_url (converts a url to a straight ascii including meta characters)
uppercase (changes a string to all uppercase letters)
x2c (converts a hex string to its ascii equivalent)

alltrim

You can remove all leading and trailing blanks in a string with the alltrim function.

char *string;

string = (char*)strdup("  abcd  ");
string = alltrim(string); /* string ends up as "abcd" */

Table of Contents

Simple Program

test_pgm_c.h

test_pgm.c

Alphabetical List of Functions

alltrim

CallServer

CallTimeKeeper

close_client

connect_port

Debug

dir_list

display_WSU_banner

escape_url

exists

exitMain

FillBag

FillStrings

FormValue

getenv

get_groups

Get_Key

get_wsu_number

GetTime

HTML_Error

INIT_Probe

INIT_Probe_Vars

InitBag

in_group

itoa

Logout_FULL

Logout_Public

lowercase

ModFormValue

Non_Browser_Authentication

parseQuery

plustospace

PostStartTime

print_header

print_meta_refresh_header

putenv

query_ups

Reauth

reverse

spacetoplus

split

squish

string_index

substr

translate

unescape_url

uppercase

x2c

Alphabetical List of Macros and Variables

ALINK

ALPHA_LIST

ALPHANUM_LIST

BACKGROUND

BGCOLOR

BODY_SRC

CHECKBROWSER

DOAUTHENTICATION

LINK

MAIN_CLIENT_CODE

MAX_BUFFER_SIZE

NUMBER_LIST

PRINT_COOKIES

PROBE_PATH

PRODUCTION

RETURN_LABEL

RETURN_LINK

SCRIPT

SCRIPT_LANGUAGE

SCRIPT_SRC

SCRIPT_TYPE

SCRIPT[2-5]

SCRIPT[2-5]_LANGUAGE

SCRIPT[2-5]_SRC

SCRIPT[2-5]_TYPE

STYLE