WACS: Using The Application Programming Interface

Contents

Overview

 This web document will attempt to introduce you to the basics of programming with the WACS API and how to get a simple program running and accessing the Wacs database, configuration and security systems. In most cases, the core information covered here is applicable to the interfaces for either Perl or PHP and function as close to identically as possible between versions. In many of the examples below, both dialects are given.

Initialisation - before you do anything else

 The first step is the pre-requisite modules: basically these are the Wacs module and the Database Interface module. Here's what you need:
Perl Version PHP Version 
use Wacs;
use DBI;

require_once "wacs.php";
require_once "DB.php";

The second step is to initialise Wacs and parse the configuration files, again this is a very simple process. The second part is to check the security system allows this access - this step uses an environment variable REMOTE_ADDR provided by the Apache web server when it calls the application and so is only really applicable to web-based programs. During debugging, you might want to set this variable so the security routines act as they will in the production environment. Note that the PHP implementation of these functions is object-orientated and so an extra step creating a Wacs instance handle is required.
Perl Version PHP Version 
# initialise WACS: read the Wacs configuration files
read_conf;

# check the auth(entication and authorisation) of this user
check_auth( $ENV{"REMOTE_ADDR"}, 1 );

$wacs = new Wacs;

// read the Wacs configuration files
$wacs->read_conf();

// check the auth(entication and authorisation) of this user
$wacs->check_auth( $_SERVER['REMOTE_ADDR'], 1 );

The check_auth routine takes two parameters, the first is the calling IP address (the basis of the authentication mechanism), the second is the vocal state. If the vocal state is set to 0, the routine will issue no error of any kind when authentication fails - correct for a utility program. If the vocal state is set to 1, it will generate an HTML error page explaining as best it can what went wrong and offering an appropriate link to allow the user to authenticate themselves.

The third step is to establish the connection to the database backend and ready it for a query. The first four lines of this code deal with ensuring the appropriate environment variable is set such that the database will find it's binaries, libraries and configuration files in the location they've been installed on the host. This is often not a problem with open-source packages like MySQL which come with the OS and are therefore in a known location, but they are needed for commercial databases like Oracle. Once again, here's the same code in both the Perl and PHP dialects:

Perl Version PHP Version 
$dbienv = conf_get_attr( "database","dbienvvar" );
if( $dbienv ne "" )
{
        $ENV{$dbienv}= conf_get_attr( "database","dbienvvalue" );
}
$dbhandle=DBI->connect( conf_get_attr("database","dbiconnect"),
        conf_get_attr("database","dbuser"),
        conf_get_attr("database","dbpass") ) ||
        die("Can't connect to database\nReason given was $DBI::errstr\n");

// database initialisation
$dbienv = $wacs->conf_get_attr("database","dbienvvar");
if( ! empty( $dbienv ))
{
        putenv($dbienv."=".$wacs->conf_get_attr("database","dbienvvalue"));
}
$dbhandle= DB::connect( $wacs->conf_get_attr("database","phpdbconnect") );
if( DB::iserror($dbhandle))
{
        print "Can't connect to database\n";
}

Do note that the PHP connect string has the password embedded while the perl version does not. Unfortunately the logical seperation of two within the PHP implementation was sufficiently poor as to make this difficult.

Using The Database in an application

 Having initialised the Wacs subsystem as shown above, you then need to run a suitable database query and display the results. To do this effectively, you will need some understanding of how the database schemas are designed and what sort of data each table contains. The next page gives a detailed breakdown of what the database tables contain and their possible values.

Having initialised the Wacs subsystem as shown above, you then need to run a suitable database query and display the results. To do this effectively, you will need some understanding of how the database schemas are designed and what sort of data each table contains. The next page covers these aspects.

The first step is to create and run a suitable SQL query against the database, once again the same query is implemented in both Perl and PHP:

Perl Version PHP Version 
#                   0      1        2          3
$cutesql = "select mname, modelno, mbigimage, mimage from ";
$cutesql.= conf_get_attr("tables","models")." ";
$cutesql.= "where mflag = 'C' order by mname ";
$cutecsr=$dbhandle->prepare( $cutesql );
$cutecsr->execute;
while( @cuterec = $cutecsr->fetchrow_array )
{
	print "Model: ".$cuterec[0]."  Number:".$cuterec[1]."\n";
}

//                                    0      1        2          3
$cuterec = $dbhandle->getAll("select mname, modelno, mbigimage, mimage from ".
                        $wacs->conf_get_attr("tables","models").
                        " where mflag = 'C' order by mname");
$entryno = 0;
while( isset( $results[$entryno] ))
{
	print "Model: ".$cuterec[$entryno][0]."  Number:".
		$cuterec[$entryno][1]."\n";
	$entryno++;
}

Adding Icons Into The Mix

 In the above examples, we simply retrieved the model's names but we can obviously include their headshot icons as well if we wish to. We already selected the two icon determining fields from the models table in the database, namely mbigimage and mimage, so how would we use these?

The small sized headshot, mimage, is assumed to be present for all models, and it will be located at:
wacs/icons/vendor/modelname.jpg
on the web server. We can get the URL for the wacs part from the Wacs configuration files which have already been read by this point - the function call is simply:

Perl: conf_get_attr("server","wacsurl")
PHP: $wacs->conf_get_attr("server","wacsurl")

A very similar function call can be used to retrieve the path to the cgi-bin directory on the server (attribute "cgiurl" in the "server" section of the config). We do this in order to link to one of the standard wacs tools, like the model page in thumbs mode (wacsmpthumbs). Note that URLs are guaranteed to contain the ending slash while file paths are not. We select the constant "icons" or "bigicons" depending on which size we want, although do consider that "bigicons" may not be filled in but "icons" should be. The rest of the path is stored in the database, so we can change the earlier code within the while loop to:
Perl Version PHP Version 
# link to the model page, thumbs version
print "<a href=\"".conf_get_attr("server","cgiurl");
print "wacsmpthumbs/".$cuterec[1]."\">";
# add in the icon
print "<img src=\"".conf_get_attr("server","wacsurl");
print "icons/".$cuterec[3]."\" alt=\"[image: ".$cuterec[0]."]\">";
# print the name, close the link
print $cuterec[0]."</a>\n";

// link to the model page, thumbs version
print "<a href=\"".$wacs->conf_get_attr("server","cgiurl");
print "wacsmpthumbs/".$cuterec[$entryno][1]."\">";
// add in the icon
print "<img src=\"".$wacs->conf_get_attr("server","wacsurl");
print "icons/".$cuterec[$entryno][3]."\" alt=\"[image: ";
print $cuterec[$entryno][0]."]\">";
// print the name, close the link
print $cuterec[$entryno][0]."</a>\n";

Next Section: Database
Back to WACS Documentation Index