shared module

Contains routines shared by other PIE routines (the routines ParseXML and
ReadConfig are in UIG.pl, since they are used before the PIE can find its
libraries)

multline routine

No longer used; parses a particular kind of encoding for multiple lines in CGI
scripts.

get_html routine

Returns the HTML to use for an item

Input: expanded, type
Output: HTML text

PDL

Get expanded and contracted HTML from itemconfig table
Choose which HTML to use
Return HTML

present_login routine

Returns login form to user and exits

Input: expanded,reason
Output: None (exits)

PDL

Call get_html routine to get HTML
Set CGI parameter reason to reason variable
Substitute for variables in HTML
Print HTTP header
Print HTML
Disconnect from database
Exit

checktime routine

Calculate unix style time (seconds since 1970) from date/time string

Input: date,time
Output: seconds

PDL

Call timelocal with appropriate parameters (substrings of date and time)
Return time

getreadabletime routine

Turns perl time array (as produced by timelocal) into a nice human readable
date/time 

Input: time array
Output: date/time string

PDL

Prepend 0 to time fields which may need it (hour/min/sec)
Set initial timestring as [hour]:[min]:[sec]
Append weekday to timestring
Append monthday to timestring
Ammend month to timestring
Add 1900 to year
Append year to timestring
Return timestring

add_to_item routine

For each item type, calculates information which is made retrievable via
<ATTRIBUTE ...> tags in the pseudo-HTML for the type

Input: itemid,type,userid,item hash,CGI paramaters (after modification by
action)
Output: modified item hash

PDL

If type="page"
    Get pages which can be read by user that they want to view for display on
    LHS of page from item, groups, userdata, readgroups tables
    Foreach page
    	Get information about link to page from viewitem table (to see if there
	is currently a link listed between page to be displayed and page to be
	linked to)
	If page id != itemid
	    Call update_page_links routine with appropriate parameters
	Else
	    Call update_page_links routine with appropriate parameters
    If itemid="edithelp"
    	Get list of help topics from help table
	Add information to list to force display of option of adding new help
	topic
	Foreach topic
	    Get helpform item from viewitem table
	    If helpform item exists
	    	Insert child of helpform item relating to this help topic into
		viewitem table
    If motd in config file is not just whitespace
    	Set ismotd parameter to HTML to go before message
    Else
    	Set ismotd parameter to " "
    If page{description} is not just whitespace
    	Set isdesc parameter to HTML to go before description
    Else
    	Set idesc parameter to " "
If type is of form "*list*" but != "listlink"
    Get number of children of list from viewitem/item tables
    Set childno parameter to number of children
If type="resource"
    Call getrdbdesc to get description of resource from resource database
    Set isrdmdesc="Official description: " if rdb description != ""
    Set isyourdesc="Your description: " if description parameter set
    If location is of form "rdb://*"
    	Call getrdburl to get list of locations for item
	Foreach location
	    Set locationid parameter in location array of hashed data
    Else
    	Fake a location array entry which just contains details of URL in
	location 
    Delete existing location data from viewitem table
    Set hassearch=0
    Set count=1
    Foreach location
    	If location{search_protocol}="none"
	    Next if location{location_id}="" (don't display locations which
	    have blank URLs in resource database or PIE database)
	    Set id=itemid."l".count
	    Insert information about location into viewitem table
	    Increment count
	Else
	    Set hassearch=1
    Call getrdbhelp to see if there is help in resource database for this item
    If help exists
    	Set helplink HTML
    Else
    	Set helplink HTML="&nbsp;"
    Call getrdblogo to get logo and alt text for resource
    If logo exists
    	Set logo HTML
    Else
    	Set logo HTML=" " to ensure broken image not displayed
    Call getrdbtraining to get training URL for resource
    If training information exists
    	Set training link HTML
    Else
    	Set training link HTML=" "
    Set searchbox=" "
    If hassearch and location is of form "rdb://*"
    	Set searchbox URL to display checkbox
If type="resourceform"
    Get location information about resource from item table
    Set rdmdesc parameter by calling getrdbdesc
If type="configform"
    Open config file
    Import config file contents into rawconfig
    Close config file
    Turn XML markup into HTTP special character strings (<,> and " to &lt; etc.)
    Set processed=""
    Set entrylength=0
    While rawconfig is of form "#($1)&lt;($2)&gt;($3)&lt;($4)&gt;" (using s
to remove each match as it happens)
	Set entrylength to length of $4
	Append processed entry as HTML to processed
	If entrylength < 80
	    Append input box to processed
	Else
	    Append textarea to processed
	Remove #s from processed
    Set configlist parameter as processed
If type="location"
    If location is of form "rdb://*"
	Get rid of rdb prefix
	Call getrdblocinfo to get information about location from resource
	database
	Make alt text for location icon from this information
	Make media type lower case
	Set URL in location{url}
	Set location{resourcedb}=1
    Else
	Get location information from item table
	Set location data
	Set alt text for location icon from config file
    Set item information from location information
    If location{available}="Y" set greyed="available" else set
    greyed="unavailable" 
    If location{available}="Y" and location{resourcedb}
	Get group list for user from userdata table
	Call rdbavailable to set greyed
    Set mediaicon for item from configfile, media_type and greyed value
    If greyed="available" 
	Set startlink and endlink HTML
    Else
	Set startlink and endlink HTML to ""
If type="pagelink"
    If item{location} is like "*response=$1"
    	Set pageid=$1
	Get list of lists on page from item table
	Foreach list
	    Set linkid
	    See if there is already an entry in viewitem table using this id
	    If entry doesn't exist
	    	Insert information about link into viewitem table
If type="helpform"
    Set helptext=" "
    If itemid is of form "hf$1" ($1 should be orderby of help topic)
    	Get information about help topic from help table
    Else
    	Set item{helptext}=" "
If type="searchform"
    If CGI parameter itemid (search item) != "search"
    	Get information about item from item table
    If CGI parameter edsource="search"
    	Get information about search from search table
	Set up search text fields
	Get list of editable pages (on which search can be saved) - call
	get_editable_pages routine
	Get parentid of search item from item table
	Set initial pagelist HTML
	Foreach page
	    Append to pagelist HTML with SELECTED OPTION for parent of search
	    item
	Append end of pagelist HTML
    Else
    	Foreach field from list of search field types
	    Set search{field} from CGI parameter field
    For i=1..3
    	Set which fields are SELECTED
	Next if i=1
	Set which operators are SELECTED
    Set default values of fields SELECTED unless some other has been SELECTED
    Call getrdbresourcetypes to get list of resource types
    Foreach type
    	Set resourcelist options with type SELECTED depending on search
	information
    Call getrdbsearchableresources to get list of searchable resources
    If response parameter != "searchresults"
    	Get resources listed in search_resources table for search item
    Else
    	Set resource list to the CGI parameter resource
    Set resourceoptions=""
    Foreach resource
    	Next if resource_id=0 (resource database - see below)
	Call inarray to see if resource is selected in search
	Append appropriate HTML to resourceoptions
    Append appropriate HTML for resource_id 0
Return item data

get_new_itemid routine

Gets an unused itemid for a new item

Input: none
Output: itemid

PDL

Lock lock file (to prevent multiple items being given same ids)
Set item=0
Get list of numeric itemids ordered numerically - as successive values of
tempitem
While tempitem
    Increment item
    Set lastitem=tempitem
    Last if item != tempitem
If item=lastitem
    Increment item (prevent end of loop error where run out of numbers before
    find a gap)
Close lock file
Return item

get_posno

Gets the next position number for a child in a particular location

Input: item id (of parent), location
Output: position number

PDL

Lock lock file (to prevent multiple items being given the same position)
Set posno=0
Get positionnos from item table - as successive values of posnotemp
While posnotemp
    Set posno=ponsotemp if posnotemp>posno
Increment posno
Close lock file
Return posno

copy_page

Copys a page and its descendants

Input: startid (page to copy),userid,user email,title (of new page)
Output: id of new page

PDL

Set parents="<".startid.">"
Set parentl{startid}=""
If title=""
    Set title="title"
Else
    Set title="'".title."'"
While parents is of form "<$1>"
    Set parent=$1
    Remove <$1> from parents
    Call get_new_itemid
    Append id to returnid list
    Insert data about new item copying parent into item table
    Insert information into readgroups,editgroups tables
    Set title="title"
    Get children of parent from item table
    Foreach child
        Append "<".child.">" to parents
	Set parentl{child}=parent
Return returnid[0]

createlist routine

Creates new (empty) list items

Input: title, pageid, userid
Output: listid

PDL

Call get_new_itemid to get new listid
Call get_posno to get position for list
Insert list information into item table
Insert list information into readgroups/editgroups tables
Return listid

recdel routine

Recursively deletes an item and its descendants from both item and viewitem
tables (contains unused variable parentl)

Input: startid
Output: none

PDL

Set parents="<".startid.">"
While parents is of form "<$1>"
    Set parent=$1
    Remove <$1> from parents
    Delete parent from item/viewitem tables
    Delete information about parent from readgroups/editgroups tables
    Get children of parent from item table
    Foreach child
    	Append "<".child.">" to parents
Return

update_page_links routine

Updates the list of page links for a page

Input: type (whether link to other page or current page), page,item,userid,link
information (if link already exists)
Output: None

PDL

If link defined
    If link{type} != type
    	Update viewitem table so link type matches type
Else
    Set itemid for link item
    Set posno for link item = pageid
    Insert information about link into viewitem table
Return

inlist routine

Check whether scalar matches any value in listref of hashes, field itemid

Input: scalar, listref
Output: 1 (true), 0 (false)

PDL

Set test=0
Foreach entry in listref
    Set test=1 if scalar=entry{itemid}
Return test

inarray routine

Check whether scalar matches any value in listref of scalars

Input: scalar, listref
Output: 1 (true), 0 (false)

PDL

Set test=0
Foreach entry in listref
    test=1 if scalar=entry
Return test

get_editable_pages routine

Gets list of pages which can be edited by user other than input pageid

Input: userid, pageid
Output:

PDL

Get list of pages which can be edited by user from item,groups,userdata,
editgroups tables
Return pages

performsearch routine

Carries out search

Input: CGI data
Output: Hashed results list by resource

PDL

Push searchlib directory into @INC
Turn info into hashref to avoid problems with CGI objects when forking
Set resources list from CGI parameter
Set infohash{resources}=reference to resources list
Foreach resource
    Call search_resource_setup (sets locres hash - locres{location} is resource
    corresponding to location)
Require searchfork library
Call start routine
Foreach location (key of locresults hash returned by searchfork)
    Set results{locres{location}}=locresults{location}
Return results hash

getsearchdate routine

Gets the date to put in search table

Input: None
Output: Array with year, month, day entries

PDL

Call localtime to get standard array of time related variables
Fix dates to be more human readable
Return array of date info

update_search routine

Updates information about a saved search when edited

Input: search itemid, CGI data
Output: none

PDL

Set fields to list of search fields
Call getsearchdate to get current date
Update fields in search table with CGI data and current date
Delete existing information from search_resources table
Foreach resource in CGI data
    Insert information about resource into search_resources table
Return

savesearch routine

Saves a search

Input: itemid,parentid,CGI data,userid,search title
Output: none

PDL

If itemid="search"
    Set expanded=1
    Call get_new_itemid to get search itemid
    Call get_posno
    Insert search data into item table
Else
    Set expanded=0
    If new parameter defined
    	Call get_posno
	Insert search data into item table
    Else
    	Update search data in item table
    Delete information about search from viewitem table
If itemid="search" or new parameter defined
    Call getsearchdate to get current date
    Insert search data into search table
    Foreach resource
    	Insert data about resource into search_resources table
Else
    Call update_search routine
Set results by calling performsearch
Set expanded=1-expanded
Foreach resource
    If resource=0 (it is the resource database)
    	Set title="PIE Resource Database"
    Else
    	Set title by calling getrdbtitle
    Call get_new_itemid for list of results for this resource
    Call get_posno
    Insert data about list of results into item table
    Set count=0
    Foreach result (from this resource)
    	Call get_new_itemid
	Call get_posno
	Insert data about result into item table
Return

search_resource_setup routine

Sets up search for resource

Input: resource id (from resource database or 0 for searching resource database)
Output:

PDL

If resource=0
    Set locationlist[0],locres[0]
Else
    Call getrdburl to get location list for resource
    Foreach location
    	Next if location{search_protocol}="none"
	Set locres{location_id}=resource
	Set locationlist{location_id}=search_protocol
Return