WWW access to allegro databases

`PHP files needed for RuckZuck`   `Construction of PHP files`

(Engl. Translation by David Helliwell, Oxford. Jan.2003)

Installation requirements
The basic demo setup assumes that Avanti-W will be installed on the c: drive in c:\avanti-w, and that it will address the Avanti-W-Demo database in c:\avanti-w\avdemo.

PHP version 4.0.6 or higher must be installed (downloadable from http://www.php.net). 
Note: PHP must relate to the "correct" Web-server (Apache, Xitami, IIS &v.)! If using PHP 4.2.3, set the  register_globals value in the configuration file php.ini to "off".

A Web-server  must be installed. The simplest option is Xitami, well tried and tested with other allegro applications. For those who work with Windows 2000, it would be appropriate to use the IIS-Web-Server which comes with the package, thus avoiding the need to install a separate Web-Server (such as Xitami).
The avanti-server must be running on the same machine as the database, which can be a different machine from the one where the Web server runs. The IP address of the avanti machine must appear in the file  av_ini.php (see below).

Where should the files be put?
Note: all filenames must be written completely in lower case, in conformity with mode 8.3, in order to avoid any problems when copying them back and forth between DOS and Unix. When you unpack the self-extracting archive PHPAC.EXE, three directories will be created:

doku:
phpaceng.rtf: the text that you are now reading. Also part of the full allegro package ("Gesamtpaket") and readable as a help file in a99 (copy it to the "help" directory and input   h phpac).

php: 
php and htm files, also ruckzuck.gif: to be put into the appropriate subdirectory for the database, eg. /catalog, on the htm directory of the Web server  ( htdocs in Apache, webpages in Xitami).

param:
Parameter files (.apr, .apt): to be put in the database directory (DbDir - rename .xpr for configuration x.cfg). In the case of the Avanti-W demo database this will be c:\avanti-w\avdemo. If the php and htm files (also ruckzuck.gif) are in  .../htdocs/katalog for example, the address for external access will be:
http://www.lib.oxbridge.org/katalog/detail.php
or for a simple search: 
http://www.lib.oxbridge.org/katalog/br.htm
or just:
http://www.lib.oxbridge.org/katalog/
if you have either renamed the file br.htm index.htm  or created your own start page with the name index.htm.for a stand-alone PC withouth any internet access:
http://127.0.0.1/catalog/detail.php
or for a simple search:
http://127.0.0.1/catalog/br.htm

What is in the files and what do they do?
PHP files
These must go into their own subdirectory of the Web server's document directory.
The start page is  br.htm or detail.php, as specified in av_ini.php.

av_ini.php contains the variables which will need to be adjusted. These include the IP number of avanti, the database name, the user name and password, the title and various other pieces of information, such as $Startpage, $TI ... (a tip: avanti can run on another machine!), a couple of sub-routines are contained in av_ini.php, to be precise, the ones that are needed for each job. This avoids the need to create an additional file for this purpose. If you need access to several databases, copy all these files to their own subdirectories. You can also do this if you need several different types of access to the same database.
Files with the prefix av_ are not independent, but are called up from within other files. Red is used for the names of files that you will need to configure.

av_ini.php	the initialisaion file for a given database, containing basic information about it 
br.htm	the start page, simply (with link to detail.php)
	Recommendation: copy to  index.htm  so it will come up as the default
detail.php	start page for a detailed search, calls up (when the user has input something):
find.php	execution of a detailed search, immediately starts one of the two following operations:
page.php	display of an index excerpt, or:
rset.php	display of a result-set, according to what the user has clicked; then:
grec.php	display of a record ("get record"), started by clicking "Bearbeiten" (= "Edit");
edrec.php	preparation of a record for editing, or display of en empty form for the creation of a new record, which will then start write.php by clicking on "Speichern" (= "Save"):
write.php	save the edited or newly-created record (password needed!)
del.php	delete the record (password needed!); started from grec.php by clicking on "Löschen" (= "Delete").

The following three files are automatically called up:
av_page.php	basic functions of page.php  (preparation of an index excerpt)
av_rset.php	and of rset.php (preparation of a result-set)
av_grec.php	and of grec.php (getting and displaying a record)
For write functions you will need to configure the files edrec.php and write.php. The things that you will need to change are marked with "xxx". They concern the fields which are specific to the database that is being edited. The package also includes:
tellme.htm	A dummy file, which can contain any information that might be needed about the database.

Parameter files
These must reside in the data directory.
For the  a.cfg  configuration file, there is the file:
d-html.apr	to produce data display in HTML (based on the DOS/Windows d-1.apr)

Recommended alternatives and models for other configurations:
d-shtm.apr	general model for display (`d-s.apt und d-k.apt` must be adpated)
d-khtm.apr	In av_ini.php put either $Dispar=d-shtm  or  $Dispar=d-khtm
h-php.apr	Extra functions, for example the preparation of an index excerpt, universally applicable to all configurations. For example, copy the file to  h-php.mpr
h-edit.apr	prepares the record for editing (includes commentary)
	must be adapted: contains a list of fields that may not be edited
p-brief.apr	produces short-titles for the result set (must be adapted)
	(used in the CoOL implementation)

These three can simply be copied to asciansi.mpt &c.:
asciansi.apt	used for ASCII-->ANSI recoding  (in h-php.apr, h-edit.apr, p-brief.apr, d-*.apr )
o.apt	code table, contains one-to-one ASCII -> ANSI equivalents; must be invoked by the index parameter with the command to
d-htm.apt	a few HTML tags (script, colours)

NB: lines for index headings (beginning with |1 ..., |2 ... &c.) and for symbolic index names (such as PER or TIT) must appear in the index parameter. The same applies for any restrictions (begining with R ...) which might have been defined. (See Handbuch, 178, 179). The symbolic index names should be given in upper case, and may include numbers.

Tips for linking the structure into your own webpages, &c.
There are chiefly three files that are used for this purpose:
page.php	shows an index excerpt with pages; the name of the index and the starting point must be read in, eg:
	page.php?reg=PER&st=shakesp
rset.php	creates and displays a result-set with pages; reads in the result of a "find" command, eg: rset.php?ufC=PER+shakesp%%3F
grec.php	retrieves and displays a record, eg:
	grec.php?urN=12345 // show rec. no. 12345
	or
	grec.php?urG=NUM&urS=12345678 // record with entry 12345678 in index NUM
edrec.php	prepares a record for editing, eg:
	edrec.php?urN=12345 // bring rec. no. 12345 into the editing screen without a record number, ready for the creation of a new record.
The actual functions are carried out by the files av_page.php,  av_rset.php and av_grec.php, so the mechanism is transparent. In your own designs you need only take account of these three av files, which are called up by the command:
include_once(av_grec.php) 
The names of the variables are related to the internal variables (#u) of "avanti", and are therefore always in the form  uxY with x in lower case and Y in upper. The most important are:
urG	index name, eg: PER
urS	index start point, eg: shakesp
ufC	find command,  eg: PER+shakesp%%3F
urN	record number (ie internal record number)
urO	filing order - default is a0 (only in RSET.PHP)
As usual, variables which are passed to PHP must be re-coded, so that a space is replaced with  + , ? with %%3F  etc. The password procedure for write functions is decribed is a supplementary file password.txt which accompanies the PHP files. Only the supervisor needs to be concerned with this.
Extra function: "delete a record". The script del.php can be started by inputting an internal record number:
.../del.php?n=number
The record with the corresponding number is then deleted.

Writing a PHP file
The advantage of PHP is that you can build scripts directly into HTML files. In the PERL and Python languages on the other hand the scripts are independent files that are called up as CGI programs. Because such scripts must be put in their own directory, the way in which the structure is put together is far from clear. For this reason PHP has become very popular, especially for database applications. You can set up your own allegro implementations by studying the PHPac package and using these scripts as a model.  (The phpac.exe archive is on the allegro FTP Server in the directory ac21).
Advice for PERL users: PHP is very similar to PERL. Perhaps that is more of a problem than an advantage, as it leads to confusion. You might be better off using Thomas Berger's populo package. This comes as a single, large PERL script which enables many functions to be implemented through your own HTML scripts. It is thus very similar to the PHP concept. It is important to note that the PHP files are first processed on the server. The user, who calls them up with a browser, does not see them, but is presented with an HTML text which they generate, but in which there is no longer any PHP. That is, it appears as just an ordinary HTML page. However, if you want to execute functions in the browser without first sending a request to the server, for example data validation, they are not done with PHP (nor even with PERL or Python), but only with Javascript. Examples of such scripts can be seen in the files rset.php and edrec.php.
So that you can get a better understanding of what a PHP script does, here is an example of one which incorporates an avanti Job. Colours are used to differentiate the various sections:

BLUE = HTML
GREEN = PHP
LILAC = Javascript
RED = FLEX
GREY = Commentary

Example of a PHP script
Note once again: end users do not see these scripts when they view "source" in the browser! Rather, instead of the PHP they see the results of what the PHP has first produced on the server. This is the purpose of the PHP command "echo" - it outputs text which is then visible. JavaScript on the other hand is fully visible to the end-user (unless you put it in a .js file).

<HTML>
<HEAD>
<!--  commentary  -->
<TITLE>
Page title, perhaps even a PHP command to show a variable title! (appears as a heading in the browser)

</TITLE>
Optional:
<script language="JavaScript">
//  Javascript functions

</script>

</HEAD>

<BODY>
<!-- your own HTML text -->

<?php
// start of a PHP program
include_once("av_ini.php");
// this executes the sendjob( ) function, which sends instructions to the database !

// your own PHP commands

$job = array(
// start of a built-in avanti-Job "FLEX"

"FLEX command",
"FLEX-command",
//  if a " or \ appear in a FLEX command, you must write  \"  or  \\
// all FLEX lines must be enclosed in inverted commas  "..." and end with a comma, except the last one:

"FLEX-command"

);
// end of the FLEX job

// any further PHP text

// send a job to avanti (the functions are in av_ini.php)
$k = sendjob($Server, $Port, $job, $erg);

// $k = number of lines in the output, ie contents of $erg

// alternative 1:
// show only the results  (contents $erg )
av_out($erg);
// this function is also in av_ini.php, and HTML text is output!

// alternative 2:
// process the results, ie array  $erg[ ], with PHP, in which case you use echo ...  and   printf...  to produce HTML text

?>
// end of the PHP job

Any other HTML and PHP sections, or even JavaScript

</BODY>
</HTML>

?PHP files needed for RuckZuck=h =What is in the files
?d-s.apt and d-k.apt=h vb154=Model
?Construction of PHP files=h =Writing a PHP file