RUBIN Systemdokumentation

OBS! Denna dokumentation är ej korrekt längre.

Index

  1. Index
  2. Generellt
  3. Konfigurering av systemet
  4. Filerna i CGI-biblioteket
  5. Datamodellen
  6. PERL-modulerna
  7. Mall-filer
  8. JavaScript-filer
  9. Förslag till förbättringar och nyutveckling

Generellt

RUBIN bokningssystem är byggt på cgi-program i perl som vid varje access anropar en databas i oracle.

Vid en access av ett cgi-program i RUBIN laddas perl som börjar med att läsa in och kompilera några moduler som behövs, inklusive egenutvecklade generella moduler. Under initieringsfasen läses en konfigurationsfil som bland annat innehåller sökvägar och uppgifter för databasuppkopplingen. Databasen kontaktas. Ytterligare initiering sker genom inläsandet av ett antal cookies. I huvudprogrammet behandlas data från formulär och argument. För genererandet av html-dokumentet avnänds en speciell template-fil i villken datan placeras. I debug-läge följs sidan av debug-data och eventuella felmeddelanden.

Konfigurering av systemet

Systemets uppträdande beror på konfigurationsfilen "config.txt". Både namn och värden är versal/gemen-känsliga. Om de viktigaste uppgifterna är rätt satta kan filen uppateras via WWW med "edit_config.txt". Filen "edit_config.tmpl" anger hur uppdateringsformuläret ska se ut. Det går bra att lägga till extra konfigurationsvariabler helt enkelt genom att lägga till dem i tmpl-filen. Alla variabler läggs som enviromentvariabler. Det betyder att om webservern till äventyrs inte själv skulle sätta variabeln "DOCUMENT_ROOT", kan detta göras i "config.txt".

"basedir" anger var rubin-biblioteket ligger, från "DOCUMENT_ROOT". Exempelvis "/konferens/". CGI-programmen måste ligga i katalogen "bokning" under basedir. Bilder måste ligga i katalogen "images". Javascriptbiblioteket anges utifrån "basedir" med "javascript"-variabeln. I övrigt används inte denna variabel konsekvent. Istället anges exempelvis hypertextlänkar till sidor som beskriver ett rum, relativt utifrån den adress som angivits i rem_block, för det block rummet tillhör.

RUBIN kommunicerar med Oracle via perlmodulen DBD::Oracle som i sin tur använder Oracles ProC API. Oracle kräver att vissa enivromentvariabler är satta för att allt ska fungera som tänkt. Speciellt behövs "ORACLE_HOME" och "NLS_LANG", villka också sätts i config.txt.

Perls databasinterface är relativt generiskt (av typen ODBC). Vid uppkopplingen mot databasen behöver man ange namn, lösenord, databas och drivrutin. Dessa sätts i config.txt med "username", "auth", "database" och "driver". Driver måste vara satt till "Oracle", men det innebär inte särskilt mycket jobb att byta ut databasen mot något annat märke.

"DEBUG"-variabeln anger om du vill ha debuginformation i HTML-sidorna eller inte.

"masterauth" anger lösenordet för att uppdatera databasen via WWW eller hantera bokningar gjorda av andra personer. I och med att lösenordet ligger okrypterat här är det nödvändigt att filen inte går att läsa via WWW.

"block" och "language" anger defaultvärden. "block" anger ett rec_id för tabellen rem_block och "language" kan anta värdet "ENG" eller "SWE". Både block och language sätts enklare för den personliga användaren genom cookies, nämligen "RUBIN:block" och "RUBIN:language".

"titlecolumn" och "titlelength" används av "overview.cgi". "titlecolumn" talar om villket fält i rem_bookings som ska visas i bokningsöversikten och "titlelength" anger hur många tecken som mest får visas i tabellcellen. Om titlecolumn sätts till en sträng innom enkelfnuttar (exempelvis "'bokad'"), visas textsträngen istället för innehållet i ett fält.

Filerna i CGI-biblioteket

Följande filer hittas i RUBIN-katalogen:

CCLanguage.pm
Generell språkhanteringsmodul. Alla sidor översätts dynamiskt till det språk som anges av cookien RUBIN:language eller det förinställda värdet i config.txt
Common.pm
Generell RUBIN-modul med de vanligaste funktionerna
config.[default|old|txt]
Konfigurationsfil (txt) med backup (old) och förslag på innehåll (default). Om de viktigaste inställningerna redan är gjorda kan denna fil editeras via WWW med "edit_config".
dokumentation.html
Gissa noll gånger...
edit_config.[cgi|tmpl]
Program och template för formulärgenerering och uppdatering av config.txt
match_room_[form.cgi|form.tmpl|result.cgi]
"form.cgi" genererar formulär utifrån "form.tmpl". Resultatet visas av "result.cgi"
overview.cgi
Skapar en översikt över lediga och upptagna tider för olika lokaler
relations.cfg
Visar var olika fält ur databasen hämtar sina värden. Denna fil används för automatgenerering av editeringsformulär för tabeller ur databasen då en motsvarande template saknas. "n" anger om flera värden får väljas eller inte. Denna fil är i huvudsak analog med datamodellen för databasen.
search.cgi
Sökprogram för att finna villka sidor som innehåller en viss textsträng. Detta program hör inte till RUBIN i övrigt
[search|view|update]_booking[.cgi|.tmpl|_form.cgi|_form.tmpl]
Skapande, uppdaterande eller radering av bokning går i fyra steg.
  1. "search_booking_form.cgi" genererar ett sökformulär med vissa defaultvärden.
  2. "search_booking.cgi" presenterar resultatet av utsökningen
  3. "view_booking.cgi" visar vald post utifrån den template som hör till "webplatsen" enligt tabellen "rem_form".
  4. "update_booking.cgi" skapar/uppdaterar/raderar bokningsposten och berättar hur det gick.
search_[form.cgi|result.cgi] | [view|update]_record.cgi
Skapande, uppdaterande eller raderande av en post i en valfri tabell. Även detta sker i fyra steg. bokningarna har en egen väg på grund av dess speciella hantering av datum och kontroll mot dubbelbokningar.
  1. "search_form.cgi" anropas med "?table=blaha" där "blaha" är den tabell i databasen villken man vill uppdatera. Om ingen template för tabellen och "webplatsen" finns angiven i tabellen "rem_form", automatgenererar programmet en websida. Innehållet i komboboxar och dropdown-menyer bestäms av filen "relations.cfg".
  2. search_result.cgi visar resultatet av utsökningen. De fält som visas i resultatpresentationen bestäms av fältet "name" i search_form. Automatgenererade sökformulär sätter "name" till "longname" eller tar med alla fälten.
  3. "view_record.cgi" visar vald post. Om ingen template för tabellen och "webplatsen" finns angiven i tabellen "rem_form", automatgenererar programmet en websida. Innehållet i komboboxar och dropdown-menyer bestäms av filen "relations.cfg".
  4. "update_record.cgi" skapar/uppdaterar/raderar posten och berättar hur det gick.
set_cookie.[cgi|tmpl]
Låter användaren välja block. Programmet används inte.
statistics.cgi
Genererar statistik över bokningar i olika rum för aktuellt block
wow.cgi
wowstub.cgi
Anropar lagrade procedurer i oracle. "wow.cgi" är en shellwrapper som sätter nödvändiga environmentvariabler för wowstub. Dessa är
  1. ORACLE_HOME=...
  2. ORACLE_SID=...
  3. ORAENV_ASK=NO
  4. PATH som måste innehålla $ORACLE_HOME/bin
  5. LD_LIBRARY_PATH som måste innehålla $ORACLE_HOME/lib
  6. WOW_UID=oracleuser/passwd
  7. TWO_TASK=... ( som behöver sättas om sqlnet används ).
En giltig URL ser ut ex vis så här: "http://www.infohwy.net/.../wow.cgi/bb?bb_id=1". Om det skulle vissa sig nödvändigt att behöva debugga wowstub.cgi så kan man sätta ovanstående variabler manuellt i shellet. Dessutom måste man också sätta
  1. REQUEST_METHOD=GET
  2. PATH_INFO="/namn.på.oracleprocedur"
  3. QUERY_STRING="indata_till_oracleprocedur"
Är dessa satta så skall man kunna exekvera ./wowstub.cgi och få ut något vettigt.

Javascriptfiler ligger i den katalog som angivits i config.txt

Datamodellen

Tabellerna knytna till RUBIN är:

De flesta tabeller har ett REC_ID som automatiskt tilldelas ett unikt nummer när en ny post skapas. De flesta tabeller har också ett LONGNAME och SHORTNAME, där shortname är en kortare version av longname. SHORTNAME_ENG och LONGNAME_ENG är dess engelska översättning.

CC_LANGUAGE

Grundspråket är engelska. I denna tabell ska en kolumn skapas för varje språk där den engelska motsvarigheten finns.

REC_ID: NUMBER
ENG: VARCHAR2(1024)
SWE: VARCHAR2(1024)

REM_BLOCK

Rummen grupperas i olika block. Alla rum i ett block är tänkta att vara av samma typ och ligga på samma ort.

REC_ID: NUMBER
Automatiskt uppräkning av unikt nummer
SHORTNAME: VARCHAR2(15)
LONGNAME: VARCHAR2(40)
SHORTNAME_ENG: VARCHAR2(15)
LONGNAME_ENG: VARCHAR2(40)
HREF: VARCHAR2(80)
URL för blockets ingengssida
SITE: NUMBER
REC_ID för posten i REM_SITE till villken blocket hör

REM_BOOKINGS

Detta är den tabell där slutanvändarnas bokningar hamnar.

STARTTID: DATE
Starttidpunkt för bokningen
SLUTTID: DATE
Sluttidpunkt för bokningen
NAMN: VARCHAR2(40)
FORETAG: VARCHAR2(40)
EMAIL: VARCHAR2(40)
FADRESS: VARCHAR2(40)
Faktureringsadress
LOKAL: NUMBER
REC_ID för posten i REM_ROOM för den lokal som bokas
UTRUSTNING: VARCHAR2(256)
Lista på REC_ID i REM_EQUIPMENT för den utrustning som önskas med lokalbokningen. Siffrorna separeras med semikolon i en textsträng
PASSWORD: VARCHAR2(10)
Det lösenord bokaren valt för att skydda sin bokning
FKAFFEANTAL: NUMBER
Hur många önskar kaffe på förmiddagen
FKAFFETIMME: NUMBER
När på förmiddagen önskas kaffe; vilken timme
FKAFFEMINUT: NUMBER
När på förmiddagen önskas kaffe; vilken minut
FBROD: VARCHAR2(10)
Önskas tilltugg till förmiddagskaffet? I så fall innehåller detta fält strängen "checked", i annat fall är fältet tomt
LUNCHANTAL: NUMBER
Hur många önskar lunch
LUNCHTIMME: NUMBER
När önskas lunch; vilken timme
LUNCHMINUT: NUMBER
När önskas lunch; vilken minut
EKAFFEANTAL: NUMBER
Hur många önskar kaffe på eftermiddagen
EKAFFETIMME: NUMBER
När på eftermiddagen önskas kaffe; vilken timme
EKAFFEMINUT: NUMBER
När på eftermiddagen önskas kaffe; vilken minut
EBROD: VARCHAR2(10)
Önskas tilltugg till eftermiddagskaffet? I så fall innehåller detta fält strängen "checked", i annat fall är fältet tomt

REM_EQUIPMENT

Den utrustning som kan finnas i rummet.

REC_ID: NUMBER
SHORTNAME: VARCHAR2(40)
SHORTNAME_ENG: VARCHAR2(40)

REM_FORM

Detta formulär kopplar tabeller och "vyer" (DBACTION) på dem till dess rätta templates och cgi-program. Olika block kan ha olika templates. HANDLER används inte i dagsläget. Tabellen avnänds för att göra en utsökning på villken template som ska användas utifrån aktuell DBACTION, TABLE_VIEW och BLOCK.

REC_ID: NUMBER
TEMPLATE: VARCHAR2(80)
Namn på en templatefil. Ingen sökväg, men med extension, dvs ".tmpl"
TABLE_VIEW: VARCHAR2(40)
Den tabell vars data ska skickas till mallen
DBACTION: VARCHAR2(40)
Kan vara "match", "new", "search" eller "update". I dagsläget använder new och update samma template, men det är valfritt
HANDLER: VARCHAR2(80)
Namnet på det cgi-program som ska använda den template och läsa den tabellen som angivits i denna post. Värdet i detta fält används inte i dagsläget.
BLOCK: VARCHAR2(40)
Lista på REC_ID i REM_BLOCK för de block som använder den angivna mallen. Siffrorna separeras med semikolon i en textsträng. Om inget block angivits anses denna post utgöra defaultvärdet för alla block, då de inte har en egen post för det aktuella SBACTION och TABLE_VIEW

REM_ROOM

Beskriver alla lokaler. USERDATA-fälten är gjorda för att hålla de data som kan vara olika för olika block. I denna implementation (med två block) har de dock bara en betydelse.

REC_ID: NUMBER
BLOCK: NUMBER
REC_ID i REM_BLOCK för det block lokalen hör till
SHORTNAME: VARCHAR2(15)
LONGNAME: VARCHAR2(40)
SHORTNAME_ENG: VARCHAR2(15)
LONGNAME_ENG: VARCHAR2(40)
CAPACITY: VARCHAR2(5)
Antal personer som ryms i lokalen
USERDATA01: VARCHAR2(128)
Eriksson REM: Rumsbeteckning
USERDATA02: VARCHAR2(128)
Eriksson REM: Internadress
EQUIPMENT: VARCHAR2(40)
Lista på REC_ID i REM_EQUIPMENT för den utrustning som ingår i lokalen. Siffrorna separeras med semikolon i en textsträng
HREF: VARCHAR2(80)
Filnamnet på den html-sida som beskriver rummet. Ange ingen sökväg, men väl extension, ex ".html". I REM_BLOCK anges den URL där den svenska rumsbeskrivningen ligger. Andra språks rumsbeskrivnngar ligger i ett underbibliotek med samma namn som det språk som är satt med cookien RUBIN:language
USERDATA03: VARCHAR2(128)
Eriksson REM: Husnummer
USERDATA04: VARCHAR2(128)
Eriksson REM: Våning
USERDATA05: VARCHAR2(128)
Eriksson REM: Lokalnummer
USERDATA06: VARCHAR2(128)
Eriksson REM: Rumsbeteckning
USERDATA07: VARCHAR2(128)
Används ej
USERDATA08: VARCHAR2(128)
Används ej
HREF_ENG: VARCHAR2(80)
Var tänkt att innehålla filnamnet för den engelska rumsbeskrivningen. Men istället används valt språk för att avgöra i villket bibliotek sidorna sidorna ligger.

REM_SITE

Blocken grupperas till olika webplatser. Dessa webplatser har egna footers och headers och en egen "hemsida". Header och footer anges relatvit cgi-sidan. Dvs lämpligen från webroten.

REC_ID: NUMBER
LONGNAME: VARCHAR2(80)
HEADER: VARCHAR2(256)
FOOTER: VARCHAR2(256)
HREF: VARCHAR2(256)
Används ej

REM_TIMES

Anger de timmar som är bokningsbara. Tabellen används vid alla skapanden av listor på timmar och för att avgöra första respektive sista bokningsbara timme.

HOUR: NUMBER
Det får inte finnas några luckor i den lista på timmar som tabellen innehåller
MINUTE: NUMBER
Används ej

PERL-modulerna

RUBIN är utvecklad under Perl, version 5.004.

Publika moduler

Standardmodulerna medföljer installationspaketet till Perl version 5.004. Utöver dessa finns det ett stort antal publika moduler i CPAN. CPAN (the Comprehensive Perl Archive Network) är ett filbibliotek som speglas över hela världen. Bland annat till sunet: ftp://ftp.sunet.se/pub/lang/perl/CPAN/.

De publika moduler som används är:

Instruktioner för installation finns i respektive pakets README-filer. Paketet packas upp i ett temporärbibliotek med "gunzip" och sedan "tar xvf". Installationen sker bland annat till katalogen site_perl i perls bibliotekskatalog (villken angivits vid installationen av perl). Efter installationen kan den temporära katalogen plockas bort. Vissa installationer inbegriper kompilering av C-program.

Egenutvecklade moduler

Anpassade moduler:

Text::Boilerplate

Modulen används för att skilja på webformulärsdesign och cgi-programmering. Originalversionen ligger på http://www.slip.net/~senelson/ där även dokumentation finns. Vi har laggt till ett par extra funktioner till modulen. Modulen är gjord för att enkelt uppdateras. Inga förändringar i befintliga filer har gjorts. Men följande extra filer är skapade i site_perl/Text/Boilerplate/Tag/:

Följande moduler ligger nu i RUBINs CGI-bibliotek

CCLanguage

"CCLanguage::translate" anropas dels via boilerplate då metoden TRANSLATE användts i en template, dels direkt från ett CGI-program. Modulen är gjord speciellt för RUBIN-programmen. Funktionen anropas med 'string' och 'option', där 'string' är en engelsk sträng. Om cookien är satt till något annat än "ENG" kontaktas databastabellen cc_language och söker upp översättningen för det aktuella språket. Är 'option' satt till '1' sker ingen konvertering till HTML av specfialtecknen. Är 'option' satt till 'js' sker konverteringen av specialtecknen till en javascriptsträng, som sedan kan kopplas samman med intilliggande strängar (i en template) med '+'.

Common

Common innehåller alla de vanliga rutinerna som används av flertalet CGI-program i RUBIN. Det handlar om initiering mot databasen, felhantering, utsökningar från databasen, inläsning av formulärdata, osv. Funktionerna läggs i samma namnutrymme som huvudprogrammet. Ingående funktioner är:

&lastpass($arg)
Byter ut alla 'table.field' mot 'table$field' i $arg och retunerar resultatet. 'table$field' används i som namn i HTML forms för att fungera med javascript.
&get_cookies
Läser in alla cookies och retunerar en hash
&read_form($option)
Läser in formulärdata till %FORM.

Om $option är 'sublist' skapas det för varje fältnamn ett "fältnamn_list" som är en lista på alla värden som hör till fältnamn.

I villket fall separeras multipla värden för ett fältnamn med semikolon

&include_footer
Retunerar innehållet i footer.htm
&sth_error(@_)
Skriver ut @_ och %FORM till STDERR
&rc_error(@_)
Skriver ut @_ och %FORM till STDERR
&debug_input
Skriver %FORM, %ENV och @INC till STDERR om $ENV{DEBUG} är satt
&read_config
Läser in data från filen 'config.txt' till %ENV
&desc_table($table)
Retunerar en lista på fälten i $table, i gemener
&select_field($statement)
Retunerar en lista med alla valda värden. Lämpligen ett enstaka fält i flera poster eller flera fält i en enstaka post.

$statement är i SQL. 'SELECT' kan utelämnas. $statement får ej avslutas med ';'

Exempel: @colours = &select_field('name from colours');

Om $option är 'sublist' blir varje element i den retunerade listan en lista med alla värden från i fältet som separerats med semikolon.

&select_list($statement, $option)
Retunerar en lista av hasher, där varje hash är en post

$statement är i SQL. 'SELECT * ' kan utelämnas. $statement får ej avslutas med ';' Exempel: @rooms = &select_list('from rooms order by name'); print $rooms[3]{name}; # Fjärde rummets namn

Om $option är 'sublist' skapas det för varje fältnamn ett "fältnamn_list" som är en lista på alla värden från fältnamn som separerats med semikolon.

&select_record($statement, $option)
Retunerar vald post i en hash

$statement är i SQL. 'SELECT * ' kan utelämnas. $statement får ej avslutas med ';'

Exempel: %kalle = select_record("from person where name='kalle'");

Om $option är 'sublist' skapas det för varje fältnamn ett "fältnamn_list" som är en lista på alla värden från fältnamn som separerats med semikolon.

&select_key($id, $statement, $option)
Retunerar en hash av hasher där den första hashen är nyckeln och den andra hashen är resten av posten.

$statement är i SQL. 'SELECT * ' kan utelämnas. $statement får ej avslutas med ';'

Exempel: %person = &select_key('name','from person'); print $person{kalle}{address} # Var bor han?

Om $option är 'sublist' skapas det för varje fältnamn ett "fältnamn_list" som är en lista på alla värden från fältnamn som separerats med semikolon.

&initialize
Initierar $DBH, %ENV, %COOKIE och $LANGEXT
&BEGIN
Omdirigerar STDERR till en temporärfil Skriver ut hela HTTP-headern
&END
Skriver ut allt som gått till STDERR om $ENV{DEBUG} är satt eller om programmet avslutades med felmeddelande

Anger exekveringstid

Mall-filer

Modulen Text::Boilerplate ger möjligheten att separera layouten av en dynamisk websida med det innehåll som CGI-programmet genererar. Layouten läggs i en template-fil (filer med extensionen 'tmpl'). Templatefilen är en vanlig HTML-fil med den skillnaden att där finns speciella templatemarkeringar. En markering kan se ut såhär: "[* kommando NAME=namn *]". När CGI-programmet exekveras läser den in rätt templatefil, byter ut alla templatemarkeringar mot det dynamiskt genererade innehållet och skickar sedan resultatet som en HTML-sida till besökarens web-browser. Det dynamiskt genererade innehållet består i RUBIN vanligtvis av data ur databasen.

Jag kan tyvärr inte uppge någon länk till dokumentationen för denna modul, då jag råkat radera alla mina bokmärken.

De mallfiler som finns är:

I RUBIN är Text::Boilerplate utökad med tre egenutvecklade markeringar. Dessa är:

Include
Laddar in filen med det filnamn som angivs i NAME och ersätter markeringen med innehållet i filen.
Textarea
Fungerar så som markeringen 'Input', med den skillnaden att den genererar en TEXTAREA HTML tag. Datan till denna tag bör ha kodats enligt följande: s/&/&amp;/; s/</&lt;/;
Translate
'Translate' tar två attribut. Attributet 'name' måste anges. Attributet 'option' är valfritt. 'name' är en sträng på engelska som motsvaras av en post i databastabellen 'cc_language'. Funktionen anropar CCLanguage::translate med $string satt till 'name' och $option satt till 'option. Se vidare translate-funktionen.

JavaScript-filer

Ja-a du...

Förslag till förbättringar och nyutveckling