Prev		Next

Prev		Next

Prev		Next

Prev		Next

Prev		Next

Prev		Next

Prev	Chapter�12.�Engineering Standards	Next

Prev	Chapter�12.�Engineering Standards	Next

Using Form Builder: building html forms dynamically

Overview

($Id$)

+Using Form Builder: building html forms dynamically

Prev	Chapter�11.�Development Reference	Next

Using Form Builder: building html forms dynamically

Overview

($Id$)

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

OpenACS has a form manager called ad_form. Ad_form has an adaptable UI. Error handling includes inline error reporting, and is customizable. However, ad_form can be tricky to use. In addition to this document, the ad_form api - documentation is helpful.

Multi-part Elements

Some elements have more than one choice, or can submit more than one value.

SELECT elements

Creating the form element.�Populate a list of lists with values for the option list.
```
set foo_options [db_list_of_lists foo_option_list "
+ documentation is helpful.
```

Multi-part Elements

Some elements have more than one choice, or can submit more than one value.

SELECT elements

Creating the form element.�Populate a list of lists with values for the option list.
```
set foo_options [db_list_of_lists foo_option_list "
     select foo,
            foo_id
       from foos
-"]
-
```
The variable foo_options should resemble {{first foo} 1234} {{second foo} 1235} -
Within ad_form, set up the element to use this list:
```
{foo:text(select)
-        {label "Which Foo"}
+"]
+
```
The variable foo_options should resemble {{first foo} 1234} {{second foo} 1235} +
Within ad_form, set up the element to use this list:
```
{foo:text(select)
+        {label "Which Foo"}
         {options $foo_options}
-    }
```
This will result in a single name/value pair coming back in the submitted form. Handle this within the same ad_form structure, in the -new_data and -edit_data. In the example, it is available as $foo

This will result in a single name/value pair coming back in the submitted form. Handle this within the same ad_form structure, in the -new_data and -edit_data. In the example, it is available as $foo

Using refreshes to pull additional information from the - database

A situation you may run into often is where you want to pull + database

A situation you may run into often is where you want to pull in form items from a sub-category when the first category is selected. Ad_form makes this fairly easy to do. In the definition of your form element, include an html section

    {pm_task_id:integer(select),optional
-        {label "Subject"}
+        {label "Subject"}
         {options {$task_options}}
-        {html {onChange "document.form_name.__refreshing_p.value='1';submit()"}}
+        {html {onChange "document.form_name.__refreshing_p.value='1';submit()"}}
         {value $pm_task_id}
     }

What this will do is set the value for pm_task_id and all the @@ -39,17 +38,17 @@ -on_refresh section of your ad_form. In that section, you'll get the values from the database, and set the values as so:

    db_1row get_task_values { }
     template::element set_value form_name estimated_hours_work $estimated_hours_work
-

Troubleshooting

A good way to troubleshoot when you're using ad_form is to +

Troubleshooting

A good way to troubleshoot when you're using ad_form is to add the following code at the top of the .tcl page (thanks Jerry Asher):

 ns_log notice it's my page!
 set mypage [ns_getform]
-if {[string equal "" $mypage]} {
+if {[string equal "" $mypage]} {
     ns_log notice no form was submitted on my page
 } else {
     ns_log notice the following form was submitted on my page
     ns_set print $mypage
 }
-

Tips for form widgets

Here are some tips for dealing with some of the form widgets:

Current widget

Common Errors

Here are some common errors and what to do when you - encounter them:

Error when selecting values

This generally happens when there is an error in your +

Tips for form widgets

Here are some tips for dealing with some of the form widgets:

Current widget

Common Errors

Here are some common errors and what to do when you + encounter them:

Error when selecting values

This generally happens when there is an error in your query.

Prev	Home	Next
Programming with AOLserver	Up	Chapter�12.�Engineering Standards

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/general-documents.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/general-documents.html,v diff -u -r1.22.2.1 -r1.22.2.2 --- openacs-4/packages/acs-core-docs/www/general-documents.html 14 Jan 2007 04:20:10 -0000 1.22.2.1 +++ openacs-4/packages/acs-core-docs/www/general-documents.html 14 Jul 2007 12:34:46 -0000 1.22.2.2 @@ -1,2 +1 @@ - -Chapter�1.�High level information: What is OpenACS?

Prev	Part�I.�OpenACS For Everyone	Next

Chapter�1.�High level information: What is OpenACS?

Table of Contents

Overview
OpenACS Release Notes

Prev	Home	Next
Part�I.�OpenACS For Everyone	Up	Overview

docs@openacs.org

View comments on this page at openacs.org +Chapter�1.�High level information: What is OpenACS?

Prev	Part�I.�OpenACS For Everyone	Next

Chapter�1.�High level information: What is OpenACS?

Table of Contents

Overview
OpenACS Release Notes

Prev	Home	Next
Part�I.�OpenACS For Everyone	Up	Overview

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -r1.27.2.1 -r1.27.2.2 --- openacs-4/packages/acs-core-docs/www/groups-design.html 14 Jan 2007 04:20:10 -0000 1.27.2.1 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 14 Jul 2007 12:34:46 -0000 1.27.2.2 @@ -1,32 +1,31 @@ - -Groups Design

Prev	Chapter�15.�Kernel Documentation	Next

Groups Design

By Rafael H. Schloming and Mark Thomas

+Groups Design

Prev	Chapter�15.�Kernel Documentation	Next

Groups Design

By Rafael H. Schloming and Mark Thomas

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Essentials

User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
OpenACS 4 Groups Requirements
Data model
PL/SQL file
- -community-core-create.sql
- groups-create.sql
ER diagram
Transaction flow diagram

Introduction

Almost all database-backed websites have users, and need to model the +

Essentials

User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
OpenACS 4 Groups Requirements
Data model
PL/SQL file
- +community-core-create.sql
- groups-create.sql
ER diagram
Transaction flow diagram

Introduction

Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services -for different user communities.

Historical Considerations

The primary limitation of the OpenACS 3.x user group system is that it -restricts the application developer to representing a "flat group" -that contains only users: The user_groups table may contain the -group_id of a parent group, but parent-child relationship +for different user communities.

Historical Considerations

The primary limitation of the OpenACS 3.x user group system is that it +restricts the application developer to representing a "flat group" +that contains only users: The user_groups table may contain the +group_id of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships expensive.

In addition, the Module Scoping design in OpenACS 3.0 introduced a party abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of -scope, user_id, and group_id columns +scope, user_id, and group_id columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer -to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption -(e.g., a row with a scope value of "group" but a null -group_id)
perform extra checks in Tcl and PL/SQL -functions and procedures to check both the user_id and -group_id values

Competitive Analysis

...

Design Tradeoffs

The core of the Group Systems data model is quite simple, but it was -designed in the hopes of modeling "real world" organizations which +to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption +(e.g., a row with a scope value of "group" but a null +group_id)
perform extra checks in Tcl and PL/SQL +functions and procedures to check both the user_id and +group_id values

Competitive Analysis

...

Design Tradeoffs

The core of the Group Systems data model is quite simple, but it was +designed in the hopes of modeling "real world" organizations which can be complex graph structures. The Groups System only considers groups that can be modeled using directed acyclic graphs, but queries over these structures are still complex enough to slow the system down. Since almost @@ -38,44 +37,44 @@ without making the system too complex or too slow. The added triggers, views, and tables and will increase storage requirements and the insert and delete times in an effort to speed access time. The limited flexibility (no updates -on membership) trades against the complexity of the code.

Data Model Discussion

The Group System data model consists of the following tables:

parties +on membership) trades against the complexity of the code.

Data Model Discussion

The Group System data model consists of the following tables:

parties: The set of all defined parties: any person, user, or -group must have a corresponding row in this table.
persons +group must have a corresponding row in this table.
persons: The set of all defined persons. To allow easy sorting of persons, the name requirement 30.10 is met by -splitting the person's name into two columns: first_names and -last_name.
users +splitting the person's name into two columns: first_names and +last_name.
users: The set of all registered users; this table includes information about -the user's email address and the user's visits to the site.
user_preferences +the user's email address and the user's visits to the site.
user_preferences -: Preferences for the user.
groups +: Preferences for the user.
groups -: The set of all defined groups.
group_types +: The set of all defined groups.
group_types: When a new type of group is created, this table holds additional -knowledge level attributes for the group and its subtypes.
membership_rels +knowledge level attributes for the group and its subtypes.
membership_rels: The set of direct membership relationships between a group and a -party.
group_member_index +party.
group_member_index -: A mapping of a party P to the groups -{G_i}the party is a member of; this mapping -includes the type of relationship by including the appropriaterel_id -from the membership_rels table.
composition_rels +: A mapping of a party P to the groups +{G_i}the party is a member of; this mapping +includes the type of relationship by including the appropriaterel_id +from the membership_rels table.
composition_rels: The set of direct component relationships between a group and another -group.
group_component_index +group.
group_component_index -: A mapping of a group Gto the set of groups -{G_i} that G is a component of; +; A mapping of a group Gto the set of groups +{G_i} that G is a component of; this mapping includes the type of relationship by including the -appropriaterel_id from the composition_rels table.

New groups are created through the group.new constructor. +appropriaterel_id from the composition_rels table.

New groups are created through the group.new constructor. When a specialized type of group is required, the group type can be extended by an application developer. Membership constraints can be specified at -creation time by passing a parent group to the constructor.

The membership_rels and composition_rels tables indicate +creation time by passing a parent group to the constructor.

The membership_rels and composition_rels tables indicate a group's direct members and direct components; these tables do not provide a record of the members or components that are in the group by virtue of being a member or component of one of the group's component groups. @@ -85,60 +84,60 @@ queries responsive, the data model includes triggers (described in the next paragraph) which watch for changes in membership or composition and update tables that maintain the group party mappings, i.e., -group_member_index and group_component_index. One can think -of these tables as a manually maintained index.

The following triggers keep the group_*_index tables up to -date:

membership_rels_in_tr +group_member_index and group_component_index. One can think +of these tables as a manually maintained index.
The following triggers keep the group_*_index tables up to +date:
membership_rels_in_tr
Is executed when a new group/member relationship is created (an insert on -membership_rels)
membership_rels_del_tr +membership_rels)
membership_rels_del_tr
Is executed when a group/member relationship is deleted (a delete on -membership_rels)
composition_rels_in_tr +membership_rels)
composition_rels_in_tr
Is executed when a new group/component relationship is created (an insert -on composition_rels)
composition_rels_del_tr +on composition_rels)
composition_rels_del_tr
Is executed when a group/component relationship is deleted (a delete on -composition_rels)
The data model provides the following views onto the -group_member_index and group_component_index tables. No -code outside of Groups System should modify the group_*_index -tables.
group_member_map +composition_rels)
The data model provides the following views onto the +group_member_index and group_component_index tables. No +code outside of Groups System should modify the group_*_index +tables.
group_member_map
A mapping of a party to the groups the party is a member of; this mapping -includes the type of relationship by including the appropriaterel_id -from the membership_rels table.
group_approved_member_map +includes the type of relationship by including the appropriaterel_id +from the membership_rels table.
group_approved_member_map
A mapping of a party to the groups the party is an approved member of -(member_state is 'approved'); this mapping includes the type -of relationship by including the appropriaterel_id from the -membership_rels table.
group_distinct_member_map +(member_state is 'approved'); this mapping includes the type +of relationship by including the appropriaterel_id from the +membership_rels table.
group_distinct_member_map
A person may appear in the group member map multiple times, for example, by being a member of two different groups that are both components of a third -group. This view is strictly a mapping of approved members -to groups.
group_component_map +group. This view is strictly a mapping of approved members +to groups.
group_component_map -
A mapping of a group Gto the set of groups -{G_i} group G is a component of; +: A mapping of a group Gto the set of groups +{G_i} group G is a component of; this mapping includes the type of relationship by including the -appropriaterel_id from the composition_rels table.
party_member_map +appropriaterel_id from the composition_rels table.
party_member_map -: A mapping of a party P to the set of parties -{P_i} party P is a member -of.
party_approved_member_map +: A mapping of a party P to the set of parties +{P_i} party P is a member +of.
party_approved_member_map -: A mapping of a party P to the set of parties -{P_i} party P is an -approved member of.

API

A mapping of a party P to the set of parties +{P_i} party P is an +approved member of.

API

The API consists of tables and views and PL/SQL functions. -

Tables and Views

The group_types table is used to create new types of groups.

The group_member_map, group_approved_member_map, -group_distinct_member_map, group_component_map, -party_member_map, and party_approved_member_map views are -used to query group membership and composition.

PL/SQL API

Person

person.new creates a new person and returns the -person_id. The function must be given the full name of the person in -two pieces: first_names and last_name. All other fields are -optional and default to null except for object_type which defaults -to person and creation_date which defaults to sysdate. The +

Tables and Views

The group_types table is used to create new types of groups.

The group_member_map, group_approved_member_map, +group_distinct_member_map, group_component_map, +party_member_map, and party_approved_member_map views are +used to query group membership and composition.

PL/SQL API

Person

person.new creates a new person and returns the +person_id. The function must be given the full name of the person in +two pieces: first_names and last_name. All other fields are +optional and default to null except for object_type which defaults +to person and creation_date which defaults to sysdate. The interface for this function is:

 function person.new (
   person_id          persons.person_id%TYPE,
@@ -151,19 +150,19 @@
   first_names        persons.first_names%TYPE,
   last_name          persons.last_name%TYPE
 ) return persons.person_id%TYPE;
-

person.delete deletes the person whose person_id is +

person.delete deletes the person whose person_id is passed to it. The interface for this procedure is:

 procedure person.delete (
   person_id     persons.person_id%TYPE
 );
-

person.name returns the name of the person whose -person_id is passed to it. The interface for this function is:

person.name returns the name of the person whose +person_id is passed to it. The interface for this function is:

 function person.name (
   person_id     persons.person_id%TYPE
 ) return varchar;
-

User

acs_user.new creates a new user and returns the user_id. +

User

acs_user.new creates a new user and returns the user_id. The function must be given the user's email address and the full name of -the user in two pieces: first_names and last_name. All +the user in two pieces: first_names and last_name. All other fields are optional. The interface for this function is:

 function acs_user.new (
   user_id            users.user_id%TYPE,
@@ -182,19 +181,19 @@
   screen_name        users.screen_name%TYPE,
   email_verified_p   users.email_verified_p%TYPE
 ) return users.user_id%TYPE;
-

acs_user.delete deletes the user whose user_id is passed +

acs_user.delete deletes the user whose user_id is passed to it. The interface for this procedure is:

 procedure acs_user.delete (
   user_id       users.user_id%TYPE
 );
-

acs_user.receives_alerts_p returns 't' if the user should +

acs_user.receives_alerts_p returns 't' if the user should receive email alerts and 'f' otherwise. The interface for this function is:

 function acs_user.receives_alerts_p (
   user_id       users.user_id%TYPE
 ) return varchar;
-

Use the procedures acs_user.approve_email and -acs_user.unapprove_email to specify whether the user's email +

Use the procedures acs_user.approve_email and +acs_user.unapprove_email to specify whether the user's email address is valid. The interface for these procedures are:

 procedure acs_user.approve_email (
   user_id       users.user_id%TYPE
@@ -203,11 +202,11 @@
 procedure acs_user.unapprove_email (
   user_id       users.user_id%TYPE
 );
-

Group

acs_group.new creates a new group and returns the -group_id. All fields are optional and default to null except for -object_type which defaults to 'group', -creation_date which defaults to sysdate, and -group_name which is required. The interface for +

Group

acs_group.new creates a new group and returns the +group_id. All fields are optional and default to null except for +object_type which defaults to 'group', +creation_date which defaults to sysdate, and +group_name which is required. The interface for this function is:

 function acs_group.new (
   group_id           groups.group_id%TYPE,
@@ -219,21 +218,21 @@
   url                parties.url%TYPE,
   group_name         groups.group_name%TYPE
 ) return groups.group_id%TYPE;
-

acs_group.name returns the name of the group whose -group_id is passed to it. The interface for this function is:

acs_group.name returns the name of the group whose +group_id is passed to it. The interface for this function is:

 function acs_group.name (
   group_id      groups.group_id%TYPE
 ) return varchar;
-

acs_group.member_p returns 't' if the specified party is +

acs_group.member_p returns 't' if the specified party is a member of the specified group. Returns 'f' otherwise. The interface for this function is:

 function acs_group.member_p (
   group_id      groups.group_id%TYPE,
   party_id      parties.party_id%TYPE,
 ) return char;
-

Membership Relationship

membership_rel.new creates a new membership relationship type -between two parties and returns the relationship type's rel_id. -All fields are optional and default to null except for rel_type +

Membership Relationship

membership_rel.new creates a new membership relationship type +between two parties and returns the relationship type's rel_id. +All fields are optional and default to null except for rel_type which defaults to membership_rel. The interface for this function is:

 function membership_rel.new (
   rel_id             membership_rels.rel_id%TYPE,
@@ -244,42 +243,42 @@
   creation_user      acs_objects.creation_user%TYPE,
   creation_ip        acs_objects.creation_ip%TYPE,
 ) return membership_rels.rel_id%TYPE;
-

membership_rel.ban sets the member_state of the given -rel_id to 'banned'. The interface for this procedure is:

membership_rel.ban sets the member_state of the given +rel_id to 'banned'. The interface for this procedure is:

 procedure membership_rel.ban (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.approve sets the member_state of the -given rel_id to 'approved'. The interface for this procedure +

membership_rel.approve sets the member_state of the +given rel_id to 'approved'. The interface for this procedure is:

 procedure membership_rel.approve (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.reject sets the member_state of the given -rel_id to 'rejected. The interface for this procedure is:

membership_rel.reject sets the member_state of the given +rel_id to 'rejected. The interface for this procedure is:

 procedure membership_rel.reject (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.unapprove sets the member_state of the -given rel_id to an empty string ''. The interface for this +

membership_rel.unapprove sets the member_state of the +given rel_id to an empty string ''. The interface for this procedure is:

 procedure membership_rel.unapprove (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.deleted sets the member_state of the -given rel_id to 'deleted'. The interface for this procedure +

membership_rel.deleted sets the member_state of the +given rel_id to 'deleted'. The interface for this procedure is:

 procedure membership_rel.deleted (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.delete deletes the given rel_id. The +

membership_rel.delete deletes the given rel_id. The interface for this procedure is:

 procedure membership_rel.delete (
   rel_id           membership_rels.rel_id%TYPE
 );
-

Composition Relationship

composition_rel.new creates a new composition relationship type -and returns the relationship's rel_id. All fields are optional -and default to null except for rel_type which defaults to +

Composition Relationship

composition_rel.new creates a new composition relationship type +and returns the relationship's rel_id. All fields are optional +and default to null except for rel_type which defaults to composition_rel. The interface for this function is:

 function membership_rel.new (
   rel_id             composition_rels.rel_id%TYPE,
@@ -289,18 +288,18 @@
   creation_user      acs_objects.creation_user%TYPE,
   creation_ip        acs_objects.creation_ip%TYPE,
 ) return composition_rels.rel_id%TYPE;
-

composition_rel.delete deletes the given rel_id. The +

composition_rel.delete deletes the given rel_id. The interface for this procedure is:

 procedure membership_rel.delete (
   rel_id           composition_rels.rel_id%TYPE
 );
-

User Interface

Describe the admin pages.

Configuration/Parameters

...

Acceptance Tests

...

Future Improvements/Areas of Likely Change

...

Authors

System creator +

User Interface

Describe the admin pages.

Configuration/Parameters

...

Acceptance Tests

...

Future Improvements/Areas of Likely Change

...

Authors

System creator: Rafael H. Schloming
System owner: Rafael H. Schloming
Documentation author -: Mark Thomas

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 08/22/2000 Rafael H. Schloming

0.2

Initial Revision

08/30/2000

Mark Thomas

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 08/22/2000 Rafael H. Schloming

0.2 Initial Revision 08/30/2000 Mark Thomas

0.3

Additional revisions; tried to clarify membership/compostion

09/08/2000

Mark Thomas Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -r1.27.2.1 -r1.27.2.2 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 14 Jan 2007 04:20:10 -0000 1.27.2.1 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 14 Jul 2007 12:34:46 -0000 1.27.2.2 @@ -1,60 +1,59 @@ - -Groups Requirements

Prev	Chapter�15.�Kernel Documentation	Next

Groups Requirements

By Rafael H. Schloming, Mark Thomas

+Groups Requirements

Prev	Chapter�15.�Kernel Documentation	Next

Groups Requirements

By Rafael H. Schloming, Mark Thomas

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Introduction

Almost all database-backed websites have users, and need to model the +

Introduction

Vision Statement

A powerful web service that can meet the needs of large enterprises must + for different user communities.

Vision Statement

A powerful web service that can meet the needs of large enterprises must be able to model the the real world's very rich organizational structures and many ways of decomposing the same organization. For example, a corporation can be broken into structures (the corporation, its divisions, and their departments) or regions (the Boston office, the LA office); a person who is employed by (is a member of) a specific department is also a member of the division and the corporation, and works at (is a member of, but in a different sense) a particular office. OpenACS's Parties and Groups - system will support such complex relations faithfully.

Historical Motivations

The primary limitation of the OpenACS 3.x user group system is that it - restricts the application developer to representing a "flat group" - that contains only users: The user_groups table may contain the - group_id of a parent group, but parent-child relationship + system will support such complex relations faithfully.

Historical Motivations

The primary limitation of the OpenACS 3.x user group system is that it + restricts the application developer to representing a "flat group" + that contains only users: The user_groups table may contain the + group_id of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships expensive.

In addition, the Module Scoping design in OpenACS 3.0 introduced a party abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of - scope, user_id, and group_id columns + scope, user_id, and group_id columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer - to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption - (e.g., a row with a scope value of "group" but a null - group_id)
perform extra checks in Tcl and PL/SQL - functions and procedures to check both the user_id and - group_id values

In sum, the goal of the Parties and Groups system is to + to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption + (e.g., a row with a scope value of "group" but a null + group_id)
perform extra checks in Tcl and PL/SQL + functions and procedures to check both the user_id and + group_id values

In sum, the goal of the Parties and Groups system is to provide OpenACS programmers and site administrators with simple tools that fully describe the complex relationships that exist among groups in the real - world.

User Scenarios

Pat Developer has a client project and wants to model the company, its + world.

User Scenarios

Pat Developer has a client project and wants to model the company, its offices, its divisions, and its departments as groups and the employees as - users.

System Overview

We start with Groups, which contain members; the - member can be either a person or another group (i.e. a + users.

System Overview

We start with Groups, which contain members; the + member can be either a person or another group (i.e. a member is a party).

In addition to membership, the party and groups system defines a - composition relationship that may exist between groups: A - group can be a component of another group. The child group + composition relationship that may exist between groups: A + group can be a component of another group. The child group is called a component group; the parent group is called a - composite group.

A group G_c can be a member and/or a component - of another group G_p; the difference is in the way - the members of G_c are related to - G_p:

If a party P is a member (or a component) of - G_c and if G_c is a - component of G_p, then P is also - a member (or a component) of G_p
If a party P is a member (or a component) of - G_c and if G_c is a - member of G_p, then no - relationship between P and - G_p exists as a result of the relationship between - G_p and G_p.

Consider an example to make this less abstract: Pretend that the Sierra + composite group.

A group G_c can be a member and/or a component + of another group G_p; the difference is in the way + the members of G_c are related to + G_p:

If a party P is a member (or a component) of + G_c and if G_c is a + component of G_p, then P is also + a member (or a component) of G_p
If a party P is a member (or a component) of + G_c and if G_c is a + member of G_p, then no + relationship between P and + G_p exists as a result of the relationship between + G_p and G_p.

Consider an example to make this less abstract: Pretend that the Sierra Club is a member of Greenpeace. The Sierra Club has chapters; each chapter is a component of the Sierra Club. If Eddie Environmentalist is a member of the Massachusetts Chapter of the Sierra Club, Eddie is @@ -67,158 +66,158 @@ Massachusetts chapter), and between the Sierra Club and Greenpeace.

Membership requirements can vary from group to group. The parties and groups system must provide a base type that specifies the bare minimum necessary to join a group.

The parties and groups system must support constraints between a composite - group G_P and any of its component groups, - G_C. For example, the system should be able to - enforce a rule like: Do not allow a party P to become a - member of G_C unless P is already - a member of G_P.

Requirements: Data Model

The data model for the parties and groups system must provide support for - the following types of entities:

10.0 Parties + group G_P and any of its component groups, + G_C. For example, the system should be able to + enforce a rule like: Do not allow a party P to become a + member of G_C unless P is already + a member of G_P.

Requirements: Data Model

The data model for the parties and groups system must provide support for + the following types of entities:

10.0 Parties -

A party is an entity used to represent either a - group or a person.

The data model should enforce these constraints:

10.10 A party has an email address, which can be - empty.

10.20 A party may have multiple email addresses - associated with it.

10.30 The email address of a party must be unique within - an OpenACS system.

20.0 Groups +

A party is an entity used to represent either a + group or a person.

The data model should enforce these constraints:

10.10 A party has an email address, which can be + empty.

10.20 A party may have multiple email addresses + associated with it.

10.30 The email address of a party must be unique within + an OpenACS system.

20.0 Groups -

A group is a collection of zero or more parties.

20.10 The data model should support the subclassing of - groups via OpenACS Objects.

30.0 Persons +

A group is a collection of zero or more parties.

20.10 The data model should support the subclassing of + groups via OpenACS Objects.

30.0 Persons -

A person represents an actual human being, past or - present.

30.10. A person must have - an associated name.

40.0 Users +

A person represents an actual human being, past or + present.

30.10. A person must have + an associated name.

40.0 Users -

A user is a person who has registered with an OpenACS site. A - user may have additional attributes, such as a screen name.

The data model should enforce these constraints:

40.10 A user must have a non-empty email address.

40.20 Two different users may not have the same email +

A user is a person who has registered with an OpenACS site. A + user may have additional attributes, such as a screen name.

The data model should enforce these constraints:

40.10 A user must have a non-empty email address.

40.20 Two different users may not have the same email address on a single OpenACS installation; i.e., an email address identifies a - single user on the system.

40.30 A user may have multiple email addresses; for - example, two or more email addresses may identify a single user.

40.40 A user must have password field which can be + single user on the system.

40.30 A user may have multiple email addresses; for + example, two or more email addresses may identify a single user.

40.40 A user must have password field which can be empty.

The data model for the parties and groups system must provide support for - the following types of relationships between entities:

50.0 Membership + the following types of relationships between entities:
50.0 Membership
- A party P is considered a member of a - group G
when a direct membership relationship exists between P - and G
or when there exists a direct membership relationship between - P and some group G_C and - G_C has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple + A party P is considered a member of a + group G
when a direct membership relationship exists between P + and G
or when there exists a direct membership relationship between + P and some group G_C and + G_C has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple times only when all the memberships have different types; for example, Jane may be a member of The Company by being both an Employee and an - Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership - constraints.
50.50The data model should support the subclassing of + Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership + constraints.
50.50The data model should support the subclassing of membership via OpenACS Relationships.
- 60.0 Composition -
A group G_C is considered a - component of a second group - G_P
when a direct composition relationship exists between - G_C and G_P
or when there exists a direct composition relationship between - G_C and some group G_i - and G_i has a composition relationship with - G_P.
60.10A group may be a component of multiple groups.
60.20A group as a component of itself is not - supported.
60.30The data model must support component - constraints.
60.40The data model should support the subclassing of - composition via OpenACS Relationships.

Requirements: API

The API should let programmers accomplish the following tasks:

70.10 Create a group + 60.0 Composition +

A group G_C is considered a + component of a second group + G_P

when a direct composition relationship exists between + G_C and G_P
or when there exists a direct composition relationship between + G_C and some group G_i + and G_i has a composition relationship with + G_P.

60.10A group may be a component of multiple groups.

60.20A group as a component of itself is not + supported.

60.30The data model must support component + constraints.

60.40The data model should support the subclassing of + composition via OpenACS Relationships.

Requirements: API

The API should let programmers accomplish the following tasks:

70.10 Create a group

The parties and groups system provides a well defined API call that creates a new group by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.

70.20 Create a person + in the data model.

70.20 Create a person

The parties and groups system provides a well defined API call that creates a new person by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.

70.30 Create a user + in the data model.

70.30 Create a user

The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out in - the data model.

80.10 Refine a person to a user + the data model.

80.10 Refine a person to a user

The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on an existing person entity. This API is subject to the constraints laid out in the data - model.

80.30 Demote a user to a person + model.

80.30 Demote a user to a person

The parties and groups system provides a well defined API call that demotes an existing user entity to a person entity by running the appropriate transactions on the existing user. This API is subject to the constraints - laid out in the data model.

90.10 Update a party + laid out in the data model.

90.10 Update a party

The programmer should be able to modify, add, and delete attributes on any - party. This API is subject to the constraints laid out in the data model.

95.10 Get the attributes of a party + party. This API is subject to the constraints laid out in the data model.

95.10 Get the attributes of a party

The programmer should be able to view the attributes on any party. This - API is subject to the constraints laid out in the data model.

100.10 Delete a party + API is subject to the constraints laid out in the data model.

100.10 Delete a party

The system provides an API for deleting a party. This API is subject to - the constraints laid out in the data model.

100.30 The system may provide a single API call to remove - the party from all groups and then delete the party.

100.40 In the case of a group, the system may provide a + the constraints laid out in the data model.

100.30 The system may provide a single API call to remove + the party from all groups and then delete the party.

100.40 In the case of a group, the system may provide a single API call to remove all parties from a group and then delete the - group.

110.0 Add a party as a member of a group + group.

110.0 Add a party as a member of a group

The parties and groups system provides an API for adding a party as a member of a group. This API is subject to the constraints laid out in the - data model.

115.0 Add a group as a component of a second group + data model.

115.0 Add a group as a component of a second group

The parties and groups system provides an API for adding a group as a component of a second group. This API is subject to the constraints laid out - in the data model.

120.0 Remove a party as a member of a group + in the data model.

120.0 Remove a party as a member of a group

The parties and groups system provides an API for deleting a party's membership in a group. This API is subject to the constraints laid out in the - data model.

125.0 Remove a group as a component of a second - group + data model.

125.0 Remove a group as a component of a second + group

The parties and groups system provides an API for deleting a group's composition in a second group. This API is subject to the constraints laid - out in the data model.

130.0 Membership check + out in the data model.

130.0 Membership check

The parties and groups system provides an API for answering the question: - "Is party P a member of group - G?"

135.0 Composition check + "Is party P a member of group + G?"

135.0 Composition check

The parties and groups system provides an API for answering the question: - "Is group G_C a component of group - G_P?"

140.0 Get members query + "Is group G_C a component of group + G_P?"

140.0 Get members query

The parties and groups system provides an API for answering the question: - "Which parties are members of group G?"

145.0 Get components query + "Which parties are members of group G?"

145.0 Get components query

The parties and groups system provides an API for answering the question: - "Which groups are components of group G?"

150.0 Member-of-groups query + "Which groups are components of group G?"

150.0 Member-of-groups query

The parties and groups system provides an API for answering the question: - "Of which groups is party P a member?"

155.0 Component-of-groups query + "Of which groups is party P a member?"

155.0 Component-of-groups query

The parties and groups system provides an API for answering the question: - "Of which groups is group G a component?"

160.0 Allowed membership check + "Of which groups is group G a component?"

160.0 Allowed membership check

The parties and groups system provides an API for answering the question: - "Is party P allowed to become a member of group - G?"

165.0 Allowed composition check + "Is party P allowed to become a member of group + G?"

165.0 Allowed composition check

The parties and groups system provides an API for answering the question: - "Is group G_C allowed to become a component - of group G_P?"

170.0 Efficiency + "Is group G_C allowed to become a component + of group G_P?"

170.0 Efficiency

Since many pages at a site may check membership in a group before serving a page (e.g., as part of a general permissions check), the data model must support the efficient storage and retrieval of party attributes and - membership.

180.0 Ease of Use + membership.

180.0 Ease of Use

Since many SQL queries will check membership in a group as part of the - where clause, whatever mechanism is used to check membership in SQL - should be fairly small and simple.

Requirements: User Interface

The user interface is a set of HTML pages that are used to drive the - underlying API. The user interface may provide the following functions:

200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks - outlined in 130.x to 165.x

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

Prev	Home	Next
Permissions Design	Up	Groups Design

docs@openacs.org

View comments on this page at openacs.org + where clause, whatever mechanism is used to check membership in SQL + should be fairly small and simple.

Requirements: User Interface

The user interface is a set of HTML pages that are used to drive the + underlying API. The user interface may provide the following functions:

200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks + outlined in 130.x to 165.x

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

Prev	Home	Next
Permissions Design	Up	Groups Design

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/high-avail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.html,v diff -u -r1.17.2.2 -r1.17.2.3 --- openacs-4/packages/acs-core-docs/www/high-avail.html 22 Apr 2007 10:21:55 -0000 1.17.2.2 +++ openacs-4/packages/acs-core-docs/www/high-avail.html 14 Jul 2007 12:34:47 -0000 1.17.2.3 @@ -1,2 +1 @@ - -High Availability/High Performance Configurations

Prev	Chapter�6.�Production Environments	Next

High Availability/High Performance Configurations

Figure�6.1.�Multiple-server configuration

Prev	Home	Next
Running multiple services on one machine	Up	Staged Deployment for Production Networks

docs@openacs.org

View comments on this page at openacs.org +High Availability/High Performance Configurations

Prev	Chapter�6.�Production Environments	Next

High Availability/High Performance Configurations

Figure�6.1.�Multiple-server configuration

Prev	Home	Next
Running multiple services on one machine	Up	Staged Deployment for Production Networks

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/how-do-I.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.html,v diff -u -r1.20.2.2 -r1.20.2.3 --- openacs-4/packages/acs-core-docs/www/how-do-I.html 22 Apr 2007 10:21:55 -0000 1.20.2.2 +++ openacs-4/packages/acs-core-docs/www/how-do-I.html 14 Jul 2007 12:34:47 -0000 1.20.2.3 @@ -1,7 +1,6 @@ - -How Do I?

Prev	Chapter�4.�Configuring a new OpenACS Site	Next

How Do I?

How do I edit the front page of a new site through a web interface?

The easiest way is to install the Edit-This-Page package.

Log in to the web site as an administrator.
Click on Admin > Install Software > Install from OpenACS Repository / Install new application
Choose Edit This Page and install
Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).

How do I let anybody who registers post to a weblog?

Go to /admin/permissions and grant Create to Registered Users

How do I replace the front page of a new site with the front page of an application on that site

Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.

On the front page, click the Admin button.
On the administration page, click Parameters link.
Change the parameter IndexRedirectUrl to be the URI of the desired application. For a default weblogger installation, this would be weblogger/. Note the trailing slash.

How do I put custom functionality on front page of a new site?

Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:

cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www

Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.

How do I change the site-wide style?

Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:

+How Do I?
Prev Chapter�4.�Configuring a new OpenACS Site Next
How Do I?
How do I edit the front page of a new site through a web interface?
The easiest way is to install the Edit-This-Page package.
1. Log in to the web site as an administrator.
2. Click on Admin > Install Software > Install from OpenACS Repository / Install new application
3. Choose Edit This Page and install
4. Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).
How do I let anybody who registers post to a weblog?
Go to /admin/permissions and grant Create to Registered Users
How do I replace the front page of a new site with the front page of an application on that site
Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.
1. On the front page, click the Admin button.
2. On the administration page, click Parameters link.
3. Change the parameter IndexRedirectUrl to be the URI of the desired application. For a default weblogger installation, this would be weblogger/. Note the trailing slash.
How do I put custom functionality on front page of a new site?
Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
1. cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www
2. Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
How do I change the site-wide style?
Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:
- A templated page uses an ADP/TCL pair. The first line in the ADP file is usually: -
 <master>
 If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite. For pages in /var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file. -
- The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)
- The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).
- Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.
Figure�4.1.�Site Templates
How do I diagnose a permissions problem?
- Steps to Reproduce.�The events package does not allow users to register for new events.
 Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.
 Select an available event
 A link such as Registration: Deadline is 03/15/2004 10:00am. -� Login or sign up to register for this event. is visible. Click on "Login or sign up" -
 Complete a new registration. Afterwards, you should be redirected back to the same page.
 Actual Results: The page says "You do not have permission to register for this event."
 Expected results: A link or form to sign up for the event is shown.
- Finding the problem.�We start with the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl. It contains this line:
 set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
 We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply
 return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
 This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
- Setting Permissions.�A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
 To grant permissions on a package, start at the site map. Find the event package and click "Set permissions".
 Click "Grant Permission"
 Grant the write permission to Registered Users.
 Figure�4.2.�Granting Permissions
 OpenACS 5.0 offers a prettier version at /admin/applications.
 Figure�4.3.�Granting Permissions in 5.0
Prev Home Next
Setting Permissions on an OpenACS package Up Chapter�5.�Upgrading
docs@openacs.org
View comments on this page at openacs.org +
```
<master>
```
If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite. For pages in /var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file. +
The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)
The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).
Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.

Figure�4.1.�Site Templates

How do I diagnose a permissions problem?

Steps to Reproduce.�The events package does not allow users to register for new events.
1. Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.
2. Select an available event
3. A link such as Registration: Deadline is 03/15/2004 10:00am. +� Login or sign up to register for this event. is visible. Click on "Login or sign up" +
4. Complete a new registration. Afterwards, you should be redirected back to the same page.
Actual Results: The page says "You do not have permission to register for this event."
Expected results: A link or form to sign up for the event is shown.
Finding the problem.�We start with the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl. It contains this line:
```
set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
```
We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply
```
return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
```
This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
Setting Permissions.�A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
1. To grant permissions on a package, start at the site map. Find the event package and click "Set permissions".
2. Click "Grant Permission"
3. Grant the write permission to Registered Users.
  Figure�4.2.�Granting Permissions
OpenACS 5.0 offers a prettier version at /admin/applications.
Figure�4.3.�Granting Permissions in 5.0

Prev	Home	Next
Setting Permissions on an OpenACS package	Up	Chapter�5.�Upgrading

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-convert.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.html,v diff -u -r1.19.2.2 -r1.19.2.3 --- openacs-4/packages/acs-core-docs/www/i18n-convert.html 22 Apr 2007 10:21:55 -0000 1.19.2.2 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.html 14 Jul 2007 12:34:47 -0000 1.19.2.3 @@ -1,5 +1,4 @@ - -How to Internationalize a Package

Prev	Chapter�14.�Internationalization	Next

How to Internationalize a Package

Tip

+How to Internationalize a Package

Prev	Chapter�14.�Internationalization	Next

How to Internationalize a Package

Tip

For multilingual websites we recommend using the UTF8 charset. In order for AOLserver to use utf8 you need to set the config parameters OutputCharset and @@ -9,23 +8,23 @@ variable set to .UTF8. You should set this variable in the nsd-oracle run script (use the acs-core-docs/www/files/nds-oracle.txt template file). -

Replace all text with temporary message tags.�From/acs-admin/apm/, select a +

Replace all text with temporary message tags.�From/acs-admin/apm/, select a package and then click on - Internationalization, then - Convert ADP, Tcl, and SQL files to using the - message catalog.. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.
You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key.
Replace the temporary message tags in ADP files.�From the same Convert ADP ... page in /acs-admin/apm as in the last step, repeat the process but deselect Find human language text ... and select Replace <# ... #> tags ... and click OK. This step replaces all of the temporary tags with "short" message lookups, inserts the message keys into the database message catalog, and then writes that catalog out to an xml file.

Replace human-readable text in TCL files with temporary tags.�Examine all of the tcl files in the packages for human-readable text and replace it with temporary tags. The temporary tags in TCL are slightly different from those in ADP. If the first character in the temporary tag is an underscore (_), then the message keys will be auto-generated from the original message text. Here is an unmodified tcl file:

-set title "Messages for $a(name) in $b(label)" -set context [list [list . "SimPlay"] \ + Internationalization, then + Convert ADP, Tcl, and SQL files to using the + message catalog.. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.

You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key.

Replace the temporary message tags in ADP files.�From the same Convert ADP ... page in /acs-admin/apm as in the last step, repeat the process but deselect Find human language text ... and select Replace <# ... #> tags ... and click OK. This step replaces all of the temporary tags with "short" message lookups, inserts the message keys into the database message catalog, and then writes that catalog out to an xml file.
Replace human-readable text in TCL files with temporary tags.�Examine all of the tcl files in the packages for human-readable text and replace it with temporary tags. The temporary tags in TCL are slightly different from those in ADP. If the first character in the temporary tag is an underscore (_), then the message keys will be auto-generated from the original message text. Here is an unmodified tcl file:
```
+set title "Messages for $a(name) in $b(label)"
+set context [list [list . "SimPlay"] \
 [list [export_vars -base case-admin { case_id }] \ 
- "Administer $a(name)"] \
- "Messages for $a(name)"]
+ "Administer $a(name)"] \
+ "Messages for $a(name)"]
 
```
... and here is the same file after temporary message tags have been manually added:
```
 set title <#admin_title Messages for %a.name% in %b.label%#>
 set context [list [list . <#_ SimPlay#>] \
 [list [export_vars -base case-admin { case_id }] \
 <#_ Administer %a.name%#>] \
 <#_ Messages for %a.name%#>]
-
```
Note that the message key case_admin_page_title was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing +
Note that the message key case_admin_page_title was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing

Replace the temporary message tags in TCL files.�Repeat step 2 for tcl files. Here is the example TCL file after conversion:

 set title [_ simulation.admin_title]
 set context [list [list . [_ simulation.SimPlay]] \
@@ -34,12 +33,12 @@
                   [_ simulation.lt_Messages_for_role_pre]]

Internationalize SQL Code.�If there is any user-visible TCL code in the .sql or .xql files, internationalize that the same way as for the TCL files.
Internationalize Package Parameters.� See Multilingual APM Parameters -
Internationalize Date and Time queries.�
1. Find datetime in .xql files. Use command line tools to find suspect SQL code:
```
grep -r "to_char.*H" *
-grep -r "to_date.*H" *
-
```
2. In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
```
to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
```
 becomes
```
to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
```
3. In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
```
-set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
```
 When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. -
4. When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
```
set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
```
 - Use the _pretty version in your ADP page. +
5. Internationalize Date and Time queries.�
 1. Find datetime in .xql files. Use command line tools to find suspect SQL code:
 grep -r "to_char.*H" * +grep -r "to_date.*H" * +
 2. In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
 to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
 becomes
 to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
 3. In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
 +set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
 When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. +
 4. When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
 set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
 + Use the _pretty version in your ADP page.
 %c: Long date and time (Mon November 18, 2002 12:00 AM)
 @@ -51,10 +50,10 @@
 %Q: Long date with weekday (Monday November 18, 2002)
 - The "q" format strings are OpenACS additions; the rest follow unix standards (see man - strftime). + The "q" format strings are OpenACS additions; the rest follow unix standards (see man + strftime).
6. Internationalize Numbers.� - To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale. + To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale.
7. Internationalizing Forms.�When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
8. Checking the Consistency of Catalog Files.� This section describes how to check that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in @@ -64,23 +63,23 @@ are always is done with one of the valid lookups described above. The script further assumes that you have perl installed and in your path. Run the script like this: - + acs-lang/bin/check-catalog.sh package_key -+
 where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks primarily on en_US xml catalog files. -
Avoiding common i18n mistakes
- Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.
 The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:
```
 Invitations are sent,
- when this wizard is completed and casting begins.
```
 has a bold tag which confuses the converter into thinking there are two message keys for the text beginning "Invitations ..." where there should be one:
 Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:
```
 <#Invitations_are_sent Invitations are sent, 
+ 
```

Avoiding common i18n mistakes

Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.

The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:

  <p class="form-help-text"><b>Invitations</b> are sent,
+          when this wizard is completed and casting begins.</p>

has a bold tag which confuses the converter into thinking there are two message keys for the text beginning "Invitations ..." where there should be one:

Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:

  <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, 
 when this wizard is completed and casting begins.#>
-  </p>

Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:

Select which case <if @simulation.casting_type@ eq "open">and
+  </p>

Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:

Select which case <if @simulation.casting_type@ eq "open">and
 role</if> to join, or create a new case for yourself.  If you do not
-select a case <if @simulation.casting_type@ eq "open">and role</if>
+select a case <if @simulation.casting_type@ eq "open">and role</if>
 to join, you will be automatically assigned to a case <if
-@simulation.casting_type@ eq "open">and role</if> when the
-simulation begins.

... can be rewritten:

<if @simulation.casting_type@ eq "open">
+@simulation.casting_type@ eq "open">and role</if> when the
+simulation begins.

... can be rewritten:

<if @simulation.casting_type@ eq "open">
 
 Select which case and role to join, or create a new case for
 yourself.  If you do not select a case and role to join, you will
@@ -96,7 +95,7 @@
 begins.
 
 </else>

Another example, where bugs are concatenated with a number:

<if @components.view_bugs_url@ not nil>
-  <a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component">
+  <a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component">
   </if>
   @components.num_bugs@ 
   <if @components.num_bugs@ eq 1>
@@ -110,7 +109,7 @@
   </if>
 
 <if @components.view_bugs_url@ not nil>
-<a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">
+<a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">
 </if>
 @components.num_bugs@ 
 <if @components.num_bugs@ eq 1>
@@ -124,39 +123,39 @@
 </if>

It would probably be better to do this as something like:

<if @components.view_bugs_url@ not nil>
   <if @components.num_bugs@ eq 1>
-    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a>
+    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a>
   </if><else>
-    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a>
+    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a>
   </else>
-</if>

Don't combine keys in display text.�Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:
Original code:
```
multirow append links "New [bug_tracker::conn Bug]" 
```
Problematic conversion:
```
multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"
```
Better conversion:
```
set bug_label [bug_tracker::conn Bug]
-multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"
```
... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.
In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):
```
<a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@">
+</if>
```
Don't combine keys in display text.�Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:
Original code:
```
multirow append links "New [bug_tracker::conn Bug]" 
```
Problematic conversion:
```
multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"
```
Better conversion:
```
set bug_label [bug_tracker::conn Bug]
+multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"
```
... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.
In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):
```
<a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@">
 @past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a>
```
Avoid unnecessary duplicate keys.�When phrases are exactly the same in several places, use a single key.
For common words such as Yes and No, you can use a library of keys at acs-kernel. For example, instead of using - myfirstpackage.Yes, you - can use acs-kernel.Yes. + myfirstpackage.Yes, you + can use acs-kernel.Yes. You can also use the Message Key Search facility to find duplicates. Be careful, however, building up sentences from keys because grammar and other elements may not be consistent across different locales.
Additional discussion: Re: - Bug 961 ("Control Panel" displayed instead of - "Administer"), Translation - server upgraded, and Localization questions.
Don't internationalize internal code words.�Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.
For example, the original code is
```
workflow::case::add_log_data \ 	    
+            Bug 961 ("Control Panel" displayed instead of
+            "Administer"), Translation
+            server upgraded, and Localization questions.
```
Don't internationalize internal code words.�Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.
For example, the original code is
```
workflow::case::add_log_data \ 	    
        -entry_id $entry_id \ 	    
-       -key "resolution" \ 	    
+       -key "resolution" \ 	    
        -value [db_string select_resolution_code {}]
```
This is incorrectly internationalized to
```
  workflow::case::add_log_data \ 	    
        -entry_id $entry_id \
-       -key "[_ bug-tracker.resolution]" \
-       -value [db_string select_resolution_code {}]
```
But resolution is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:
```
{show_patch_status "open"}
```
It is broken if changed to
```
{show_patch_status "[_ bug-tracker.open]"}
```
Fix automatic truncated message keys.�The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:
```
-<msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg>
-<msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch 
+ -key "[_ bug-tracker.resolution]" \
+ -value [db_string select_resolution_code {}]
```
But resolution is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:
```
{show_patch_status "open"}
```
It is broken if changed to
```
{show_patch_status "[_ bug-tracker.open]"}
```
Fix automatic truncated message keys.�The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:
```
+<msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg>
+<msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch 
 and users with write permission on this Bug Tracker project (package instance) may do so.</msg>
-<msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch 
-and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
```
These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? -
Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:
```
<msg key="Fix">for version</msg>
-<msg key="Fix_1">for</msg>
-<msg key="Fix_2">for Bugs</msg>
```
Another example: Bug-tracker component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it should be bug_tracker_component_maintainer.
Translations in Avoid "clever" message reuse.�Translations may need to differ depending on the context in which +<msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch +and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? +
Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:
```
<msg key="Fix">for version</msg>
+<msg key="Fix_1">for</msg>
+<msg key="Fix_2">for Bugs</msg>
```
Another example: Bug-tracker component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it should be bug_tracker_component_maintainer.
Translations in Avoid "clever" message reuse.�Translations may need to differ depending on the context in which the message appears. -
Avoid plurals.�Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.
Quoting in the message catalog for tcl.�Watch out for quoting and escaping when editing text that is also code. For example, the original string
```
set title "Patch \"$patch_summary\" is nice."
```
breaks if the message text retains all of the escaping that was in the tcl command:
```
<msg>Patch \"$patch_summary\" is nice.</msg>
```
When it becomes a key, it should be:
```
<msg>Patch "$patch_summary" is nice.</msg>
```
Also, some keys had %var;noquote%, which is not needed since those +
Avoid plurals.�Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.
Quoting in the message catalog for tcl.�Watch out for quoting and escaping when editing text that is also code. For example, the original string
```
set title "Patch \"$patch_summary\" is nice."
```
breaks if the message text retains all of the escaping that was in the tcl command:
```
<msg>Patch \"$patch_summary\" is nice.</msg>
```
When it becomes a key, it should be:
```
<msg>Patch "$patch_summary" is nice.</msg>
```
Also, some keys had %var;noquote%, which is not needed since those variables are not quoted (and in fact the variable won't even be - recognized so you get the literal %var;noquote% in the output).
Be careful with curly brackets.�Code within curly brackets isn't evaluated. TCL uses curly brackets as an alternative way to build lists. But TCL also uses curly brackets as an alternative to quotation marks for quoting text. So this original code
```
array set names { key "Pretty" ...} 
```
... if converted to
```
array set names { key "[_bug-tracker.Pretty]" ...} 
```
... won't work since the _ func will not be called. Instead, it should be
```
array set names [list key [_bug-tracker.Pretty] ...]
```

Prev	Home	Next
How Internationalization/Localization works in OpenACS	Up	Design Notes

docs@openacs.org

View comments on this page at openacs.org + recognized so you get the literal %var;noquote% in the output).

Be careful with curly brackets.�Code within curly brackets isn't evaluated. TCL uses curly brackets as an alternative way to build lists. But TCL also uses curly brackets as an alternative to quotation marks for quoting text. So this original code

array set names { key "Pretty" ...}

... if converted to

array set names { key "[_bug-tracker.Pretty]" ...}

... won't work since the _ func will not be called. Instead, it should be

array set names [list key [_bug-tracker.Pretty] ...]

Prev	Home	Next
How Internationalization/Localization works in OpenACS	Up	Design Notes

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-design.html,v diff -u -r1.9.2.1 -r1.9.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-design.html 14 Jan 2007 04:20:10 -0000 1.9.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-design.html 14 Jul 2007 12:34:47 -0000 1.9.2.2 @@ -1,3 +1,2 @@ - -Design Notes

Prev	Chapter�14.�Internationalization	Next

Design Notes

User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:

Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (Accept-Language HTTP header)
Use system locale (an APM parameter for acs_lang)
default to en_US

For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is +Design Notes

Prev	Chapter�14.�Internationalization	Next

Design Notes

User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:

Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (Accept-Language HTTP header)
Use system locale (an APM parameter for acs_lang)
default to en_US

Prev	Home	Next
How to Internationalize a Package	Up	Translator's Guide

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-introduction.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-introduction.html,v diff -u -r1.11.2.1 -r1.11.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.html 14 Jan 2007 04:20:10 -0000 1.11.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.html 14 Jul 2007 12:34:47 -0000 1.11.2.2 @@ -1,20 +1,19 @@ - -How Internationalization/Localization works in OpenACS

Prev	Chapter�14.�Internationalization	Next

How Internationalization/Localization works in OpenACS

+How Internationalization/Localization works in OpenACS

Prev	Chapter�14.�Internationalization	Next

How Internationalization/Localization works in OpenACS

This document describes how to develop internationalized OpenACS packages, including writing new packages with internationalization and converting old packages. Text that - users might see is "localizable text"; replacing monolingual text + users might see is "localizable text"; replacing monolingual text and single-locale date/time/money functions with generic - functions is "internationalization"; translating first - generation text into a specific language is "localization." At + functions is "internationalization"; translating first + generation text into a specific language is "localization." At a minimum, all packages should be internationalized. If you do not also localize your package for different locales, volunteers - may use a public "localization server" to submit suggested text. + may use a public "localization server" to submit suggested text. Otherwise, your package will not be usable for all locales.

The main difference between monolingual and internationalized packages is that all user-visible text in the code of an internationalized - package are coded as "message keys." The message keys + package are coded as "message keys." The message keys correspond to a message catalog, which contains versions of the text for each available language. Script files (.adp and .tcl and .vuh), database files (.sql), and APM parameters are affected. @@ -33,33 +32,33 @@ which are static and mostly text, it may be easier to create a new ADP page for each language. In this case, the pages are distinguished by a file naming convention. -

User Content

OpenACS does not have a general system for supporting multiple, localized versions of user-input content. This document currently refers only to internationalizing the text in the package user interface.

Separate Templates for each Locale

If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.

Message Catalogs

Message Keys in Template Files (ADP Files)

User Content

Separate Templates for each Locale

Message Catalogs

Message Keys in Template Files (ADP Files)

Internationalizing templates is about replacing human readable text in a certain language with internal message keys, which can then be dynamically replaced with real human language in the desired locale. Message keys themselves should be in ASCII English, as should all code. Three different syntaxes are possible for message keys.

- "Short" syntax is the recommended syntax and should be used + "Short" syntax is the recommended syntax and should be used for new development. When internationalizing an existing - package, you can use the "temporary" syntax, which the APM can + package, you can use the "temporary" syntax, which the APM can use to auto-generate missing keys and automatically translate - to the short syntax. The "verbose" syntax is useful while + to the short syntax. The "verbose" syntax is useful while developing, because it allows default text so that the page is usable before you have done localization.

- The short: - #package_key.message_key# + The short: + #package_key.message_key#
The advantage of the short syntax is that it's short. It's as simple as inserting the value of a variable. Example: #forum.title#
- The verbose: <trn - key="package_key.message_key" - locale="locale">default - text</trn> + The verbose: <trn + key="package_key.message_key" + locale="locale">default + text</trn>
The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended @@ -68,11 +67,11 @@ in the message catalog yet, because what it'll do is create the message key with the default text from the tag as the localized message. Example: <trn - key="forum.title" locale="en_US">Title</trn> + key="forum.title" locale="en_US">Title</trn>
- The temporary: - <#message_key - original text#> + The temporary: + <#message_key + original text#>
This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that @@ -83,21 +82,21 @@ auto-generated by the APM. Example: <_ Title>

We recommend the short notation for new package development. -

Message Keys in TCL Files

In adp files message lookups are typically done with the syntax - \#package_key.message_key\#. In Tcl + \#package_key.message_key\#. In Tcl files all message lookups *must* be on either of the following formats:

Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
- Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
- Dynamic key lookup: [lang::util::localize $var_with_embedded_message_keys] - In this case the message keys in the variable var_with_embedded_message_keys must appear as string literals \#package_key.message_key\# somewhere in the code. Here is an example of a dynamic lookup: - set message_key_array { +
- Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
- + Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
- + Dynamic key lookup: [lang::util::localize $var_with_embedded_message_keys] - In this case the message keys in the variable var_with_embedded_message_keys must appear as string literals \#package_key.message_key\# somewhere in the code. Here is an example of a dynamic lookup: + set message_key_array { dynamic_key_1 \#package_key.message_key1\# dynamic_key_2 \#package_key.message_key2\# } set my_text [lang::util::localize $message_key_array([get_dynamic_key])] -+
Translatable texts in page TCL scripts are often found in page titles, @@ -106,16 +105,16 @@ that can be used on Linux to highlight translatable text in TCL files:
```
 # Find text in double quotes
-find -iname '*.tcl'|xargs egrep -i '"[a-z]'
+find -iname '*.tcl'|xargs egrep -i '"[a-z]'
 
 # Find untranslated text in form labels, options and values
-find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'
+find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'
 
 # Find text in page titles and context bars
-find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'
+find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'
 
 # Find text in error messages
-find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'
+find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'
 
 
```
You may mark up translatable text in TCL library files and TCL pages @@ -132,74 +131,74 @@ tempoarary message tag (<#_ text_with_percentage_vars#>) and run the action replace tags with keys in the APM.

The variable values in the message are usually fetched with upvar, here is an example from dotlrn: - - ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] - must have no[parameter::get -parameter class_instances_pretty_plural] to be deleted" - + + ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] + must have no[parameter::get -parameter class_instances_pretty_plural] to be deleted" + was replaced by: - + set subject [parameter::get -localize -parameter classes_pretty_name] set class_instances [parameter::get -localize -parameter class_instances_pretty_plural] ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted] -+

This kind of interpolation also works in adp files where adp variable values will be inserted into the message.

Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes:

-set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]
+set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]
 
 ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted $msg_subst_list]
-
+

When we were done going through the tcl files we ran the following commands to check for mistakes:

 # Message tags should usually not be in curly braces since then the message lookup may not be
 # executed then (you can usually replace curly braces with the list command). Find message tags 
 # in curly braces (should return nothing, or possibly a few lines for inspection)
-find -iname '*.tcl'|xargs egrep -i '\{.*<#'
+find -iname '*.tcl'|xargs egrep -i '\{.*<#'
 
 # Check if you've forgotten space between default key and text in message tags (should return nothing)
-find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
+find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
 
 # Review the list of tcl files with no message lookups
-for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done
+for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done

When you feel ready you may vist your package in the package manager - and run the action "Replace tags with keys - and insert into catalog" on the TCL files that you've edited to + and run the action "Replace tags with keys + and insert into catalog" on the TCL files that you've edited to replace the temporary tags with calls to the message lookup procedure. -

Dates, Times, and Numbers in TCL files

Most date, time, and number variables are calculated in TCL files. Dates and times must be converted when stored in the database, when retrieved from the database, and when displayed. All dates are stored in the database in the server's timezone, which is an APM Parameter set at - /acs-lang/admin/set-system-timezone + /acs-lang/admin/set-system-timezone and readable at - lang::system::timezone.. When + lang::system::timezone.. When retrieved from the database and displayed, dates and times must be localized to the user's locale. -

APM Parameters

Some parameters contain text that need to be localized. In this case, instead of storing the real text in the parameter, you should use message keys using the short notation above, - i.e. #package_key.message_key#. + i.e. #package_key.message_key#.

In order to avoid clashes with other uses of the hash character, you need to tell the APM that the parameter value needs to be localized when retrieving it. You do that by saying: - parameter::get -localize. + parameter::get -localize.

Here are a couple of examples. Say we have the following two parameters, taken directly from the dotlrn package.

Parameter Name	Parameter Value
class_instance_pages_csv	#dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column
departments_pretty_name	#departments_pretty_name#

Then, depending on how we retrieve the value, here's what we get: -

Command used to retrieve Value	Retrieved Value
parameter::get -localize -parameter class_instances_pages_csv	Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
parameter::get -localize -parameter departments_pretty_name	Abteilung
parameter::get -parameter departments_pretty_name	#departments_pretty_name#

Command used to retrieve Value	Retrieved Value
parameter::get -localize -parameter class_instances_pages_csv	Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
parameter::get -localize -parameter departments_pretty_name	Abteilung
parameter::get -parameter departments_pretty_name	#departments_pretty_name#

The value in the rightmost column in the table above is the value returned by an invocation of parameter::get. Note that for localization to happen you must use the -localize flag. @@ -209,5 +208,5 @@ locale.

Developers are responsible for creating the keys in the message - catalog, which is available at /acs-lang/admin/ + catalog, which is available at /acs-lang/admin/

Prev	Home	Next
Internationalization and Localization Overview	Up	How to Internationalize a Package

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-overview.html,v diff -u -r1.9.2.1 -r1.9.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-overview.html 14 Jan 2007 04:20:10 -0000 1.9.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-overview.html 14 Jul 2007 12:34:47 -0000 1.9.2.2 @@ -1,2 +1 @@ - -Internationalization and Localization Overview

Prev	Chapter�14.�Internationalization	Next

Internationalization and Localization Overview

Table�14.1.�Internationalization and Localization Overview

Stage	Task	Who
Internationalization	Package Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information)	Package Developer
Release Management	The newly internationalized package is released.	Package Developer
Release Management	The translation server is updated with the new package.	Translation server maintainers
Localization	Translators work in their respective locales to write text for each message key. (More information)	Translators
Release Management	The translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server.	Translation server maintainers
	The catalog files are committed to the OpenACS code base.	Translation server maintainers
	A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.	Release Manager
Upgrading	Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS	Site Administrators
Upgrading	Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.	Site Administrators

Prev	Home	Next
Chapter�14.�Internationalization	Up	How Internationalization/Localization works in OpenACS

docs@openacs.org

View comments on this page at openacs.org +Internationalization and Localization Overview

Prev	Chapter�14.�Internationalization	Next

Internationalization and Localization Overview

Table�14.1.�Internationalization and Localization Overview

Stage	Task	Who
Internationalization	Package Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information)	Package Developer
Release Management	The newly internationalized package is released.	Package Developer
Release Management	The translation server is updated with the new package.	Translation server maintainers
Localization	Translators work in their respective locales to write text for each message key. (More information)	Translators
Release Management	The translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server.	Translation server maintainers
	The catalog files are committed to the OpenACS code base.	Translation server maintainers
	A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.	Release Manager
Upgrading	Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS	Site Administrators
Upgrading	Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.	Site Administrators

Prev	Home	Next
Chapter�14.�Internationalization	Up	How Internationalization/Localization works in OpenACS

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v diff -u -r1.19.2.1 -r1.19.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 14 Jan 2007 04:20:10 -0000 1.19.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 14 Jul 2007 12:34:47 -0000 1.19.2.2 @@ -1,19 +1,18 @@ - -OpenACS Internationalization Requirements

Prev	Chapter�15.�Kernel Documentation	Next

OpenACS Internationalization Requirements

by Henry Minsky, +OpenACS Internationalization Requirements

Prev	Chapter�15.�Kernel Documentation	Next

OpenACS Internationalization Requirements

by Henry Minsky, Yon Feldman, Lars Pind, Peter Marklund, Christian Hvid, and others.

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Introduction

This document describes the requirements for functionality in the OpenACS platform to support globalization of the core and optional modules. The goal is to make it possible to support delivery of applications which work properly in multiple locales with the lowest development and maintenance cost. -

Definitions

internationalization (i18n): +

Definitions

internationalization (i18n): The provision within a computer program of the capability of making itself adaptable to the requirements of different native languages, local customs and coded character sets. @@ -28,7 +27,7 @@ A product development approach which ensures that software products are usable in the worldwide markets through a combination of internationalization and localization. -

Vision Statement

The Mozilla project suggests keeping two catchy phrases in +

Vision Statement

The Mozilla project suggests keeping two catchy phrases in mind when thinking about globalization:

One code base for the world
English is just another language

Building an application often involves making a number of assumptions on the part of the developers which depend on their own culture. These include constant strings in the user interface and @@ -44,7 +43,7 @@ kind of globalization support would be large and ongoing, since without a mechanism to incorporate the locale-specific changes cleanly back into the code base, it would require making a new fork -of the source code for each locale.

System/Application Overview

A globalized application will perform some or all of the +of the source code for each locale.

System/Application Overview

A globalized application will perform some or all of the following steps to handle a page request for a specific locale:

Decide what the target locale is for an incoming page request
Decide which character set encoding the output should be @@ -69,7 +68,7 @@ Java which we will want to move to. So the design to meet the requirements will tend to rely on these capabilities, or close approximations to them where possible, in order to make it easier -to maintain Tcl and Java OpenACS versions.

Use-cases and User-scenarios

Here are the cases that we need to be able to handle +to maintain Tcl and Java OpenACS versions.

Use-cases and User-scenarios

Here are the cases that we need to be able to handle efficiently:

A developer needs to author a web site/application in a language besides English, and possibly a character set besides ISO-8859-1. This includes the operation of the OpenACS itself, i.e., @@ -91,9 +90,9 @@ resources such as message catalogs, non-text assets such as graphics, and use of templates which help to separate application logic from presentation.

Competitive -Analysis

Other application servers: ATG Dyanmo, Broadvision, Vignette, +Analysis

Other application servers: ATG Dyanmo, Broadvision, Vignette, ... ? Anyone know how they deal with i18n ?

Related -Links

System/Package "coversheet" - where all +Links

System/Package "coversheet" - where all documentation for this software is linked off of
Design document
Developer's guide
User's guide
Other-cool-system-related-to-this-one document
LI18NUX 2000 Globalization Specification: @@ -105,10 +104,10 @@ Codes for the representation of names of countries and their subdivisions Part 1: Country codes http://www.niso.org/3166.html
IANA -Registry of Character Sets
Test plan
Competitive system(s)

Requirements

Because the requirements for globalization affect many areas +Registry of Character Sets

Test plan

Competitive system(s)

Requirements

Because the requirements for globalization affect many areas of the system, we will break up the requirements into phases, with a base required set of features, and then stages of increasing -functionality.

Locales

10.0

A standard representation of locale will be used throughout +functionality.

Locales

10.0

A standard representation of locale will be used throughout the system. A locale refers to a language and territory, and is uniquely identified by a combination of ISO language and ISO country abbreviations.

See @@ -118,19 +117,19 @@ locale-aware formatting and parsing functions for numbers, dates and times. Note that Java has builtin support for these already.
10.30 For each locale there will be -default date, number and currency formats. Currency i18n is -NOT IMPLEMENTED for 5.0.0.
10.40Administrators can upgrade their -servers to use new locales via the APM. NOT IMPLEMENTED in +default date, number and currency formats. Currency i18n is +NOT IMPLEMENTED for 5.0.0.
10.40Administrators can upgrade their +servers to use new locales via the APM. NOT IMPLEMENTED in 5.0.0; current workaround is to get an xml file and load it -manually.

Associating a Locale with a Request

20.0

The request processor must have a mechanism for associating a +manually.

Associating a Locale with a Request

20.0

The request processor must have a mechanism for associating a locale with each request. This locale is then used to select the appropriate template for a request, and will also be passed as the locale argument to the message catalog or locale-specific formatting functions.

20.10 The locale for a request should be computed by the following method, in descending order of priority:
get locale associated with subsite or package id
get locale from user preference
get locale from site wide default
20.20 An API will be provided for getting the current request locale from the -ad_conn structure.

Resource Bundles / Content Repository

30.0

A mechanism must be provided for a developer to group a set +ad_conn structure.

Resource Bundles / Content Repository

30.0

A mechanism must be provided for a developer to group a set of arbitrary content resources together, keyed by a unique identifier and a locale.

For example, what approaches could be used to implement a localizable nav-bar mechanism for a site? A navigation bar might be @@ -142,7 +141,7 @@ functionality might include using templates, Java ResourceBundles, content-item containers in the Content Repository, or some convention assigning a common prefix to key strings in the message -catalog.

Message Catalog for String Translation

40.0

A message catalog facility will provide a database of +catalog.

Message Catalog for String Translation

40.0

A message catalog facility will provide a database of translations for constant strings for multilingual applications. It must support the following:

40.10 Each message will referenced via unique a key.
40.20 The key for a message will have @@ -167,7 +166,7 @@ is modified, the other translations of that string can be flagged as needing update.
40.90 The message lookup must be as efficient as possible so as not to slow down the delivery of -pages.

Character Set Encoding

Character Sets

50.0 A locale will have a primary +pages.

Character Set Encoding

Character Sets

50.0 A locale will have a primary associated character set which is used to encode text in the language. When given a locale, we can query the system for the associated character set to use.

The assumption is that we are going to use Unicode in our @@ -182,7 +181,7 @@ Writing Files

When the acs-templating package writes an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, - then acs-templating assumes it's that charset.

Tcl Source File Character Set

There are two classes of Tcl files loaded by the system; + then acs-templating assumes it's that charset.

Tcl Source File Character Set

There are two classes of Tcl files loaded by the system; library files loaded at server startup, and page script files, which are run on each page request.
Should we require all Tcl files be stored as UTF8? That seems too much of a burden on developers.
50.10 Tcl library files can be authored @@ -191,31 +190,31 @@ filename.
50.20 Tcl page script files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from - the filename.

Submitted Form Data Character Set

50.30 Data which is submitted with a + the filename.

Submitted Form Data Character Set

50.30 Data which is submitted with a HTTP request using a GET or POST method may be in any character set. The system must be able to determine the encoding of the form data and convert it to Unicode on demand.

50.35 The developer must be able to override the default system choice of character set when parsing - and validating user form data. INCOMPLETE - form + and validating user form data. INCOMPLETE - form widgets in acs-templating/tcl/date-procs.tcl are not internationalized. Also, acs-templating's UI needs to be internationalized by replacing all user-visible strings with - message keys.

50.30.10In Japan and some + message keys.

50.30.10In Japan and some other Asian languages where there are multiple character set encodings in common use, the server may need to attempt to do an auto-detection of the character set, because buggy browsers may - submit form data in an unexpected alternate encoding.

Output Character Set

50.40 The output character set for a + submit form data in an unexpected alternate encoding.

Output Character Set

50.40 The output character set for a page request will be determined by default by the locale associated with the request (see requirement 20.0).
50.50 It must be possible for a developer to manually override the output character set encoding for a request using an API function. -

ACS Kernel Issues

60.10 All OpenACS error messages must use +

ACS Kernel Issues

60.10 All OpenACS error messages must use the message catalog and the request locale to generate error -message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
60.20 Web server error messages such as +message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
60.20 Web server error messages such as 404, 500, etc must also be delivered in the appropriate locale.
60.30 Where files are written or read from disk, their filenames must use a character set and character -values which are safe for the underlying operating system.

Templates

70.0 For a given abstract URL, the +values which are safe for the underlying operating system.

Templates

70.0 For a given abstract URL, the designer may create multiple locale-specific template files may be created (one per locale or language)
70.10 For a given page request, the system must be able to select an approprate locale-specific @@ -227,27 +226,27 @@ any character set. The system must have a way to know which character set a template file contains, so it can properly process it.

Formatting -Datasource Output in Templates

70.50 The properties of a datasource +Datasource Output in Templates

70.50 The properties of a datasource column may include a datatype so that the templating system can format the output for the current locale. The datatype is defined by a standard OpenACS datatype plus a format token or format string, for example: a date column might be specified as 'current_date:date LONG,' or 'current_date:date -"YYYY-Mon-DD"'

Forms

70.60 The forms API must support +"YYYY-Mon-DD"'

Forms

70.60 The forms API must support construction of locale-specific HTML form widgets, such as date entry widgets, and form validation of user input data for locale-specific data, such as dates or numbers. NOT IMPLEMENTED in 5.0.0.
70.70 For forms which allow users to upload files, a standard method for a user to indicate the charset of a text file being uploaded must be provided.
Design note: this presumably applies to uploading -data to the content repository as well

Sorting and Searching

80.10 Support API for correct collation +data to the content repository as well

Sorting and Searching

80.10 Support API for correct collation (sorting order) on lists of strings in locale-dependent way.
80.20 For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL operations (i.e., we won't provide a Tcl API for this). We require a Tcl API function to return the correct incantation of NLS_SORT to use for a -given locale with ORDER BY clauses in +given locale with ORDER BY clauses in queries.
80.40 The system must handle full-text -search in any supported language.

Time Zones

90.10 Provide API support for specifying +search in any supported language.

Time Zones

90.10 Provide API support for specifying a time zone
90.20 Provide an API for computing time and date operations which are aware of timezones. So for example a calendar module can properly synchronize items inserted into a @@ -258,13 +257,13 @@ zone preference should be attached via a session or else UTC should be used to display every date and time.
90.60 The default if we can't determine a time zone is to display all dates and times in some -universal time zone such as GMT.

Database

100.10 Since UTF8 strings can use up to +universal time zone such as GMT.

Database

100.10 Since UTF8 strings can use up to three (UCS2) or six (UCS4) bytes per character, make sure that column size declarations in the schema are large enough to accomodate required data (such as email addresses in -Japanese). Since 5.0.0, this is covered in the database -install instructions for both PostgreSQL and Oracle.

Email and -Messaging

When sending an email message, just as when delivering the +Japanese). Since 5.0.0, this is covered in the database +install instructions for both PostgreSQL and Oracle.

Email and +Messaging

When sending an email message, just as when delivering the content in web page over an HTTP connection, it is necessary to be able to specify what character set encoding to use.

110.10 The email message sending API @@ -287,10 +286,10 @@ (http://www.ietf.org/rfc/rfc3282.txt) and other RFCs.
Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject? INCOMPLETE - The mail functions in acs_mail and acs_mail_lite -are not internationalized.
Incoming mail should be localized.

Implementation Notes

+are not internationalized.

Incoming mail should be localized.

Implementation Notes

Because globalization touches many different parts of the system, we want to reduce the implementation risk by breaking the implementation into phases. -

Revision History

Document Revision # Action Taken, Notes When? By Whom?

1 Updated with results of MIT-sponsored i18n work at Collaboraid. 14 Aug 2003 Joel Aufrecht

0.4

converting from HTML to DocBook and importing the document to the OpenACS +

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
1	Updated with results of MIT-sponsored i18n work at Collaboraid.	14 Aug 2003	Joel Aufrecht
0.4	converting from HTML to DocBook and importing the document to the OpenACS kernel documents. This was done as a part of the internationalization of OpenACS and .LRN for the Heidelberg University in Germany	12 September 2002	Peter Marklund
0.3	comments from Christian	1/14/2000	Henry Minsky
0.2	Minor typos fixed, clarifications to wording	11/14/2000	Henry Minsky
0.1	Creation	11/08/2000	Henry Minsky

Prev	Home	Next
Database Access API	Up	Security Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-translators.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-translators.html,v diff -u -r1.9.2.1 -r1.9.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-translators.html 14 Jan 2007 04:20:10 -0000 1.9.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-translators.html 14 Jul 2007 12:34:47 -0000 1.9.2.2 @@ -1,2 +1 @@ - -Translator's Guide

Prev	Chapter�14.�Internationalization	Next

Translator's Guide

Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.

The basic steps for translators:

Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
Translating with Translator Mode.�To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
While in Translator mode, a list of all message keys appears at the bottom of each page.
Batch translation.�To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.

When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.

Prev	Home	Next
Design Notes	Up	Appendix�D.�Using CVS with an OpenACS Site

docs@openacs.org

View comments on this page at openacs.org +Translator's Guide

Prev	Chapter�14.�Internationalization	Next

Translator's Guide

The basic steps for translators:

Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
Translating with Translator Mode.�To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
While in Translator mode, a list of all message keys appears at the bottom of each page.
Batch translation.�To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.

Prev	Home	Next
Design Notes	Up	Appendix�D.�Using CVS with an OpenACS Site

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -r1.27.2.1 -r1.27.2.2 --- openacs-4/packages/acs-core-docs/www/i18n.html 14 Jan 2007 04:20:10 -0000 1.27.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n.html 14 Jul 2007 12:34:47 -0000 1.27.2.2 @@ -1,5 +1,4 @@ - -Chapter�14.�Internationalization

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�14.�Internationalization

Table of Contents

Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide

+Chapter�14.�Internationalization

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�14.�Internationalization

Table of Contents

Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide

By Peter Marklund and Lars Pind

Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -r1.46.2.2 -r1.46.2.3 --- openacs-4/packages/acs-core-docs/www/index.html 22 Apr 2007 10:21:56 -0000 1.46.2.2 +++ openacs-4/packages/acs-core-docs/www/index.html 14 Jul 2007 12:34:47 -0000 1.46.2.3 @@ -1,4 +1,3 @@ - -OpenACS Core Documentation

		Next

OpenACS Core Documentation

Table of Contents

I. OpenACS For Everyone

1. High level information: What is OpenACS?

Overview
OpenACS Release Notes

II. Administrator's Guide

2. Installation Overview

Basic Steps
Prerequisite Software

3. Complete Installation

Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.3.1
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X

4. Configuring a new OpenACS Site

Installing OpenACS packages
Mounting OpenACS packages
Configuring an OpenACS package
Setting Permissions on an OpenACS package
How Do I?

5. Upgrading

Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components

6. Production Environments

Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems

7. Database Management

Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly

8. Backup and Recovery

Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-recovery

A. Install Red Hat 8/9

B. Install additional supporting software

Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1

C. Credits

Where did this document come from?
Linux Install Guides
Security Information
Resources

III. For OpenACS Package Developers

9. Development Tutorial

Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing

10. Advanced Topics

Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics

11. Development Reference

OpenACS Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS
Groups, Context, Permissions
Writing OpenACS Application Pages
Parties in OpenACS
OpenACS Permissions Tediously Explained
Object Identity
Programming with AOLserver
Using Form Builder: building html forms dynamically

12. Engineering Standards

OpenACS Style Guide
+OpenACS Core Documentation
Next
OpenACS Core Documentation
Table of Contents
I. OpenACS For Everyone
1. High level information: What is OpenACS?
Overview
OpenACS Release Notes
II. Administrator's Guide
2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.3.2
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
Installing OpenACS packages
Mounting OpenACS packages
Configuring an OpenACS package
Setting Permissions on an OpenACS package
How Do I?
5. Upgrading
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components
6. Production Environments
Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems
7. Database Management
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
8. Backup and Recovery
Backup Strategy
Manual backup and recovery
Automated Backup
Using CVS for backup-recovery
A. Install Red Hat 8/9
B. Install additional supporting software
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
III. For OpenACS Package Developers
9. Development Tutorial
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
10. Advanced Topics
Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics
11. Development Reference
OpenACS Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS
Groups, Context, Permissions
Writing OpenACS Application Pages
Parties in OpenACS
OpenACS Permissions Tediously Explained
Object Identity
Programming with AOLserver
Using Form Builder: building html forms dynamically
12. Engineering Standards
OpenACS Style Guide
CVS Guidelines -
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing
13. Documentation Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
14. Internationalization
Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide
D. Using CVS with an OpenACS Site
IV. For OpenACS Platform Developers
15. Kernel Documentation
Overview
Object Model Requirements
Object Model Design
Permissions Requirements
Permissions Design
Groups Requirements
Groups Design
Subsites Requirements
Subsites Design Document
Package Manager Requirements
Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Security Requirements
Security Design
Security Notes
Request Processor Requirements
Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
16. Releasing OpenACS
OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations
Index
List of Figures
4.1. Site Templates
4.2. Granting Permissions
4.3. Granting Permissions in 5.0
5.1. Upgrading with the APM
5.2. Upgrading a local CVS repository
6.1. Multiple-server configuration
6.2. Simple A/B Deployment - Step 1
6.3. Simple A/B Deployment - Step 2
6.4. Simple A/B Deployment - Step 3
6.5. Complex A/B Deployment - Step 1
6.6. Complex A/B Deployment - Step 2
6.7. Complex A/B Deployment - Step 3
6.8. Query Analysis example
8.1. Backup and Recovery Strategy
9.1. Assumptions in this section
9.2. Tutorial Data Model
9.3. The Database Creation Script
9.4. Database Deletion Script
9.5. Page Map
10.1. Upgrading a local CVS repository
11.1. Server file layout diagram
11.2. Package file layout diagram
List of Tables
2.1. Default directories for a standard install
2.2. Version Compatibility Matrix
5.1. Assumptions in this section
6.1. How it Works
10.1. table showing ETP layout
11.1. Package files
11.2. Context Hierarchy Example
11.3. acs_objects example data
14.1. Internationalization and Localization Overview
List of Examples
12.1. Getting datetime from the database ANSI-style
Next
Part�I.�OpenACS For Everyone
docs@openacs.org
View comments on this page at openacs.org +
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing

13. Documentation Standards

OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template

14. Internationalization

Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide

D. Using CVS with an OpenACS Site

IV. For OpenACS Platform Developers

15. Kernel Documentation

Overview
Object Model Requirements
Object Model Design
Permissions Requirements
Permissions Design
Groups Requirements
Groups Design
Subsites Requirements
Subsites Design Document
Package Manager Requirements
Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Security Requirements
Security Design
Security Notes
Request Processor Requirements
Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements

16. Releasing OpenACS

OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations

Index

List of Figures

4.1. Site Templates
4.2. Granting Permissions
4.3. Granting Permissions in 5.0
5.1. Upgrading with the APM
5.2. Upgrading a local CVS repository
6.1. Multiple-server configuration
6.2. Simple A/B Deployment - Step 1
6.3. Simple A/B Deployment - Step 2
6.4. Simple A/B Deployment - Step 3
6.5. Complex A/B Deployment - Step 1
6.6. Complex A/B Deployment - Step 2
6.7. Complex A/B Deployment - Step 3
6.8. Query Analysis example
8.1. Backup and Recovery Strategy
9.1. Assumptions in this section
9.2. Tutorial Data Model
9.3. The Database Creation Script
9.4. Database Deletion Script
9.5. Page Map
10.1. Upgrading a local CVS repository
11.1. Server file layout diagram
11.2. Package file layout diagram

List of Tables

2.1. Default directories for a standard install
2.2. Version Compatibility Matrix
5.1. Assumptions in this section
6.1. How it Works
10.1. table showing ETP layout
11.1. Package files
11.2. Context Hierarchy Example
11.3. acs_objects example data
14.1. Internationalization and Localization Overview

List of Examples

12.1. Getting datetime from the database ANSI-style

		Next
		Part�I.�OpenACS For Everyone

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/individual-programs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v diff -u -r1.26.2.2 -r1.26.2.3 --- openacs-4/packages/acs-core-docs/www/individual-programs.html 22 Apr 2007 10:21:56 -0000 1.26.2.2 +++ openacs-4/packages/acs-core-docs/www/individual-programs.html 14 Jul 2007 12:34:47 -0000 1.26.2.3 @@ -1,16 +1,15 @@ - -Prerequisite Software

Prev	Chapter�2.�Installation Overview	Next

Prerequisite Software

by Joel Aufrecht

+Prerequisite Software

Prev	Chapter�2.�Installation Overview	Next

Prerequisite Software

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

OpenACS requires, at a minimum, an operating system, database, and webserver to work. Many additional programs, such as a build environment, Mail Transport Agent, and source control system, are also needed for a fully effective installation. -

Table�2.2.�Version Compatibility Matrix

OpenACS Version		3.2.5	4.5	4.6.2	4.6.3	5.0	5.1	5.2
AOLserver	3	Yes	No
	3.3+ad13	Maybe	Yes					No
	3.3oacs1	Maybe	Yes					No
	3.4.4	No
	3.4.4oacs1	Maybe		Yes		No
	3.5.5	Maybe		Yes		No
	4.0	Maybe		Yes
PostgreSQL	7.0	Yes	No
	7.2	Maybe	Yes			No
	7.3.2 - 7.3.x	No			Yes
	7.4	No				Yes
	8.0	No					Maybe	Yes
Oracle	8.1.6	Maybe	Yes
	8.1.7	Maybe	Yes
	9i	No				Yes
10g	�	No						Maybe

The OpenACS installation instructions assume the operating system and build environment are installed. +

Table�2.2.�Version Compatibility Matrix

OpenACS Version		3.2.5	4.5	4.6.2	4.6.3	5.0	5.1	5.2
AOLserver	3	Yes	No
	3.3+ad13	Maybe	Yes					No
	3.3oacs1	Maybe	Yes					No
	3.4.4	No
	3.4.4oacs1	Maybe		Yes		No
	3.5.5	Maybe		Yes		No
	4.0	Maybe		Yes
PostgreSQL	7.0	Yes	No
	7.2	Maybe	Yes			No
	7.3.2 - 7.3.x	No			Yes
	7.4	No				Yes
	8.0	No					Maybe	Yes
Oracle	8.1.6	Maybe	Yes
	8.1.7	Maybe	Yes
	9i	No				Yes
10g	�	No						Maybe

The OpenACS installation instructions assume the operating system and build environment are installed. The instructions explain installation of TCL, tDOM, tclwebtest, a Web Server, a Database, a Process Controller, and Source Control software. The following external links are for reference only. -

OpenACS 5.3.1.�The OpenACS tarball comprises the core packages and +
- OpenACS 5.3.2.�The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL and Oracle. Some scripts require bash shell.
- Operating System.�OpenACS is designed for a Unix-like system. It is @@ -19,8 +18,8 @@ standard Linux shell. If you are using a different shell, you will need to substitute your shell's conventions for setting environment variables when - appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use - wget to download software.
- Mac OS X.�Section�, “OpenACS Installation Guide for Mac OS X”
- Windows/VMWare.�Section�, “OpenACS Installation Guide for Windows2000” The only + appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use + wget to download software.
- Mac OS X.�the section called “OpenACS Installation Guide for Mac OS X”
- Windows/VMWare.�the section called “OpenACS Installation Guide for Windows2000” The only way to run OpenACS on Windows is through the VMWare emulator. (Please let me know if you have OpenACS running directly in Windows.)
Build Environment.�The Reference Platform installation compiles most programs from @@ -30,19 +29,19 @@ operating system distribution.
GNU Make 3.76.1 or newer, REQUIRED.�PostgreSQL and AOLserver require gmake to compile. Note that on most linux distributions, GNU Make is simply named - make and + make and there is no - gmake, + gmake, whereas on BSD distributions, - make and - gmake are + make and + gmake are different --use gmake.

TCL 8.4.x.�

TCL 8.4.x, REQUIRED.�OpenACS is written in TCL, an interpreted language. A threaded version of the TCL interpreter must be installed for OpenACS to work. The TCL interpreter that is included in most standard distributions may not be thread safe.
TCL 8.4.x development headers and libraries, OPTIONAL.� The site-wide-search service, OpenFTS, requires these to - compile. (Debian users: apt-get install - tcl8.4-dev). You need this - to install OpenFTS.

tDOM, REQUIRED.�OpenACS 5.3.1 stores + compile. (Debian users: apt-get install + tcl8.4-dev). You need this + to install OpenFTS.

tDOM, REQUIRED.�OpenACS 5.3.2 stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which was used prior to 4.6.4.)

tclwebtest, OPTIONAL.�tclwebtest is a tool for testing web interfaces via tcl scripts.

Web Server.�The web server handles incoming HTTP requests, provides @@ -51,7 +50,7 @@ errors. OpenACS uses AOLserver; some people have had success running Apache with mod_nsd.

AOLserver 4.x, REQUIRED.�Provides the base HTTP server

Mat Kovach is graciously maintaining an AOLserver distribution that - includes all the patches and modules needed to run OpenACS 5.3.1. These + includes all the patches and modules needed to run OpenACS 5.3.2. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and perhaps more to come), currently located at uptime.openacs.org. @@ -68,14 +67,14 @@ (i.e. postgres.so)

- The patch that makes exec work + The patch that makes exec work on BSD is available at sourceforge.net

- The patch for aolserver 3.x that makes ns_uuencode + The patch for aolserver 3.x that makes ns_uuencode work for binary files is available at sourceforge.net

The patch that makes AOLserver 3.x respect the - -g flag is available at + -g flag is available at sourceforge.net

nsopenssl, OPTIONAL.�Provides SSL capabilities for AOLserver. It requires OpenSSL. You need this if you want users to make @@ -94,7 +93,7 @@ higher, full text search is also available via tsearch2.

Analog 5.32 or newer, OPTIONAL.�This program examines web server request logs, looks up DNS values, and produces a report. You need this if you - want to see how much traffic your site is getting.

Balance 3.11 or newer, OPTIONAL.�"Balance is a simple but powerful generic tcp proxy with round robin load balancing and failover mechanisms." You need this or something equivalent if you are running a high-availability production site and do not have an external load balancing system.

Database.�The data on your site (for example, user names and passwords, + want to see how much traffic your site is getting.

Database.�The data on your site (for example, user names and passwords, calender entries, and notes) is stored in the database. OpenACS separates the database with an abstraction layer, which means that several different databases all function @@ -106,7 +105,7 @@ restarts that software if it fails. On Linux, we recommend using Daemontools to control AOLserver and qmail.

Daemontools 0.76, OPTIONAL.�You need this if - you want AOLserver and qmail to run "supervised," + you want AOLserver and qmail to run "supervised," meaning that they are monitored and automatically restarted if they fail. An alternative would be to run the services from inittab.

Mail Transport Agent.�A Mail Transport Agent is a program that handles all Index: openacs-4/packages/acs-core-docs/www/install-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v diff -u -r1.33.2.2 -r1.33.2.3 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 22 Apr 2007 10:21:56 -0000 1.33.2.2 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 14 Jul 2007 12:34:47 -0000 1.33.2.3 @@ -1,7 +1,6 @@ - -Initialize CVS (OPTIONAL)

Prev	Appendix�B.�Install additional supporting software	Next

Initialize CVS (OPTIONAL)

CVS is a source control system. Create and initialize a - directory for a local cvs repository.

[root tmp]# mkdir /cvsroot
-[root tmp]# cvs -d /cvsroot init
+Initialize CVS (OPTIONAL)Prev Appendix�B.�Install additional supporting software  Next
Initialize CVS (OPTIONAL)
CVS is a source control system.  Create and initialize a
+      directory for a local cvs repository.
[root tmp]# mkdir /cvsroot
+[root tmp]# cvs -d /cvsroot init
 [root tmp]#
 mkdir /cvsroot
 cvs -d /cvsroot init
Prev Home  Next
Unpack the OpenACS tarball Up  Add PSGML commands to emacs init file (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v
diff -u -r1.34.2.2 -r1.34.2.3
--- openacs-4/packages/acs-core-docs/www/install-daemontools.html	22 Apr 2007 10:21:56 -0000	1.34.2.2
+++ openacs-4/packages/acs-core-docs/www/install-daemontools.html	14 Jul 2007 12:34:47 -0000	1.34.2.3
@@ -1,15 +1,14 @@
-
-Install Daemontools (OPTIONAL)Prev Appendix�B.�Install additional supporting software  Next
Install Daemontools (OPTIONAL)
Daemontools is a collection of programs for controlling
+Install Daemontools (OPTIONAL)
Prev Appendix�B.�Install additional supporting software  Next
Install Daemontools (OPTIONAL)
Daemontools is a collection of programs for controlling
       other processes.  We use daemontools to run and monitor AOLserver.  It is
       installed in /package.  These commands install daemontools and
       svgroup.  svgroup is a script for granting permissions, to allow
       users other than root to use daemontools for specific
-      services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]# mkdir -p /package
-[root root]# chmod 1755 /package/
-[root root]# cd /package/
-[root package]# tar xzf /tmp/daemontools-0.76.tar.gz
-[root package]# cd admin/daemontools-0.76/
-[root daemontools-0.76]# package/install
+      services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]# mkdir -p /package
+[root root]# chmod 1755 /package/
+[root root]# cd /package/
+[root package]# tar xzf /tmp/daemontools-0.76.tar.gz
+[root package]# cd admin/daemontools-0.76/
+[root daemontools-0.76]# package/install
 Linking ./src/* into ./compile...
 
 Creating /service...
@@ -22,13 +21,13 @@
 tar xzf /tmp/daemontools-0.76.tar.gz 
 cd admin/daemontools-0.76 
 package/install
Red Hat 9, Fedora Core 1-4
Make sure you have the source tarball in
-          /tmp, or download it.
-
[root root]# mkdir -p /package
-[root root]# chmod 1755 /package/
-[root root]# cd /package/
-[root package]# tar xzf /tmp/daemontools-0.76.tar.gz
-[root package]# cd admin
-[root admin]# wget http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch
+          /tmp, or download it.
+
[root root]# mkdir -p /package
+[root root]# chmod 1755 /package/
+[root root]# cd /package/
+[root package]# tar xzf /tmp/daemontools-0.76.tar.gz
+[root package]# cd admin
+[root admin]# wget http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch
 --14:19:24--  http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch
            => `daemontools-0.76.errno.patch'
 Resolving moni.csi.hu... done.
@@ -40,9 +39,9 @@
 
 14:19:24 (346.68 KB/s) - `daemontools-0.76.errno.patch' saved [355/355]
 
-[root admin]# cd daemontools-0.76
-[root daemontools-0.76]# patch -p1 < ../daemontools-0.76.errno.patch
-[root daemontools-0.76]# package/install
+[root admin]# cd daemontools-0.76
+[root daemontools-0.76]# patch -p1 < ../daemontools-0.76.errno.patch
+[root daemontools-0.76]# package/install
 Linking ./src/* into ./compile...(many lines omitted)
 Creating /service...
 Adding svscanboot to inittab...
@@ -57,13 +56,13 @@
 cd daemontools-0.76
 patch -p1 < ../daemontools-0.76.errno.patch
 package/install
FreeBSD (follow standard install)
Make sure you have the source tarball in
-          /tmp, or download it.
-
[root root]# mkdir -p /package
-[root root]# chmod 1755 /package/
-[root root]# cd /package/
-[root package]# tar xzf /tmp/daemontools-0.76.tar.gz
-[root package]# cd admin/daemontools-0.76
-[root daemontools-0.76]# package/install
+          /tmp, or download it.
+
[root root]# mkdir -p /package
+[root root]# chmod 1755 /package/
+[root root]# cd /package/
+[root package]# tar xzf /tmp/daemontools-0.76.tar.gz
+[root package]# cd admin/daemontools-0.76
+[root daemontools-0.76]# package/install
 Linking ./src/* into ./compile...(many lines omitted)
 Creating /service...
 Adding svscanboot to inittab...
@@ -74,13 +73,13 @@
 cd /package 
 tar xzf /tmp/daemontools-0.76.tar.gz 
 cd admin/daemontools-0.76
-package/install
Debian
[root ~]# apt-get install daemontools-installer
-[root ~]# build-daemontools
Verify that svscan is running.  If it is, you should see
-      these two processes running:
[root root]# ps -auxw | grep service
+package/install
Debian
[root ~]# apt-get install daemontools-installer
+[root ~]# build-daemontools
Verify that svscan is running.  If it is, you should see
+      these two processes running:
[root root]# ps -auxw | grep service
 root     13294  0.0  0.1  1352  272 ?        S    09:51   0:00 svscan /service
 root     13295  0.0  0.0  1304  208 ?        S    09:51   0:00 readproctitle service errors: .......................................
 [root root]#
Install a script to grant non-root users permission to
-        control daemontools services.
[root root]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup
-[root root]# chmod 755 /usr/local/bin/svgroup
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup 
+        control daemontools services.
[root root]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup
+[root root]# chmod 755 /usr/local/bin/svgroup
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup 
 chmod 755 /usr/local/bin/svgroup
Prev Home  Next
Add PSGML commands to emacs init file (OPTIONAL) Up  Install qmail (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html,v
diff -u -r1.4.2.2 -r1.4.2.3
--- openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html	22 Apr 2007 10:21:56 -0000	1.4.2.2
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html	14 Jul 2007 12:34:47 -0000	1.4.2.3
@@ -1,27 +1,26 @@
-
-Install Full Text Search using OpenFTS (deprecated see tsearch2)Prev Appendix�B.�Install additional supporting software  Next
Install Full Text Search using OpenFTS (deprecated see tsearch2)
By Joel Aufrecht and Malte Sussdorff
+Install Full Text Search using OpenFTS (deprecated see tsearch2)Prev Appendix�B.�Install additional supporting software  Next
Install Full Text Search using OpenFTS (deprecated see tsearch2)
By Joel Aufrecht and Malte Sussdorff
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
OpenFTS and tsearch1 use is deprecated in favor of
       Tsearch2. See 
       Install       Full Text Search using Tsearch2. Tsearch2 is much easier to install, requiring only
       compilation of one module from PostgreSQL contrib, with an
-      automated install process using the tsearch2-driver package.
Install OpenFTS module
If you want full text search, and you are running PostgreSQL, install this module to support FTS.  Do this step after you have installed both PostgreSQL and
+      automated install process using the tsearch2-driver package.
Install OpenFTS module
If you want full text search, and you are running PostgreSQL, install this module to support FTS.  Do this step after you have installed both PostgreSQL and
       AOLserver.  You will need the openfts
-      tarball in /tmp.
Install Tsearch.  This is a PostgreSQL module that
-	  OpenFTS requires.
[root root]# su - postgres
-[postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/
-[postgres tsearch]$ make
+      tarball in /tmp.
Install Tsearch.  This is a PostgreSQL module that
+	  OpenFTS requires.
[root root]# su - postgres
+[postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/
+[postgres tsearch]$ make
 sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql
 /usr/bin/flex  -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted)
 rm -f libtsearch.so
 ln -s libtsearch.so.0.0 libtsearch.so
-[postgres tsearch]$ make install
+[postgres tsearch]$ make install
 mkdir /usr/local/pgsql/share/contrib
 mkdir /usr/local/pgsql/doc/contrib
 (2 lines omitted)
 /bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so
-[postgres tsearch]$ exit
+[postgres tsearch]$ exit
 logout
 
 [root root]#
@@ -30,27 +29,27 @@
 make
 make install
 exit
Unpack the OpenFTS tarball and compile and install
-              the driver.
[root root]# cd /usr/local/src
-[root src]# tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz
-[root src]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/
-[root Search-OpenFTS-tcl-0.3.2]# ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/
+              the driver.
[root root]# cd /usr/local/src
+[root src]# tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz
+[root src]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/
+[root Search-OpenFTS-tcl-0.3.2]# ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/
 checking prefix... /usr/local
 checking for gcc... gcc
 (many lines omitted)
 configure: creating ./config.status
 config.status: creating Makefile.global
-[root Search-OpenFTS-tcl-0.3.2]# make
+[root Search-OpenFTS-tcl-0.3.2]# make
 (cd parser; make all)
 make[1]: Entering directory `/usr/local/src/Search-OpenFTS-tcl-0.3.2/parser'
 (many lines omitted)
 packages provided were {Lingua::Stem::Snowball 0.3.2}
 processed fts_base_snowball.tcl
-[root Search-OpenFTS-tcl-0.3.2]# cd aolserver
-[root aolserver]# make
-gcc -c -fPIC  -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR
+[root Search-OpenFTS-tcl-0.3.2]# cd aolserver
+[root aolserver]# make
+gcc -c -fPIC  -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR
 (many lines omitted)
 n_stem.o italian_stem.o norwegian_stem.o portuguese_stem.o russian_stem.o nsfts.o  -o nsfts.so
-[root aolserver]# cp nsfts.so /usr/local/aolserver/bin/
+[root aolserver]# cp nsfts.so /usr/local/aolserver/bin/
 [root aolserver]#
 cd /usr/local/src 
 tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz
@@ -60,75 +59,75 @@
 cd aolserver
 make
 cp nsfts.so /usr/local/aolserver/bin
-
Build some supplemental modules.
[root aolserver]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2
-[root Search-OpenFTS-tcl-0.3.2]# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib
-[root Search-OpenFTS-tcl-0.3.2]# cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts
-[root pgsql_contrib_openfts]# make
+
Build some supplemental modules.
[root aolserver]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2
+[root Search-OpenFTS-tcl-0.3.2]# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib
+[root Search-OpenFTS-tcl-0.3.2]# cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts
+[root pgsql_contrib_openfts]# make
 sed 's,MODULE_PATHNAME,$libdir/openfts,g' openfts.sql.in >openfts.sql
 gcc -O2 -Wall -Wmissing-prototypes -Wmissing-declarations -fpic -I. -I../../src/include   -c -o openfts.o openfts.c
 gcc -shared -o openfts.so openfts.o
 rm openfts.o
-[root pgsql_contrib_openfts]# su postgres
-[postgres pgsql_contrib_openfts]$ make install
+[root pgsql_contrib_openfts]# su postgres
+[postgres pgsql_contrib_openfts]$ make install
 /bin/sh ../../config/install-sh -c -m 644 openfts.sql /usr/local/pgsql/share/contrib
 /bin/sh ../../config/install-sh -c -m 755 openfts.so /usr/local/pgsql/lib
 /bin/sh ../../config/install-sh -c -m 644 ./README.openfts /usr/local/pgsql/doc/contrib
-[postgres pgsql_contrib_openfts]$ exit
+[postgres pgsql_contrib_openfts]$ exit
 [root pgsql_contrib_openfts]#
 cd /usr/local/src/Search-OpenFTS-tcl-0.3.2
 cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib
 cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts
 make
 su postgres
 make install
-exit
Install OpenFTS prerequisites in PostgreSQL instance
If you are installing Full Text Search, add required
+exit

Install OpenFTS prerequisites in PostgreSQL instance

If you are installing Full Text Search, add required packages to the new database. (In order for full text search to work, you must also install the PostgreSQL - OpenFTS module and prerequisites.)

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql + OpenFTS module and prerequisites.)

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql
 BEGIN
 CREATE
 (many lines omitted)
 INSERT 0 1
 COMMIT
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql
 CREATE
 CREATE
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
 /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql
 /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql

Note

If you get the error - ERROR: could not access file "$libdir/tsearch": no such file or directory + ERROR: could not access file "$libdir/tsearch": no such file or directory It is probably because PostgreSQL's libdir configuration variable points to a diffent directory than where tsearch is. You can find out where PostgreSQL expects to find tsearch via -

pg_config --pkglibdir

Enable OpenFTS in config.tcl

If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)

#ns_param   nsfts           ${bindir}/nsfts.so

Install Full Text Search Engine

Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install -software link.
Click on the Install -new service link.
Click on the Install link next to OpenFTS Driver.

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the OpenFTS Full Text Search Engine in the site map.
1. Click the new sub folder link on the "/" line, the first line under Main Site:/.
2. Type openfts -and click New.
3. On the new openfts line, click the mount link.
4. Click OpenFTS -Driver.
5. On the openfts line, click set parameters.
6. Change openfts_tcl_src_path to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ and click Set Parameters +
```
pg_config --pkglibdir
```
  +

Enable OpenFTS in config.tcl

If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)

#ns_param   nsfts           ${bindir}/nsfts.so

Install Full Text Search Engine

Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install +software link.
Click on the Install +new service link.
Click on the Install link next to OpenFTS Driver.

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the OpenFTS Full Text Search Engine in the site map.
1. Click the new sub folder link on the "/" line, the first line under Main Site:/.
2. Type openfts +and click New.
3. On the new openfts line, click the mount link.
4. Click OpenFTS +Driver.
5. On the openfts line, click set parameters.
6. Change openfts_tcl_src_path to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ and click Set Parameters
Mount the Search interface in the site map.
1. Click the -new sub folder link on the -Main Site line.
2. Type search -and click New.
3. Click the new -application link on the search - line.
4. Type search +new sub folder link on the +Main Site line.
5. Type search +and click New.
6. Click the new +application link on the search + line.
7. Type search where it says -untitled, choose -search from the +untitled, choose +search from the drop-down list, and click -New. -

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Wait a minute, then click on Main Site at the top of the page.
Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.
Near the bottom of the page, click on the OpenFTS Driver link. Click on Administration. -Click on Initialize OpenFTS Engine. -Click Initialize OpenFTS Engine.
Add the FTS Engine service contract
1. Click on the DevAdmin.
2. Click on the Service Contract link.
3. On the FtsEngineDriver +New. +

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Wait a minute, then click on Main Site at the top of the page.
Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.
Near the bottom of the page, click on the OpenFTS Driver link. Click on Administration. +Click on Initialize OpenFTS Engine. +Click Initialize OpenFTS Engine.
Add the FTS Engine service contract
1. Click on the DevAdmin.
2. Click on the Service Contract link.
3. On the FtsEngineDriver line, click -Install. -

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Enable Full Text Search in packages

Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package

Install the package. -
1. Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
2. Click on the Install - software link.
3. Click on the Install - new application link.
4. Click on the Install link next to Weblogger.
5. Install all required packages as well (always say okay until you shall restart the server)
-

Load the service contracts datamodell and enable the service contract

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql
-[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql

Note: Usually this script is called package_name-sc-create.sql

Restart the service.

[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME +Install. +

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Enable Full Text Search in packages

Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package

Install the package. +
1. Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
2. Click on the Install + software link.
3. Click on the Install + new application link.
4. Click on the Install link next to Weblogger.
5. Install all required packages as well (always say okay until you shall restart the server)
+

Load the service contracts datamodell and enable the service contract

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql
+[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql

Note: Usually this script is called package_name-sc-create.sql

Restart the service.

[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME
                 [$OPENACS_SERVICE_NAME postgresl]$

If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.

Prev	Home	Next
Install Full Text Search using Tsearch2	Up	Install nsopenssl

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html,v diff -u -r1.4.2.2 -r1.4.2.3 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 22 Apr 2007 10:21:56 -0000 1.4.2.2 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 14 Jul 2007 12:34:47 -0000 1.4.2.3 @@ -1,12 +1,11 @@ - -Install Full Text Search using Tsearch2

Prev	Appendix�B.�Install additional supporting software	Next

Install Full Text Search using Tsearch2

By Dave +Install Full Text Search using Tsearch2

Prev	Appendix�B.�Install additional supporting software	Next

Install Full Text Search using Tsearch2

By Dave Bauer, Joel Aufrecht and Malte Sussdorff with help from Tsearch V2 Introduction by Andrew J. Kopciuch

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Install Tsearch2 module

If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and +

Install Tsearch2 module

If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and AOLserver. You will need the tseach2 module form PostgreSQL contrib. This is included with the PostgreSQL full source distribution. It is also available with the PostgreSQL contrib @@ -30,11 +29,11 @@ place it in your postgreSQL source tree ($PGSQL_SRC). This patch makes the backup and restore procedures very simple.

-            [postgres pgsql]$ cd /tmp
-            [postgres tmp]$ wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz
-            [postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/
-            [postgres postgresql-7.4.5] gunzip /tmp/regprocedure_7.4.patch.gz
-            [postgres postgresql-7.4.5] patch -b -p1 < regprocedure_7.4.patch
+            [postgres pgsql]$ cd /tmp
+            [postgres tmp]$ wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz
+            [postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/
+            [postgres postgresql-7.4.5] gunzip /tmp/regprocedure_7.4.patch.gz
+            [postgres postgresql-7.4.5] patch -b -p1 < regprocedure_7.4.patch

If you have a working version of tsearch2 in your database, you do not need to re-install the tsearch2 module. Just @@ -57,52 +56,52 @@ 8.0.

Install Tsearch2. This is a PostgreSQL module that the tsearch2-driver OpenACS package requires. These instructions assume you are using the latest point - release of PostgreSQL 7.4.5.

[root root]# su - postgres
-[postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/
-[postgres tsearch2]$ make
-[postgres tsearch2]$ make install
+              release of PostgreSQL 7.4.5.
[root root]# su - postgres
+[postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/
+[postgres tsearch2]$ make
+[postgres tsearch2]$ make install
 mkdir /usr/local/pgsql/share/contrib
 mkdir /usr/local/pgsql/doc/contrib
 (2 lines omitted)
 /bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so
-[postgres tsearch]$ exit
+[postgres tsearch]$ exit
 logout
 
 [root root]#
 su - postgres
 cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2
 make
 make install
-exit

Install Full Text Search Engine Package in OpenACS

Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install -software link.
Click on the Install -new service link.
Click on the - Install +exit

Install Full Text Search Engine Package in OpenACS

Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install +software link.
Click on the Install +new service link.
Click on the + Install link next to Tsearch2 Driver. If you have installed tsearch2 into your PostgreSQL database, the installer will - automatically enable tsearch in your OpenACS database instance.

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the Search interface in the site map.
1. Click the -new sub folder link on the -Main Site line.
2. Type search -and click New.
3. Click the new -application link on the search - line.
4. Type search + automatically enable tsearch in your OpenACS database instance.
5. Restart the service.
```
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
```
6. Wait a minute, then browse back to the home page.
7. Click on Admin on the top of the screen.
8. Click on Main Site Administration in the "Subsite Administration" section.
9. Click on Site Map in the "Advanced Features" section.
10. Mount the Search interface in the site map.
  1. Click the +new sub folder link on the +Main Site line.
  2. Type search +and click New.
  3. Click the new +application link on the search + line.
  4. Type search where it says -untitled, choose -search from the +untitled, choose +search from the drop-down list, and click -New. +New.
  5. Click the -Parameters link - next to the Search package istance.
  6. Type tsearch2-driver +Parameters link + next to the Search package istance.
  7. Type tsearch2-driver where it says -openfts-driver +openfts-driver in the - FtsEngineDriver parameter. -
11. Restart the service.
```
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
```
12. Wait a minute, then click on Main Site at the top of the page.

Enable Full Text Search in packages

Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package

Install the package. -
1. Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
2. Click on the Install - software link.
3. Click on the Install - new application link.
4. Click on the Install link next to Weblogger.
5. Install all required packages as well (always say okay until you shall restart the server)
-

Load the service contracts datamodell and enable the service contract

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql
-[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql

Note: Usually this script is called package_name-sc-create.sql

Restart the service.

[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME + FtsEngineDriver parameter. +

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Wait a minute, then click on Main Site at the top of the page.

Enable Full Text Search in packages

Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package

Install the package. +
1. Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
2. Click on the Install + software link.
3. Click on the Install + new application link.
4. Click on the Install link next to Weblogger.
5. Install all required packages as well (always say okay until you shall restart the server)
+

Load the service contracts datamodell and enable the service contract

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql
+[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql

Note: Usually this script is called package_name-sc-create.sql

Restart the service.

[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME
                 [$OPENACS_SERVICE_NAME postgresl]$

If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.

Prev	Home	Next
Install nspam	Up	Install Full Text Search using OpenFTS (deprecated see tsearch2)

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-ldap-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ldap-radius.html,v diff -u -r1.4.2.1 -r1.4.2.2 --- openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 14 Jan 2007 04:20:10 -0000 1.4.2.1 +++ openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 14 Jul 2007 12:34:47 -0000 1.4.2.2 @@ -1,13 +1,12 @@ - -Install LDAP for use as external authentication

Prev	Appendix�B.�Install additional supporting software	Next

Install LDAP for use as external authentication

By Malte Sussdorff

+Install LDAP for use as external authentication

Prev	Appendix�B.�Install additional supporting software	Next

Install LDAP for use as external authentication

By Malte Sussdorff

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section

Install openldap.�Download and install ns_ldap

[root aolserver]# cd /usr/local/src/
-          [root src]# wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz
-          [root src]# tar xvfz openldap-2.2.17.tgz
-          [root src]# cd openldap-2.2.17
-          [root src]# ./configure --prefix=/usr/local/openldap
-          [root openldap]# make install
+

Install openldap.�Download and install ns_ldap

[root aolserver]# cd /usr/local/src/
+          [root src]# wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz
+          [root src]# tar xvfz openldap-2.2.17.tgz
+          [root src]# cd openldap-2.2.17
+          [root src]# ./configure --prefix=/usr/local/openldap
+          [root openldap]# make install
           [root openldap]#
 cd /usr/local/src/
 wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz
@@ -16,18 +15,18 @@
 ./configure --prefix=/usr/local/openldap --disable-slapd
 make install
 
-

Install ns_ldap.�Download and install ns_ldap

[root aolserver]# cd /usr/local/src/aolserver/
-          [root aolserver]# wget http://www.sussdorff.de/ressources/nsldap.tgz
-          [root aolserver]# tar xfz nsldap.tgz
-          [root aolserver]# cd nsldap
-          [root ns_pam-0.1]# make install LDAP=/usr/local/openldap INST=/usr/local/aolserver
+

Install ns_ldap.�Download and install ns_ldap

[root aolserver]# cd /usr/local/src/aolserver/
+          [root aolserver]# wget http://www.sussdorff.de/ressources/nsldap.tgz
+          [root aolserver]# tar xfz nsldap.tgz
+          [root aolserver]# cd nsldap
+          [root ns_pam-0.1]# make install LDAP=/usr/local/openldap INST=/usr/local/aolserver
           [root ns_pam-0.1]#
 cd /usr/local/src/aolserver/
 wget http://www.sussdorff.de/resources/nsldap.tgz
 tar xfz nsldap.tgz
 cd nsldap
 make install LDAP=/usr/local/openldap INST=/usr/local/aolserver
 
-

Configure ns_ldap for traditional use.�Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the usernamestored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead.
- - Change config.tcl. Remove the # in front of ns_param nsldap ${bindir}/nsldap.so to enable the loading of the ns_ldap module. -
Configure ns_ldap for use with LDAP bind.�LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the ns_ldap bind command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it).

Prev	Home	Next
Install PAM Radius for use as external authentication	Up	Install AOLserver 3.3oacs1

docs@openacs.org

View comments on this page at openacs.org +

Configure ns_ldap for traditional use.�Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the usernamestored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead.

+ Change config.tcl. Remove the # in front of ns_param nsldap ${bindir}/nsldap.so to enable the loading of the ns_ldap module. +

Configure ns_ldap for use with LDAP bind.�LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the ns_ldap bind command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it).

Prev	Home	Next
Install PAM Radius for use as external authentication	Up	Install AOLserver 3.3oacs1

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-more-software.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.html,v diff -u -r1.16.2.1 -r1.16.2.2 --- openacs-4/packages/acs-core-docs/www/install-more-software.html 14 Jan 2007 04:20:10 -0000 1.16.2.1 +++ openacs-4/packages/acs-core-docs/www/install-more-software.html 14 Jul 2007 12:34:47 -0000 1.16.2.2 @@ -1,9 +1,8 @@ - -Appendix�B.�Install additional supporting software

Prev	Part�II.�Administrator's Guide	Next

Appendix�B.�Install additional supporting software

Table of Contents

Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1

By Joel Aufrecht

+Appendix�B.�Install additional supporting software

Prev	Part�II.�Administrator's Guide	Next

Appendix�B.�Install additional supporting software

Table of Contents

Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1

By Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

This section assumes that the source tarballs for supporting - software are in /tmp. It assumes + software are in /tmp. It assumes that you begin each continuous block of commands as root, and you should end each block as root. It doesn't care which directory you start in. Text instructions always precede the commands they Index: openacs-4/packages/acs-core-docs/www/install-next-add-server.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-add-server.html,v diff -u -r1.10.2.2 -r1.10.2.3 --- openacs-4/packages/acs-core-docs/www/install-next-add-server.html 22 Apr 2007 10:21:56 -0000 1.10.2.2 +++ openacs-4/packages/acs-core-docs/www/install-next-add-server.html 14 Jul 2007 12:34:47 -0000 1.10.2.3 @@ -1,12 +1,11 @@ - -Running multiple services on one machine

Prev	Chapter�6.�Production Environments	Next

Running multiple services on one machine

Services on different ports.�To run a different service on another port but the same - ip, simply repeat Install OpenACS 5.3.1 replacing +Running multiple services on one machine

Prev	Chapter�6.�Production Environments	Next

Running multiple services on one machine

Services on different ports.�To run a different service on another port but the same + ip, simply repeat Install OpenACS 5.3.2 replacing $OPENACS_SERVICE_NAME, and change the

set httpport              8000
 set httpsport             8443

to different values.

Services on different host names.�For example, suppose you want to support -http://service0.com and - http://bar.com on the same +http://service0.com and + http://bar.com on the same machine. The easiest way is to assign each one a different ip address. Then you can install two services as above, but with different values for Index: openacs-4/packages/acs-core-docs/www/install-next-backups.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-backups.html,v diff -u -r1.7.2.1 -r1.7.2.2 --- openacs-4/packages/acs-core-docs/www/install-next-backups.html 14 Jan 2007 04:20:10 -0000 1.7.2.1 +++ openacs-4/packages/acs-core-docs/www/install-next-backups.html 14 Jul 2007 12:34:47 -0000 1.7.2.2 @@ -1,5 +1,4 @@ - -Backup Strategy

Prev	Chapter�8.�Backup and Recovery	Next

Backup Strategy

+Backup Strategy

Prev	Chapter�8.�Backup and Recovery	Next

Backup Strategy

The purpose of backup is to enable recovery. Backup and recovery are always risky; here are some steps that minimize the chance recovery is necessary: @@ -28,9 +27,9 @@ OpenACS installations comprise files and database contents. If you follow the reference install and put all files, including configuration files, in - /var/lib/aolserver/$OPENACS_SERVICE_NAME/, + /var/lib/aolserver/$OPENACS_SERVICE_NAME/, and back up the database nightly to a file in - /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup, + /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup, then you can apply standard file-based backup strategies to - /var/lib/aolserver/$OPENACS_SERVICE_NAME + /var/lib/aolserver/$OPENACS_SERVICE_NAME

Prev	Home	Next
Chapter�8.�Backup and Recovery	Up	Manual backup and recovery

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html,v diff -u -r1.16.2.2 -r1.16.2.3 --- openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 22 Apr 2007 10:21:56 -0000 1.16.2.2 +++ openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 14 Jul 2007 12:34:47 -0000 1.16.2.3 @@ -1,19 +1,18 @@ - -Vacuum Postgres nightly

Prev	Chapter�7.�Database Management	Next

Vacuum Postgres nightly

- The "vacuum" command must be run periodically to reclaim space - in versions of PostgreSQL before 7.4. The "vacuum analyze" form +Vacuum Postgres nightly

Prev	Chapter�7.�Database Management	Next

Vacuum Postgres nightly

+ The "vacuum" command must be run periodically to reclaim space + in versions of PostgreSQL before 7.4. The "vacuum analyze" form additionally collects statistics on the disbursion of columns in the database, which the optimizer uses when it calculates just how to execute queries. The availability of this data can make a tremendous difference in the execution speed of queries. This command can also be run from cron, but it probably makes more sense to run this command as part of your nightly backup - procedure - if "vacuum" is going to screw up the database, you'd + procedure - if "vacuum" is going to screw up the database, you'd prefer it to happen immediately after (not before!) you've made a - backup! The "vacuum" command is very reliable, but conservatism is + backup! The "vacuum" command is very reliable, but conservatism is the key to good system management. So, if you're using the export procedure described above, you don't need to do this extra step. -

Edit your crontab:

[joeuser ~]$ crontab -e

We'll set vacuum up to run nightly at 1 AM. Add the following +

Edit your crontab:

[joeuser ~]$ crontab -e

We'll set vacuum up to run nightly at 1 AM. Add the following line:

 0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME

($Id$)

Prev	Home	Next
Deleting a tablespace	Up	Chapter�8.�Backup and Recovery

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -r1.20.2.1 -r1.20.2.2 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 14 Jan 2007 04:20:10 -0000 1.20.2.1 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 14 Jul 2007 12:34:47 -0000 1.20.2.2 @@ -1,26 +1,25 @@ - -Install nsopenssl

Prev	Appendix�B.�Install additional supporting software	Next

Install nsopenssl

By Joel Aufrecht and Malte Sussdorff

+Install nsopenssl

Prev	Appendix�B.�Install additional supporting software	Next

Install nsopenssl

By Joel Aufrecht and Malte Sussdorff

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

This AOLserver module is required if you want people to connect to your site via https. These commands compile nsopenssl and install it, along with a tcl helper script to handle https connections. You will also need ssl certificates. Because those should be different for each server service, you won't need those instructions until - later.

Install on AOLserver3

You will need the unpacked Aolserver tarball in - /usr/local/src/aolserver and + later.

Install on AOLserver3

You will need the unpacked Aolserver tarball in + /usr/local/src/aolserver and the nsopenssl tarball in - /tmp.

Red Hat 9 note: see this - thread for details on compiling nsopenssl.)

[root bin]# cd /usr/local/src/aolserver
-[root aolserver]# wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz
-[root aolserver]# tar xzf nsopenssl-2.1.tar.gz 
-[root aolserver]# cd nsopenssl-2.1
-[root nsopenssl-2.1]# make OPENSSL=/usr/local/ssl
+          /tmp.
Red Hat 9 note: see this
+          thread for details on compiling nsopenssl.)
[root bin]# cd /usr/local/src/aolserver
+[root aolserver]# wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz
+[root aolserver]# tar xzf nsopenssl-2.1.tar.gz 
+[root aolserver]# cd nsopenssl-2.1
+[root nsopenssl-2.1]# make OPENSSL=/usr/local/ssl
 gcc -I/usr/local/ssl/include -I../aolserver/include -D_REENTRANT=1 -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1   -c -o nsopenssl.o nsopenssl.c
 (many lines omitted)
 gcc -shared -nostartfiles -o nsopenssl.so nsopenssl.o config.o init.o ssl.o thread.o tclcmds.o -L/usr/local/ssl/lib -lssl -lcrypto
-[root nsopenssl-2.1]# cp nsopenssl.so /usr/local/aolserver/bin
-[root nsopenssl-2.1]# cp https.tcl /usr/local/aolserver/modules/tcl/
+[root nsopenssl-2.1]# cp nsopenssl.so /usr/local/aolserver/bin
+[root nsopenssl-2.1]# cp https.tcl /usr/local/aolserver/modules/tcl/
 [root nsopenssl-2.1]#
 cd /usr/local/src/aolserver
 wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz
@@ -35,15 +34,15 @@
 cd nsopenssl-2.1
 make OPENSSL=/usr/lib/ssl
 cp nsopenssl.so /usr/local/aolserver/bin
-cp https.tcl /usr/local/aolserver/modules/tcl/

Install on AOLserver4

You will need the AOLserver4 source in /usr/local/src/aolserver/aolserver and OpenSSL installed in /usr/local/ssl (or at least symlinked there). The use of INST=/point/to/aolserver is being replaced with AOLSERVER=/point/to/aolserver. We are including both here, because while this module still requires INST, if one just uses AOLSERVER, the default value would be used and could intefere with another existing installation.

FreeBSD note: build nsopenssl with gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10 -

[root bin]# cd /usr/local/src/aolserver
-[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login
-[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl
-[root aolserver]# cd nsopenssl
-[root nsopenssl]# make OPENSSL=/usr/local/ssl
+cp https.tcl /usr/local/aolserver/modules/tcl/

Install on AOLserver4

FreeBSD note: build nsopenssl with gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10 +

[root bin]# cd /usr/local/src/aolserver
+[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login
+[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl
+[root aolserver]# cd nsopenssl
+[root nsopenssl]# make OPENSSL=/usr/local/ssl
 gcc -I/usr/local/ssl/include (many items omitted)  -c -o sslcontext.o sslcontext.c
 (many lines omitted)
-[root nsopenssl-2.1]# make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10
+[root nsopenssl-2.1]# make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10
 [root nsopenssl-2.1]#
 cd /usr/local/src/aolserver
 cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login
@@ -52,9 +51,9 @@
 make OPENSSL=/usr/local/ssl 
 make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver AOLSERVER=/usr/local/aolserver4r10

If you have problems starting your server with nsopenssl.so due to missing libssl.so.0.9.7 (or lower), you have to create symlinks

-[root nsopenssl]# cd /usr/local/aolserver/lib
-[root lib]# ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7
-[root lib]# ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7
+[root nsopenssl]# cd /usr/local/aolserver/lib
+[root lib]# ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7
+[root lib]# ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7
 [root lib]#
 cd /usr/local/aolserver/lib
 ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7
@@ -64,11 +63,11 @@
 
SSL support must be enabled seperately in each OpenACS
         server (Generate ssl certificates. 
If your ports for SSL are privileged (below 1024), you
         will have to start AOLserver with prebinds for both your HTTP
-        and your HTTPS port (usually by adding -b
-        your_ip:your_http_port,your_ip:your_https_port
+        and your HTTPS port (usually by adding -b
+        your_ip:your_http_port,your_ip:your_https_port
         to the nsd call. If you are using daemontools, this can be
-        changed in your etc/daemontools/run
-        file).
To enable SSL support in your server, make sure your
-      etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If
+        changed in your etc/daemontools/run
+        file).
To enable SSL support in your server, make sure your
+      etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If
       that section is not present, try looking at the README file in
-      /usr/local/src/aolserver/nsopenssl.

Prev	Home	Next
Install Full Text Search using OpenFTS (deprecated see tsearch2)	Up	Install tclwebtest.

docs@openacs.org

View comments on this page at openacs.org + /usr/local/src/aolserver/nsopenssl.

Prev	Home	Next
Install Full Text Search using OpenFTS (deprecated see tsearch2)	Up	Install tclwebtest.

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-nspam.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nspam.html,v diff -u -r1.11.2.1 -r1.11.2.2 --- openacs-4/packages/acs-core-docs/www/install-nspam.html 14 Jan 2007 04:20:10 -0000 1.11.2.1 +++ openacs-4/packages/acs-core-docs/www/install-nspam.html 14 Jul 2007 12:34:47 -0000 1.11.2.2 @@ -1,2 +1 @@ - -Install nspam

Prev	Appendix�B.�Install additional supporting software	Next

Install nspam

/doc/acs-authentication/ext-auth-install.html

Prev	Home	Next
Install Analog web file analyzer	Up	Install Full Text Search using Tsearch2

docs@openacs.org

View comments on this page at openacs.org +Install nspam

Prev	Appendix�B.�Install additional supporting software	Next

Install nspam

/doc/acs-authentication/ext-auth-install.html

Prev	Home	Next
Install Analog web file analyzer	Up	Install Full Text Search using Tsearch2

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html,v diff -u -r1.7.2.1 -r1.7.2.2 --- openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 14 Jan 2007 04:20:10 -0000 1.7.2.1 +++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 14 Jul 2007 12:34:47 -0000 1.7.2.2 @@ -1,25 +1,24 @@ - -Deleting a tablespace

Prev	Chapter�7.�Database Management	Next

Deleting a tablespace

Skip down for instructions on Deleting a PostgreSQL tablespace. -

Deleting an Oracle tablespace

+Deleting a tablespace

Prev	Chapter�7.�Database Management	Next

Deleting a tablespace

Skip down for instructions on Deleting a PostgreSQL tablespace. +

Deleting an Oracle tablespace

Should it become necessary to rebuild a tablespace from scratch, - you can use the drop user command - in SVRMGRL with the cascade + you can use the drop user command + in SVRMGRL with the cascade option. This command will drop the user and every database object - the user owns.

SVRMGR> drop user $OPENACS_SERVICE_NAME cascade;

- If this does not work because svrmgrl "cannot drop a user that - is currently connected", make sure to kill the AOLserver using - this user. If it still does not work, do:

SVRMGR> select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME';

and then

SVRMGR> alter system kill session 'sid, serial#';

+ the user owns.

SVRMGR> drop user $OPENACS_SERVICE_NAME cascade;

+ If this does not work because svrmgrl "cannot drop a user that + is currently connected", make sure to kill the AOLserver using + this user. If it still does not work, do:

SVRMGR> select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME';

and then

SVRMGR> alter system kill session 'sid, serial#';

where sid and serial# are - replaced with the corresponding values for the open session.

Use with caution!

+ replaced with the corresponding values for the open session.

Use with caution!

If you feel the need to delete everything - related to the service, you can also issue the following:

SVRMGR> drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints;

Deleting a PostgreSQL tablespace

+ related to the service, you can also issue the following:

SVRMGR> drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints;

Deleting a PostgreSQL tablespace

Dropping a PostgreSQL tablespace is easy. You have to stop any AOLserver instances that are using the database that you wish to drop. If you're using daemontools, this is simple, just use the 'down' flag (-d). If you're using inittab, you have to comment out - your server in /etc/inittab, - reread the inittab with /sbin/init - q, and then restart-aolserver - $OPENACS_SERVICE_NAME.

Then, to drop the db, just do:

-[$OPENACS_SERVICE_NAME ~]$ dropdb $OPENACS_SERVICE_NAME + your server in /etc/inittab, + reread the inittab with /sbin/init + q, and then restart-aolserver + $OPENACS_SERVICE_NAME.

Then, to drop the db, just do:

+[$OPENACS_SERVICE_NAME ~]$ dropdb $OPENACS_SERVICE_NAME
 DROP DATABASE

Prev	Home	Next
Running a PostgreSQL database on another server	Up	Vacuum Postgres nightly

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html,v diff -u -r1.7.2.1 -r1.7.2.2 --- openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 14 Jan 2007 04:20:10 -0000 1.7.2.1 +++ openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 14 Jul 2007 12:34:47 -0000 1.7.2.2 @@ -1,5 +1,4 @@ - -AOLserver keepalive with inittab

Prev	Chapter�6.�Production Environments	Next

AOLserver keepalive with inittab

This is an alternative method for keeping the AOLserver +AOLserver keepalive with inittab

Prev	Chapter�6.�Production Environments	Next

AOLserver keepalive with inittab

This is an alternative method for keeping the AOLserver process running. The recommended method is to run AOLserver supervised.

This step should be completed as root. This can break every service @@ -8,32 +7,32 @@ There are 2 general steps to getting this working.

Install a script called - restart-aolserver. This + restart-aolserver. This script doesn't actually restart AOLserver - it just kills it.
Ask the OS to restart our service whenever it's not running. We do this by adding a line to - /etc/inittab. + /etc/inittab.

- Calling restart-aolserver + Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling - restart-aolserver effectively + restart-aolserver effectively restarts our service.

Copy this file into - /var/tmp/restart-aolserver.txt. + /var/tmp/restart-aolserver.txt.

This script needs to be SUID-root, which means that the script will run as root. This is necessary to ensure that the AOLserver processes are killed regardless of who owns them. However the script should be executable by the - web group to ensure that the + web group to ensure that the users updating the web page can use the script, but that general system users cannot run the script. You also need to have Perl installed and also a symbolic link to it in - /usr/local/bin. + /usr/local/bin.

 [joeuser ~]$ su - 
 Password: ***********
@@ -42,10 +41,10 @@
 [root ~]# chmod 4750 /usr/local/bin/restart-aolserver
 [root ~]# ln -s /usr/bin/perl /usr/local/bin/perl
 [root ~]# exit

- Test the restart-aolserver + Test the restart-aolserver script. We'll first kill all running servers to clean the slate. Then, we'll start one server and use - restart-aolserver to kill + restart-aolserver to kill it. If it works, then there should be no more servers running. You should see the following lines.

 [joeuser ~]$ killall nsd
@@ -56,34 +55,34 @@
 [joeuser ~]$ killall nsd
 nsd: no process killed

The number 23727 indicates the process id(s) (PIDs) of the - processes being killed. It is important that no processes are killed by the second - call to killall. If there are + processes being killed. It is important that no processes are killed by the second + call to killall. If there are processes being killed, it means that the script is not working.

- Assuming that the restart-aolserver + Assuming that the restart-aolserver script worked, login as root and open - /etc/inittab for + /etc/inittab for editing.

 [joeuser ~]$ su -
 Password: ************
 [root ~]# emacs -nw /etc/inittab

Copy this line into the bottom of the file as a template, making sure that the first field - nss1 is unique. + nss1 is unique.

 nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl

- Important: Make sure there is a + Important: Make sure there is a newline at the end of the file. If there is not a newline at the end of the file, the system may suffer catastrophic failures.

Still as root, enter the following command to re-initialize - /etc/inittab.

+            /etc/inittab. 
 [root ~]# killall nsd    
 nsd: no process killed
 [root ~]# /sbin/init q

See if it worked by running the - restart-aolserver script + restart-aolserver script again.

 [root ~]# restart-aolserver birdnotes
 Killing 23750

Index: openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html,v diff -u -r1.17.2.2 -r1.17.2.3 --- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 22 Apr 2007 10:21:56 -0000 1.17.2.2 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 14 Jul 2007 12:34:47 -0000 1.17.2.3 @@ -1,69 +1,68 @@ - -Starting and Stopping an OpenACS instance.

Prev	Chapter�6.�Production Environments	Next

Starting and Stopping an OpenACS instance.

The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.

A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.

The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.

Daemontools must already be installed. If not, install it.

Each service controlled by daemontools must have a - directory in /service. That +Starting and Stopping an OpenACS instance.

Prev	Chapter�6.�Production Environments	Next

Starting and Stopping an OpenACS instance.

The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.

Daemontools must already be installed. If not, install it.

Each service controlled by daemontools must have a + directory in /service. That directory must have a file called - run. It works like this:

The init program starts every - time the computer is booted.
A line in init's configuration - file, /etc/inittab, tells init to + run. It works like this:
- The init program starts every + time the computer is booted.
- A line in init's configuration + file, /etc/inittab, tells init to run, and to restart if necessary, - svscanboot.
- svscanboot checks - the directory /service + svscanboot.
- svscanboot checks + the directory /service every few seconds.
- If it sees a subdirectory there, it looks for a file in the subdirectory called - run. If it finds a run file, it creates a supervise process
- supervise executes the run script. Whenever the run script stops, supervise executes it again. It also creates additional control files in the same directory.
Hence, the AOLserver + run. If it finds a run file, it creates a supervise process
supervise executes the run script. Whenever the run script stops, supervise executes it again. It also creates additional control files in the same directory.

Hence, the AOLserver instance for your development server is started by the file - /service/$OPENACS_SERVICE_NAME/run. + /service/$OPENACS_SERVICE_NAME/run. But we use a symlink to make it easier to add and remove - stuff from the /service, so + stuff from the /service, so the actual location is - /var/lib/aolserver/$OPENACS_SERVICE_NAMEetc/daemontools/run.

Daemontools creates additional files and directories to track status and + /var/lib/aolserver/$OPENACS_SERVICE_NAMEetc/daemontools/run.

Daemontools creates additional files and directories to track status and log. A daemontools directory is included in the OpenACS tarball at - /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run.

[$OPENACS_SERVICE_NAME etc]$ killall nsd + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run.

[$OPENACS_SERVICE_NAME etc]$ killall nsd
 nsd: no process killed
-[$OPENACS_SERVICE_NAME etc]$ emacs /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run
-[$OPENACS_SERVICE_NAME etc]$ exit
+[$OPENACS_SERVICE_NAME etc]$ emacs /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run
+[$OPENACS_SERVICE_NAME etc]$ exit
 
-[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/ /service/$OPENACS_SERVICE_NAME

Verify that AOLserver is running.

[root root]# ps -auxw | grep nsd
+[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/ /service/$OPENACS_SERVICE_NAME

Verify that AOLserver is running.

[root root]# ps -auxw | grep nsd
 $OPENACS_SERVICE_NAME   5562 14.4  6.2 22436 15952 ?       S    11:55   0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl -u serve
 root      5582  0.0  0.2  3276  628 pts/0    S    11:55   0:00 grep nsd
 [root root]#

The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands:
- - svc -d /service/$OPENACS_SERVICE_NAME - + svc -d /service/$OPENACS_SERVICE_NAME - Bring the server down
- - svc -u /service/$OPENACS_SERVICE_NAME - + svc -u /service/$OPENACS_SERVICE_NAME - Start the server up and leave it in keepalive mode.
- - svc -o /service/$OPENACS_SERVICE_NAME - + svc -o /service/$OPENACS_SERVICE_NAME - Start the server up once. Do not restart it if it stops.
- - svc -t /service/$OPENACS_SERVICE_NAME - + svc -t /service/$OPENACS_SERVICE_NAME - Stop and immediately restart the server.
- - svc -k /service/$OPENACS_SERVICE_NAME - + svc -k /service/$OPENACS_SERVICE_NAME - Sends the server a KILL signal. This is like KILL -9. AOLserver exits immediately. If svc -t fails to fully kill AOLserver, use this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately.

Install a script to automate the stopping and starting - of AOLserver services via daemontools. You can then restart a service via restart-aolserver $OPENACS_SERVICE_NAME

[root root]# cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver -[root root]# chmod 755 /usr/local/bin/restart-aolserver + of AOLserver services via daemontools. You can then restart a service via restart-aolserver $OPENACS_SERVICE_NAME

[root root]# cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver
+[root root]# chmod 755 /usr/local/bin/restart-aolserver
 [root root]#

At this point, these commands will work only for the - root user. Grant permission for the web group to use svc commands on the $OPENACS_SERVICE_NAME server.
```
[root root]# /usr/local/bin/svgroup web /service/$OPENACS_SERVICE_NAME
-[root root]#
```
Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands. + root user. Grant permission for the web group to use svc commands on the $OPENACS_SERVICE_NAME server.
```
[root root]# /usr/local/bin/svgroup web /service/$OPENACS_SERVICE_NAME
+[root root]#
```
Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands.
Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO. -

Table�6.1.�How it Works

Program	Invoked by this program ...	... using this file	Where to find errors	Log goes to	Use these commands to control it
svscanboot -	init	/etc/inittab	ps -auxw \| grep readproctitle	n/a	�
aolserver	supervise -(a child of svscanboot)	/service/$OPENACS_SERVICE_NAME/run	/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log	/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.log	svc -k /service/$OPENACS_SERVICE_NAME
postgresql	Redhat init scripts during boot	/etc/init.d/postgresql	/usr/local/pgsql/data/server.log	�	service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)

Prev	Home	Next
Chapter�6.�Production Environments	Up	AOLserver keepalive with inittab

docs@openacs.org

View comments on this page at openacs.org +

Table�6.1.�How it Works

Program	Invoked by this program ...	... using this file	Where to find errors	Log goes to	Use these commands to control it
svscanboot +	init	/etc/inittab	ps -auxw \| grep readproctitle	n/a	�
aolserver	supervise +(a child of svscanboot)	/service/$OPENACS_SERVICE_NAME/run	/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log	/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.log	svc -k /service/$OPENACS_SERVICE_NAME
postgresql	Redhat init scripts during boot	/etc/init.d/postgresql	/usr/local/pgsql/data/server.log	�	service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)

Prev	Home	Next
Chapter�6.�Production Environments	Up	AOLserver keepalive with inittab

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-origins.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-origins.html,v diff -u -r1.11.2.1 -r1.11.2.2 --- openacs-4/packages/acs-core-docs/www/install-origins.html 14 Jan 2007 04:20:10 -0000 1.11.2.1 +++ openacs-4/packages/acs-core-docs/www/install-origins.html 14 Jul 2007 12:34:47 -0000 1.11.2.2 @@ -1,5 +1,4 @@ - -Where did this document come from?

Prev	Appendix�C.�Credits	Next

Where did this document come from?

+Where did this document come from?

Prev	Appendix�C.�Credits	Next

Where did this document come from?

This document was created by Vinod Kurup, but it's really just plagiarism from a number of documents that came before it. If I've used something that you've written without proper credit, let me Index: openacs-4/packages/acs-core-docs/www/install-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v diff -u -r1.27.2.1 -r1.27.2.2 --- openacs-4/packages/acs-core-docs/www/install-overview.html 14 Jan 2007 04:20:10 -0000 1.27.2.1 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 14 Jul 2007 12:34:47 -0000 1.27.2.2 @@ -1,5 +1,4 @@ - -Chapter�2.�Installation Overview

Prev	Part�II.�Administrator's Guide	Next

Chapter�2.�Installation Overview

Table of Contents

Basic Steps
Prerequisite Software

by Vinod Kurup

+Chapter�2.�Installation Overview

Prev	Part�II.�Administrator's Guide	Next

Chapter�2.�Installation Overview

Table of Contents

Basic Steps
Prerequisite Software

by Vinod Kurup

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Prev	Home	Next
Part�II.�Administrator's Guide	Up	Basic Steps

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-pam-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-pam-radius.html,v diff -u -r1.4.2.1 -r1.4.2.2 --- openacs-4/packages/acs-core-docs/www/install-pam-radius.html 14 Jan 2007 04:20:10 -0000 1.4.2.1 +++ openacs-4/packages/acs-core-docs/www/install-pam-radius.html 14 Jul 2007 12:34:47 -0000 1.4.2.2 @@ -1,12 +1,11 @@ - -Install PAM Radius for use as external authentication

Prev	Appendix�B.�Install additional supporting software	Next

Install PAM Radius for use as external authentication

By Malte Sussdorff

+Install PAM Radius for use as external authentication

Prev	Appendix�B.�Install additional supporting software	Next

Install PAM Radius for use as external authentication

By Malte Sussdorff

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

This step by step guide is derived from the installation instructions which you can find at yourdomain.com/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.

Install ns_pam.�Download and install ns_pam

[root aolserver]# cd /usr/local/src/aolserver/
-          [root aolserver]# wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz
-          [root aolserver]# tar xvfz ns_pam-0.1.tar.gz
-          [root aolserver]# cd ns_pam-0.1
-          [root ns_pam-0.1]# make install INST=/usr/local/aolserver
+

Install ns_pam.�Download and install ns_pam

[root aolserver]# cd /usr/local/src/aolserver/
+          [root aolserver]# wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz
+          [root aolserver]# tar xvfz ns_pam-0.1.tar.gz
+          [root aolserver]# cd ns_pam-0.1
+          [root ns_pam-0.1]# make install INST=/usr/local/aolserver
           [root ns_pam-0.1]#
 cd /usr/local/src/aolserver/
 wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz
@@ -16,23 +15,23 @@

Configure ns_pam.�Configure AOLserver for ns_pam
To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.
- Change config.tcl. Remove the - # in front of ns_param - nspam ${bindir}/nspam.so to enable the loading + # in front of ns_param + nspam ${bindir}/nspam.so to enable the loading of the ns_pam module.
- Change config.tcl. Replace - pam_domain in the section - ns/server/${server}/module/nspam - with aolserver + pam_domain in the section + ns/server/${server}/module/nspam + with aolserver
- Create /etc/pam.d/aolserver.
```
-              [root ns_pam]#cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver
-            
```

Configure PAM Radius.�Configure and install PAM Radius

You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.

[root ns_pam]# cd /usr/local/src/
-          [root src]# wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar
-          [root src]# tar xvf pam_radius-1.3.16
-          [root src]# cd pam_radius
-          [root pam_radius]# make
-          [root pam_radius]# cp pam_radius_auth.so /lib/security/
+              [root ns_pam]#cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver
+

Configure PAM Radius.�Configure and install PAM Radius

You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.

[root ns_pam]# cd /usr/local/src/
+          [root src]# wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar
+          [root src]# tar xvf pam_radius-1.3.16
+          [root src]# cd pam_radius
+          [root pam_radius]# make
+          [root pam_radius]# cp pam_radius_auth.so /lib/security/
           [root pam_radius]#
 cd /usr/local/src
 wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar
@@ -41,6 +40,6 @@
 make
 cp pam_radius_auth.so /lib/security/
 
-

Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.

[root pam_radius]# echo "radius.yourdomain.com:1645 your_radius_password >>/etc/rddb/server
-          [root src]# chown service0:web /etc/rddb/server
+

[root pam_radius]# echo "radius.yourdomain.com:1645 your_radius_password >>/etc/rddb/server
+          [root src]# chown service0:web /etc/rddb/server

Prev	Home	Next
Install Squirrelmail for use as a webmail system for OpenACS	Up	Install LDAP for use as external authentication

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-php.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-php.html,v diff -u -r1.9.2.1 -r1.9.2.2 --- openacs-4/packages/acs-core-docs/www/install-php.html 14 Jan 2007 04:20:10 -0000 1.9.2.1 +++ openacs-4/packages/acs-core-docs/www/install-php.html 14 Jul 2007 12:34:47 -0000 1.9.2.2 @@ -1,12 +1,11 @@ - -Install PHP for use in AOLserver

Prev	Appendix�B.�Install additional supporting software	Next

Install PHP for use in AOLserver

By Malte Sussdorff

+Install PHP for use in AOLserver

Prev	Appendix�B.�Install additional supporting software	Next

Install PHP for use in AOLserver

By Malte Sussdorff

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from www.php.net. For convenience we get version 4.3.4 from a mirror

[root root]# cd /usr/local/src
-[root src]# wget http://de3.php.net/distributions/php-4.3.4.tar.gz
-[root src]# tar xfz php-4.3.4.tar.gz
-[root src]# cd php-4.3.4
-[root php-4.3.4]# cd php-4.3.4
-[root php-4.3.4]#  ./configure --with-aolserver=/usr/local/aolserver/ --with-pgsql=/usr/local/pgsql --without-mysql
-[root php-4.3.4]# make install
-

Once installed you can enable this by configuring your config file. Make sure your config file supports php (it should have a php section with it). Furthermore add index.php as the last element to your directoryfile directive.

Prev	Home	Next
Install tclwebtest.	Up	Install Squirrelmail for use as a webmail system for OpenACS

docs@openacs.org

View comments on this page at openacs.org +

[root root]# cd /usr/local/src
+[root src]# wget http://de3.php.net/distributions/php-4.3.4.tar.gz
+[root src]# tar xfz php-4.3.4.tar.gz
+[root src]# cd php-4.3.4
+[root php-4.3.4]# cd php-4.3.4
+[root php-4.3.4]#  ./configure --with-aolserver=/usr/local/aolserver/ --with-pgsql=/usr/local/pgsql --without-mysql
+[root php-4.3.4]# make install
+

Prev	Home	Next
Install tclwebtest.	Up	Install Squirrelmail for use as a webmail system for OpenACS

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-qmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v diff -u -r1.34.2.2 -r1.34.2.3 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 22 Apr 2007 10:21:56 -0000 1.34.2.2 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 14 Jul 2007 12:34:47 -0000 1.34.2.3 @@ -1,53 +1,52 @@ - -Install qmail (OPTIONAL)

Prev	Appendix�B.�Install additional supporting software	Next

Install qmail (OPTIONAL)

Qmail is a Mail Transfer Agent. It handles incoming and +Install qmail (OPTIONAL)

Prev	Appendix�B.�Install additional supporting software	Next

Install qmail (OPTIONAL)

Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.

Red Hat 9: all djb tools (qmail, daemontools, ucspi) will fail to compile in Red Hat 9 because of changes to glibc (patches)

Install ucspi.�This program handles incoming tcp connections. - Download ucspi and install it.

[root root]# cd /usr/local/src
-[root src]# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz
-[root src]# tar xzf ucspi-tcp-0.88.tar.gz
+            Download ucspi and install it.
[root root]# cd /usr/local/src
+[root src]# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz
+[root src]# tar xzf ucspi-tcp-0.88.tar.gz
 cd /usr/local/src 
 wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz
 tar xzf ucspi-tcp-0.88.tar.gz 
Red Hat 9 only
wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch
 cd ucspi-tcp-0.88
 patch -p1 <../ucspi-tcp-0.88.errno.patch
-cd ..
All platforms continue:
[root src]# cd ucspi-tcp-0.88
-[root ucspi-tcp-0.88]# make
+cd ..
All platforms continue:
[root src]# cd ucspi-tcp-0.88
+[root ucspi-tcp-0.88]# make
 ( cat warn-auto.sh; \
-echo 'main="$1"; shift'; \(many lines omitted)
+echo 'main="$1"; shift'; \(many lines omitted)
 ./compile instcheck.c
 ./load instcheck hier.o auto_home.o unix.a byte.a
-[root ucspi-tcp-0.88]# make setup check
+[root ucspi-tcp-0.88]# make setup check
 ./install
 ./instcheck
 [root ucspi-tcp-0.88]#
 
 cd ucspi-tcp-0.88 
 make 
 make setup check
Verify that ucspi-tcp was installed successfully by
-running the tcpserver program which is part of ucspi-tcp:
[root ucspi-tcp-0.88]# tcpserver
+running the tcpserver program which is part of ucspi-tcp:
[root ucspi-tcp-0.88]# tcpserver
 tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid
 ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program
 [root ucspi-tcp-0.88]#
-

+

 (I'm not sure if this next step is 100% necessary, but when I skip it
-I get problems.  If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.)  AOLserver sends outgoing mail via the ns_sendmail
+I get problems.  If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.)  AOLserver sends outgoing mail via the ns_sendmail
 command, which pipes a command to the sendmail executable.  Or, in our
 case, the qmail replacement wrapper for the sendmail executable.  In
 some cases, though, the outgoing mail requset is apparently sent
 through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP
-address that means the local machine - the "loopback" interface).
+address that means the local machine - the "loopback" interface).
 Unless this mail is addressed to the same machine, qmail thinks that
 it's an attempt to relay mail, and rejects it.  So these two commands
 set up an exception so that any mail sent from 127.0.0.1 is allowed to
-send outgoing mail.
[root ucspi-tcp-0.88]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
-[root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp 
-tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp

Install Qmail.�

Download qmail, - set up the standard supporting users and build the binaries:

[root root]# cd /usr/local/src -[root src]# wget http://www.qmail.org/netqmail-1.04.tar.gz -[root src]# tar xzf netqmail-1.04.tar.gz +send outgoing mail.

[root ucspi-tcp-0.88]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp
+[root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp 
+tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp

Install Qmail.�

Download qmail, + set up the standard supporting users and build the binaries:

[root root]# cd /usr/local/src
+[root src]# wget http://www.qmail.org/netqmail-1.04.tar.gz
+[root src]# tar xzf netqmail-1.04.tar.gz
 --15:04:11--  http://www.qmail.org/netqmail-1.04.tar.gz
            => `netqmail-1.04.tar.gz'
 Resolving www.qmail.org... done.
@@ -59,18 +58,18 @@
 
 15:04:21 (24.04 KB/s) - `netqmail-1.04.tar.gz' saved [242310/242310]
 
-[root src]# mkdir /var/qmail
-[root src]# groupadd nofiles
-[root src]# useradd -g nofiles -d /var/qmail/alias alias
-[root src]# useradd -g nofiles -d /var/qmail qmaild
-[root src]# useradd -g nofiles -d /var/qmail qmaill
-[root src]# useradd -g nofiles -d /var/qmail qmailp
-[root src]# groupadd qmail
-[root src]# useradd -g qmail -d /var/qmail qmailq
-[root src]# useradd -g qmail -d /var/qmail qmailr
-[root src]# useradd -g qmail -d /var/qmail qmails
-[root src]# cd netqmail-1.04
-[root netqmail-1.04]# ./collate.sh
+[root src]# mkdir /var/qmail
+[root src]# groupadd nofiles
+[root src]# useradd -g nofiles -d /var/qmail/alias alias
+[root src]# useradd -g nofiles -d /var/qmail qmaild
+[root src]# useradd -g nofiles -d /var/qmail qmaill
+[root src]# useradd -g nofiles -d /var/qmail qmailp
+[root src]# groupadd qmail
+[root src]# useradd -g qmail -d /var/qmail qmailq
+[root src]# useradd -g qmail -d /var/qmail qmailr
+[root src]# useradd -g qmail -d /var/qmail qmails
+[root src]# cd netqmail-1.04
+[root netqmail-1.04]# ./collate.sh
 
 You should see 7 lines of text below.  If you see anything
 else, then something might be wrong.
@@ -81,8 +80,8 @@
 [5] Renaming qmail-1.03 to netqmail-1.04...
 [6] Continue installing qmail using the instructions found at:
 [7] http://www.lifewithqmail.org/lwq.html#installation
-[root netqmail-1.04]# cd netqmail-1.04
-[root netqmail-1.04]# make setup check
+[root netqmail-1.04]# cd netqmail-1.04
+[root netqmail-1.04]# make setup check
 ( cat warn-auto.sh; \
 echo CC=\'`head -1 conf-cc`\'; \(many lines omitted)
 ./install
@@ -103,11 +102,11 @@
 cd netqmail-1.04
 ./collate.sh
 cd netqmail-1.04
-make setup check

Replace sendmail with qmail's wrapper.

[root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail
-[root qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
+make setup check

Replace sendmail with qmail's wrapper.

[root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail
+[root qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
 [root qmail-1.03]#
 rm -f /usr/bin/sendmail /usr/sbin/sendmail
-ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail

Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.

[root qmail-1.03]# ./config-fast yourserver.test
+ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail

[root qmail-1.03]# ./config-fast yourserver.test
 Your fully qualified host name is yourserver.test.
 Putting yourserver.test into control/me...
 Putting yourserver.test into control/defaultdomain...
@@ -117,66 +116,66 @@
 Now qmail will refuse to accept SMTP messages except to yourserver.test.
 Make sure to change rcpthosts if you add hosts to locals or virtualdomains!
 [root qmail-1.03]#
-./config-fast yourserver.test

All incoming mail that isn't for a specific user is handled by the alias user. This includes all root mail. These commands prepare the alias user to receive mail.

[root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
-[root alias]# chmod 644 ~alias/.qmail*
-[root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/
-[root alias]# chown -R alias.nofiles /var/qmail/alias/Maildir
+./config-fast yourserver.test

All incoming mail that isn't for a specific user is handled by the alias user. This includes all root mail. These commands prepare the alias user to receive mail.

[root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root
+[root alias]# chmod 644 ~alias/.qmail*
+[root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/
+[root alias]# chown -R alias.nofiles /var/qmail/alias/Maildir
 [root alias]#
 cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root 
 chmod 644 ~alias/.qmail* 
 /var/qmail/bin/maildirmake ~alias/Maildir/ 
-chown -R alias.nofiles /var/qmail/alias/Maildir

Configure qmail to use the Maildir delivery format - (instead of mbox), and install a version of the qmail startup script modified to use Maildir.

[root alias]# echo "./Maildir" > /var/qmail/bin/.qmail
-[root alias]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc
-[root alias]# chmod 755 /var/qmail/rc
+chown -R alias.nofiles /var/qmail/alias/Maildir

Configure qmail to use the Maildir delivery format + (instead of mbox), and install a version of the qmail startup script modified to use Maildir.

[root alias]# echo "./Maildir" > /var/qmail/bin/.qmail
+[root alias]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc
+[root alias]# chmod 755 /var/qmail/rc
 [root alias]# 
-echo "./Maildir" > /var/qmail/bin/.qmail 
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc 
+echo "./Maildir" > /var/qmail/bin/.qmail 
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc 
 chmod 755 /var/qmail/rc

Set up the skeleton directory so that new users will - be configured for qmail.

[root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir -[root root]# echo "./Maildir/" > /etc/skel/.qmail + be configured for qmail.

[root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir
+[root root]# echo "./Maildir/" > /etc/skel/.qmail
 [root root]# 
 /var/qmail/bin/maildirmake /etc/skel/Maildir
-echo "./Maildir/" > /etc/skel/.qmail

As recommended, we will run qmail with daemontools - control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.

[root root]# mkdir -p /var/qmail/supervise/qmail-send/log
-[root root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log
-[root root]# mkdir /var/log/qmail
-[root root]# chown qmaill /var/log/qmail
-[root root]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
-[root root]# chmod 755 /var/qmail/bin/qmailctl
-[root root]# ln -s /var/qmail/bin/qmailctl /usr/bin
-[root root]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run 
-[root root]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
-[root root]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
-[root root]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
-[root root]# chmod 755 /var/qmail/supervise/qmail-send/run
-[root root]# chmod 755 /var/qmail/supervise/qmail-send/log/run
-[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run
-[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/log/run
-[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
-[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
+echo "./Maildir/" > /etc/skel/.qmail

As recommended, we will run qmail with daemontools + control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.

[root root]# mkdir -p /var/qmail/supervise/qmail-send/log
+[root root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log
+[root root]# mkdir /var/log/qmail
+[root root]# chown qmaill /var/log/qmail
+[root root]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
+[root root]# chmod 755 /var/qmail/bin/qmailctl
+[root root]# ln -s /var/qmail/bin/qmailctl /usr/bin
+[root root]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run 
+[root root]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
+[root root]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
+[root root]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
+[root root]# chmod 755 /var/qmail/supervise/qmail-send/run
+[root root]# chmod 755 /var/qmail/supervise/qmail-send/log/run
+[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run
+[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/log/run
+[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
+[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
 mkdir -p /var/qmail/supervise/qmail-send/log
 mkdir -p /var/qmail/supervise/qmail-smtpd/log
 mkdir /var/log/qmail
 chown qmaill /var/log/qmail
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl
 chmod 755 /var/qmail/bin/qmailctl
 ln -s /var/qmail/bin/qmailctl /usr/bin
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run
 chmod 755 /var/qmail/supervise/qmail-send/run
 chmod 755 /var/qmail/supervise/qmail-send/log/run
 chmod 755 /var/qmail/supervise/qmail-smtpd/run
 chmod 755 /var/qmail/supervise/qmail-smtpd/log/run
 ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service
-

Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.

[root root]# qmailctl stat
+

[root root]# qmailctl stat
 /service/qmail-send: up (pid 32700) 430 seconds
 /service/qmail-send/log: up (pid 32701) 430 seconds
 /service/qmail-smtpd: up (pid 32704) 430 seconds
 /service/qmail-smtpd/log: up (pid 32705) 430 seconds
 messages in queue: 0
 messages in queue but not yet preprocessed: 0
-[root root]#

Further verify by sending and receiving email. Incoming mail for root is stored in /var/qmail/alias/Maildir.

Prev	Home	Next
Install Daemontools (OPTIONAL)	Up	Install Analog web file analyzer

docs@openacs.org

View comments on this page at openacs.org +[root root]#

Further verify by sending and receiving email. Incoming mail for root is stored in /var/qmail/alias/Maildir.

Prev	Home	Next
Install Daemontools (OPTIONAL)	Up	Install Analog web file analyzer

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -r1.34.2.2 -r1.34.2.3 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 22 Apr 2007 10:21:56 -0000 1.34.2.2 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 14 Jul 2007 12:34:47 -0000 1.34.2.3 @@ -1,5 +1,4 @@ - -Appendix�A.�Install Red Hat 8/9

Prev	Part�II.�Administrator's Guide	Next

Appendix�A.�Install Red Hat 8/9

by Joel Aufrecht

+Appendix�A.�Install Red Hat 8/9

Prev	Part�II.�Administrator's Guide	Next

Appendix�A.�Install Red Hat 8/9

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

This section takes a blank PC and sets up some supporting @@ -16,8 +15,8 @@

(For Oracle) Starting an X server and running an X program remotely

- Basic file management using cp, rm, - mv, and cd + Basic file management using cp, rm, + mv, and cd

Compiling a program using ./config and make.

@@ -27,35 +26,35 @@

Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. - + (Wherever you see - the word secure, you should always read it as, "secure + the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're willing to exert and the estimated risk and - consequences.")
Insert Red Hat 8.0 or 9.0 Disk 1 into the + consequences.")
Insert Red Hat 8.0 or 9.0 Disk 1 into the CD-ROM and reboot the computer
At the - boot: + boot: prompt, press Enter for a graphical install. The text install is fairly different, so if you need to do that instead proceed with caution, because the guide won't match the steps.
Checking the media is probably a waste of time, so when it asks press Tab and - then Enter to skip it.
After the graphical introduction page loads, click Next
Choose the language you want to use and then click -Next -
Select the keyboard layout you will use and Click Next
Choose your mouse type and Click Next
Red Hat has several templates for new - computers. We'll start with the "Server" template and then + then Enter to skip it.
After the graphical introduction page loads, click Next
Choose the language you want to use and then click +Next +
Select the keyboard layout you will use and Click Next
Choose your mouse type and Click Next
Red Hat has several templates for new + computers. We'll start with the "Server" template and then fine-tune it during the rest of the install. Choose - Server + Server and click - Next.
Reformat the hard drive. If you know what you're doing, + Next.
Reformat the hard drive. If you know what you're doing, do this step on your own. Otherwise: we're going to let the installer wipe out the everything on the main hard drive and then arrange things to - its liking.
1. Choose Automatically Partition - and click Next
2. Uncheck -Review (and modify if needed) the partitions created and click Next
3. On the pop-up window asking "Are you sure - you want to do this?" click - Yes - IF YOU ARE WIPING YOUR HARD DRIVE.
4. Click Next on the boot loader screen
Configure Networking. + its liking.
1. Choose Automatically Partition + and click Next
2. Uncheck +Review (and modify if needed) the partitions created and click Next
3. On the pop-up window asking "Are you sure + you want to do this?" click + Yes + IF YOU ARE WIPING YOUR HARD DRIVE.
4. Click Next on the boot loader screen
Configure Networking. Again, if you know what you're doing, do this step yourself, being sure to note the firewall holes. Otherwise, follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
1. DHCP is a system by which a computer that @@ -64,21 +63,21 @@ IP address (if it doesn't, it will be tricky to access the OpenACS service from the outside world), we're going to set up that address. If you don't know your netmask, 255.255.255.0 is usually a pretty safe -guess. Click Edit, uncheck Configure using DHCP -and type in your IP and netmask. Click Ok.
2. Type in your host -name, gateway, and DNS server(s). Then click Next.
3. We're going to use the firewall template for high +guess. Click Edit, uncheck Configure using DHCP +and type in your IP and netmask. Click Ok.
4. Type in your host +name, gateway, and DNS server(s). Then click Next.
5. We're going to use the firewall template for high security, meaning that we'll block almost all incoming traffic. Then we'll add a few holes to the firewall for services which we need and -know are secure. Choose High +know are secure. Choose High security level. Check -WWW, -SSH, and -Mail (SMTP). In the Other ports -box, enter 443, 8000, 8443. Click -Next. -Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
Select any additional languages you want the +WWW, +SSH, and +Mail (SMTP). In the Other ports +box, enter 443, 8000, 8443. Click +Next. +Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.

Select any additional languages you want the computer to support and then click - Next

Choose your time zone and click Next.

Type in a root + Next

Choose your time zone and click Next.

Type in a root password, twice.

On the Package selection page, we're going to uncheck a lot of packages that install software we don't need, and add packages that have stuff we do need. You should install everything @@ -88,54 +87,54 @@ risk that's still screened by the firewall, or a resource hog. Just don't install a database or web server, because that would conflict with the database and web server we'll install later. -

check Editors (this installs emacs),

click Details next to Text-based Internet, check lynx, and click OK;

check Authoring and Publishing (this installs docbook),

uncheck Server Configuration Tools,

uncheck Web Server,

uncheck Windows File Server,

check SQL Database Server (this installs PostgreSQL),

check Development Tools (this installs gmake and other build tools),

uncheck Administration Tools, and

uncheck Printing Support.

At the bottom, check Select Individual Packages and click Next

We need to fine-tune the exact list of packages. +

check Editors (this installs emacs),

click Details next to Text-based Internet, check lynx, and click OK;

check Authoring and Publishing (this installs docbook),

uncheck Server Configuration Tools,

uncheck Web Server,

uncheck Windows File Server,

check SQL Database Server (this installs PostgreSQL),

check Development Tools (this installs gmake and other build tools),

uncheck Administration Tools, and

uncheck Printing Support.

At the bottom, check Select Individual Packages and click Next

We need to fine-tune the exact list of packages. The same rules apply as in the last step - you can add more stuff, but you shouldn't remove anything the guide adds. We're going to go through all the packages in one big list, so select -Flat -View and wait. In a minute, a -list of packages will appear.

uncheck apmd (monitors power, not very useful for servers),

check ImageMagick (required for the photo-album packages,

uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon),

check mutt (a mail program that reads Maildir),

uncheck nfs-utils (nfs is a major security risk),

uncheck pam-devel (I don't remember why, but we don't want this),

uncheck portmap,

uncheck postfix (this is an MTA, but we're going to install qmail later),

check postgresql-devel,

uncheck rsh (rsh is a security hole),

uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),

check tcl (we need tcl), and

uncheck xinetd (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp).

Click Next

Red Hat isn't completely happy with the combination +Flat +View and wait. In a minute, a +list of packages will appear.

uncheck apmd (monitors power, not very useful for servers),

check ImageMagick (required for the photo-album packages,

uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon),

check mutt (a mail program that reads Maildir),

uncheck nfs-utils (nfs is a major security risk),

uncheck pam-devel (I don't remember why, but we don't want this),

uncheck portmap,

uncheck postfix (this is an MTA, but we're going to install qmail later),

check postgresql-devel,

uncheck rsh (rsh is a security hole),

uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),

check tcl (we need tcl), and

uncheck xinetd (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp).

Click Next

Red Hat isn't completely happy with the combination of packages we've selected, and wants to satisfy some dependencies. Don't let it. On the next screen, choose -Ignore Package -Dependencies and click -Next. +Ignore Package +Dependencies and click +Next.

Click - Next + Next to start the copying of files.

Wait. Insert Disk 2 when asked.

Wait. Insert Disk 3 when asked.

If you know how to use it, create a boot disk. Since you can also boot into recovery mode with the Install CDs, this is less useful than it used to be, and we - won't bother. Select No,I do not want to create a boot disk and click Next.

Click Exit, remove the CD, and watch the + won't bother. Select No,I do not want to create a boot disk and click Next.

Click Exit, remove the CD, and watch the computer reboot.

After it finishes rebooting and shows the login - prompt, log in:

yourserver login: root + prompt, log in:

yourserver login: root
 Password:
 [root root]#

Install any security patches. For example, insert your CD with - patches, mount it with mount - /dev/cdrom, then cd - /mnt/cdrom, then rpm -UVH - *rpm. Both Red Hat 8.0 and 9.0 have had both + patches, mount it with mount + /dev/cdrom, then cd + /mnt/cdrom, then rpm -UVH + *rpm. Both Red Hat 8.0 and 9.0 have had both kernel and openssl/openssh root exploits, so you should be upgrading all of that. Since you are upgrading the kernel, reboot after this step.

Lock down SSH

- + SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming ssh connections. As a security precaution, we are now going to tell ssh not to allow anyone to connect directly to this computer as root. Type this into the shell: -
```
emacs /etc/ssh/sshd_config
```
Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.

Make the following changes:

#Protocol 2,1 to - Protocol 2 - (this prevents any connections via SSH 1, which is insecure)

#PermitRootLogin yes to - PermitRootLogin no +

emacs /etc/ssh/sshd_config

Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.

Make the following changes:

#Protocol 2,1 to + Protocol 2 + (this prevents any connections via SSH 1, which is insecure)

#PermitRootLogin yes to + PermitRootLogin no (this prevents the root user from logging in remotely via ssh. If you do this, be sure to create a remote access - account, such as "remadmin", which you can use to get ssh - before using "su" to become root)

#PermitEmptyPasswords no to PermitEmptyPasswords no - (this blocks passwordless accounts) and save and exit by typing C-x C-s C-x C-c

Restart sshd so that the change takes effect.

service sshd restart

+ account, such as "remadmin", which you can use to get ssh + before using "su" to become root)

#PermitEmptyPasswords no to PermitEmptyPasswords no + (this blocks passwordless accounts) and save and exit by typing C-x C-s C-x C-c

Restart sshd so that the change takes effect.
```
service sshd restart
```

Red Hat still installed a few services we don't need, and which can be security holes. Use the service command to turn them off, and then use chkconfig to automatically edit the @@ -149,34 +148,34 @@ (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's had any trouble leaving PostgreSQL the way it is.) -

[root root]# service pcmcia stop
-[root root]# service netfs stop
-[root root]# chkconfig --del pcmcia
-[root root]# chkconfig --del netfs
+       
[root root]# service pcmcia stop
+[root root]# service netfs stop
+[root root]# chkconfig --del pcmcia
+[root root]# chkconfig --del netfs
 [root root]#
 service pcmcia stop
 service netfs stop
 chkconfig --del pcmcia
 chkconfig --del netfs
If you installed PostgreSQL, do also
-service postgresql start and chkconfig --add postgresql.

Plug in the network cable.

Verify that you have connectivity by going to another +service postgresql start and chkconfig --add postgresql.

Plug in the network cable.

Verify that you have connectivity by going to another computer and ssh'ing to yourserver, logging in as - remadmin, and promoting yourself to root:

[joeuser@someotherserver]$  ssh remadmin@yourserver.test
+          remadmin, and promoting yourself to root:
[joeuser@someotherserver]$  ssh remadmin@yourserver.test
 The authenticity of host 'yourserver.test (1.2.3.4)' can't be established.
 DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5.
-Are you sure you want to continue connecting (yes/no)? yes
+Are you sure you want to continue connecting (yes/no)? yes
 Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts.
 Password:
 Last login: Mon Mar  3 21:15:27 2003 from host-12-01.dsl-sea.seanet.com
-[remadmin remadmin]$ su -
+[remadmin remadmin]$ su -
 Password: 
 [root root]#

If you didn't burn a CD of patches and use it, can still download and install the necessary patches. Here's how to do it for the kernel; you should also check for other critical packages.

Upgrade the kernel to fix a security hole. The default Red Hat 8.0 system kernel (2.4.18-14, which you can check - with uname -a) has several security problems. Download the new kernel, install it, and reboot.

[root root]# cd /var/tmp
-[root tmp]# wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
+          with uname -a) has several security problems.  Download the new kernel, install it, and reboot.
[root root]# cd /var/tmp
+[root tmp]# wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
 --20:39:00--  http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
            => `kernel-2.4.18-27.7.x.i686.rpm'
 Resolving updates.redhat.com... done.
@@ -188,11 +187,11 @@
 
 20:41:39 (78.38 KB/s) - `kernel-2.4.18-27.7.x.i686.rpm' saved [12736430/12736430]
 
-root@yourserver tmp]# rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm
+root@yourserver tmp]# rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm
 warning: kernel-2.4.18-27.7.x.i686.rpm: V3 DSA signature: NOKEY, key ID db42a60e
 Preparing...                ########################################### [100%]
    1:kernel                 ########################################### [100%]
-[root tmp]# reboot
+[root tmp]# reboot
 
 Broadcast message from root (pts/0) (Sat May  3 20:46:39 2003):
 
Index: openacs-4/packages/acs-core-docs/www/install-resources.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-resources.html,v
diff -u -r1.11.2.1 -r1.11.2.2
--- openacs-4/packages/acs-core-docs/www/install-resources.html	14 Jan 2007 04:20:10 -0000	1.11.2.1
+++ openacs-4/packages/acs-core-docs/www/install-resources.html	14 Jul 2007 12:34:47 -0000	1.11.2.2
@@ -1,7 +1,6 @@
-
-ResourcesPrev Appendix�C.�Credits  Next
Resources

+Resources
Prev Appendix�C.�Credits  Next
Resources

       Here are some resources that OpenACS users have found useful.
-    
Books

+    
Books

 
             Philip
             and Alex's Guide to Web Publishing - A very readable
@@ -16,8 +15,8 @@
           

 
             UNIX
-            System Administration Handbook (formerly the "red book"
-            - now the "purple" book)
+            System Administration Handbook (formerly the "red book"
+            - now the "purple" book)
 
           
 
 
@@ -34,7 +33,7 @@
             Linux
               in a Nutshell 
 
-          
Web Sites

+          
Web Sites

 
             The UNIX
               Reference Desk
Index: openacs-4/packages/acs-core-docs/www/install-squirrelmail.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-squirrelmail.html,v
diff -u -r1.10.2.1 -r1.10.2.2
--- openacs-4/packages/acs-core-docs/www/install-squirrelmail.html	14 Jan 2007 04:20:10 -0000	1.10.2.1
+++ openacs-4/packages/acs-core-docs/www/install-squirrelmail.html	14 Jul 2007 12:34:47 -0000	1.10.2.2
@@ -1,11 +1,10 @@
-
-Install Squirrelmail for use as a webmail system for OpenACS
Prev Appendix�B.�Install additional supporting software  Next
Install Squirrelmail for use as a webmail system for OpenACS
By Malte Sussdorff
+Install Squirrelmail for use as a webmail system for OpenACSPrev Appendix�B.�Install additional supporting software  Next
Install Squirrelmail for use as a webmail system for OpenACS
By Malte Sussdorff
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a seperate webmail package within OpenACS
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd www
-[$OPENACS_SERVICE_NAME www]# wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.4.tar.gz
-[$OPENACS_SERVICE_NAME www]# tar xfz squirrelmail-1.4.4.tar.gz
-[$OPENACS_SERVICE_NAME www]# mv squirrelmail-1.4.4 mail
-[$OPENACS_SERVICE_NAME www]# cd mail/config
-[$OPENACS_SERVICE_NAME www]# ./conf.pl
+        
This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a seperate webmail package within OpenACS
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd www
+[$OPENACS_SERVICE_NAME www]# wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.4.tar.gz
+[$OPENACS_SERVICE_NAME www]# tar xfz squirrelmail-1.4.4.tar.gz
+[$OPENACS_SERVICE_NAME www]# mv squirrelmail-1.4.4 mail
+[$OPENACS_SERVICE_NAME www]# cd mail/config
+[$OPENACS_SERVICE_NAME www]# ./conf.pl
       
Now you are about to configure Squirrelmail. The configuration heavily depends on your setup, so no instructions are given here.
Prev Home  Next
Install PHP for use in AOLserver Up  Install PAM Radius for use as external authentication
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/install-ssl.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ssl.html,v
diff -u -r1.9.2.1 -r1.9.2.2
--- openacs-4/packages/acs-core-docs/www/install-ssl.html	14 Jan 2007 04:20:10 -0000	1.9.2.1
+++ openacs-4/packages/acs-core-docs/www/install-ssl.html	14 Jul 2007 12:34:47 -0000	1.9.2.2
@@ -1,27 +1,26 @@
-
-Installing SSL Support for an OpenACS servicePrev Chapter�6.�Production Environments  Next
Installing SSL Support for an OpenACS service
Debian Users: apt-get install openssl before proceeding.
Make sure nsopenssl.so is installed for AOLserver.
Uncomment this line from config.tcl.
#ns_param   nsopenssl       ${bindir}/nsopenssl.so
-
Prepare a certificate directory for the service.
[$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
-[$OPENACS_SERVICE_NAME etc]$ chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
+Installing SSL Support for an OpenACS servicePrev Chapter�6.�Production Environments  Next
Installing SSL Support for an OpenACS service
Debian Users: apt-get install openssl before proceeding.
Make sure nsopenssl.so is installed for AOLserver.
Uncomment this line from config.tcl.
#ns_param   nsopenssl       ${bindir}/nsopenssl.so
+
Prepare a certificate directory for the service.
[$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
+[$OPENACS_SERVICE_NAME etc]$ chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
 [$OPENACS_SERVICE_NAME etc]$ 
 mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
 chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
It takes two files to support an SSL connection.  The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl.  The key is the private half of the key pair.  In addition, the certificate must be signed by Certificate Authority or browsers will protest.  Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys.  Only a site certificate signed by a known and approved CA will work smoothly.  Any other certificate will cause browsers to produce some messages or block the site.  Unfortunately, getting a site certificate signed by a CA costs money.  In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
Use an OpenSSL perl script to generate a certificate and key.

           Debian users: use /usr/lib/ssl/misc/CA.pl instead of /usr/share/ssl/CA
         

           Mac OS X users: use perl /System/Library/OpenSSL/misc/CA.pl -newcert instead of /usr/share/ssl/CA
-        
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
-[$OPENACS_SERVICE_NAME certs]$ perl /usr/share/ssl/misc/CA -newcert
+        
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
+[$OPENACS_SERVICE_NAME certs]$ perl /usr/share/ssl/misc/CA -newcert
 Using configuration from /usr/share/ssl/openssl.cnf
 Generating a 1024 bit RSA private key
 ...++++++
 .......++++++
 writing new private key to 'newreq.pem'
 Enter PEM pass phrase:
Enter a pass phrase for the CA certificate.  Then, answer the rest of the questions.  At the end you should see this:
Certificate (and private key) is in newreq.pem
-[$OPENACS_SERVICE_NAME certs]$
newreq.pem contains our certificate and private key.  The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts.  This is impractical and unnecessary, so we create an unprotected version of the key.  Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do.  Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
[root misc]# openssl rsa -in newreq.pem -out keyfile.pem
+[$OPENACS_SERVICE_NAME certs]$
newreq.pem contains our certificate and private key.  The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts.  This is impractical and unnecessary, so we create an unprotected version of the key.  Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do.  Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
[root misc]# openssl rsa -in newreq.pem -out keyfile.pem
 read RSA key
 Enter PEM pass phrase:
 writing RSA key
-[$OPENACS_SERVICE_NAME certs]$ 
To create the certificate file, we take the combined file, copy it, and strip out the key.
[$OPENACS_SERVICE_NAME certs]$ cp newreq.pem certfile.pem
-[root misc]# emacs certfile.pem
Strip out the section that looks like
-----BEGIN RSA PRIVATE KEY-----
+[$OPENACS_SERVICE_NAME certs]$ 
To create the certificate file, we take the combined file, copy it, and strip out the key.
[$OPENACS_SERVICE_NAME certs]$ cp newreq.pem certfile.pem
+[root misc]# emacs certfile.pem
Strip out the section that looks like
-----BEGIN RSA PRIVATE KEY-----
 Proc-Type: 4,ENCRYPTED
 DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997
 S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T
Index: openacs-4/packages/acs-core-docs/www/install-steps.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-steps.html,v
diff -u -r1.28.2.2 -r1.28.2.3
--- openacs-4/packages/acs-core-docs/www/install-steps.html	22 Apr 2007 10:21:56 -0000	1.28.2.2
+++ openacs-4/packages/acs-core-docs/www/install-steps.html	14 Jul 2007 12:34:47 -0000	1.28.2.3
@@ -1,49 +1,49 @@
-
-Basic StepsPrev Chapter�2.�Installation Overview  Next
Basic Steps

+Basic Steps
Prev Chapter�2.�Installation Overview  Next
Basic Steps

     The basic steps for installing OpenACS are:
-  
Install an OS and supporting software (see Install a Unix-like OS or Appendix�A, Install Red Hat 8/9 for more details).  See the Table�2.2.
Install a database (see Section�, “Install Oracle 8.1.7” or
+  
Install an OS and supporting software (see Install a Unix-like OS or Appendix�A, Install Red Hat 8/9 for more details).  See the Table�2.2, “Version Compatibility Matrix”.
Install a database (see the section called “Install Oracle 8.1.7” or
         Install PostgreSQL).
 Install AOLserver (Install AOLserver 4) .
Create a unique database and system user.
         Install the OpenACS tarball, start and AOLserver instance, and
         use the OpenACS web pages to complete installation
-        (see Install OpenACS 5.3.1).
 Specific instructions are available for Mac OS X and
-    Windows2000 (see Section�, “OpenACS Installation Guide for Mac OS X” or
-    Section�, “OpenACS Installation Guide for Windows2000”).
Binaries and other shortcuts
You can try out OpenACS using some binary installers. In
+        (see Install OpenACS 5.3.2).
 Specific instructions are available for Mac OS X and
+    Windows2000 (see the section called “OpenACS Installation Guide for Mac OS X” or
+    the section called “OpenACS Installation Guide for Windows2000”).
Binaries and other shortcuts
You can try out OpenACS using some binary installers. In
     general, they are not yet supported by the community, so they are
     mostly for evaluation purposes. Installing
     OpenACS
You can see a list of current installers.
     

           The packaged version of
           PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.
Once AOLserver and a database are installed, a bash script automates the OpenACS checkout and
             installation.
-        
System Requirements

+        
System Requirements

       You will need a PC (or equivalent) with at least these minimum
       specifications:
     
128MB RAM (much more if you want Oracle)
1GB free space on your hard drive (much more if you want Oracle)
A Unix-like operating system with Tcl, tDOM, and
-          a mail transport agent like sendmail or qmail. (see Section�, “Prerequisite Software”)

+          a mail transport agent like sendmail or qmail. (see the section called “Prerequisite Software”)

       All of the software mentioned is open-source and available without direct costs,
       except for Oracle. You can obtain a free copy of Oracle for
       development purposes. This is described in the Acquire Oracle section.
-    
How to use this guide
This is text you will see on
-          screen, such as a Button or link
-          in a radio button list or menu.
This is text that you will type.
This is text from a program or file which you may need to
-          examine or edit:
if {$database == "oracle"} {
-          set db_password        "mysitepassword"
+    
How to use this guide
This is text you will see on
+          screen, such as a Button or link
+          in a radio button list or menu.
This is text that you will type.
This is text from a program or file which you may need to
+          examine or edit:
if {$database == "oracle"} {
+          set db_password        "mysitepassword"
 }
This is text that you will
-          see and type in a command shell, including text you may have to
+          see and type in a command shell, including text you may have to
             change.  It is followed by a list of just the commands,
-          which you can copy and paste. The command prompt varies by system; in the examples we use the form[$OPENACS_SERVICE_NAME aolserver]$, where $OPENACS_SERVICE_NAME is the current user and aolserver is the current directory.  The root prompt is shown ending in # and all other prompts in $.
-[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ svc -d /service/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ dropdb $OPENACS_SERVICE_NAME
+          which you can copy and paste. The command prompt varies by system; in the examples we use the form[$OPENACS_SERVICE_NAME aolserver]$, where $OPENACS_SERVICE_NAME is the current user and aolserver is the current directory.  The root prompt is shown ending in # and all other prompts in $.
+[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ svc -d /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ dropdb $OPENACS_SERVICE_NAME
 DROP DATABASE
-[$OPENACS_SERVICE_NAME aolserver]$ createdb $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ createdb $OPENACS_SERVICE_NAME
 CREATE DATABASE
 su - $OPENACS_SERVICE_NAME
 svc -d /service/$OPENACS_SERVICE_NAME
 dropdb $OPENACS_SERVICE_NAME
-createdb $OPENACS_SERVICE_NAME
Setting a global shell variable for cut and paste.�In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME.  In order to set it globally so that it works for any new users or special service users you may create, edit the file /etc/profile ( /etc/share/skel/dot.profile for FreeBSD) and add this line:
export OPENACS_SERVICE_NAME=service0
Paths and Users
Table�2.1.�Default directories for a standard install
Fully qualified domain name of your server yourserver.test
name of administrative access account remadmin
OpenACS service $OPENACS_SERVICE_NAME (set to service0 in default install)
OpenACS service account $OPENACS_SERVICE_NAME
OpenACS database name $OPENACS_SERVICE_NAME
Root of OpenACS service file tree (SERVERROOT) /var/lib/aolserver/$OPENACS_SERVICE_NAME
Location of source code tarballs for new software /var/tmp
The OpenACS tarball contains some files which
+createdb $OPENACS_SERVICE_NAMESetting a global shell variable for cut and paste.�In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME.  In order to set it globally so that it works for any new users or special service users you may create, edit the file /etc/profile ( /etc/share/skel/dot.profile for FreeBSD) and add this line:
export OPENACS_SERVICE_NAME=service0
Paths and Users
Table�2.1.�Default directories for a standard install
Fully qualified domain name of your server yourserver.test
name of administrative access account remadmin
OpenACS service 
+                $OPENACS_SERVICE_NAME (set to service0 in default install)
OpenACS service account $OPENACS_SERVICE_NAME
OpenACS database name $OPENACS_SERVICE_NAME
Root of OpenACS service file tree (SERVERROOT) /var/lib/aolserver/$OPENACS_SERVICE_NAME
Location of source code tarballs for new software /var/tmp
The OpenACS tarball contains some files which
                 are useful while setting up other software.  Those
-                files are located at: /var/tmp/openacs-5.3.1/packages/acs-core-docs/www/files
Database backup directory /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup
Service config files /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
Service log files /var/lib/aolserver/$OPENACS_SERVICE_NAME/log
Compile directory /usr/local/src
PostgreSQL directory /usr/local/pgsql
AOLserver directory /usr/local/aolserver

+                files are located at: /var/tmp/openacs-5.3.2/packages/acs-core-docs/www/files
Database backup directory /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup
Service config files /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
Service log files /var/lib/aolserver/$OPENACS_SERVICE_NAME/log
Compile directory /usr/local/src
PostgreSQL directory /usr/local/pgsql
AOLserver directory /usr/local/aolserver


       None of these locations are set in stone - they're simply
       the values that we've chosen.  The values that you'll
       probably want to change, such as service name, are
@@ -53,16 +53,16 @@
         Some of the paths and user accounts have been changed from
         those recommended in previous versions of this document to
         improve security and maintainability.  See this
-	  thread for discussion.
Getting Help during installation

+	  thread for discussion.
Getting Help during installation

       We'll do our best to assure that following our instructions will get
       you to the promised land. If something goes wrong, don't
       panic. There are plenty of ways to get help. Here are some tips:
     

           Keep track of the commands you are run and record their output. I
           like to do my installations in a shell inside of emacs
-          (M-x shell) so that I can save
+          (M-x shell) so that I can save
           the output if needed. An alternative would be to use the
-          script command.
+          script command.
         

           We'll point out where the error logs for the various pieces of
           software are. Output from those logs will help us help you. Don't
Index: openacs-4/packages/acs-core-docs/www/install-tclwebtest.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-tclwebtest.html,v
diff -u -r1.14.2.1 -r1.14.2.2
--- openacs-4/packages/acs-core-docs/www/install-tclwebtest.html	14 Jan 2007 04:20:10 -0000	1.14.2.1
+++ openacs-4/packages/acs-core-docs/www/install-tclwebtest.html	14 Jul 2007 12:34:47 -0000	1.14.2.2
@@ -1,5 +1,4 @@
-
-Install tclwebtest.
Prev Appendix�B.�Install additional supporting software  Next
Install tclwebtest.
Download the tclwebtest
+Install tclwebtest.
Prev Appendix�B.�Install additional supporting software  Next
Install tclwebtest.
Download the tclwebtest
       source, unpack it, and put it an appropriate
       place.  (tclwebtest 1.0 will be required for auto-tests in OpenACS 5.1.  When it exists, the cvs command here will be replaced with http://prdownloads.sourceforge.net/tclwebtest/tclwebtest-0.3.tar.gz?download.) As root:
cd /tmp
 cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tclwebtest co tclwebtest
Index: openacs-4/packages/acs-core-docs/www/ix01.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v
diff -u -r1.22.2.2 -r1.22.2.3
--- openacs-4/packages/acs-core-docs/www/ix01.html	22 Apr 2007 10:21:56 -0000	1.22.2.2
+++ openacs-4/packages/acs-core-docs/www/ix01.html	14 Jul 2007 12:34:47 -0000	1.22.2.3
@@ -1,3 +1,2 @@
-
-IndexPrev  
Index
Symbols
$OPENACS_SERVICE_NAME, Paths and Users
A
AOLserver
configuration, Installation Option 2: Install from tarball
Automated tests, Write automated tests
C
computeroutput
code, Code
cvs
initializing, Initialize CVS (OPTIONAL)
setup, Using CVS with an OpenACS Site
D
daemontools
installation, Install Daemontools (OPTIONAL)
docbook
installation, Install Red Hat 8/9
DocBook
DTD, OpenACS Documentation Strategy: Why DocBook?
emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
Document structure, Document Structure
E
emacs
installation, Install Red Hat 8/9
emphasis
bold, italics, Emphasis
F
full text search
installation, Install Tsearch2 module, Install OpenFTS module, Install OpenFTS prerequisites in PostgreSQL instance
G
Graphics
Images, Graphics
I
informaltable
table, Tables
L
language
installation, Install Red Hat 8/9
Linking, Links
lists, Lists
O
OpenACS Package, What a Package Looks Like
P
photo-album
installation (see ImageMagick)
Postgres
Vacuuming, Installation Option 2: Install from tarball
Q
qmail
installation, Install qmail (OPTIONAL)
Maildir, Install qmail (OPTIONAL)
rcpthosts error message, Install qmail (OPTIONAL)
S
sect1, Headlines, Sections
sect2, Headlines, Sections
Sections
Headlines, Headlines, Sections
security
definition, Install Red Hat 8/9
firewall, Install Red Hat 8/9
sendmail
removing, Install qmail (OPTIONAL)
ssh, Install Red Hat 8/9
T
The publish point for new packages should be
+IndexPrev  
Index
Symbols
$OPENACS_SERVICE_NAME, Paths and Users
A
AOLserver
configuration, Installation Option 2: Install from tarball
Automated tests, Write automated tests
C
computeroutput
code, Code
cvs
initializing, Initialize CVS (OPTIONAL)
setup, Using CVS with an OpenACS Site
D
daemontools
installation, Install Daemontools (OPTIONAL)
docbook
installation, Install Red Hat 8/9
DocBook
DTD, OpenACS Documentation Strategy: Why DocBook?
emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
Document structure, Document Structure
E
emacs
installation, Install Red Hat 8/9
emphasis
bold, italics, Emphasis
F
full text search
installation, Install Tsearch2 module, Install OpenFTS module, Install OpenFTS prerequisites in PostgreSQL instance
G
Graphics
Images, Graphics
I
informaltable
table, Tables
L
language
installation, Install Red Hat 8/9
Linking, Links
lists, Lists
O
OpenACS Package, What a Package Looks Like
P
photo-album
installation (see ImageMagick)
Postgres
Vacuuming, Installation Option 2: Install from tarball
Q
qmail
installation, Install qmail (OPTIONAL)
Maildir, Install qmail (OPTIONAL)
rcpthosts error message, Install qmail (OPTIONAL)
S
sect1, Headlines, Sections
sect2, Headlines, Sections
Sections
Headlines, Headlines, Sections
security
definition, Install Red Hat 8/9
firewall, Install Red Hat 8/9
sendmail
removing, Install qmail (OPTIONAL)
ssh, Install Red Hat 8/9
T
The publish point for new packages should be
         fixed., Prepare the package for distribution.
U
ulink, Links
upgrade
OpenACS 4.5 to 4.6.x
Linux/Unix, Upgrading 4.5 or higher to 4.6.3
X
XML guidelines, OpenACS Documentation Strategy: Why DocBook?
xref
linkend, Links
xreflabel, Headlines, Sections
Prev Home  
How to Update the translations Up  
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v
diff -u -r1.30.2.1 -r1.30.2.2
--- openacs-4/packages/acs-core-docs/www/kernel-doc.html	14 Jan 2007 04:20:10 -0000	1.30.2.1
+++ openacs-4/packages/acs-core-docs/www/kernel-doc.html	14 Jul 2007 12:34:47 -0000	1.30.2.2
@@ -1,2 +1 @@
-
-Chapter�15.�Kernel DocumentationPrev Part�IV.�For OpenACS Platform Developers  Next
Chapter�15.�Kernel Documentation
Table of Contents
Overview
Object Model Requirements
Object Model Design
Permissions Requirements
Permissions Design
Groups Requirements
Groups Design
Subsites Requirements
Subsites Design Document
Package Manager Requirements
Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Security Requirements
Security Design
Security Notes
Request Processor Requirements
Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
Prev Home  Next
Part�IV.�For OpenACS Platform Developers Up  Overview
docs@openacs.org
View comments on this page at openacs.org
+Chapter�15.�Kernel DocumentationPrev Part�IV.�For OpenACS Platform Developers  Next
Chapter�15.�Kernel Documentation
Table of Contents
Overview
Object Model Requirements
Object Model Design
Permissions Requirements
Permissions Design
Groups Requirements
Groups Design
Subsites Requirements
Subsites Design Document
Package Manager Requirements
Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Security Requirements
Security Design
Security Notes
Request Processor Requirements
Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
Prev Home  Next
Part�IV.�For OpenACS Platform Developers Up  Overview
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v
diff -u -r1.24.2.1 -r1.24.2.2
--- openacs-4/packages/acs-core-docs/www/kernel-overview.html	14 Jan 2007 04:20:10 -0000	1.24.2.1
+++ openacs-4/packages/acs-core-docs/www/kernel-overview.html	14 Jul 2007 12:34:47 -0000	1.24.2.2
@@ -1,5 +1,4 @@
-
-OverviewPrev Chapter�15.�Kernel Documentation  Next
Overview

+Overview
Prev Chapter�15.�Kernel Documentation  Next
Overview

               The OpenACS Kernel, which
               handles system-wide necessities such as metadata,
               security, users and groups, subsites, and package
Index: openacs-4/packages/acs-core-docs/www/mac-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/mac-installation.html,v
diff -u -r1.36.2.2 -r1.36.2.3
--- openacs-4/packages/acs-core-docs/www/mac-installation.html	22 Apr 2007 10:21:56 -0000	1.36.2.2
+++ openacs-4/packages/acs-core-docs/www/mac-installation.html	14 Jul 2007 12:34:47 -0000	1.36.2.3
@@ -1,9 +1,8 @@
-
-OpenACS Installation Guide for Mac OS X
Prev Chapter�3.�Complete Installation  Next
OpenACS Installation Guide for Mac OS X
Prerequisites.�Install readline:
Download readline from http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz into /usr/local/src
Extract readline in /usr/local/src, configure, compile, and install:
su - root
+OpenACS Installation Guide for Mac OS XPrev Chapter�3.�Complete Installation  Next
OpenACS Installation Guide for Mac OS X
Prerequisites.�Install readline:Download readline from http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz into /usr/local/srcExtract readline in /usr/local/src, configure, compile, and install:su - root
 cd /usr/local/src
 tar xvfz readline-4.3.tar.gz
 readline-4.3
 ./configure
 make
-make install
Proceed with the Unix-like system instructions.  OS X is incompatible with Oracle 8, and Oracle 9i on OSX is not yet verified for OpenACS.  So continue with Install PostgreSQL.  Additional special steps for OS X are documented inline with the standard Unix-like instructions.
Additional resources for installing on OS X.
OpenACS on Mac OS X Quickstart
An
+make install
Proceed with the Unix-like system instructions.  OS X is incompatible with Oracle 8, and Oracle 9i on OSX is not yet verified for OpenACS.  So continue with Install PostgreSQL.  Additional special steps for OS X are documented inline with the standard Unix-like instructions.
Additional resources for installing on OS X.
OpenACS on Mac OS X Quickstart
An
     older forum thread
($Id$)
Prev Home  Next
OpenACS Installation Guide for Windows2000 Up  Chapter�4.�Configuring a new OpenACS Site
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/maint-performance.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.html,v
diff -u -r1.22.2.2 -r1.22.2.3
--- openacs-4/packages/acs-core-docs/www/maint-performance.html	22 Apr 2007 10:21:56 -0000	1.22.2.2
+++ openacs-4/packages/acs-core-docs/www/maint-performance.html	14 Jul 2007 12:34:47 -0000	1.22.2.3
@@ -1,8 +1,7 @@
-
-Diagnosing Performance ProblemsPrev Chapter�6.�Production Environments  Next
Diagnosing Performance Problems
Did performance problems happen overnight, or did they sneak up on
+Diagnosing Performance Problems
Prev Chapter�6.�Production Environments  Next
Diagnosing Performance Problems
Did performance problems happen overnight, or did they sneak up on
     you? Any clue what caused the performance problems (e.g. loading 20K
-    users into .LRN)
Is the file system out of space?  Is the machine swapping to disk constantly?
Isolating and solving database problems.
Without daily internal maintenance, most databases slowly degrade in performance.  For PostGreSQL, see Section�, “Vacuum Postgres nightly”.  For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
You can track the exact amount of time each database query on a page takes:
Go to Main Site : Site-Wide Administration : Install Software
Click on "Install New Application" in "Install from OpenACS Repository"
Choose "ACS Developer Support">
After install is complete, restart the server.
Browse to Developer Support, which is automatically mounted at /ds.
-              
Turn on Database statistics
Browse directly to a slow page and click "Request Information" at the bottom of the page.
This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took.
Figure�6.8.�Query Analysis example
Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process.
Log in to SQL*Plus as the admin:
[$OPENACS_SERVICE_NAME ~]$ svrmgrl
+    users into .LRN)
Is the file system out of space?  Is the machine swapping to disk constantly?
Isolating and solving database problems.
Without daily internal maintenance, most databases slowly degrade in performance.  For PostGreSQL, see the section called “Vacuum Postgres nightly”.  For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
You can track the exact amount of time each database query on a page takes:
Go to Main Site : Site-Wide Administration : Install Software
Click on "Install New Application" in "Install from OpenACS Repository"
Choose "ACS Developer Support">
After install is complete, restart the server.
Browse to Developer Support, which is automatically mounted at /ds.
+              
Turn on Database statistics
Browse directly to a slow page and click "Request Information" at the bottom of the page.
This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took.
Figure�6.8.�Query Analysis example

Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process.
Log in to SQL*Plus as the admin:
[$OPENACS_SERVICE_NAME ~]$ svrmgrl
 
 Oracle Server Manager Release 3.1.7.0.0 - Production
 
@@ -12,7 +11,7 @@
 With the Partitioning option
 JServer Release 8.1.7.3.0 - Production
 
-SVRMGR> connect internal	        
+SVRMGR> connect internal	        
 Password:
See all of the running queries, and match the UNIX PID:
select p.spid  -- The UNIX PID
        ,s.sid  ,s.serial#
        ,p.username  as os_user
@@ -27,7 +26,7 @@
  where sql.address    = s.sql_address
    and sql.hash_value = s.sql_hash_value
  --and upper(s.username) like 'USERNAME%'
- order by s.username ,s.sid ,s.serial# ,sql.piece ;
To kill a troubled process:
alter system kill session 'SID,SERIAL#';  --substitute values for SID and SERIAL#
(See Andrew Piskorski's Oracle notes)
Identify a runaway Postgres query.  First, logging must be enabled in the database.  This imposes a performance penalty and should not be done in normal operation.
Edit the file postgresql.conf - its location depends on the PostGreSQL installation - and change
#stats_command_string = false
to
stats_command_string = true
Next, connect to postgres (psql service0) and select * from pg_stat_activity;.  Typical output should look like:
+ order by s.username ,s.sid ,s.serial# ,sql.piece ;
To kill a troubled process:
alter system kill session 'SID,SERIAL#';  --substitute values for SID and SERIAL#
(See Andrew Piskorski's Oracle notes)
Identify a runaway Postgres query.  First, logging must be enabled in the database.  This imposes a performance penalty and should not be done in normal operation.
Edit the file postgresql.conf - its location depends on the PostGreSQL installation - and change
#stats_command_string = false
to
stats_command_string = true
Next, connect to postgres (psql service0) and select * from pg_stat_activity;.  Typical output should look like:
   datid   |   datname   | procpid | usesysid | usename |  current_query
 ----------+-------------+---------+----------+---------+-----------------
  64344418 | openacs.org |   14122 |      101 | nsadmin | <IDLE>
@@ -42,7 +41,7 @@
  64344418 | openacs.org |   14311 |      101 | nsadmin | <IDLE>
  64344418 | openacs.org |   14549 |      101 | nsadmin | <IDLE>
 (8 rows)
-openacs.org=>
Creating an appropriate tuning and monitoring environment

+openacs.org=>
Creating an appropriate tuning and monitoring environment

       The first task is to create an appropriate environment for finding out
       what is going on inside Oracle. Oracle provides Statspack, a package to
       monitor and save the state of the v$ performance views. These reports
@@ -58,10 +57,10 @@
       Oracle Support information.
     

       To be able to get a overview of how Oracle executes a particular query,
-      install "autotrace". I usually follow the instructions here http://asktom.oracle.com/~tkyte/article1/autotrace.html.
-    
Make sure, that the Oracle CBO works with adequate statistics

+      install "autotrace". I usually follow the instructions here http://asktom.oracle.com/~tkyte/article1/autotrace.html.
+    
Make sure, that the Oracle CBO works with adequate statistics

     The Oracle Cost Based optimizer is a piece of software that tries to find
-    the "optimal" execution plan for a given SQL statement. For that it
+    the "optimal" execution plan for a given SQL statement. For that it
     estimates the costs of running a SQL query in a particular way (by default
     up to 80.000 permutations are being tested in a Oracle 8i). To get an
     adequate cost estimate, the CBO needs to have adequate statistics. For
Index: openacs-4/packages/acs-core-docs/www/maintenance-deploy.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-deploy.html,v
diff -u -r1.17.2.2 -r1.17.2.3
--- openacs-4/packages/acs-core-docs/www/maintenance-deploy.html	22 Apr 2007 10:21:56 -0000	1.17.2.2
+++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html	14 Jul 2007 12:34:47 -0000	1.17.2.3
@@ -1,8 +1,7 @@
-
-Staged Deployment for Production Networks
Prev Chapter�6.�Production Environments  Next
Staged Deployment for Production Networks
($Id$)
By Joel Aufrecht
+Staged Deployment for Production NetworksPrev Chapter�6.�Production Environments  Next
Staged Deployment for Production Networks
($Id$)
By Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
This section describes two minimal-risk methods for deploying changes on a production network.  The important characteristics of a safe change deployment include:  (THIS SECTION IN DEVELOPMENT)
Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested.
Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.
Method 1: Deployment with CVS
With this method, we control the files on a site via
+        
This section describes two minimal-risk methods for deploying changes on a production network.  The important characteristics of a safe change deployment include:  (THIS SECTION IN DEVELOPMENT)
Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested.
Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.
Method 1: Deployment with CVS
With this method, we control the files on a site via
       CVS. This example uses one developmental server (service0-dev) and one
       production server (service0). Depending on your needs, you can also
       have a staging server for extensive testing before you go
@@ -42,7 +41,7 @@
 /usr/local/pgsql/bin/psql -f /var/lib/aolserver/service0-dev/packages/acs-kernel/sql/postgresql/postgresql.sql service0
 mv /var/lib/aolserver/service0/database-backup/service0-nightly-backup.dmp.gz /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp.gz
 /bin/gunzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp.gz
-/usr/bin/perl -pi -e "s/^\\connect service0$/\\connect service0-dev/" /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp
+/usr/bin/perl -pi -e "s/^\\connect service0$/\\connect service0-dev/" /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp
 /usr/local/pgsql/bin/psql service0-dev < /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp
 /usr/local/bin/svc -u /service/service0-dev
 /bin/gzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp
@@ -59,12 +58,12 @@
 the lines starting > will be added and the lines
 starting < will be removed, when you commit
 if that looks okay, commit with: 
-cvs -m "changing text on front page for February conference" index.adp
-the stuff in -m "service0" is a comment visible only from within cvs commands
+cvs -m "changing text on front page for February conference" index.adp
+the stuff in -m "service0" is a comment visible only from within cvs commands
 
To make these changes take place on service0:
 4) update the file on production:
 cd /var/lib/aolserver/service0/www
 cvs up -Pd index.adp
If you make changes that require changes to the database,
       test them out first on service0-dev, using either -create.sql or
       upgrade scripts. Once you've tested them, you then update and
-      run the upgrade scripts from the package manager. 
The production site can run "HEAD" from cvs.
The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.'  So a better method is to use a tag.  This guarantees that, at any time in the future, you can retrieve exactly the same set of code.  This is useful for both of the characteristics of safe change deployment.  For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code.  For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems.  .... example of using tags to follow ...

Method 2: A/B Deployment

The approach taken in this section is to always create a new service with the desired changes, running in parallel with the existing site. This guarantees control, at least at the final step of the process: you know what changes you are about to make because you can see them directly. It does not, by itself, guarantee the entire control chain. You need additional measures to make sure that the change you are making is exactly and completely the change you intended to make and tested previously, and nothing more. Those additional measures typically take the form of source control tags and system version numbers. The parallel-server approach also guarantees rollback because the original working service is not touched; it is merely set aside.

This approach can has limitations. If the database or file system regularly receiving new data, you must interrupt this function or risk losing data in the shuffle. It also requires extra steps if the database will be affected.

Simple A/B Deployment: Database is not changed

Figure�6.2.�Simple A/B Deployment - Step 1

Figure�6.3.�Simple A/B Deployment - Step 2

Figure�6.4.�Simple A/B Deployment - Step 3

Complex A/B Deployment: Database is changed

Figure�6.5.�Complex A/B Deployment - Step 1

Figure�6.6.�Complex A/B Deployment - Step 2

Figure�6.7.�Complex A/B Deployment - Step 3

Prev	Home	Next
High Availability/High Performance Configurations	Up	Installing SSL Support for an OpenACS service

docs@openacs.org

View comments on this page at openacs.org + run the upgrade scripts from the package manager.

The production site can run "HEAD" from cvs.

The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.' So a better method is to use a tag. This guarantees that, at any time in the future, you can retrieve exactly the same set of code. This is useful for both of the characteristics of safe change deployment. For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code. For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems. .... example of using tags to follow ...

Method 2: A/B Deployment

Simple A/B Deployment: Database is not changed

Figure�6.2.�Simple A/B Deployment - Step 1

Figure�6.3.�Simple A/B Deployment - Step 2

Figure�6.4.�Simple A/B Deployment - Step 3

Complex A/B Deployment: Database is changed

Figure�6.5.�Complex A/B Deployment - Step 1

Figure�6.6.�Complex A/B Deployment - Step 2

Figure�6.7.�Complex A/B Deployment - Step 3

Prev	Home	Next
High Availability/High Performance Configurations	Up	Installing SSL Support for an OpenACS service

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v diff -u -r1.34.2.1 -r1.34.2.2 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 14 Jan 2007 04:20:10 -0000 1.34.2.1 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 14 Jul 2007 12:34:47 -0000 1.34.2.2 @@ -1,5 +1,4 @@ - -Chapter�6.�Production Environments

Prev	Part�II.�Administrator's Guide	Next

Chapter�6.�Production Environments

Table of Contents

Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems

by Joel Aufrecht

+Chapter�6.�Production Environments

Prev	Part�II.�Administrator's Guide	Next

Chapter�6.�Production Environments

Table of Contents

Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Prev	Home	Next
Upgrading Platform components	Up	Starting and Stopping an OpenACS instance.

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/nxml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/nxml-mode.html,v diff -u -r1.11.2.1 -r1.11.2.2 --- openacs-4/packages/acs-core-docs/www/nxml-mode.html 14 Jan 2007 04:20:10 -0000 1.11.2.1 +++ openacs-4/packages/acs-core-docs/www/nxml-mode.html 14 Jul 2007 12:34:47 -0000 1.11.2.2 @@ -1,5 +1,4 @@ - -Using nXML mode in Emacs

Prev	Chapter�13.�Documentation Standards	Next

Using nXML mode in Emacs

By Jeff Davis

+Using nXML mode in Emacs

Prev	Chapter�13.�Documentation Standards	Next

Using nXML mode in Emacs

By Jeff Davis

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -r1.42.2.2 -r1.42.2.3 --- openacs-4/packages/acs-core-docs/www/object-identity.html 22 Apr 2007 10:21:56 -0000 1.42.2.2 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 14 Jul 2007 12:34:47 -0000 1.42.2.3 @@ -1,19 +1,18 @@ - -Object Identity

Prev	Chapter�11.�Development Reference	Next

Object Identity

By Rafael H. Schloming

+Object Identity

Prev	Chapter�11.�Development Reference	Next

Object Identity

By Rafael H. Schloming

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

One of the major design features of OpenACS 5.3.1 is the explicit representation -of object identity. The reason I say "explicit -representation" is because the concept of object identity has been +

One of the major design features of OpenACS 5.3.2 is the explicit representation +of object identity. The reason I say "explicit +representation" is because the concept of object identity has been around forever. It is inherent to our problem domain. Consider the example of 3.x style scoping. The 3.x data models use the triple (user_id, group_id, -scope) to identify an object. In the 5.3.1 data model this +scope) to identify an object. In the 5.3.2 data model this object is explicitly represented by a single party_id.

Another good example of this is can be found in the user groups data model. The 3.x user groups data model contains another example of an implied identity. Every mapping between a user and a group could have an arbitrary number of attached values (user_group_member_fields, etc.). In this case it is the pair (group_id, user_id) that implicitly refers to an -object (the person's membership in a group). In the 5.3.1 data model this +object (the person's membership in a group). In the 5.3.2 data model this object identity is made explicit by adding an integer primary key to the table that maps users to groups.

Coming from a purely relational world, this might seem slightly weird at first. The pair (group_id, user_id) is sufficient to uniquely identify the Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -r1.28.2.1 -r1.28.2.2 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 14 Jan 2007 04:20:10 -0000 1.28.2.1 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 14 Jul 2007 12:34:47 -0000 1.28.2.2 @@ -1,22 +1,21 @@ - -Object Model Design

Prev	Chapter�15.�Kernel Documentation	Next

Object Model Design

By Pete Su, Michael Yoon, Richard Li, Rafael Schloming

+Object Model Design

Prev	Chapter�15.�Kernel Documentation	Next

Object Model Design

By Pete Su, Michael Yoon, Richard Li, Rafael Schloming

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Essentials

Data Model

Essentials

Data Model

Tcl Files

Not yet linked.

Requirements

Object Model +acs-relationships-create.sql

Tcl Files

Not yet linked.

Requirements

Introduction

Before OpenACS 4, software developers writing OpenACS applications or modules +Requirements

Introduction

Before OpenACS 4, software developers writing OpenACS applications or modules would develop each data model separately. However, many applications built on OpenACS share certain characteristics or require certain common services. Examples of such services include:

User comments
Storage of user-defined or extensible sets of attributes
Access control
General auditing and bookkeeping (e.g. creation date, IP addresses, and so forth)
Presentation tools (e.g. how to display a field in a form or on a page)

All of these services involve relating additional service-related information to application data objects. Examples of application objects include:

forum messages
A user home page
A ticket in the ticket tracker

In the past, developers had to use ad-hoc and inconsistent schemes to -interface to various "general" services. OpenACS 4 defines a central +interface to various "general" services. OpenACS 4 defines a central data model that keeps track of the application objects that we wish to manage, and serves as a primary store of metadata. By metadata, we mean data stored on behalf of an application @@ -33,54 +32,54 @@ object type (e.g. users) to instances of another object type (e.g. groups).

The next section will explore these facilities in the context of the the -particular programming idioms that we wish to generalize.

History

The motivation for most of the facilities in the OpenACS 4 Object Model can be +particular programming idioms that we wish to generalize.

Related Links

This design document should be read along with the design documents for the new groups system, subsites and the permissions system

History

The motivation for most of the facilities in the OpenACS 4 Object Model can be understood in the context of the 3.x code base and the kinds of programming -idioms that evolved there. These are listed and discussed below.

Object Identification

Object identification is a central mechanism in OpenACS 4. Every application +idioms that evolved there. These are listed and discussed below.

Object Identification

Object identification is a central mechanism in OpenACS 4. Every application object in OpenACS 4 has a unique ID which is mapped to a row in a central table -called acs_objects. Developers that wish to use OpenACS 4 services +called acs_objects. Developers that wish to use OpenACS 4 services need only take a few simple steps to make sure that their application objects appear in this table. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. In other words, we use object identifiers to enable centralized services in a global and uniform manner.

Implicit Object Identifiers in OpenACS 3.x

The motivation for implementing general object identifiers comes from several observations of data models in OpenACS 3.x. Many modules use a -(user_id, group_id, scope) column-triple for the purpose of +(user_id, group_id, scope) column-triple for the purpose of recording ownership information on objects, for access control. User/groups -also uses (user_id, group_id) pairs in its -user_group_map table as a way to identify data associated with a +also uses (user_id, group_id) pairs in its +user_group_map table as a way to identify data associated with a single membership relation.

Also, in OpenACS 3.x many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, -general comments maintains a table that maps application "page" +general comments maintains a table that maps application "page" data (static or dynamic pages on the website) to one or more user comments on that page. It does so by constructing a unique identifier for each page, usually a combination of the table in which the data is stored, and the value of the primary key value for the particular page. This idiom is referred to -as the "(on_which_table + on_what_id)" method for identifying +as the "(on_which_table + on_what_id)" method for identifying application data. In particular, general comments stores its map from pages -to comments using a "(on_which_table + on_what_id)" key plus the ID +to comments using a "(on_which_table + on_what_id)" key plus the ID of the comment itself.

All of these composite key constructions are implicit object identifiers - they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent, making the construction of generic application-independent services unnecessarily difficult.

Object Identifiers in OpenACS 4

The OpenACS 4 Object Model defines a single mechanism that applications use to attach unique identifiers to application data. This identifier is the primary -key of the acs_objects table. This table forms the core of what +key of the acs_objects table. This table forms the core of what we need to provide generic services like access control, general attribute storage, general presentation and forms tools, and generalized administrative interfaces. In addition, the object system provides an API that makes it easy to create new objects when creating application data. All an application must do to take advantage of general services in OpenACS 4 is to use the new API to make sure every object the system is to manage is associated with a row in -acs_objects. More importantly, if they do this, new services +acs_objects. More importantly, if they do this, new services like general comments can be created without requiring existing applications -to "hook into" them via new metadata.

Note: Object identifiers are a good example of metadata -in the new system. Each row in acs_objects stores information +to "hook into" them via new metadata.

Note: Object identifiers are a good example of metadata +in the new system. Each row in acs_objects stores information about the application object, but not the application object itself. This becomes more clear if you skip ahead and look at the SQL schema code -that defines this table.

Object Context and Access Control

Until the implementation of the general permissions system, every OpenACS +that defines this table.

Object Context and Access Control

Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a -notion of "scoping" was introduced into the core data model.

"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:

...	`scope`	`user_id`	`group_id`	...
...	`user`	`123`	�	...
...	`group`	�	`456`	...
...	`public`	�	�	...

The first row represents an entry in User 123's personal address book, +notion of "scoping" was introduced into the core data model.

"Scope" is a term best explained by example. Consider some +hypothetical rows in the address_book table:

...	`scope`	`user_id`	`group_id`	...
...	`user`	`123`		...
...	`group`		`456`	...
...	`public`			...

The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book.

In this way, the scoping columns identify the security context in which a @@ -94,29 +93,29 @@ forum message would probably list a forum topic as its context, and a forum topic might list a subsite as its context. Thus, contexts make it easier to break the site up into security domains according to its natural -structure. An object's context is stored in the context_id -column of the acs_objects table.

We use an object's context to provide a default answer to questions -regarding access control. Whenever we ask a question of the form "can -user X perform action Y on object Z", the OpenACS security model will defer +structure. An object's context is stored in the context_id +column of the acs_objects table.

We use an object's context to provide a default answer to questions +regarding access control. Whenever we ask a question of the form "can +user X perform action Y on object Z", the OpenACS security model will defer to an object's context if there is no information about user X's permission to perform action Y on object Z.

The context system forms the basis for the rest of the OpenACS access control system, which is described in in two separate documents: one for the permissions system and another for the party groups system. The context system -is also used to implement subsites.

Object Types

As mentioned above, many OpenACS modules provide extensible data models, and +is also used to implement subsites.

Object Types

As mentioned above, many OpenACS modules provide extensible data models, and need to use application specific mechanisms to keep track of user defined attributes and to map application data to these attributes. In the past, modules either used user/groups or their own ad hoc data model to provide this functionality.

User/Groups in OpenACS 3.x

The user/group system allowed developers to define group types along with attributes to be stored with each instance of a group type. Each group type could define a helper table that stored attributes on each instance of the group type. This table was called the -"_info" table because the name was generated by -appending _info to the name of the group type.

The user/groups data model also provided the -user_group_type_member_fields and -user_group_member_fields tables to define attributes for members +"_info" table because the name was generated by +appending _info to the name of the group type.

The user/groups data model also provided the +user_group_type_member_fields and +user_group_member_fields tables to define attributes for members of groups of a specific type and for members of a specific group, -respectively. The user_group_member_field_map table stored -values for both categories of attributes in its field_value +respectively. The user_group_member_field_map table stored +values for both categories of attributes in its field_value column. These tables allowed developers and users to define custom sets of attributes to store on groups and group members without changing the data model at the code level.

Many applications in OpenACS 3.x and earlier used the group type mechanism in @@ -131,39 +130,39 @@ The motivation for subtypes comes from the need for OpenACS to be more extensible. In OpenACS 3.x, many applications extended the core data models by directly adding more columns, in order to provide convenient access to new -information. This resulted in core data tables that were too "fat", +information. This resulted in core data tables that were too "fat", containing a hodge podge of unrelated information that should have been normalized away. The canonical example of this is the explosion of the -users table in OpenACS 3.x. In addition to being sloppy technically, +users table in OpenACS 3.x. In addition to being sloppy technically, these fat tables have a couple of other problems:

They degrade performance.
Denormalization can make it hard to maintain consistency constraints on the data.

Object subtypes provide a way to factor the data model while still keeping track of the fact that each member of a subtype (i.e. for each row in the subtype's table), is also a member of the parent type (i.e. there is a corresponding row in the parent type table). Therefore, applications an use this mechanism without worrying about this bookkeeping themselves, and we avoid having applications pollute the core data model with their specific -information.

Object Attributes, Skinny Tables

As we described above, the OpenACS 3.x user/groups system stored object +information.

Object Attributes, Skinny Tables

As we described above, the OpenACS 3.x user/groups system stored object attributes in two ways. The first was to use columns in the helper table. The second consisted of two tables, one describing attributes and one storing values, to provide a flexible means for attaching attributes to metadata objects. This style of attribute storage is used in several other parts of -OpenACS 3.x, and we will refer to it as "skinny tables". For -example:

In the Ecommerce data model, the ec_custom_product_fields +OpenACS 3.x, and we will refer to it as "skinny tables". For +example:
- In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the -ec_custom_product_field_values table stores values for those -attributes.
- In the Photo DB data model, the ph_custom_photo_fields table +ec_custom_product_field_values table stores values for those +attributes.
- In the Photo DB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables named according to the convention -"ph_user_<user_id>_custom_info" are used to +"ph_user_<user_id>_custom_info" are used to store values for those attributes.
In addition, there are some instances where we are not using this model -but should, e.g. the users_preferences table, which +but should, e.g. the users_preferences table, which stores preferences for registered users in columns such as -prefer_text_only_p and dont_spam_me_p. The -"standard" way for an OpenACS 3.x-based application to add to the list -of user preferences is to add a column to the users_preferences +prefer_text_only_p and dont_spam_me_p. The +"standard" way for an OpenACS 3.x-based application to add to the list +of user preferences is to add a column to the users_preferences table (exactly the kind of data model change that has historically complicated the process of upgrading to a more recent OpenACS version).
The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups -system. It defines a table called acs_attributes that record +system. It defines a table called acs_attributes that record what attributes belong to which object types, and how the attributes are stored. As before, attributes can either be stored in helper tables, or in a single central skinny table. The developer makes this choice on a case by @@ -173,53 +172,53 @@ skinny tables because doing so allows developers and users to dynamically update the set of attributes stored on an object without updating the data model at the code level. The bottom line: Helper tables are more functional -and more efficient, skinny tables are more flexible but limited.

Relation Types

Many OpenACS 3.x modules use mapping tables to model relationships +and more efficient, skinny tables are more flexible but limited.

Relation Types

Many OpenACS 3.x modules use mapping tables to model relationships between application objects. Again, the 3.x user/groups system provides the canonical example of this design style. In that system, there was a single -table called user_group_map that kept track of which users +table called user_group_map that kept track of which users belonged to what groups. In addition, as we discussed in the previous -section, the system used the user_group_member_fields and -user_group_member_fields_map tables to allow developers to +section, the system used the user_group_member_fields and +user_group_member_fields_map tables to allow developers to attach custom attributes to group members. In fact, these attributes were not really attached to the users, but to the fact that a user was a member of a particular group - a subtle but important distinction.

In OpenACS 4, relation types generalize this mechanism. Relation types allow developers to define general mappings from objects of a given type T, to other objects of a given type R. Each relation type is a subtype -of acs_object, extended with extra attributes that store +of acs_object, extended with extra attributes that store constraints on the relation, and the types of objects the relation actually maps. In turn, each instance of a relation type is an object that represents -a single fact of the form "the object t of type T is related to the -object r of type R." That is, each instance of a relation type is +a single fact of the form "the object t of type T is related to the +object r of type R." That is, each instance of a relation type is essentially just a pair of objects.

Relation types generalize mapping tables. For example, the 3.x user/groups data model can be largely duplicated using a single relation type describing -the "group membership" relation. Group types would then be subtypes +the "group membership" relation. Group types would then be subtypes of this membership relation type. Group type attributes would be attached to the relation type itself. Group member attributes would be attached to instances of the membership relation. Finally, the mapping table would be replaced by a central skinny table that the relation type system defines.

Relation types should be used when you want to be able to attach data to -the "fact" that object X and object Y are related to each other. On +the "fact" that object X and object Y are related to each other. On the face of it, they seem like a redundant mechanism however, since one could easily create a mapping table to do the same thing. The advantage of registering this table as a relation type is that in principle the OpenACS 4 object system could use the meta data in the types table to do useful things in a generic way on all relation types. But this mechanism doesn't really exist yet.

Relation types are a somewhat abstract idea. To get a better feel for -them, you should just skip to the data model.

Summary and Design Considerations

The OpenACS 4 Object Model is designed to generalize and unify the following +them, you should just skip to the data model.

Summary and Design Considerations

The OpenACS 4 Object Model is designed to generalize and unify the following mechanisms that are repeatedly implemented in OpenACS-based systems to manage -generic and application specific metadata:

Why not Object Databases?

The presence of a framework for subtyping and inheritance always brings up +generic and application specific metadata:

Why not Object Databases?

The presence of a framework for subtyping and inheritance always brings up the question of why we don't just use an object database. The main reason is that all of the major object database vendors ship products that are effectively tied to some set of object oriented programming languages. Their idea is to provide tight language-level integration to lower the -"impedance mismatch" between the database and the language. +"impedance mismatch" between the database and the language. Therefore, database objects and types are generally directly modeled on language level objects and types. Of course, this makes it nearly impossible to interact with the database from a language that does not have this tight coupling, and it limits the data models that we can write to ideas that are expressible in the host language. In particular, we lose many of the best features of the relational database model. This is a disaster from an ease of use standpoint. -

The "Object relational" systems provide an interesting +

The "Object relational" systems provide an interesting alternative. Here, some notion of subtyping is embedded into an existing SQL or SQL-like database engine. Examples of systems like this include the new Informix, PostgreSQL 7, and Oracle has something like this too. The main @@ -230,7 +229,7 @@ practice. Finally, object databases are not as widely used as traditional relational systems. They have not been tested as extensively and their scalability to very large databases is not proven (though some will disagree -with this statement).

Oracle

The conclusion: the best design is to add a limited notion of subtyping to +with this statement).

Oracle

The conclusion: the best design is to add a limited notion of subtyping to our existing relational data model. By doing this, we retain all the power of the relational data model while gaining the object oriented features we need most.

In the context of OpenACS 4, this means using the object model to make our @@ -241,9 +240,9 @@ the more limited domain of the metadata model, this is acceptable since the type hierarchy is fairly small. But the object system data model is not designed to support, for example, a huge type tree like the Java runtime -libraries might define.

This last point cannot be over-stressed: the object model is not -meant to be used for large scale application data storage. It is -meant to represent and store metadata, not application data.

Data Model

Like most data models, the OpenACS Core data model has two levels:

The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)

+libraries might define.

This last point cannot be over-stressed: the object model is not +meant to be used for large scale application data storage. It is +meant to represent and store metadata, not application data.

Data Model

Like most data models, the OpenACS Core data model has two levels:

The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)

You can browse the data models themselves from here:

acs-metadata-create.sql
@@ -254,12 +253,12 @@ the SQL definitions of many tables. Generally, these match the actual definitions in the existing data model but they are meant to reflect design information, not implementation. Some less relevant columns may be left out, -and things like constraint names are not included.
Knowledge-Level Model
The knowledge level data model for OpenACS objects centers around three tables +and things like constraint names are not included.
Knowledge-Level Model
The knowledge level data model for OpenACS objects centers around three tables that keep track of object types, attributes, and relation types. The first -table is acs_object_types, shown here in an abbreviated +table is acs_object_types, shown here in an abbreviated form:
```
 
-create table acs_object_types (
+create table acs_object_types (
         object_type          varchar(100) not null primary key,
         supertype            references acs_object_types (object_type),
         abstract_p           char(1) default 'f' not null
@@ -270,26 +269,26 @@
         name_method          varchar(30),
         type_extension_table varchar(30)
 );
-
+
 
 
```
This table contains one row for every object type in the system. The key things to note about this table are:
- For every type, we store metadata for how to display this type in certain -contexts (pretty_name and pretty_plural).
- If the type is a subtype, then its parent type is stored in the column -supertype.
- We support a notion of "abstract" types that contain no +contexts (pretty_name and pretty_plural).
- If the type is a subtype, then its parent type is stored in the column +supertype.
- We support a notion of "abstract" types that contain no instances (as of 9/2000 this is not actually used). These types exist only to -be subtyped. An example might be a type representing "shapes" that +be subtyped. An example might be a type representing "shapes" that contains common characteristics of all shapes, but which is only used to create subtypes that represent real, concrete shapes like circles, squares, and so on.
- Every type defines a table in which one can find one row for every -instance of this type (table_name, id_column).
- type_extension_table is for naming a table that stores extra -generic attributes.
The second table we use to describe types is acs_attributes. +instance of this type (table_name, id_column).
type_extension_table is for naming a table that stores extra +generic attributes.

The second table we use to describe types is acs_attributes. Each row in this table represents a single attribute on a specific object -type (e.g. the "password" attribute of the "user" type). +type (e.g. the "password" attribute of the "user" type). Again, here is an abbreviated version of what this table looks like. The actual table used in the implementation is somewhat different and is discussed in a separate document.

 
-create table acs_attributes (
+create table acs_attributes (
         attribute_id    integer not null primary key
         object_type     not null references acs_object_types (object_type),
         attribute_name  varchar(100) not null,
@@ -305,38 +304,38 @@
         max_n_values    integer default 1 not null,
         static_p        varchar(1)
 );
-
+

The following points are important about this table:

Every attribute has a unique identifier.
Every attribute is associated with an object type.
We store various things about each attribute for presentation -(pretty_name, sort_order).
The data_type column stores type information on this +(pretty_name, sort_order).
The data_type column stores type information on this attribute. This is not the SQL type of the attribute; it is just a human readable name for the type of data we think the attribute holds (e.g. -"String", or "Money"). This might be used later to -generate a user interface.
The sort_order column stores information about how to sort -the attribute values.
Attributes can either be stored explicitly in a table ("type -specific storage") or in a skinny table ("generic storage"). +"String", or "Money"). This might be used later to +generate a user interface.
The sort_order column stores information about how to sort +the attribute values.
Attributes can either be stored explicitly in a table ("type +specific storage") or in a skinny table ("generic storage"). In most cases, an attribute maps directly to a column in the table identified -by the table_name of the corresponding object type, although, as +by the table_name of the corresponding object type, although, as mentioned above, we sometimes store attribute values as key-value pairs in a -"skinny" table. However, when you ask the question "What are -the attributes of this type of object?", you don't really care about +"skinny" table. However, when you ask the question "What are +the attributes of this type of object?", you don't really care about how the values for each attribute are stored (in a column or as key-value -pairs); you expect to receive the complete list of all attributes.
The max_n_values and min_n_values columns +pairs); you expect to receive the complete list of all attributes.
The max_n_values and min_n_values columns encode information about the number of values an attribute may hold. -Attributes can be defined to hold 0 or more total values.
The static_p flag indicates whether this attribute value is +Attributes can be defined to hold 0 or more total values.
The static_p flag indicates whether this attribute value is shard by all instances of a type, as with static member fields in C++. Static attribute are like group level attributes in OpenACS 3.x.

The final part of the knowledge level model keeps track of relationship types. We said above that object relationships are used to generalize the 3.x notion of group member fields. These were fields that a developer could store on each member of a group, but which were contextualized to the -membership relation. That is, they were really "attached" to the +membership relation. That is, they were really "attached" to the fact that a user was a member of a particular group, and not really attached to the user. This is a subtle but important distinction, because it allowed the 3.x system to store multiple sets of attributes on a given user, one set for each group membership relation in which they participated.

In OpenACS 4, this sort of data can be stored as a relationship type, in -acs_rel_types. The key parts of this table look like this:

+acs_rel_types. The key parts of this table look like this:
 
-create table acs_rel_types (
+create table acs_rel_types (
         rel_type        varchar(100) not null
                         references acs_object_types(object_type),
         object_type_one not null
@@ -350,31 +349,31 @@
         min_n_rels_two  integer default 0 not null,
         max_n_rels_two  integer
 );
-
+
 
 
Things to note about this table:
The main part of this table records the fact that the relation is between
-instances of object_type_one and instances of
-object_type_two. Therefore, each instance of this relation type
-will be a pair of objects of the appropriate types.
The role columns store human readable names for the roles
-played by each object in the relation (e.g. "employee" and
-"employer"). Each role must appear in the
-acs_rel_roles.
The min_n_rels_one column, and its three friends allow the
+instances of object_type_one and instances of
+object_type_two. Therefore, each instance of this relation type
+will be a pair of objects of the appropriate types.
The role columns store human readable names for the roles
+played by each object in the relation (e.g. "employee" and
+"employer"). Each role must appear in the
+acs_rel_roles.
The min_n_rels_one column, and its three friends allow the
 programmer to specify constraints on how many objects any given object can be
-related to on either side of the relation.
This table is easier to understand if you also know how the acs_rels table works.
To summarize, the acs_object_types and
-acs_attributes tables store metadata that describes every object
+related to on either side of the relation.

This table is easier to understand if you also know how the acs_rels table works.

To summarize, the acs_object_types and +acs_attributes tables store metadata that describes every object type and attribute in the system. These tables generalize the group types -data model in OpenACS 3.x. The acs_rel_types table stores +data model in OpenACS 3.x. The acs_rel_types table stores information about relation types.

This part of the data model is somewhat analogous to the data dictionary in Oracle. The information stored here is primarily metadata that describes the data stored in the operational level of the data -model, which is discussed next.

Operational-level Data Model

The operational level data model centers around the -acs_objects table. This table contains a single row for every -instance of the type acs_object. The table contains the +model, which is discussed next.

Operational-level Data Model

The operational level data model centers around the +acs_objects table. This table contains a single row for every +instance of the type acs_object. The table contains the object's unique identifier, a reference to its type, security information, and generic auditing information. Here is what the table looks like:

 
-create table acs_objects (
+create table acs_objects (
         object_id               integer not null,
         object_type             not null
                                 references acs_object_types (object_type),
@@ -388,32 +387,32 @@
         modifying_user          integer,
         modifying_ip            varchar(50)
 );
-
+

As we said in Section III, security contexts are hierarchical and also modeled as objects. There is another table called -acs_object_context_index that stores the context hierarchy.

Other tables in the core data model store additional information related -to objects. The table acs_attribute_values and -acs_static_attr_values are used to store attribute values that +acs_object_context_index that stores the context hierarchy.

Other tables in the core data model store additional information related +to objects. The table acs_attribute_values and +acs_static_attr_values are used to store attribute values that are not stored in a helper table associated with the object's type. The former is used for instance attributes while the latter is used for -class-wide "static" values. These tables have the same basic form, +class-wide "static" values. These tables have the same basic form, so we'll only show the first:

 
-create table acs_attribute_values (
+create table acs_attribute_values (
         object_id       not null
                         references acs_objects (object_id) on delete cascade,
         attribute_id    not null
                         references acs_attributes (attribute_id),
         attr_value      varchar(4000),
         primary key     (object_id, attribute_id)
 );
-
+
 
-

Finally, the table acs_rels is used to store object pairs +

Finally, the table acs_rels is used to store object pairs that are instances of a relation type.

 
-create table acs_rels (
+create table acs_rels (
         rel_id          not null
                         references acs_objects (object_id)
                         primary key
@@ -425,33 +424,33 @@
                         references acs_objects (object_id),
         unique (rel_type, object_id_one, object_id_two)
 );
-
+
 
-

This table is somewhat subtle:

rel_id is the ID of an instance of some relation +
This table is somewhat subtle:
- rel_id is the ID of an instance of some relation type. We do this so we can store all the mapping tables in this one -table.
- rel_type is the ID of the relation type to which this object +table.
- rel_type is the ID of the relation type to which this object belongs.
- The next two object IDs are the IDs of the objects being mapped.
All this table does is store one row for every pair of objects that we'd like to attach with a relation. Any additional attributes that we'd like to attach to this pair of objects is specified in the attributes of the relation type, and could be stored in any number of places. As in the 3.x user/groups system, these places include helper tables or -generic skinny tables.
This table, along with acs_attributes and -acs_attribute_values generalize the old user/group tables -user_group_map, user_group_member_fields_map and -user_group_member_fields.

Summary and Discussion

The core tables in the OpenACS 4 data model store information about instances -of object types and relation types. The acs_object table +generic skinny tables.

This table, along with acs_attributes and +acs_attribute_values generalize the old user/group tables +user_group_map, user_group_member_fields_map and +user_group_member_fields.

Summary and Discussion

The core tables in the OpenACS 4 data model store information about instances +of object types and relation types. The acs_object table provides the central location that contains a single row for every object in the system. Services can use this table along with the metadata in stored in the knowledge level data model to create, manage, query and manipulate -objects in a uniform manner. The acs_rels table has an analogous +objects in a uniform manner. The acs_rels table has an analogous role in storing information on relations.

These are all the tables that we'll discuss in this document. The rest of the Kernel data model is described in the documents for subsites, the permissions system and for the groups system.

Some examples of how these tables are used in the system can be found in -the discussion of the API, which comes next.

API

Now we'll examine each piece of the API in detail. Bear in mind that -the Object Model API is defined primarily through PL/SQL packages.

Object Types and Attributes

The object system provides an API for creating new object types and then -attaching attributes to them. The procedures create_type and -drop_type are used to create and delete type definitions.

The two calls show up in the package acs_object_type.

+the discussion of the API, which comes next.

API

Now we'll examine each piece of the API in detail. Bear in mind that +the Object Model API is defined primarily through PL/SQL packages.

Object Types and Attributes

The object system provides an API for creating new object types and then +attaching attributes to them. The procedures create_type and +drop_type are used to create and delete type definitions.

The two calls show up in the package acs_object_type.

 
-  procedure create_type (
+  procedure create_type (
     object_type         in acs_object_types.object_type%TYPE,
     pretty_name         in acs_object_types.pretty_name%TYPE,
     pretty_plural       in acs_object_types.pretty_plural%TYPE,
@@ -470,13 +469,13 @@
     object_type         in acs_object_types.object_type%TYPE,
     cascade_p           in char default 'f'
   );
-
+
 
-

Here the cascade_p argument indicates whether dropping a type +

Here the cascade_p argument indicates whether dropping a type should also remove all its subtypes from the system.

We define a similar interface for defining attributes in the package -acs_attribute:

+acs_attribute:
 
-  function create_attribute (
+  function create_attribute (
     object_type         in acs_attributes.object_type%TYPE,
     attribute_name      in acs_attributes.attribute_name%TYPE,
     datatype            in acs_attributes.datatype%TYPE,
@@ -497,12 +496,12 @@
     attribute_name in varchar
   );
 
-
+
 
 
In addition, the following two calls are available for attaching extra
 annotations onto attributes:
 
-  procedure add_description (
+  procedure add_description (
     object_type         in acs_attribute_descriptions.object_type%TYPE,
     attribute_name      in acs_attribute_descriptions.attribute_name%TYPE,
     description_key     in acs_attribute_descriptions.description_key%TYPE,
@@ -514,30 +513,30 @@
     attribute_name      in acs_attribute_descriptions.attribute_name%TYPE,
     description_key     in acs_attribute_descriptions.description_key%TYPE
   );
-
+
 
 
At this point, what you must do to hook into the object system from your
-own data model becomes clear:
Create a table that will store the instances of the new type.
Call acs_object_type.create_type() to fill in the metadata
+own data model becomes clear:
Create a table that will store the instances of the new type.
Call acs_object_type.create_type() to fill in the metadata
 table on this new type. If you want your objects to appear in the
-acs_objects table, then your new type must be a subtype of
-acs_object.
Call acs_attribute.create_attribute() to fill in information
+acs_objects table, then your new type must be a subtype of
+acs_object.
Call acs_attribute.create_attribute() to fill in information
 on the attributes that this type defines.
So, suppose we are writing a new version of the ticket tracker for 4.0. We
 probably define a table to store tickets in, and each ticket might have an ID
 and a description. If we want each ticket to be an object, then
-ticket_id must reference the object_id column in
-acs_objects:
+ticket_id must reference the object_id column in
+acs_objects:
 
-create table tickets ( 
+create table tickets ( 
     ticket_id references acs_objects (object_id),
     description varchar(512), 
     ... 
 ) ;
-
+
 
 
In addition to defining the table, we need this extra PL/SQL code to hook
 into the object type tables:
 
-declare
+declare
  attr_id acs_attributes.attribute_id%TYPE;
 begin
  acs_object_type.create_type (
@@ -562,25 +561,25 @@
 
 commit;
 end;
-
+
 
 
Thus, with a small amount of extra code, the new ticket tracker will now
 automatically be hooked into every generic object service that exists. Better
 still, this code need not be changed as new services are added. As an aside,
 the most important service that requires you to subtype
-acs_object is permissions.
Objects
The next important piece of the API is defined in the
-acs_object package, and is concerned with creating and managing
+acs_object is permissions.
Objects
The next important piece of the API is defined in the
+acs_object package, and is concerned with creating and managing
 objects. This part of the API is designed to take care of the mundane
 bookkeeping needed to create objects and query their attributes.
 Realistically however, limitations in PL/SQL and Oracle will make it hard to
 build generic procedures for doing large scale queries in the object system,
 so developers who need to do this will probably have to be fairly familiar
-with the data model at a lower level.
The function acs_object.new() makes a new object for you. The
-function acs_object.del() deletes an object. As before, this
+with the data model at a lower level.
The function acs_object.new() makes a new object for you. The
+function acs_object.del() deletes an object. As before, this
 is an abbreviated interface with all the long type specs removed. See the
 data model or developer's guide for the full interface.
 
- function new (
+ function new (
   object_id     in acs_objects.object_id%TYPE default null,
   object_type   in acs_objects.object_type%TYPE
                            default 'acs_object',
@@ -595,28 +594,28 @@
  procedure delete (
   object_id     in acs_objects.object_id%TYPE
  );
-
+
 
 
Next, we define some generic functions to manipulate attributes. Again,
 these interfaces are useful to an extent, but for large scale queries,
 it's likely that developers would have to query the data model directly,
-and then encapsulate their queries in procedures.
For names, the default_name function is used if you don't
+and then encapsulate their queries in procedures.
For names, the default_name function is used if you don't
 want to define your own name function.
 
- function name (
+ function name (
   object_id     in acs_objects.object_id%TYPE
  ) return varchar;
 
  function default_name (
   object_id     in acs_objects.object_id%TYPE
  ) return varchar;
 
-
+
 
 
The following functions tell you where attributes are stored, and fetch
 single attributes for you.
 
- procedure get_attribute_storage ( 
+ procedure get_attribute_storage ( 
    object_id_in      in  acs_objects.object_id%TYPE,
    attribute_name_in in  acs_attributes.attribute_name%TYPE,
    v_column          out varchar2,
@@ -634,17 +633,17 @@
    attribute_name_in in  acs_attributes.attribute_name%TYPE,
    value_in          in  varchar2
  );
-
+
 
-
The main use of the acs_object package is to create
+

The main use of the acs_object package is to create application objects and make them available for services via the -acs_objects table. To do this, you just have to make sure you -call acs_object.new() on objects that you wish to appear in the -acs_objects table. In addition, all such objects must be -instances of some subtype of acs_object.

Continuing the ticket example, we might define the following sort of +acs_objects table. To do this, you just have to make sure you +call acs_object.new() on objects that you wish to appear in the +acs_objects table. In addition, all such objects must be +instances of some subtype of acs_object.

Continuing the ticket example, we might define the following sort of procedure for creating a new ticket:

 
- function new_ticket (
+ function new_ticket (
   package_id        in tickets.ticket_id%TYPE 
             default null,
   description       in tickets.description%TYPE default '',
@@ -664,42 +663,42 @@
     (v_ticket_id, description);
     return v_ticket_id;
   end new_ticket;
-
+

This function will typically be defined in the context of a PL/SQL package, but we've left it stand-alone here for simplicity.

To summarize: in order to take advantage of OpenACS 4 services, a new application need only do three things:

Define a data model to describe application objects. This can just be a normal SQL table.
Create an object type, using code like in the example from the previous section.
Make sure application objects are created using -acs_object.new() in addition to whatever SQL code is needed to +acs_object.new() in addition to whatever SQL code is needed to insert a new row into the application data model.

One of the design goals of OpenACS 4 was to provide a straightforward and consistent mechanism to provide applications with general services. What we have seen here is that three simple steps and minimal changes in the application data model are sufficient to make sure that application objects -are represented in the acs_objects table. Subsequently, all of +are represented in the acs_objects table. Subsequently, all of the general services in OpenACS 4 (i.e. permissions, general comments, and so on) -are written to work with any object that appears in acs_objects. +are written to work with any object that appears in acs_objects. Therefore, in general these three steps are sufficient to make OpenACS 4 services -available to your application.

Relation Types

The relations system defines two packages: acs_rel_type for -creating and managing relation types, and acs_rel for relating +available to your application.

Relation Types

The relations system defines two packages: acs_rel_type for +creating and managing relation types, and acs_rel for relating objects.

These two procedures just insert and remove roles from the -acs_rel_roles table. This table stores the legal relationship -"roles" that can be used when creating relation types. Examples of -roles are, say, "member", or "employer".

+acs_rel_roles table. This table stores the legal relationship
+"roles" that can be used when creating relation types. Examples of
+roles are, say, "member", or "employer".
 
- procedure create_role (
+ procedure create_role (
     role        in acs_rel_roles.role%TYPE
   );
 
   procedure drop_role (
     role        in acs_rel_roles.role%TYPE
   );
-
+
 
-
The main functions in the acs_rel_type package are used to
+

The main functions in the acs_rel_type package are used to create and drop relation types.

 
-  procedure create_type (
+  procedure create_type (
     rel_type            in acs_rel_types.rel_type%TYPE,
     pretty_name         in acs_object_types.pretty_name%TYPE,
     pretty_plural       in acs_object_types.pretty_plural%TYPE,
@@ -725,12 +724,12 @@
     rel_type            in acs_rel_types.rel_type%TYPE,
     cascade_p           in char default 'f'
   );
-
+
 
-

Finally, the acs_rel package provides an API that you use to +

Finally, the acs_rel package provides an API that you use to create and destroy instances of a relation type:

 
-  function new (
+  function new (
     rel_id              in acs_rels.rel_id%TYPE default null,
     rel_type            in acs_rels.rel_type%TYPE default 'relationship',
     object_id_one       in acs_rels.object_id_one%TYPE,
@@ -743,15 +742,15 @@
   procedure delete (
     rel_id      in acs_rels.rel_id%TYPE
   );
-
+

A good example of how to use relation types appears in the OpenACS 4 data model for groups. As in 3.x, group membership is modeled using a mapping table, but now we create this mapping using relation types instead of explicitly creating a table. First, we create a helper table to store state on each membership fact:

 
-create table membership_rels (
+create table membership_rels (
         rel_id          constraint membership_rel_rel_id_fk
                         references acs_rels (rel_id)
                         constraint membership_rel_rel_id_pk
@@ -761,11 +760,11 @@
                         check (member_state in ('approved', 'banned',
                                                 'rejected', 'deleted'))
 );
-
+

Then, we create a new object type to describe groups.

 
- acs_object_type.create_type (
+ acs_object_type.create_type (
    object_type => 'group',
    pretty_name => 'Group',
    pretty_plural => 'Groups',
@@ -774,18 +773,18 @@
    type_extension_table => 'group_types',
    name_method => 'acs_group.name'
  );
-
+

In this example, we've made groups a subtype of -acs_object to make the code simpler. The actual data model is +acs_object to make the code simpler. The actual data model is somewhat different. Also, we've assumed that there is a helper table -called groups to store information on groups, and that there is -a helper table called group_types that has been defined to store -extra attributes on groups.

Now, assuming we have another object type called person to +called groups to store information on groups, and that there is +a helper table called group_types that has been defined to store +extra attributes on groups.

Now, assuming we have another object type called person to represent objects that can be group members, we define the following relationship type for group membership:

 
- acs_rel_type.create_role ('member');
+ acs_rel_type.create_role ('member');
 
  acs_rel_type.create_type (
    rel_type => 'membership_rel',
@@ -798,16 +797,16 @@
    object_type_two => 'person', role_two => 'member',
    min_n_rels_two => 0, max_n_rels_two => null
  );
-
+

Now we can define the following procedure to add a new member to a group. All this function does is create a new instance of the membership relation type and then insert the membership state into the helper table that we define above. In the actual implementation, this function is implemented in -the membership_rel package. Here we just define an independent +the membership_rel package. Here we just define an independent function:

 
-function member_add (
+function member_add (
     rel_id              in membership_rels.rel_id%TYPE default null,
     rel_type            in acs_rels.rel_type%TYPE default 'membership_rel',
     group               in acs_rels.object_id_one%TYPE,
@@ -834,12 +833,12 @@
     value
      (v_rel_id, new.member_state);
   end;
-
+

Another simple function can be defined to remove a member from a group:

 
-  procedure member_delete (
+  procedure member_delete (
     rel_id  in membership_rels.rel_id%TYPE
   )
   is
@@ -849,13 +848,13 @@
 
     acs_rel.del(rel_id);
   end;
-
+
 
-

Summary and Discussion

The Object Model's API and data model provides a small set of simple +

Summary and Discussion

The Object Model's API and data model provides a small set of simple procedures that allow applications to create object types, object instances, and object relations. Most of the data model is straightforward; the relation type mechanism is a bit more complex, but in return it provides functionality -on par with the old user/groups system in a more general way.

Future Improvements/Areas of Likely Change

Nothing here yet.

Authors

Pete Su generated this document +on par with the old user/groups system in a more general way.

Future Improvements/Areas of Likely Change

Nothing here yet.

Authors

Pete Su generated this document from material culled from other documents by Michael Yoon, Richard Li and Rafael Schloming. But, any remaining lies -are his and his alone.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/09/2000	Pete Su
0.2	Edited for ACS 4 Beta	9/30/2000	Kai Wu
0.3	Edited for ACS 4.0.1, fixed some mistakes, removed use of term -"OM"	11/07/2000	Pete Su

Prev	Home	Next
Object Model Requirements	Up	Permissions Requirements

docs@openacs.org

View comments on this page at openacs.org +are his and his alone.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/09/2000	Pete Su
0.2	Edited for ACS 4 Beta	9/30/2000	Kai Wu
0.3	Edited for ACS 4.0.1, fixed some mistakes, removed use of term +"OM"	11/07/2000	Pete Su

Prev	Home	Next
Object Model Requirements	Up	Permissions Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -r1.27.2.1 -r1.27.2.2 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 14 Jan 2007 04:20:10 -0000 1.27.2.1 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 14 Jul 2007 12:34:47 -0000 1.27.2.2 @@ -1,56 +1,55 @@ - -Object Model Requirements

Prev	Chapter�15.�Kernel Documentation	Next

Object Model Requirements

By Pete Su

+Object Model Requirements

Prev	Chapter�15.�Kernel Documentation	Next

Object Model Requirements

By Pete Su

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

I. Introduction

A major goal in OpenACS 4 is to unify and normalize many of the core services +

I. Introduction

A major goal in OpenACS 4 is to unify and normalize many of the core services of the system into a coherent common data model and API. In the past, these services were provided to applications in an ad-hoc and irregular fashion. Examples of such services include:

General Comments
User/groups
Attribute storage in user/groups
General Permissions
Site wide search
General Auditing

All of these services involve relating extra information and services to application data objects, examples of which include:

Bboard messages
A user home page
A ticket in the Ticket Tracker
A photograph in the PhotoDB

In the past, developers had to use ad-hoc and inconsistent schemes to -interface to the various "general" services mentioned above. Since +interface to the various "general" services mentioned above. Since each service used its own scheme for storing its metadata and mapping this data to application objects, we could not implement any kind of centralized management system or consistent administrative pages for all the services. Consequently, a large amount of duplicate code appeared throughout the system -for dealing with these services.

Unifying and "normalizing" these interfaces, to minimize the +for dealing with these services.

Unifying and "normalizing" these interfaces, to minimize the amount of code repetition in applications, is a primary goal of OpenACS 4. Thus the Object Model (OM, also referred to later as the object system) is concerned primarily with the storage and management of metadata, on -any object within a given instance of OpenACS 4. The term "metadata" +any object within a given instance of OpenACS 4. The term "metadata" refers to any extra data the OM stores on behalf of the application - outside of the application's data model - in order to enable certain generic -services. The term "object" refers to any entity being represented +services. The term "object" refers to any entity being represented within the OpenACS, and typically corresponds to a single row within the -relational database.

Vision Statement

The OpenACS 4 Object Model must address five high-level requirements that +relational database.

Vision Statement

The OpenACS 4 Object Model must address five high-level requirements that repeatedly exhibit themselves in the context of existing services in OpenACS 3.x, -as described below.

Object Identifiers for General Services

Generic services require a single unambiguous way of identifying +as described below.

Object Identifiers for General Services

Generic services require a single unambiguous way of identifying application objects that they manage or manipulate. In OpenACS 3.x, there are several different idioms that construct object identifiers from other data. -Many modules use a (user_id, group_id, scope) triple combination +Many modules use a (user_id, group_id, scope) triple combination for the purpose of recording ownership information on objects for access -control. User/groups also uses (user_id, group_id) pairs in its -user_group_map table as a way to identify data associated with a +control. User/groups also uses (user_id, group_id) pairs in its +user_group_map table as a way to identify data associated with a single membership relation.

Also in OpenACS 3.x, many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, general comments maintains a mapping table that maps application -"page" data (static or dynamic) to one or more user comments on the +"page" data (static or dynamic) to one or more user comments on the page, by constructing a unique identifier for each page. This identifier is usually a combination of the table in which the data is stored, and the value of the primary key value for the particular page. This idiom is referred to -as the "(on_which_table + on_what_id)" method for identifying +as the "(on_which_table + on_what_id)" method for identifying application data. General comments stores its map from pages to comments -using a "(on_which_table + on_what_id)" key, plus the id of the +using a "(on_which_table + on_what_id)" key, plus the id of the comment itself.

All of these composite key constructions are implicit object identifiers: they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent. This makes the construction of generic application-independent services difficult. Therefore, the OpenACS 4 Object Model should provide a centralized and uniform -mechanism for tagging application objects with unique identifiers.

Support for Unified Access Control

Access control should be as transparent as possible to the application +mechanism for tagging application objects with unique identifiers.

Support for Unified Access Control

Access control should be as transparent as possible to the application developer. Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later -on, a notion of "scoping" was introduced into the core data -model.

"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:

...	`scope`	`user_id`	`group_id`	...
...	`user`	`123`	�	...
...	`group`	�	`456`	...
...	`public`	�	�	...

The first row represents an entry in User 123's personal address book, +on, a notion of "scoping" was introduced into the core data +model.

"Scope" is a term best explained by example. Consider some +hypothetical rows in the address_book table:

...	`scope`	`user_id`	`group_id`	...
...	`user`	`123`		...
...	`group`		`456`	...
...	`public`			...

In this way, the scoping columns identify the security context in which a @@ -64,9 +63,9 @@ page, a security problem could result.

Thus the OpenACS 4 Object Model must support a more general access control system that allows access control domains to be hierarchical, and specifiable with a single piece of data, instead of the old composite keys described -above.

Extensible Data Models

Another problem with previous OpenACS data models is that many of the central +above.

Extensible Data Models

Another problem with previous OpenACS data models is that many of the central tables in the system became bloated as they were extended to support an -increasing number of modules. The users table is the best case +increasing number of modules. The users table is the best case in point: it became full of columns that exist for various special applications (e.g. user portraits), but that aren't really related to each other in any way except that they store information on users, i.e. the @@ -82,33 +81,33 @@ custom extensions to the existing data models, and the OM does the bookkeeping necessary to make this easier, providing a generic API for object creation that automatically keeps track of the location and relationships -between data.

Design Note: While this doesn't really belong in a +between data.

Design Note: While this doesn't really belong in a requirements document, the fact that we are constrained to using relational databases means that certain constraints on the overall design of the object -data model exist, which you can read about in Summary and Design Considerations.

Modifiable Data Models

Another recurring applications problem is how to store a modifiable data +data model exist, which you can read about in Summary and Design Considerations.

Modifiable Data Models

Another recurring applications problem is how to store a modifiable data model, or how to store information that may change extensively between releases or in different client installations. Furthermore, we want to avoid changes to an application's database queries in the face of any custom extensions, since such changes are difficult or dangerous to make at runtime, and can make updating the system difficult. Some example applications in OpenACS 3.x with modifiable data models include:

User/groups: developers and users can attach custom data to group types, -groups, and members of groups.
In the Ecommerce data model, the ec_custom_product_fields +groups, and members of groups.
In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the -ec_custom_product_field_values table stores values for those -attributes.
In the PhotoDB data model, the ph_custom_photo_fields table +ec_custom_product_field_values table stores values for those +attributes.
In the PhotoDB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables named according to the convention -"ph_user_<user_id>_custom_info" are used to +"ph_user_<user_id>_custom_info" are used to store values for those attributes.

Thus the Object Model must provide a general mechanism for applications and developers to modify or extend data models, without requiring changes to the SQL schema of the system. This ensures that all applications use the same -base schema, resulting in a uniform and more maintainable system.

Generic Relations

Many OpenACS applications define simple relationships between application +base schema, resulting in a uniform and more maintainable system.

Generic Relations

Many OpenACS applications define simple relationships between application objects, and tag those relationships with extra data. In OpenACS 3.x, this was done using mapping tables. The user/groups module has the most highly developed data model for this purpose, using a single table called -user_group_map that mapped users to groups. In addition, it uses -the the user_group_member_fields and -user_group_member_fields_map tables to allow developers to +user_group_map that mapped users to groups. In addition, it uses +the the user_group_member_fields and +user_group_member_fields_map tables to allow developers to attach custom attributes to group members. In fact, these custom attributes were not really attached to the users, but to the fact that a user was a member of a particular group - a subtle but important distinction. As a @@ -120,17 +119,17 @@ Relation types are themselves object types that do nothing but represent relations. They can be used by applications that previously used user/groups for the same purpose, but without the extraneous, artificial -dependencies.

System Overview

The Object Model package is a combination of data model and a procedural +dependencies.

System Overview

The Object Model package is a combination of data model and a procedural API for manipulating application objects within an OpenACS instance. The OM allows developers to describe a hierarchical system of object types that store metadata on application objects. The object type system supports subtyping with inheritance, so new object types can be defined in terms of existing object types.

The OM data model forms the main part of the OpenACS 4 Kernel data model. The -other parts of the Kernel data model include:

Parties and Groups
Permissions

Each of these is documented elsewhere at length.

Use-cases and User-scenarios

(Pending as of 8/27/00)

Requirements: Data Model

The data model for the object system provides support for the following -kinds of schema patterns that are used by many existing OpenACS modules:

10.0 Object Identification and Storage

Object identification is a central mechanism in the new metadata system. +other parts of the Kernel data model include:

Parties and Groups
Permissions

Each of these is documented elsewhere at length.

Use-cases and User-scenarios

(Pending as of 8/27/00)

Requirements: Data Model

The data model for the object system provides support for the following +kinds of schema patterns that are used by many existing OpenACS modules:

10.0 Object Identification and Storage

Object identification is a central mechanism in the new metadata system. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. Thus the only action required of -an application to obtain any general service is to "hook into" the +an application to obtain any general service is to "hook into" the object system.

In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for objects that they manage. Generally, these unique IDs are built from other IDs that happen to be in the data model. Because there is no consistency in @@ -148,15 +147,15 @@ application data. More importantly, object identifiers will enable developers to readily build and use generic services that work globally across a system.

The object identifiers should be subject to the following -requirements:

10.10 Uniqueness

The object ID should be unique among all the IDs in the entire OpenACS system -in which the object lives.

10.20 Useful as a Reference

Applications should be able to use the unique object ID as a reference, -with which they can fetch any or all of the object's attributes.

10.30 Storable

Object IDs should be storable in tables. e.g. you should be able to use +requirements:

10.10 Uniqueness

The object ID should be unique among all the IDs in the entire OpenACS system +in which the object lives.

10.20 Useful as a Reference

Applications should be able to use the unique object ID as a reference, +with which they can fetch any or all of the object's attributes.

10.30 Storable

Object IDs should be storable in tables. e.g. you should be able to use them to implement mapping tables between objects, to represent -relationships.

10.40 Moveable

Objects should be mobile between databases. That is, information will +relationships.

10.40 Moveable

Objects should be mobile between databases. That is, information will often need to be moved between multiple servers (development, staging, and production), so a mechanism for moving this data is necessary. In addition, a mechanism for tagging these objects in a way similar to CVS would be useful -in determining which objects need to be synchronized.

20.0 Object Types

An object type refers to a specification of one or more +in determining which objects need to be synchronized.

20.0 Object Types

An object type refers to a specification of one or more attributes to be managed along with a piece of application data.

The object system should provide a data model for describing and representing object types. This data model is somewhat analogous to the Oracle data dictionary, which stores information about all user defined @@ -169,33 +168,33 @@ is meant to be a generalization of this mechanism. The data model should allow developers to at least do everything they used to with user/groups, but without its administrative hassles.

Therefore, the data model must be able to represent object types that have -the following characteristics:

20.10 Type Name

A human readable name for the object type.

20.20 Type Attributes

Attributes whose values are shared by all instances of the object -type.

20.30 Object Attributes

Attributes that are specific to each particular object belonging to a -given type.

The data model must also enforce certain constraints on object types:

20.40 Type Uniqueness

Object type names must be unique.

20.50 Attribute Name Uniqueness

Attribute names must be unique in the scope of a single object type and -any of its parent types.

30.0 Type Extension

The Object Model must support the definition of object types that are +the following characteristics:

20.10 Type Name

A human readable name for the object type.

20.20 Type Attributes

Attributes whose values are shared by all instances of the object +type.

20.30 Object Attributes

Attributes that are specific to each particular object belonging to a +given type.

The data model must also enforce certain constraints on object types:

20.40 Type Uniqueness

Object type names must be unique.

20.50 Attribute Name Uniqueness

Attribute names must be unique in the scope of a single object type and +any of its parent types.

30.0 Type Extension

The Object Model must support the definition of object types that are subtypes of existing types. A subtype inherits all the attributes of its parent type, and defines some attributes of its own. A critical aspect of the OM is parent types may be altered, and any such change must propagate to child subtypes.

The OM data model must enforce constraints on subtypes that are similar to -the ones on general object types.

30.10 Subtype Uniqueness

Subtype names must be unique (this parallels requirement 10.40).

30.20 Subtype Attribute Name Uniqueness

Attribute names must be unique in the scope of a single object -subtype.

30.30 Parent Type Prerequisite

Subtypes must be defined in terms of parent types that, in fact, already -exist.

30.40

The extended attribute names in a subtype must not be the same as those in -its parent type.

35.0 Methods

35.10 Method and Type Association

The OM data model should define a mechanism for associating procedural +the ones on general object types.

30.10 Subtype Uniqueness

Subtype names must be unique (this parallels requirement 10.40).

30.20 Subtype Attribute Name Uniqueness

Attribute names must be unique in the scope of a single object +subtype.

30.30 Parent Type Prerequisite

Subtypes must be defined in terms of parent types that, in fact, already +exist.

30.40

The extended attribute names in a subtype must not be the same as those in +its parent type.

35.0 Methods

35.10 Method and Type Association

The OM data model should define a mechanism for associating procedural code, called methods, with objects of a given type. Methods are associated with the each object type - not each object -instance.

35.20 Method Sharing

All instances of a given object type should share the same set of defined -methods for that type.

40.0 Object Attribute Value Storage

In addition to information on types, the OM data model provides for the +instance.

35.20 Method Sharing

All instances of a given object type should share the same set of defined +methods for that type.

40.0 Object Attribute Value Storage

In addition to information on types, the OM data model provides for the centralized storage of object attribute values. This facility unifies the many ad-hoc attribute/value tables that exist in various OpenACS 3.x data models, such as:

User groups: Each instance of a group type can have custom data.
Photo DB: Users can define their own custom metadata to attach to photograph objects.
Ecommerce: Vendors can attach custom fields to the data model describing -their products.

40.10 Generic Retrieval

Attributes should be stored so that they are retrievable in a way that is +their products.

40.10 Generic Retrieval

Attributes should be stored so that they are retrievable in a way that is independent of the type of the object that they belong to. That is, the only data needed to retrieve an attribute should be the system-wide ID of an -object (see requirement 10.20 above) and the attribute name.

40.20 Inherited Attributes

The system should allow for the automatic retrieval of inherited attribute -values, for an object belonging to a subtype.

40.30. Constraints on Attributes

The system should allow the developer to put down constraints on the +object (see requirement 10.20 above) and the attribute name.

40.20 Inherited Attributes

The system should allow for the automatic retrieval of inherited attribute +values, for an object belonging to a subtype.

40.30. Constraints on Attributes

The system should allow the developer to put down constraints on the values that an attribute may hold, for the purposes of maintaining -application specific integrity rules.

50.0 Object Contexts

In OpenACS 3.x, there was a notion of "scope" for application +application specific integrity rules.

50.0 Object Contexts

In OpenACS 3.x, there was a notion of "scope" for application objects. An object could be belong to one of three scopes: public, group or user. This provided a crude way to associate objects with particular scopes in the system, but it was awkward to use and limited in flexibility.

The OpenACS 4 Object Model provides a generalized notion of scope that allows @@ -204,64 +203,64 @@ object has no explicit permissions attached to it, then it inherits permissions from its context.

The context data model also forms the basis of the subsites system, and is a basic part of the permissions system, -described in separate documents.

The context data model should provide the following facilities:

50.10 Unique ID

Every context should have a unique ID in the system.

50.20 Tree Structure

The data model should support a tree structured organization of contexts. -That is, contexts can be logically "contained" within other +described in separate documents.

The context data model should provide the following facilities:

50.10 Unique ID

Every context should have a unique ID in the system.

50.20 Tree Structure

The data model should support a tree structured organization of contexts. +That is, contexts can be logically "contained" within other contexts (i.e. contexts have parents) and contexts can contain other contexts -(i.e. contexts can have children).

50.30 Data Model Constraints

All objects must have a context ID. This ID must refer to an existing +(i.e. contexts can have children).

50.30 Data Model Constraints

All objects must have a context ID. This ID must refer to an existing context or be NULL. The meaning of a NULL context is determined by the -implementation.

Note:

The current system interprets the NULL context as meaning the default -"site-wide" context in some sense. I wanted to note this fact for +implementation.

Note:

The current system interprets the NULL context as meaning the default +"site-wide" context in some sense. I wanted to note this fact for others, but there is no need to make this a requirement of the system. I think it would be reasonable to have a NULL context be an error (psu -8/24/2000).

55.0 Object Relations

The data model should include a notion of pair-wise relations between +8/24/2000).

55.0 Object Relations

The data model should include a notion of pair-wise relations between objects. Relations should be able to record simple facts of the form -"object X is related to object Y by relationship R," and also be -able to attach attributes to these facts.

Requirements: API

The API should let programmers accomplish the following actions:

60.0 Object Type Creation

60.10 Create a New Object Type

The object system API should provide a procedure call that creates a new +"object X is related to object Y by relationship R," and also be +able to attach attributes to these facts.

Requirements: API

The API should let programmers accomplish the following actions:

60.0 Object Type Creation

60.10 Create a New Object Type

The object system API should provide a procedure call that creates a new object type by running the appropriate transactions on the object system data model. This API call is subject to the constraints laid out in the data -model. We call this operation "instantiating" an object.

60.20 Create a New Object Subtype

The object system API should provide a procedure call for creating +model. We call this operation "instantiating" an object.

60.20 Create a New Object Subtype

The object system API should provide a procedure call for creating subtypes of a given type. Operationally, this API is the same as requirement 60.10. Instances of subtypes automatically contain all attributes of the parent type in addition to all attributes of the subtype. This API is subject -to the constraints laid out in the data model.

60.30 Create a New Relation Type

There should be an API call to create a new type of object relation. +to the constraints laid out in the data model.

60.30 Create a New Relation Type

There should be an API call to create a new type of object relation. Relation types can be modeled as object types. The API below for manipulating -attributes can then be used to add attributes to relation types.

70.0 Update an Object Type

The object system API must allow the programmer to modify, add, and delete +attributes can then be used to add attributes to relation types.

70.0 Update an Object Type

The object system API must allow the programmer to modify, add, and delete attributes from any object type. Updates should be propagated to any child subtypes. This API is subject to the constraints laid out in the data -model.

80.0 Delete an Object Type

The system provides an API call for deleting an object type.

80.10

Deleting an object type destroys all instances of the type. It should be +model.

80.0 Delete an Object Type

The system provides an API call for deleting an object type.

80.10

Deleting an object type destroys all instances of the type. It should be an error to delete types that have dependent subtypes. This API is subject to -the constraints laid out in the data model.

80.10.10

However, the programmer should also be able to specify that all the +the constraints laid out in the data model.

80.10.10

However, the programmer should also be able to specify that all the subtypes and instances of those subtypes be destroyed before destroying the -object type. This is similar to a "delete cascade" constraint in -SQL.

90.0 Object Instance Creation and Destruction

The system must provide API calls to manage the creation and destruction -of object instances.

90.10 Create an Instance of an Object Type

The system should provide an API call for creating a new instance of a +object type. This is similar to a "delete cascade" constraint in +SQL.

90.0 Object Instance Creation and Destruction

The system must provide API calls to manage the creation and destruction +of object instances.

90.10 Create an Instance of an Object Type

The system should provide an API call for creating a new instance of a given object type. The new instance should be populated with values for each of the attributes specified in the definition of the type. In addition, it should be possible to create the new instance with an optional context ID -that refers to the default context that the object will live in.

90.20 Delete an Object Instance

The OM should provide an API call for object deletion. Objects can be +that refers to the default context that the object will live in.

90.20 Delete an Object Instance

The OM should provide an API call for object deletion. Objects can be deleted only when no other objects in the system refer to them. Since it -might not be practical to provide a mechanism like "delete cascade" +might not be practical to provide a mechanism like "delete cascade" here in a reliable way, providing such a facility in the system is -optional.

94.0 Object Relation Creation and Destruction

The system must provide API calls to manage the creation and destruction -of object relations.

94.10 Create an Object Relation

The OM must provide an API call to declare that two objects are related to +optional.

94.0 Object Relation Creation and Destruction

The system must provide API calls to manage the creation and destruction +of object relations.

94.10 Create an Object Relation

The OM must provide an API call to declare that two objects are related to each other by a given relation type. This API call should also allow -programmers to attach attributes to this object relation.

94.20 Destroy an Object Relation

There should be an API call for destroying object relations and their -attributes.

95.10 Create and Destroy Contexts

The system should provide an API to create and destroy object -contexts.

100.10 Set Attribute Values for an Object

The system should provide an API for updating the attribute values of a -particular instance of an object type.

110.10 Get Attribute Values for an Object

The system should provide an API for retrieving attribute values from a -particular instance of an object type.

120.10 Efficiency

The Object Model must support the efficient storage and retrieval of +programmers to attach attributes to this object relation.

94.20 Destroy an Object Relation

There should be an API call for destroying object relations and their +attributes.

95.10 Create and Destroy Contexts

The system should provide an API to create and destroy object +contexts.

100.10 Set Attribute Values for an Object

The system should provide an API for updating the attribute values of a +particular instance of an object type.

110.10 Get Attribute Values for an Object

The system should provide an API for retrieving attribute values from a +particular instance of an object type.

120.10 Efficiency

The Object Model must support the efficient storage and retrieval of object attributes. Since the OM is intended to form the core of many general services in the OpenACS, and these services will likely make extensive use of the OM tables, queries on these tables must be fast. The major problem here seems to be supporting subtyping and inheritance in a way that does not severely -impact query performance.

130.10 Ease of Use

Most OpenACS packages will be expected to use the Object Model in one way or +impact query performance.

130.10 Ease of Use

Most OpenACS packages will be expected to use the Object Model in one way or another. Since it is important that the largest audience of developers possible adopts and uses the OM, it must be easy to incorporate into applications, and it must not impose undue requirements on an -application's data model. In other words, it should be easy to "hook -into" the object model, and that ability should not have a major impact -on the application data model.

Note: Is the API the only way to obtain values? How does -this integrate with application level SQL queries?

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 08/10/2000 Bryan Quinn

0.2 Major re-write 08/11/2000 Pete Su

0.3 Draft completed after initial reviews 08/22/2000 Pete Su

0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu

� Final edits before freeze 08/24/2000 Pete Su

0.5 Edited for consistency 08/27/2000 Kai Wu

0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su

0.7

Added requirement that knowledge-level objects must be moveable between +application's data model. In other words, it should be easy to "hook +into" the object model, and that ability should not have a major impact +on the application data model.

Note: Is the API the only way to obtain values? How does +this integrate with application level SQL queries?

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/10/2000	Bryan Quinn
0.2	Major re-write	08/11/2000	Pete Su
0.3	Draft completed after initial reviews	08/22/2000	Pete Su
0.4	Edited, updated to conform to requirements template, pending freeze	08/23/2000	Kai Wu
	Final edits before freeze	08/24/2000	Pete Su
0.5	Edited for consistency	08/27/2000	Kai Wu
0.6	Put Object ID stuff first, because it makes more sense	08/28/2000	Pete Su
0.7	Added requirement that knowledge-level objects must be moveable between databases.	08/29/2000	Richard Li
0.8	Rewrote intro to match language and concepts in the design document. Also cleaned up usage a bit in the requirements section. Added short vague requirements on relation types.	09/06/2000	Pete Su
0.9	Edited for ACS 4 Beta release.	09/30/2000	Kai Wu

Prev	Home	Next
Overview	Up	Object Model Design

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v diff -u -r1.45.2.2 -r1.45.2.3 --- openacs-4/packages/acs-core-docs/www/objects.html 22 Apr 2007 10:21:56 -0000 1.45.2.2 +++ openacs-4/packages/acs-core-docs/www/objects.html 14 Jul 2007 12:34:47 -0000 1.45.2.3 @@ -1,9 +1,8 @@ - -OpenACS Data Models and the Object System

Prev	Chapter�11.�Development Reference	Next

OpenACS Data Models and the Object System

By Pete Su

+OpenACS Data Models and the Object System

Prev	Chapter�11.�Development Reference	Next

OpenACS Data Models and the Object System

By Pete Su

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Overview

-Developing data models in OpenACS 5.3.1 is much like developing data models +

Overview

+Developing data models in OpenACS 5.3.2 is much like developing data models for OpenACS 3, save for the implementation. As usual, you need to examine how to model the information that the application must store and manipulate, and define a suitable set of SQL tables. In our Notes @@ -28,12 +27,12 @@

Define access control policies on notes.
Attach user comments on notes.
Allow users to define custom fields to store on their notes.
Automatically generate input forms or output displays for notes.
Allow other applications to use notes in ways we don't know of yet.

In OpenACS, the key to enabling these types of services on your application data is to take advantage of the Object System. The first -question, then, is "Just what are objects, and what do -you use them for anyway?". The short answer: objects are anything +question, then, is "Just what are objects, and what do +you use them for anyway?". The short answer: objects are anything represented in the application's data model that will need to be managed by any central service in OpenACS, or that may be reusable in the context of future applications. Every object in the system is -represented using a row in the acs_objects table. This +represented using a row in the acs_objects table. This table defines all the standard attributes that are stored on every object, including its system-wide unique ID, object type, and some generic auditing columns. @@ -45,19 +44,19 @@

The Permissions System lets you track who is allowed to do what to the rows in an application table, and gives you an easy way to enforce - this from Tcl.
Every object has an attribute called context_id + this from Tcl.
Every object has an attribute called context_id that provides a way to trivially specify both the default - permissions for an object, and the intended "scope" of an - object. Just set the context_id to the controlling + permissions for an object, and the intended "scope" of an + object. Just set the context_id to the controlling object and forget about it.
And most importantly, any future object-level service - from a general-comments replacement to personalized ranking - will - become available to your application "for free."

How to Use Objects

+ become available to your application "for free."

How to Use Objects

Using ACS objects is straightforward: all that's required are a few extra steps in the design of your application data model.

In order to hook our Notes application into the object system, we -make some calls to use our notes table as the basis for a +make some calls to use our notes table as the basis for a new object type. Object types are analogous to classes in programming languages such as C++ and Java. In Java, a class defines a set of attributes that store data and a set of methods @@ -66,21 +65,21 @@ define the programming interface to the data model.

The object type itself is described using data in the -acs_object_types and -acs_attributes tables, which play a role +acs_object_types and +acs_attributes tables, which play a role similar to the data dictionary in Oracle. As in Java, object types can inherit attributes from a parent type, so the type system forms a hierarchy. Unlike Java, Oracle does not support this inheritance transparently, so we have to make sure we add our own bookkeeping code to keep everything consistent. Below you'll find the code needed to describe a -new object type called notes in your +new object type called notes in your system.

Fire up your text editor and open the -ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created +ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created when we created the package. Then, do the following: -

Describe the new type to the type system

-First, add an entry to the acs_object_types table with the following PL/SQL call: +

Describe the new type to the type system

+First, add an entry to the acs_object_types table with the following PL/SQL call:

 begin  
   acs_object_type.create_type ( 
@@ -96,18 +95,18 @@
 show errors;

This PL/SQL call tells the system that we would like to use the table -NOTES as the basis for a new object type called -note. This type is a subtype of the -acs_object type, which means that we want to inherit all +NOTES as the basis for a new object type called +note. This type is a subtype of the +acs_object type, which means that we want to inherit all of the basic attributes of all ACS objects. As mentioned, it will take some work on our part to make this happen, since Oracle can't do it automatically. In general, most basic applications will define types -that are simple subtypes of acs_object. +that are simple subtypes of acs_object.

-Add entries to the acs_attributes table to describe +Add entries to the acs_attributes table to describe the data attributes of the new type. This data can eventually be used to do things like automatically generate user interfaces to manipulate -the notes table, though that functionality isn't yet +the notes table, though that functionality isn't yet available.

 declare 
@@ -133,17 +132,17 @@
 show errors;

We can stop here and not bother to register the usual OpenACS 3.x -attributes of creation_user, creation_date -and last_modified, since the object type -acs_object already defines these attributes. Again, -because the new type note is a subtype of -acs_object, it will inherit these attributes, so there is +attributes of creation_user, creation_date +and last_modified, since the object type +acs_object already defines these attributes. Again, +because the new type note is a subtype of +acs_object, it will inherit these attributes, so there is no need for us to define them. -

Define a table in which to store your objects

The next thing we do is make a small modification to the data model to -reflect the fact that each row in the notes table +reflect the fact that each row in the notes table represents something that is not only an object of type -note, but also an acs_object. The new table +note, but also an acs_object. The new table definition looks like this:

 create table notes (
@@ -153,18 +152,18 @@
     body       varchar(1024)
 )

-The usual creation_date and -modified_date columns are absent since they already exist -in acs_objects. Also, note the constraint we have added -to reference the acs_objects table, which makes clear -that since note is a subtype of acs_object, +The usual creation_date and +modified_date columns are absent since they already exist +in acs_objects. Also, note the constraint we have added +to reference the acs_objects table, which makes clear +that since note is a subtype of acs_object, every row in the notes table must have a corresponding row in the -acs_objects table. This is the fundamental means by which +acs_objects table. This is the fundamental means by which we model inheritance; it guarantees that any services that -use the acs_objects table to find objects will +use the acs_objects table to find objects will transparently find any objects that are instances of any subtype of -acs_objects. -

Define a package for type specific procedures

+acs_objects. +

Define a package for type specific procedures

The next step is to define a PL/SQL package for your new type, and write some basic procedures to create and delete objects. Here is a package definition for our new type: @@ -196,30 +195,30 @@ calls, since we haven't mentioned them before. These parameters are needed to fill out information that will be stored about the object that's not stored directly in the table you defined. The OpenACS Object -System defines these attributes on the type acs_object +System defines these attributes on the type acs_object since all objects should have these attributes. Internally, there are tables that store this information for you. Most of the data is pretty self-explanatory and reflects attributes that existed in the earlier -OpenACS 3.x data models, with the exception of the context_id +OpenACS 3.x data models, with the exception of the context_id attribute.

-The context_id attribute stores the ID of an object that +The context_id attribute stores the ID of an object that represents the default security domain to which the object belongs. It is used by the permissions system in this way: if no permissions are explicitly attached to the object, then the object inherits its permissions from the context. For example, if I had told you how to use the permissions system to specify that an -object OBJ was "read only", then any other object that used OBJ as its -context would also be "read only" by default. We'll talk about this more +object OBJ was "read only", then any other object that used OBJ as its +context would also be "read only" by default. We'll talk about this more later. -

Define a package body for type specific procedures

The PL/SQL package body contains the implementations of the procedures defined above. The only subtle thing going on here is that we must use -acs_object.new to insert a row into -acs_objects, before inserting a row into the -notes. Similarly, when we delete a row from -note, we have to be sure to delete the corresponding -acs_object row. +acs_object.new to insert a row into +acs_objects, before inserting a row into the +notes. Similarly, when we delete a row from +note, we have to be sure to delete the corresponding +acs_object row.

 create or replace package body note 
 as 
@@ -272,14 +271,14 @@
 / 
 show errors;

-That's pretty much it! As long as you use the note.new -function to create notes, and the note.delete function to +That's pretty much it! As long as you use the note.new +function to create notes, and the note.delete function to delete them, you'll be assured that the relationship each -note has with its corresponding acs_object +note has with its corresponding acs_object is preserved.

The last thing to do is to make a file -ROOT/packages/notes/sql/notes-drop.sql so it's easy to +ROOT/packages/notes/sql/notes-drop.sql so it's easy to drop the data model when, say, you're testing:

 begin 
@@ -290,17 +289,17 @@
  
 drop package note; 
 drop table notes; 
-

When to Use Objects

While it is hard to give general design advice without knowing anything about a particular application, you should follow the following rule of thumb when deciding when to hook part of your data model to the object system:

Anything in your data model that needs to be available to general OpenACS services such as user comments, permissions, and so on should be a -subtype of acs_object. In addition, if you want your data +subtype of acs_object. In addition, if you want your data model to take advantage of attributes that exist in some object type -that is a subtype of acs_object, then you should use the +that is a subtype of acs_object, then you should use the object system.

For example, for most applications, you will want to use objects to @@ -310,34 +309,34 @@ kind of design decision is mostly made on an application-by-application basis, but this is a good baseline from which to start. -

Design Guidance

In this section we cover some overall guidelines for designing data models that are meant to be integrated with the OpenACS object system.

-There are two basic rules you should follow when designing OpenACS 5.3.1 data +There are two basic rules you should follow when designing OpenACS 5.3.2 data models:

-Never utilize fields in the acs_objects table in +Never utilize fields in the acs_objects table in application specific ways. That is, never assign any application-specific semantics to this data. In the notes -application, we use the creation_date and -last_modified fields, but this is OK since we do not +application, we use the creation_date and +last_modified fields, but this is OK since we do not assign any application-specific meaning to these fields.
In particular, never assign any application specific semantics to the -context_id attribute of an object. This field is used for +context_id attribute of an object. This field is used for a very specific purpose by the permissions system, and using this field in any other way whatsoever is guaranteed to make your application act strangely.
As we'll see later, the Notes example will point each note object's -context_id to the package instance in which the note was +context_id to the package instance in which the note was created. The idea will be that in a real site, the administrator would create one package instance for every separate set of Notes (say, one -per user). The instance would "own" all of the notes that it created, +per user). The instance would "own" all of the notes that it created, and the administrator would be able to use the package instance as the basis for access control, which is convenient.

@@ -355,43 +354,43 @@ that the data model is trying to support.

Another less important reason for these two rules is to not introduce -any joins against the acs_objects table in SQL queries in +any joins against the acs_objects table in SQL queries in your application that you do not absolutely need.

In the Notes example, the result of applying these rules is that we -are careful to define our own attribute for owner_id -rather than overloading creation_user from the objects -table. But, since we will probably use creation_date and +are careful to define our own attribute for owner_id +rather than overloading creation_user from the objects +table. But, since we will probably use creation_date and so on for their intended purposes, we don't bother to define our own attributes to store that data again. This will entail joins with -acs_objects but that's OK because it makes the overall +acs_objects but that's OK because it makes the overall data model cleaner. The real lesson is that deciding exactly how and when to use inherited attributes is fairly straightforward, but requires a good amount of thought at design time even for simple applications. -

Summary

-Hooking into the OpenACS 5.3.1 object system brings the application developer +

Summary

+Hooking into the OpenACS 5.3.2 object system brings the application developer numerous benefits, and doing it involves only four easy steps:

Describe the a new object type to the system. Most new application -types will be subtypes of the built-in type acs_object. +types will be subtypes of the built-in type acs_object.
Define a table to store application object data.
Define a PL/SQL package to store procedures related to the new -type. You have to define at least a function called new +type. You have to define at least a function called new to create new application objects and a procedure called -delete to delete them. +delete to delete them.
Define a package body that contains the implementations of the PL/SQL procedures defined above.
Try not to write queries in your application that join against -acs_objects. This means you should never use the fields -in acs_objects for application-specific purposes. This is -especially true for the context_id field. +acs_objects. This means you should never use the fields +in acs_objects for application-specific purposes. This is +especially true for the context_id field.

($Id$)

Prev	Home	Next
OpenACS Packages	Up	The Request Processor

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v diff -u -r1.23.2.1 -r1.23.2.2 --- openacs-4/packages/acs-core-docs/www/openacs-overview.html 14 Jan 2007 04:20:10 -0000 1.23.2.1 +++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 14 Jul 2007 12:34:47 -0000 1.23.2.2 @@ -1,5 +1,4 @@ - -Overview

Prev	Chapter�1.�High level information: What is OpenACS?	Next

Overview

+Overview

Prev	Chapter�1.�High level information: What is OpenACS?	Next

Overview

OpenACS (Open Architecture Community System) is an advanced toolkit for building scalable, community-oriented web applications. If you're thinking of building an Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.html,v diff -u -r1.22.2.2 -r1.22.2.3 --- openacs-4/packages/acs-core-docs/www/openacs-unpack.html 22 Apr 2007 10:21:56 -0000 1.22.2.2 +++ openacs-4/packages/acs-core-docs/www/openacs-unpack.html 14 Jul 2007 12:34:47 -0000 1.22.2.3 @@ -1,18 +1,17 @@ - -Unpack the OpenACS tarball

Prev	Appendix�B.�Install additional supporting software	Next

Unpack the OpenACS tarball

The OpenACS tarball contains sample configuration files +Unpack the OpenACS tarball

Prev	Appendix�B.�Install additional supporting software	Next

Unpack the OpenACS tarball

The OpenACS tarball contains sample configuration files for some of the packages listed below. In order to access those - files, unpack the tarball now.

[root root]# cd /tmp -[root tmp]# tar xzf openacs-5.3.1.tgz + files, unpack the tarball now.

[root root]# cd /tmp
+[root tmp]# tar xzf openacs-5.3.2.tgz
 cd /tmp
-tar xzf openacs-5.3.1.tgz

If you are installing from a different method and just need the configuration files, you can instead get them from CVS:

[root root]# cd /tmp
-[root tmp]# cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/
+tar xzf openacs-5.3.2.tgz

If you are installing from a different method and just need the configuration files, you can instead get them from CVS:

[root root]# cd /tmp
+[root tmp]# cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/
 cvs checkout: warning: failed to open /root/.cvspass for reading: No such file or directory
 cvs server: Updating openacs-4/packages/acs-core-docs/www/files
 U openacs-4/packages/acs-core-docs/www/files/README.TXT
 (many lines omitted)
 U openacs-4/packages/acs-core-docs/www/files/template-ini.ini
 U openacs-4/packages/acs-core-docs/www/files/winnsd.txt
-[root tmp]# mv openacs-4 openacs-5.3.1
+[root tmp]# mv openacs-4 openacs-5.3.2
 cd /tmp
 cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/
 mv openacs-4 openacs-5.0.0a4

Prev	Home	Next
Appendix�B.�Install additional supporting software	Up	Initialize CVS (OPTIONAL)

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v diff -u -r1.44.2.2 -r1.44.2.3 --- openacs-4/packages/acs-core-docs/www/openacs.html 22 Apr 2007 10:21:56 -0000 1.44.2.2 +++ openacs-4/packages/acs-core-docs/www/openacs.html 14 Jul 2007 12:34:47 -0000 1.44.2.3 @@ -1,8 +1,7 @@ - -Install OpenACS 5.3.1

Prev	Chapter�3.�Complete Installation	Next

Install OpenACS 5.3.1

by Vinod Kurup

+Install OpenACS 5.3.2

Prev	Chapter�3.�Complete Installation	Next

Install OpenACS 5.3.2

by Vinod Kurup

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Set up a user account for each site.

AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and run as another user, which you must specify on the command line. It's @@ -15,60 +14,60 @@ for each different service. A service name should be a single word, letters and numbers only. If the name of your site is one word, that would be a good choice. For - example "$OPENACS_SERVICE_NAME" might be the service name for the + example "$OPENACS_SERVICE_NAME" might be the service name for the $OPENACS_SERVICE_NAME.net community.

We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put - it in the $OPENACS_SERVICE_NAME group so that it + it in the $OPENACS_SERVICE_NAME group so that it can use database and server commands associated with that group. (If you don't know how to do this, type - man usermod. You can type - groups to find out which groups a user + man usermod. You can type + groups to find out which groups a user is a part of)

-[root root]# useradd $OPENACS_SERVICE_NAME
+[root root]# useradd $OPENACS_SERVICE_NAME

You also need to set up a group called web.

-[root root]# groupadd web
+[root root]# groupadd web

Then change the user to be a part of this group:

-[root root]# usermod -g web $OPENACS_SERVICE_NAME
+[root root]# usermod -g web $OPENACS_SERVICE_NAME

FreeBSD creates the user this way:

-[root root]# mkdir -p /home/$OPENACS_SERVICE_NAME
-[root root]# pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash
+[root root]# mkdir -p /home/$OPENACS_SERVICE_NAME
+[root root]# pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash
 [root root]#
 mkdir -p /home/$OPENACS_SERVICE_NAME
 pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash
-

Set up the file system for one or more OpenACS Sites

For Linux Standard Base compliance and ease of backup, +

Set up the file system for one or more OpenACS Sites

For Linux Standard Base compliance and ease of backup, all of the files in each OpenACS site are stored in a subdirectory of - /var/lib/aolserver, one + /var/lib/aolserver, one subdirectory per site. The first time you install an OpenACS - site on a server, you must create the parent directory and set its permissions:

[root root]# mkdir /var/lib/aolserver
-[root root]# chgrp web /var/lib/aolserver
-[root root]# chmod 770 /var/lib/aolserver
+      site on a server, you must create the parent directory and set its permissions:
[root root]# mkdir /var/lib/aolserver
+[root root]# chgrp web /var/lib/aolserver
+[root root]# chmod 770 /var/lib/aolserver
 [root root]#
 mkdir /var/lib/aolserver
 chgrp web /var/lib/aolserver
-chmod 770 /var/lib/aolserver

Installation Option 1: Use automated script

A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation.

Get the install script from CVS. It is located within +chmod 770 /var/lib/aolserver

Installation Option 1: Use automated script

Get the install script from CVS. It is located within the main cvs tree, at /etc/install. Use anonymous CVS checkout to get that directory in the home directory of the service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target - location.

[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install
+        location.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install
 cvs server: Updating install
 U install/README
 U install/TODO
   ... many lines omitted ...
 U install/tcl/twt-procs.tcl
 U install/tcl/user-procs.tcl
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install
-[$OPENACS_SERVICE_NAME install]$ emacs install.tcl
-
Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file.  If your system is different from the one described in the previous sections, check the file paths as well.  Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation).  If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.
Run the install script install.sh as root:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit 
-[root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install
+[$OPENACS_SERVICE_NAME install]$ emacs install.tcl
+
Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file.  If your system is different from the one described in the previous sections, check the file paths as well.  Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation).  If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.
Run the install script install.sh as root:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit 
+[root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh
 /home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file 
 /home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/
 $OPENACS_SERVICE_NAME, server_url=http://0.0.0.0:8000, do_checkout=yes, do_install=yes, 
@@ -80,68 +79,68 @@
 admin email   : admin@yourserver.net
 admin password: xxxx
 ######################################################################
-[root root]#
You can proceed to Section�, “Next Steps”.

Installation Option 2: Install from tarball

You should already have downloaded the OpenACS tarball - to the /var/tmp directory. If +[root root]#

You can proceed to the section called “Next Steps”.

Installation Option 2: Install from tarball

You should already have downloaded the OpenACS tarball + to the /var/tmp directory. If not, download the OpenACS tarball and save it in - /var/tmp and proceed:

Unpack the OpenACS tarball and rename it to $OPENACS_SERVICE_NAME. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.

FreeBSD note: Change the period in chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME to a colon: chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME -

[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver
-[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/openacs-5.3.1.tgz
-[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-5.3.1 $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ ls -al
+      /var/tmp and proceed:
Unpack the OpenACS tarball and rename it to $OPENACS_SERVICE_NAME.  Secure the directory so that only the owner can access it.  Check the permissions by listing the directory.
FreeBSD note: Change the period in chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME to a colon: chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME
+        
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver
+[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/openacs-5.3.2.tgz
+[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-5.3.2 $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ ls -al
 total 3
 drwxrwx---    3 root     web          1024 Mar 29 16:41 .
 drwxr-xr-x   25 root     root         1024 Mar 29 16:24 ..
 drwx------    7 $OPENACS_SERVICE_NAME web          1024 Jan  6 14:36 $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ exit
+[$OPENACS_SERVICE_NAME aolserver]$ exit
 logout
 [root root]#
 su - $OPENACS_SERVICE_NAME
 cd /var/lib/aolserver
-tar xzf /var/tmp/openacs-5.3.1.tgz
-mv openacs-5.3.1 $OPENACS_SERVICE_NAME
+tar xzf /var/tmp/openacs-5.3.2.tgz
+mv openacs-5.3.2 $OPENACS_SERVICE_NAME
 chmod -R 755 $OPENACS_SERVICE_NAME
 chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME
 exit
Add the Service to CVS (OPTIONAL)
Prepare the database
Prepare Oracle for OpenACS.�If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service

 	  You should be sure that your user account
-	  (e.g. $OPENACS_SERVICE_NAME) is in the
-	  dba group.
+	  (e.g. $OPENACS_SERVICE_NAME) is in the
+	  dba group.
 	
 
 		  Verify membership by typing
-		  groups when you login:
+		  groups when you login:
 
 		  
[$OPENACS_SERVICE_NAME ~]$ groups
 dba web

 
 		  If you do not see these groups, take the following action: 
 
-		  
[$OPENACS_SERVICE_NAME ~]$ su -
+		  
[$OPENACS_SERVICE_NAME ~]$ su -
 Password: ************
-[root ~]# adduser $OPENACS_SERVICE_NAME dba

+[root ~]# adduser $OPENACS_SERVICE_NAME dba

 
 		  If you get an error about an undefined group, then add that group
 		  manually:
 
-
[root ~]# groupadd dba
-[root ~]# groupadd web

+
[root ~]# groupadd dba
+[root ~]# groupadd web

 
-		  Make sure to logout as root when
+		  Make sure to logout as root when
 		  you are finished with this step and log back in as
 		  your regular user.
 		
 
 		  Connect to Oracle using
-		  svrmgrl and login:
+		  svrmgrl and login:
         
-		  
[$OPENACS_SERVICE_NAME ~]$ svrmgrl
-SVRMGR> connect internal
+		  
[$OPENACS_SERVICE_NAME ~]$ svrmgrl
+SVRMGR> connect internal
 Connected.

 		

 		  Determine where the system tablespaces are stored: 
 
-		  
SVRMGR> select file_name from dba_data_files;

+		  
SVRMGR> select file_name from dba_data_files;

         Example results: 
 		  
/ora8/m01/app/oracle/oradata/ora8/system01.dbf
 /ora8/m01/app/oracle/oradata/ora8/tools01.dbf
@@ -154,108 +153,108 @@
 		  Using the above output, you should determine where
 		  to store your tablespace. As a general rule, you'll want to
 		  store your tablespace on a mount point under the
-		  /ora8 directory that is separate
+		  /ora8 directory that is separate
 		  from the Oracle system data files. By default, the Oracle system
-		  is on m01, so we will use
-		  m02. This enables your Oracle
+		  is on m01, so we will use
+		  m02. This enables your Oracle
 		  system and database files to be on separate disks for optimized
 		  performance. For more information on such a configuration, see
 		  Chapter
 		  12 of Philip's
 		  book.  For this example, we'll use
-		  /ora8/m02/oradata/ora8/.
+		  /ora8/m02/oradata/ora8/.
 		
 
 		  Create the directory for the datafile; to do this,
-		  exit from svrmgrl and login as
-		  root for this step: 
-SVRMGR> exit
-[$OPENACS_SERVICE_NAME ~]$ su -
+		  exit from svrmgrl and login as
+		  root for this step: 
+SVRMGR> exit
+[$OPENACS_SERVICE_NAME ~]$ su -
 Password: ************
-[root ~]# mkdir -p /ora8/m02/oradata/ora8/
-[root ~]# chown $OPENACS_SERVICE_NAME:web /ora8/m02/oradata/ora8
-[root ~]# chmod 775 /ora8/m02/oradata/ora8
-[root ~]# exit
+[root ~]# mkdir -p /ora8/m02/oradata/ora8/
+[root ~]# chown $OPENACS_SERVICE_NAME:web /ora8/m02/oradata/ora8
+[root ~]# chmod 775 /ora8/m02/oradata/ora8
+[root ~]# exit
 [$OPENACS_SERVICE_NAME ~]$
 
 
 		  Create a tablespace for the service. It is important that the
-		  tablespace can autoextend. This
+		  tablespace can autoextend. This
 		  allows the tablespace's storage capacity to grow as the size
 		  of the data grows. We set the pctincrease to be a very low value
 		  so that our extents won't grow geometrically. We do not set
 		  it to 0 at the tablespace level because this would affect
 		  Oracle's ability to automatically coalesce free space in the
 		  tablespace.
 
-		
[$OPENACS_SERVICE_NAME ~]$ svrmgrl
-SVRMGR> connect internal;
-SVRMGR> create tablespace $OPENACS_SERVICE_NAME
+		[$OPENACS_SERVICE_NAME ~]$ svrmgrl
+SVRMGR> connect internal;
+SVRMGR> create tablespace $OPENACS_SERVICE_NAME
       datafile '/ora8/m02/oradata/ora8/$OPENACS_SERVICE_NAME01.dbf' 
       size 50M 
       autoextend on 
       next 10M
       maxsize 300M
       extent management local
-      uniform size 32K;
 
+      uniform size 32K;

Create a database user for this service. Give the user access to the tablespace and rights to connect. We'll use - $OPENACS_SERVICE_NAMEpassword as our password.
+ $OPENACS_SERVICE_NAMEpassword as our password.
Write down what you specify as service_name - (i.e. $OPENACS_SERVICE_NAME) + (i.e. $OPENACS_SERVICE_NAME) and database_password - (i.e. $OPENACS_SERVICE_NAMEpassword). You + (i.e. $OPENACS_SERVICE_NAMEpassword). You will need this information for configuring exports and AOLserver.
```
-SVRMGR> create user $OPENACS_SERVICE_NAME identified by $OPENACS_SERVICE_NAMEpassword default tablespace $OPENACS_SERVICE_NAME
-    temporary tablespace temp quota unlimited on $OPENACS_SERVICE_NAME;
-SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to $OPENACS_SERVICE_NAME;
-SVRMGR> revoke unlimited tablespace from $OPENACS_SERVICE_NAME;
-SVRMGR> alter user $OPENACS_SERVICE_NAME quota unlimited on $OPENACS_SERVICE_NAME;
-SVRMGR> exit;
```
+SVRMGR> create user $OPENACS_SERVICE_NAME identified by $OPENACS_SERVICE_NAMEpassword default tablespace $OPENACS_SERVICE_NAME + temporary tablespace temp quota unlimited on $OPENACS_SERVICE_NAME; +SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to $OPENACS_SERVICE_NAME; +SVRMGR> revoke unlimited tablespace from $OPENACS_SERVICE_NAME; +SVRMGR> alter user $OPENACS_SERVICE_NAME quota unlimited on $OPENACS_SERVICE_NAME; +SVRMGR> exit;
Your table space is now ready. In case you are trying to delete a - previous OpenACS installation, consult these commands in Section�, “Deleting a tablespace” below. + previous OpenACS installation, consult these commands in the section called “Deleting a tablespace” below.

Make sure that you can login to Oracle using your - service_name account:

[$OPENACS_SERVICE_NAME ~]$ sqlplus $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAMEpassword
-SQL> select sysdate from dual;
+        service_name account: 
[$OPENACS_SERVICE_NAME ~]$ sqlplus $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAMEpassword
+SQL> select sysdate from dual;
 SYSDATE
 ----------
 2001-12-20
-SQL> exit;

+SQL> exit;

You should see today's date in a format 'YYYY-MM-DD.' If you can't login, try redoing step 1 again. If the date is in the wrong format, make sure you followed the steps outlined in - Section�, “Troubleshooting Oracle Dates” + the section called “Troubleshooting Oracle Dates”

Prepare PostgreSQL for an OpenACS Service.�

PostgreSQL:

Create a user in the database matching the service - name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.

[root root]# su - postgres -[postgres pgsql]$ createuser -a -d $OPENACS_SERVICE_NAME + name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.

[root root]# su - postgres
+[postgres pgsql]$ createuser -a -d $OPENACS_SERVICE_NAME
 CREATE USER
-[postgres pgsql]$ exit
+[postgres pgsql]$ exit
 logout
-[root root]#

Create a database with the same name as our service name, $OPENACS_SERVICE_NAME. The full pathname for createdb needs to be used, since the pgsql directory has not been added to the $OPENACS_SERVICE_NAME bash profile.
```
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME
+[root root]#
```

Create a database with the same name as our service name, $OPENACS_SERVICE_NAME. The full pathname for createdb needs to be used, since the pgsql directory has not been added to the $OPENACS_SERVICE_NAME bash profile.

[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME
 CREATE DATABASE
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
 su - $OPENACS_SERVICE_NAME
-/usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME

Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day.
```
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ export EDITOR=emacs;crontab -e
```
Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information.
```
0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze $OPENACS_SERVICE_NAME
+/usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME
```
Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day.
```
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ export EDITOR=emacs;crontab -e
```
Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information.
```
0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze $OPENACS_SERVICE_NAME
 0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze $OPENACS_SERVICE_NAME
```
Depending on your distribution, you may receive email when the crontab items are executed. If you don't want to receive email for those crontab items, - you can add > /dev/null - 2>&1 to the end of each crontab + you can add > /dev/null + 2>&1 to the end of each crontab line
Add Full Text Search Support (OPTIONAL)
At this point the database should be ready for installing OpenACS.

Configure an AOLserver Service for OpenACS.�

The AOLserver architecture lets you run an arbitrary number of virtual servers. A virtual server is an HTTP service running on a specific port, e.g. port 80. In order for OpenACS to work, you need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, - /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl. - Open it in an editor to adjust the parameters.

[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
-[$OPENACS_SERVICE_NAME etc]$ emacs config.tcl
+	  /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl.
+	   Open it in an editor to adjust the parameters.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
+[$OPENACS_SERVICE_NAME etc]$ emacs config.tcl
 

-	  You can continue without changing any values in the file.  However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines.
+	  You can continue without changing any values in the file.  However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines.
 	
httpport - If you want your
 		  server on a different port, enter it here.  The Reference Platform port is 8000, which is suitable for development use.  Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test.  So you should use port 80 for your production site.
httpsport - This is the
       port for https requests.  The Reference Platform https port is
@@ -278,50 +277,50 @@
 	
Enable OpenFTS Full Text Search (OPTIONAL)
Install nsopenssl
         for SSL support. (OPTIONAL)

Verify AOLserver startup.�

Kill any current running AOLserver processes and start a new - one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run.

If you want to use port 80, there are complications. AOLserver must be root to use system ports such as + one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run.

If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the $OPENACS_SERVICE_NAME user via - grep $OPENACS_SERVICE_NAME - /etc/passwd and then put those numbers into - the command line via -u + grep $OPENACS_SERVICE_NAME + /etc/passwd and then put those numbers into + the command line via -u 501 -g - 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.

If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep - nsd and selectively kill by job number.

[$OPENACS_SERVICE_NAME etc]$ killall nsd + 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.

If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep + nsd and selectively kill by job number.

[$OPENACS_SERVICE_NAME etc]$ killall nsd
 nsd: no process killed
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file...
 [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.

- Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000
+ Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000
You should see a page that looks like this. If you imported your files into cvs, now that you know it worked you can erase the temp - directory with rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig. + directory with rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig.
If you don't see the login page, view your error log - (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) + (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of a firewall, and aolserver failing to start due to permissions errors or missing files. If you need to make changes, don't forget to kill any running servers with - killall nsd. + killall nsd.
Automate AOLserver keepalive (OPTIONAL)

Configure a Service with the OpenACS Installer.� Now that you've got AOLserver up and running, let's install OpenACS - 5.3.1. + 5.3.2.

You should see a page from the webserver titled - OpenACS Installation: - Welcome. You will be warned if your version of + OpenACS Installation: + Welcome. You will be warned if your version of the database driver is out of date, if AOLserver cannot connect to the database, if any modules are missing or out-of-date, or if there are any problems with filesystem permissions on the server side. But if everything is fine, you can click - Next to proceed to load the + Next to proceed to load the OpenACS Kernel data model.
@@ -334,42 +333,42 @@ Loading package .info files ... this will take a few minutes
This will really take a few minutes. Have faith! Finally, another - Next button will appear at the + Next button will appear at the bottom - click it.
The following page shows the results of loading the core package data models. You should see positive results for each of the previously selected packages, but watch out for any - errors. Eventually, the page will display "Generating secret - tokens" and then "Done"- click - Next. + errors. Eventually, the page will display "Generating secret + tokens" and then "Done"- click + Next.
- You should see a page, "OpenACS Installation: Create - Administrator" with form fields to define the OpenACS site + You should see a page, "OpenACS Installation: Create + Administrator" with form fields to define the OpenACS site administrator. Fill out the fields as appropriate, and click - Create User. + Create User.
- You should see a page, "OpenACS Installation: Set System - Information" allowing you to name your service. Fill out the - fields as appropriate, and click Set System - Information + You should see a page, "OpenACS Installation: Set System + Information" allowing you to name your service. Fill out the + fields as appropriate, and click Set System + Information
- You'll see the final Installer page, "OpenACS - Installation: Complete." It will tell you that the server is + You'll see the final Installer page, "OpenACS + Installation: Complete." It will tell you that the server is being restarted; note that unless you already set up a way for AOLserver to restart itself (ie. inittab or daemontools), you'll need to manually restart your service. -
```
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl
```

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl

Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login near the upper right. Congratulations, OpenACS - 5.3.1 is now up and running! -

Installation Option 3: Install from CVS

If you want to track fresh code developments inbetween releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to Option 2 except that you get the files from CVS instead of the tarball: CVS Checkout Instructions. So, instead of tar xzf /var/tmp/openacs-5.3.1.tgz, cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co acs-core.

Next Steps

Use daemontools supervise and svc, or inittab, to automate server startup and shutdown.
Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled + 5.3.2 is now up and running! +

Installation Option 3: Install from CVS

If you want to track fresh code developments inbetween releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to Option 2 except that you get the files from CVS instead of the tarball: CVS Checkout Instructions. So, instead of tar xzf /var/tmp/openacs-5.3.2.tgz, cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co acs-core.

Next Steps

Use daemontools supervise and svc, or inittab, to automate server startup and shutdown.
Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled OpenFTS, you can now install the OpenFTS Driver package and Full Text Search Engine package in the OpenACS service.
This is a good time to make a backup of your service. If this is a production site, you should set up automatic nightly backups.

If you want traffic reports, set up analog or another log @@ -380,8 +379,8 @@ database while logged in as the service user. They do not directly affect the service's run-time connection with the database, because those environmental variables are set by the - wrapper scripts nsd-postgres and nsd-oracle.

[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc

Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.

PostgreSQL:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
+	wrapper scripts nsd-postgres and nsd-oracle.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc
Put in the appropriate lines for the database you are running.  If you will use both databases, put in both sets of lines.
PostgreSQL:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
 export PATH=$PATH:/usr/local/pgsql/bin
Oracle.  These environment variables are specific for a local Oracle
       installation communicating via IPC. If you are connecting to a remote
       Oracle installation, you'll need to adjust these appropriately. Also,
@@ -393,10 +392,10 @@
 export ORACLE_SID=ora8
 export ORACLE_TERM=vt100
 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data

Test this by logging out and back in as - $OPENACS_SERVICE_NAME and checking the paths.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
+	$OPENACS_SERVICE_NAME and checking the paths.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
 logout
-[root src]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME ~]$ env
+[root src]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME ~]$ env
 
For PostgreSQL, you should see:
 LD_LIBRARY_PATH=:/usr/local/pgsql/lib
 PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:\
@@ -407,4 +406,4 @@
 LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib
 ORACLE_SID=ora8
 ORACLE_TERM=vt100
-ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data

Test your backup and recovery procedure.
Set up Section�, “External uptime validation”.

($Id$)

Prev	Home	Next
Install AOLserver 4	Up	OpenACS Installation Guide for Windows2000

docs@openacs.org

View comments on this page at openacs.org +ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data

Test your backup and recovery procedure.

Set up the section called “External uptime validation”.

($Id$)

Prev	Home	Next
Install AOLserver 4	Up	OpenACS Installation Guide for Windows2000

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/oracle.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v diff -u -r1.42.2.2 -r1.42.2.3 --- openacs-4/packages/acs-core-docs/www/oracle.html 22 Apr 2007 10:21:56 -0000 1.42.2.2 +++ openacs-4/packages/acs-core-docs/www/oracle.html 14 Jul 2007 12:34:47 -0000 1.42.2.3 @@ -1,13 +1,12 @@ - -Install Oracle 8.1.7

Prev	Chapter�3.�Complete Installation	Next

Install Oracle 8.1.7

By Vinod Kurup

+Install Oracle 8.1.7

Prev	Chapter�3.�Complete Installation	Next

Install Oracle 8.1.7

By Vinod Kurup

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

If you are installing PostGreSQL instead of Oracle, skip this section.

- OpenACS 5.3.1 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See Andrew Piskorski's Oracle 9i notes for guidance. + OpenACS 5.3.2 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See Andrew Piskorski's Oracle 9i notes for guidance.

- This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document. T + This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document. T

This document assumes that you'll be installing Oracle on the same @@ -17,7 +16,7 @@

Useful links to find help on how to set up Oracle under Linux are:

Acquire Oracle

+ Roger's company - on Oracle on Linux

Werner Puschitz - Oracle on Red Hat Linux

SuSE/Oracle Support matrix

Acquire Oracle

Production Oracle systems should run on certified platforms. Follow the metalink note 223718.1to find certified platforms. If you don't have @@ -47,7 +46,7 @@ To be able to download a patchset, you need a (to-pay-for) account on Metalink. You may find the appropriate patchset by following Andrew's suggestion. -

Things to Keep in Mind

Oracle is very well-documented software, the online documentation comes with printable PDFs and full-text search. Altogether there is more than 20.000 pages of documentation, so do not expect to understand Oracle @@ -67,7 +66,7 @@ of passwords, we advise you to follow these defaults unless you know what you are doing. Subsequent documents will expect that you used the defaults, so a change made here will necessitate further changes - later. For a guide to the defaults, please see Section�, “Defaults”. + later. For a guide to the defaults, please see the section called “Defaults”.

In order for OpenACS to work properly you need to set the environment @@ -83,25 +82,25 @@ umask 022

 open_cursors = 500

-nls_date_format = "YYYY-MM-DD"

+nls_date_format = "YYYY-MM-DD"

For additional resources/documentation, please see this thread and Andrew Piskorski's mini-guide. -

Pre-Installation Tasks

Though Oracle 8.1.7 has an automated installer, we still need to perform several manual, administrative tasks before we can launch it. You must perform all of these steps as the - root user. We recommend entering the - X window system as a normal user and then doing a su - -. This command gives you full root access. + root user. We recommend entering the + X window system as a normal user and then doing a su + -. This command gives you full root access.

Login as a non-root user and start X by typing - startx + startx
```
 [joeuser ~]$ startx
```
@@ -117,12 +116,12 @@
- Create and setup the oracle - group and oracle account + Create and setup the oracle + group and oracle account
- We need to create a user oracle, + We need to create a user oracle, which is used to install the product, as well as starting and stopping the database. @@ -140,13 +139,13 @@ Setup the installation location for Oracle. While Oracle can reside in a variety of places in the file system, OpenACS has - adopted /ora8 as the base + adopted /ora8 as the base directory.
- Note: the Oracle install needs - about 1 GB free on /ora8 to + Note: the Oracle install needs + about 1 GB free on /ora8 to install successfully.
```
@@ -156,22 +155,22 @@
 root:/ora8# chown -R oracle.dba /ora8
 root:/ora8# exit
```

- Set up the oracle user's + Set up the oracle user's environment

Log in as the user - oracle by typing the + oracle by typing the following:
```
 [joeuser ~]$ su - oracle
 Password: ********
```

Use a text editor to edit the - .bash_profile file in the - oracle account home + .bash_profile file in the + oracle account home directory.

@@ -180,7 +179,7 @@
               You may get this error trying to start emacs: 
 
             
-Xlib: connection to ":0.0" refused by server
+Xlib: connection to ":0.0" refused by server
 Xlib: Client is not authorized to connect to Server
 emacs: Cannot connect to X server :0.
 Check the DISPLAY environment variable or use `-d'.
@@ -205,7 +204,7 @@
 
               Add the following lines (substituting your
               Oracle version number as needed) to
-              .bash_profile:
+              .bash_profile:
 
             
 export ORACLE_BASE=/ora8/m01/app/oracle
@@ -218,14 +217,14 @@
 
 umask 022

 
-              Save the file by typing CTRL-X
-                CTRL-S and then exit by typing
-                CTRL-X
-                CTRL-C. Alternatively, use the menus.
+              Save the file by typing CTRL-X
+                CTRL-S and then exit by typing
+                CTRL-X
+                CTRL-C. Alternatively, use the menus.

- Make sure that you do not add + Make sure that you do not add any lines like the following

@@ -243,11 +242,11 @@
         
 [oracle ~]$ exit

- Log back in as oracle and double + Log back in as oracle and double check that your environment variables are as intended. The - env command lists all of the + env command lists all of the variables that are set in your environment, and - grep shows you just the lines + grep shows you just the lines you want (those with ORA in it).
```
@@ -264,47 +263,47 @@
 ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data
```
If not, try adding the files to - ~/.bashrc instead of - .bash_profile. Then logout and + ~/.bashrc instead of + .bash_profile. Then logout and log back in again. Also, be certain you are doing - su - oracle and not just - su oracle. The - - means that - .bashrc and - .bash_profile will be + su - oracle and not just + su oracle. The + - means that + .bashrc and + .bash_profile will be evaluated.
- Make sure that /bin, - /usr/bin, and - /usr/local/bin are in your path + Make sure that /bin, + /usr/bin, and + /usr/local/bin are in your path by typing:
```
 [oracle ~]$ echo $PATH
 /bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin
```
If they are not, then add them to the - .bash_profile by changing the + .bash_profile by changing the PATH statement above to - PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin + PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin -

Installing Oracle 8.1.7 Server

- Log in as oracle and +

Installing Oracle 8.1.7 Server

+ Log in as oracle and start X if not already running. Start a new terminal:

 [joeuser ~]$ xhost +localhost
 [joeuser ~]$ su - oracle
 Password: **********
 [oracle ~]$ export DISPLAY=localhost:0.0

- Find the runInstaller script + Find the runInstaller script
- If you are installing Oracle from a CD-ROM, it is located in - the install/linux path from + the install/linux path from the cd-rom mount point
```
@@ -314,7 +313,7 @@
 [oracle ~]$ cd /mnt/cdrom
```
- If you are installing from the tarball, the install script is - located in the Oracle8iR2 + located in the Oracle8iR2 directory that was created when you expanded the archive.
```
@@ -327,7 +326,7 @@
 doc  index.htm  install  runInstaller  stage  starterdb
```
  If you don't see - runInstaller, you are in the + runInstaller, you are in the wrong directory.
- @@ -339,72 +338,72 @@ A window will open that welcomes you to the 'Oracle Universal Installer' (OUI). Click on - "Next" + "Next"
  Note
  Some people have had trouble with this step on RedHat 7.3 and 8.0. If so, try the following steps before calling - ./runInstaller: + ./runInstaller:
  Execute the following command: - /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh + /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh
  - Type export LD_ASSUME_KERNEL=2.2.5 + Type export LD_ASSUME_KERNEL=2.2.5
- - The "File Locations" screen in the OUI: + The "File Locations" screen in the OUI:
  - - "Source" path should have been - prefilled with "(wherever you mounted the - CDROM)/stage/products.jar" + "Source" path should have been + prefilled with "(wherever you mounted the + CDROM)/stage/products.jar"
  - - "destination" path says - "/ora8/m01/app/oracle/product/8.1.7" + "destination" path says + "/ora8/m01/app/oracle/product/8.1.7"
    If the destination is not correct it is because your environment variables are not set properly. Make sure you - logged on as oracle using - su - oracle. If so, edit the - ~/.bash_profile as you - did in Section�, “Pre-Installation Tasks” + logged on as oracle using + su - oracle. If so, edit the + ~/.bash_profile as you + did in the section called “Pre-Installation Tasks”
  - - Click "Next" (a pop up window will display Loading + Click "Next" (a pop up window will display Loading Product information).
- - The "Unix Group Name" screen in the OUI: + The "Unix Group Name" screen in the OUI:
  - The Unix Group name needs to be set to - 'oinstall' ( we made + 'oinstall' ( we made this Unix group earlier ).
  - - Click "Next" + Click "Next"
  - A popup window appears instantly, requesting you to run a script as root: -
  - +
    Debian users need to link - /bin/awk to - /usr/bin/awk before + /bin/awk to + /usr/bin/awk before running the script below
    [joueser ~]$ su - @@ -419,119 +418,119 @@ [root ~]# mkdir -p /usr/local/java [root ~]# exit [joeuser ~]$ exit
    - Click "Retry" + Click "Retry"
    - The "Available Products" screen in the OUI: + The "Available Products" screen in the OUI:
    - Select "Oracle 8i Enterprise Edition 8.1.7.1.0" + Select "Oracle 8i Enterprise Edition 8.1.7.1.0"
    - Click "Next" + Click "Next"
    - The "Installation Types" screen + The "Installation Types" screen
    - Select the "Custom" installation type. + Select the "Custom" installation type.
    - Click "Next" + Click "Next"
    - The "Available Product Components" screen + The "Available Product Components" screen
    - In addition to the defaults, make sure that "Oracle SQLJ - 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and - "Linux Documentation 8.1.7.0.0" are also checked. + In addition to the defaults, make sure that "Oracle SQLJ + 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and + "Linux Documentation 8.1.7.0.0" are also checked.
    - Click "Next" + Click "Next"
    A progress bar will appear for about 1 minute.
    - The "Component Locations" screen in the OUI + The "Component Locations" screen in the OUI
    - Click on the "Java Runtime Environment 1.1.8" It + Click on the "Java Runtime Environment 1.1.8" It should have the path - "/ora8/m01/app/oracle/jre/1.1.8" + "/ora8/m01/app/oracle/jre/1.1.8"
    - Click "Next" + Click "Next"
    A progress bar will appear for about 1 minute.
    - The "Privileged Operation System Groups" screen in the + The "Privileged Operation System Groups" screen in the OUI
    - Enter "dba" for "Database Administrator - (OSDBA) Group" + Enter "dba" for "Database Administrator + (OSDBA) Group"
    - Enter "dba" for the "Database Operator - (OSOPER) Group" + Enter "dba" for the "Database Operator + (OSOPER) Group"
    - Click "Next" + Click "Next"
    A progress bar will appear for about 1 minute.
    - The "Authentication Methods" screen + The "Authentication Methods" screen
    - Click "Next" + Click "Next"
    - The next screen is "Choose JDK home directory" + The next screen is "Choose JDK home directory"
    - Keep the default path: /usr/local/java + Keep the default path: /usr/local/java
    - Click "Next" + Click "Next"
    - The "Create a Database" screen in the OUI + The "Create a Database" screen in the OUI
    - Select "No" as we will do this later, after some + Select "No" as we will do this later, after some important configuration changes.
    - Click "Next" + Click "Next"
    - The next screen is "Oracle Product Support" + The next screen is "Oracle Product Support"
    - TCP should be checked with "Status" listed as + TCP should be checked with "Status" listed as Required
    - Click "Next" + Click "Next"
    - The "Summary" screen in the OUI + The "Summary" screen in the OUI
    - Check the "Space Requirements" section to verify + Check the "Space Requirements" section to verify you have enough disk space for the install.
    - Check that "(144 products)" is in the "New - Installations" section title. + Check that "(144 products)" is in the "New + Installations" section title.
    - Click "Install" + Click "Install"
    A progress bar will appear for about 20 - 30 minutes. Now is a good time to take a break.
    - A "Setup Privileges" window will popup towards the + A "Setup Privileges" window will popup towards the end of the installation asking you to run a script as - root + root
    Run the script. Switch to the oracle user first to set the environment appropriately and then do - su to get root privileges, while keeping + su to get root privileges, while keeping the oracle user's enviroment.
    [joeuser ~]$ su - oracle @@ -552,7 +551,7 @@ Enter the full pathname of the local bin directory: [/usr/local/bin]: -Press ENTER here to accept default of /usr/local/bin +Press ENTER here to accept default of /usr/local/bin Creating /etc/oratab file... @@ -570,93 +569,93 @@
    [root ~]# exit [joeuser ~]$ exit
    - Go back to the pop-up window and click "OK" + Go back to the pop-up window and click "OK"
    - The "Configuration Tools" screen in the OUI + The "Configuration Tools" screen in the OUI
    This window displays the config tools that will automatically be launched.
    - The "Welcome" screen in the "net 8 Configuration - Assistant" + The "Welcome" screen in the "net 8 Configuration + Assistant"
    - Make sure the "Perform Typical installation" is - not selected. + Make sure the "Perform Typical installation" is + not selected.
    - Click "Next" + Click "Next"
    - The "Directory Service Access" screen in the - "Net 8 Configuration Assistant" + The "Directory Service Access" screen in the + "Net 8 Configuration Assistant"
    - Select "No" + Select "No"
    - Click "Next" + Click "Next"
    - The "Listener Configuration, Listener Name" screen in - the "Net 8 Configuration Assistant" + The "Listener Configuration, Listener Name" screen in + the "Net 8 Configuration Assistant"
    - Accept the default listener name of "LISTENER" + Accept the default listener name of "LISTENER"
    - Click "Next" + Click "Next"
    - The "Listener Configuration, Select - Protocols" screen in the "Net 8 Configuration - Assistant" + The "Listener Configuration, Select + Protocols" screen in the "Net 8 Configuration + Assistant"
    - The only choice in "Select protocols:" should be - "TCP/IP" + The only choice in "Select protocols:" should be + "TCP/IP"
    - Click "Next" + Click "Next"
    - The "Listener Configuration TCP/IP Protocol" screen in - the "Net 8 Configuration Assistant" + The "Listener Configuration TCP/IP Protocol" screen in + the "Net 8 Configuration Assistant"
    Default Port should be 1521 and selected.
    - Click "Next" + Click "Next"
    - The "Listener Configuration, More Listeners" screen in - the "Net 8 Configuration Assistant" + The "Listener Configuration, More Listeners" screen in + the "Net 8 Configuration Assistant"
    - Select "No" + Select "No"
    - Click "Next" + Click "Next"
    - The "Listener Configuration Done" screen in the - "Net 8 Configuration Assistant" + The "Listener Configuration Done" screen in the + "Net 8 Configuration Assistant"
    - Click "Next" + Click "Next"
    - The "Naming Methods Configuration" screen - in the "Net 8 Configuration Assistant" + The "Naming Methods Configuration" screen + in the "Net 8 Configuration Assistant"
    - Select "No" + Select "No"
    - Click "Next" + Click "Next"
    - The "Done" screen in the "Net 8 Configuration - Assistant" + The "Done" screen in the "Net 8 Configuration + Assistant"
    - Click "Finish" + Click "Finish"
    - The "End of Installation" screen in the OUI + The "End of Installation" screen in the OUI
    - Click "Exit" + Click "Exit"
    - Click "Yes" on the confirmation pop up window. + Click "Yes" on the confirmation pop up window.
    The Oracle Universal Installer window should have disappeared!
    Congratulations, you have just installed Oracle 8.1.7 Server! However, you still need to create a database which can take about an hour of non-interactive time, so don't quit yet. -
  Creating the First Database
  +
  Creating the First Database
  This step will take you through the steps of creating a customized database. Be warned that this process takes about an hour on a Pentium II with 128 MB of RAM. -
  Note
  RedHat 7.3 and 8.0 users: Before running dbassist, do the following.
  +
  Note
  RedHat 7.3 and 8.0 users: Before running dbassist, do the following.
  Download the glibc - patch from Oracle Technet into /var/tmp. + patch from Oracle Technet into /var/tmp.
  cd $ORACLE_HOME
  @@ -665,165 +664,165 @@ ./setup_stubs
  Make sure you are running X. Open up a terminal and - su to oracle and then run the - dbassist program. + su to oracle and then run the + dbassist program.
  [joeuser ~]$ xhost +localhost [joeuser ~]$ su - oracle Password: ********* [oracle ~]$ export DISPLAY=localhost:0.0 [oracle ~]$ dbassist
  - The "Welcome" screen in the Oracle Database + The "Welcome" screen in the Oracle Database Configuration Agent (ODCA)
  - Select "Create a database" + Select "Create a database"
  - Click "Next" + Click "Next"
  - The "Select database type" screen in the ODCA + The "Select database type" screen in the ODCA
  - Select "Custom" + Select "Custom"
  - Click "Next" + Click "Next"
  - The "Primary Database Type" window in ODCA + The "Primary Database Type" window in ODCA
  - Select "Multipurpose" + Select "Multipurpose"
  - Click "Next" + Click "Next"
  - The "concurrent users" screen of the ODCA + The "concurrent users" screen of the ODCA
  - Select "60" concurrent users. + Select "60" concurrent users.
  - Click "Next" + Click "Next"
  - Select "Dedicated Server - Mode", click - "Next" + Select "Dedicated Server + Mode", click + "Next"
  Accept all of the options, and click - Next Oracle Visual + Next Oracle Visual Information Retrieval may be grayed out. If so, you can ignore it; just make sure that everything else is checked.
  - For "Global Database Name", enter - "ora8"; for - "SID", also enter - "ora8" (it should do - this automatically). Click "Change - Character Set and select - UTF8. Click - "Next". + For "Global Database Name", enter + "ora8"; for + "SID", also enter + "ora8" (it should do + this automatically). Click "Change + Character Set and select + UTF8. Click + "Next".
  Accept the defaults for the next screen (control file location). Click - "Next" + "Next"
  - Go to the "temporary" and - "rollback" tabs, and change the Size + Go to the "temporary" and + "rollback" tabs, and change the Size (upper-right text box) to - 150MB. Click - "Next" + 150MB. Click + "Next"
  Increase the redo log sizes to - 10000K each. Click - "Next" + 10000K each. Click + "Next"
  Use the default checkpoint interval & timeout. Click - "Next" + "Next"
  - Increase "Processes" - to 100; - "Block Size" to - 4096 (better for small Linux + Increase "Processes" + to 100; + "Block Size" to + 4096 (better for small Linux boxes; use 8192 for a big Solaris machine).
  Accept the defaults for the Trace File Directory. Click - "Next" + "Next"
  - Finally, select "Save information to a shell - script" and click - "Finish" (We're + Finally, select "Save information to a shell + script" and click + "Finish" (We're going to examine the contents of this file before creating our database.)
  - Click the "Save" + Click the "Save" button. Oracle will automatically save it to the correct directory and with the correct file name. This will likely be - /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh + /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh
  It will alert you that the script has been saved successfully.
  Now we need to customize the database configuration a bit. While - still logged on as oracle, edit + still logged on as oracle, edit the database initialization script (run when the db loads). The scripts are kept in - $ORACLE_HOME/dbs and the name of + $ORACLE_HOME/dbs and the name of the script is usually - initSID.ora + initSID.ora where SID is the SID of your database. Assuming your - $ORACLE_HOME matches our default + $ORACLE_HOME matches our default of - /ora8/m01/app/oracle/product/8.1.7, + /ora8/m01/app/oracle/product/8.1.7, the following will open the file for editing.
  [oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora
  Add the following line to the end:
  -nls_date_format = "YYYY-MM-DD"
  - Now find the open_cursors line +nls_date_format = "YYYY-MM-DD"
  + Now find the open_cursors line in the file. If you're using - emacs scroll up to the top of - the buffer and do CTRL-S and - type open_cursors to find the - line. The default is 100. Change - it to 500. + emacs scroll up to the top of + the buffer and do CTRL-S and + type open_cursors to find the + line. The default is 100. Change + it to 500.
  open_cursors = 500
  - Save the file. In emacs, do CTRL-X - CTRL-S to save followed by - CTRL-X CTRL-C to exit or use + Save the file. In emacs, do CTRL-X + CTRL-S to save followed by + CTRL-X CTRL-C to exit or use the menu.
  At this point, you are ready to initiate database creation. We recommend shutting down X to free up some RAM unless you have 256 MB of RAM or more. You can do this quickly by doing a - CRTL-ALT-BACKSPACE, but make + CRTL-ALT-BACKSPACE, but make sure you have saved any files you were editing. You should now be returned to a text shell prompt. If you get sent to a graphical login screen instead, switch to a virtual console by doing - CRTL-ALT-F1. Then login as - oracle. + CRTL-ALT-F1. Then login as + oracle.
  Change to the directory where the database creation script is and run it:
  [oracle ~]$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh
  In some instances, Oracle will save the file to - /ora8/m01/app/oracle/product/8.1.7/assistants/dbca + /ora8/m01/app/oracle/product/8.1.7/assistants/dbca Try running the script there if your first attempt does not succeed.
  Your database will now be built. It will take > 1 hour - no fooling. You will see lots of errors scroll by (like: - "ORA-01432: public synonym to be dropped does not - exist") Fear not, this is normal. + "ORA-01432: public synonym to be dropped does not + exist") Fear not, this is normal.
  Eventually, you'll be returned to your shell prompt. In the meantime, relax, you've earned it. -
  Acceptance Test
  +

Acceptance Test

For this step, open up a terminal and - su to - oracle as usual. You should be + su to + oracle as usual. You should be running X and Netscape (or other web browser) for this phase.

- You need to download the "Oracle Acceptance Test" file. + You need to download the "Oracle Acceptance Test" file. It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. - Save the file to /var/tmp + Save the file to /var/tmp

In the oracle shell, copy the file.

@@ -832,15 +831,15 @@
           your term and type the following:
         
 [oracle ~]$ sqlplus system/manager

-          SQL*Plus should startup. If you get an ORA-01034:
-            Oracle not Available error, it is because your
+          SQL*Plus should startup. If you get an ORA-01034:
+            Oracle not Available error, it is because your
           Oracle instance is not running.  You can manually start it as
-          the oracle user.
+          the oracle user.
 [oracle ~]$ svrmgrl
 SVRMGR> connect internal
 SVRMGR> startup

Now that you're into SQL*Plus, change the default passwords - for system, sys, and ctxsys to "alexisahunk" (or to + for system, sys, and ctxsys to "alexisahunk" (or to something you'll remember):

 SQL> alter user system identified by alexisahunk;
@@ -850,7 +849,7 @@
         
 SQL> select sysdate from dual;

           If you don't see a date that fits the format
-          YYYY-MM-DD, please read Section�, “Troubleshooting Oracle Dates”.
+          YYYY-MM-DD, please read the section called “Troubleshooting Oracle Dates”.

At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes. @@ -865,76 +864,76 @@ 2000-06-10 SQL>
- Many people encounter an error regarding maximum - key length: + Many people encounter an error regarding maximum + key length:
```
 ERROR at line 1:
 ORA-01450: maximum key length (758) exceeded
```
This error occurs if your database block size is wrong and is usually suffered by people trying to load OpenACS into a pre-existing database. Unfortunately, the only solution is to create a new database with a block size of at least - 4096. For instructions on how to - do this, see Section�, “Creating the First Database” above. You + 4096. For instructions on how to + do this, see the section called “Creating the First Database” above. You can set the parameter using the - dbassist program or by setting - the DB_BLOCK_SIZE parameter in + dbassist program or by setting + the DB_BLOCK_SIZE parameter in your database's creation script.
If there were no errors, then consider yourself fortunate. Your Oracle installation is working. -

Automating Startup & Shutdown

You will want to automate the database startup and shutdown process. It's probably best to have Oracle spring to life when you boot up your machine.

Oracle includes a script called - dbstart that can be used to + dbstart that can be used to automatically start the database. Unfortunately, the script shipped in the Linux distribution does not work out of the box. The fix is simple. Follow these directions to apply it. First, save dbstart to - /var/tmp. Then, as - oracle, do the following: + /var/tmp. Then, as + oracle, do the following:
```
 [oracle ~]$ cp /var/tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart 
 [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart
```
While you're logged in as - oracle, you should configure the - oratab file to load your + oracle, you should configure the + oratab file to load your database at start. Edit the file - /etc/oratab: + /etc/oratab:
- You will see this line.
```
 ora8:/ora8/m01/app/oracle/product/8.1.7:N
```
  By the way, if you changed the service name or have multiple databases, the format of this file is:
  - service_name:$ORACLE_HOME:Y || N - (for autoload) + service_name:$ORACLE_HOME:Y || N + (for autoload)
- - Change the last letter from "N" to - "Y". This tells Oracle that you want the database + Change the last letter from "N" to + "Y". This tells Oracle that you want the database to start when the machine boots. It should look like this.
```
 ora8:/ora8/m01/app/oracle/product/8.1.7:Y
```
- Save the file & quit the terminal.
You need a script to automate startup and shutdown. Save oracle8i.txt in - /var/tmp. Then login as - root and install the + /var/tmp. Then login as + root and install the script. (Debian users: substitute - /etc/init.d for - /etc/rc.d/init.d throughout + /etc/init.d for + /etc/rc.d/init.d throughout this section)
```
 [oracle ~]$ su -
 [root ~]# cp /var/tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i
 [root ~]# chown root.root /etc/rc.d/init.d/oracle8i
 [root ~]# chmod 755 /etc/rc.d/init.d/oracle8i
```

Test the script by typing the following commands and checking the - output. (Debian Users: as root, do mkdir - /var/lock/subsys first) + output. (Debian Users: as root, do mkdir + /var/lock/subsys first)

 [root ~]# /etc/rc.d/init.d/oracle8i stop
 Oracle 8i auto start/stop
@@ -955,7 +954,7 @@
 ORACLE instance shut down.
 SVRMGR>
 Server Manager complete.
-Database "ora8" shut down.
+Database "ora8" shut down.
       
 [root ~]# /etc/rc.d/init.d/oracle8i start
 Oracle 8i auto start/stop
@@ -976,9 +975,9 @@
 Database opened.
 SQL> Disconnected
 
-Database "ora8" warm started.
+Database "ora8" warm started.
 
-Database "ora8" warm started.

+Database "ora8" warm started.

If it worked, then run these commands to make the startup and shutdown automatic.

Red Hat users:

@@ -1043,7 +1042,7 @@
           and full site search.
         

           Download these three scripts into
-          /var/tmp
+          /var/tmp
         

               startlsnr.txt
             

@@ -1052,7 +1051,7 @@
               listener8i.txt
             

           Now issue the following commands (still as
-          root).
+          root).
         
 [root ~]# su - oracle
 [oracle ~]$ cp /var/tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
@@ -1112,8 +1111,8 @@
           normally. Login into the database using the listener naming
           convention.
         

-          sqlplus
-          username/password/@SID
+          sqlplus
+          username/password/@SID
         
 [root ~]# su - oracle
 [oracle ~]$ sqlplus system/alexisahunk@ora8
@@ -1127,15 +1126,15 @@
 SQL> exit
 [oracle ~]$ exit
 [root ~]#
RedHat users:

-              Now run chkconfig on the
-              listener8i script.
+              Now run chkconfig on the
+              listener8i script.
             
 [root ~]# cd /etc/rc.d/init.d/
 root:/etc/rc.d/init.d# chkconfig --add listener8i
 root:/etc/rc.d/init.d# chkconfig --list listener8i
 listener8i      0:off   1:off   2:off   3:on    4:on    5:on    6:off
Debian users:

-              Now run update-rc.d on the 
-              listener8i script.
+              Now run update-rc.d on the 
+              listener8i script.
             
 [root ~]# update-rc.d listener8i defaults 21 19
  Adding system startup for /etc/init.d/listener8i ...
@@ -1160,30 +1159,30 @@
 SQL> exit

       Congratulations, your installation of Oracle 8.1.7 is
       complete.
-

Troubleshooting Oracle Dates

Oracle has an internal representation for storing the data based on the number of seconds elapsed since some date. However, for the purposes of inputing dates into Oracle and getting them back out, Oracle needs to be told to use a specific date format. By default, it uses an Oracle-specific format which isn't copacetic. You want Oracle to use the ANSI-compliant date format which is of form - 'YYYY-MM-DD'. + 'YYYY-MM-DD'.

To fix this, you should include the following line in - $ORACLE_HOME/dbs/initSID.ora + $ORACLE_HOME/dbs/initSID.ora or for the default case, - $ORACLE_HOME/dbs/initora8.ora + $ORACLE_HOME/dbs/initora8.ora

-nls_date_format = "YYYY-MM-DD"

+nls_date_format = "YYYY-MM-DD"

You test whether this solved the problem by firing up - sqlplus and typing: + sqlplus and typing:

 SQL> select sysdate from dual;

You should see back a date like - 2000-06-02. If some of the date is - chopped off, i.e. like 2000-06-0, + 2000-06-02. If some of the date is + chopped off, i.e. like 2000-06-0, everything is still fine. The problem here is that - sqlplus is simply truncating the + sqlplus is simply truncating the output. You can fix this by typing:

 SQL> column sysdate format a15
@@ -1210,13 +1209,13 @@
       Setting this environment variable will override the date
       setting. Either delete this line and login again or add the following
       entry to your login scripts after the
-      nls_lang line:
+      nls_lang line:
     
 export nls_date_format = 'YYYY-MM-DD'

       Log back in again. If adding the
-      nls_date_format line doesn't
+      nls_date_format line doesn't
       help, you can ask for advice in our OpenACS forums.
-

Useful Procedures

Dropping a tablespace

Run sqlplus as the dba: @@ -1233,9 +1232,9 @@

 SQL> drop tablespace table_space_name including contents cascade constraints;

For more information on Oracle, please consult the documentation. -

Oracle Next Steps

Section�, “Creating an appropriate tuning and monitoring environment”

Defaults

We used the following defaults while installing Oracle.

Variable Value Reason

ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.

ORACLE_SERVICE

ora8

The service name is a domain-qualified identifier for +

Oracle Next Steps

the section called “Creating an appropriate tuning and monitoring environment”

Defaults

We used the following defaults while installing Oracle.

Variable	Value	Reason
ORACLE_HOME	/ora8/m01/app/oracle/product/8.1.7	This is the default Oracle installation directory.
ORACLE_SERVICE	ora8	The service name is a domain-qualified identifier for your Oracle server.
ORACLE_SID	ora8	This is an identifier for your Oracle server.
ORACLE_OWNER	oracle	The user who owns all of the oracle files.
ORACLE_GROUP	dba	The special oracle group. Users in the dba group are - authorized to do a `connect - internal` within - `svrmgrl` to gain full system + authorized to do a `connect + internal` within + `svrmgrl` to gain full system access to the Oracle system.

($Id$)

Prev	Home	Next
Install a Unix-like system and supporting software	Up	Install PostgreSQL

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/os-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-install.html,v diff -u -r1.11.2.1 -r1.11.2.2 --- openacs-4/packages/acs-core-docs/www/os-install.html 14 Jan 2007 04:20:10 -0000 1.11.2.1 +++ openacs-4/packages/acs-core-docs/www/os-install.html 14 Jul 2007 12:34:47 -0000 1.11.2.2 @@ -1,5 +1,4 @@ - -Linux Install Guides

Prev	Appendix�C.�Credits	Next

Linux Install Guides

+Linux Install Guides

Prev	Appendix�C.�Credits	Next

Linux Install Guides

Here's a list of some helpful documentation for various OS's

Painless Debian Index: openacs-4/packages/acs-core-docs/www/os-security.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-security.html,v diff -u -r1.11.2.1 -r1.11.2.2 --- openacs-4/packages/acs-core-docs/www/os-security.html 14 Jan 2007 04:20:10 -0000 1.11.2.1 +++ openacs-4/packages/acs-core-docs/www/os-security.html 14 Jul 2007 12:34:47 -0000 1.11.2.2 @@ -1,8 +1,7 @@ - -Security Information

Prev	Appendix�C.�Credits	Next

Security Information

+Security Information

Prev	Appendix�C.�Credits	Next

Security Information

Once you get your OS installed, it's imperative that you secure your - installation. As Jon Griffin repeatedly warns us, "No distribution is - secure out of the box." The Reference Platform implements + installation. As Jon Griffin repeatedly warns us, "No distribution is + secure out of the box." The Reference Platform implements some basic precautions, but security is a process, not a condition. If you are responsible for a computer hooked to the internet, you are responsible for learning some rudiments of Index: openacs-4/packages/acs-core-docs/www/packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v diff -u -r1.44.2.2 -r1.44.2.3 --- openacs-4/packages/acs-core-docs/www/packages.html 22 Apr 2007 10:21:56 -0000 1.44.2.2 +++ openacs-4/packages/acs-core-docs/www/packages.html 14 Jul 2007 12:34:47 -0000 1.44.2.3 @@ -1,19 +1,18 @@ - -OpenACS Packages

Prev	Chapter�11.�Development Reference	Next

OpenACS Packages

By Pete Su and Bryan Quinn

+OpenACS Packages

Prev	Chapter�11.�Development Reference	Next

OpenACS Packages

By Pete Su and Bryan Quinn

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Overview

This document is a guide on how to write a software package for OpenACS. OpenACS packages are installed and maintained with the OpenACS Package Manager (APM) which is part of the acs-admin package. This document presents reasons for packaging software, conventions for the file system and naming that must be followed, and step by step instructions for creating a new - package for the "Notes" example package. -

Server file layout

+ package for the "Notes" example package. +

Server file layout

Here is how an OpenACS 5 server is laid out starting from the Server root (ROOT): -

Figure�11.1.�Server file layout diagram

+    
Figure�11.1.�Server file layout diagram
 ROOT/
     bin/
         Various executables and scripts for server maintanence.
@@ -31,7 +30,7 @@
     tcl/
         bootstrap code
     www/
-        Pages not in packages (static content, customized pages)
What a Package Looks Like

+        Pages not in packages (static content, customized pages)

What a Package Looks Like

Each package encapsulates all of its data model, library code, logic, adminstration pages and user pages in a single part of the file tree. This means developers can track down @@ -50,8 +49,8 @@

To illustrate the general structure of a package, let's see what the - package for the "notes" application should look like. -

Figure�11.2.�Package file layout diagram

+      package for the "notes" application should look like.
+    
Figure�11.2.�Package file layout diagram
 ROOT/
   +-- packages/    APM Root
         |
@@ -108,38 +107,42 @@
         |     |     +-- *.adp                             UI Templates
         |     |     +-- *-oracle.xql                      Oracle-specific Queries
         |     |     +-- *-postgresql.xql                  PostgreSQL-specific Queries
-        +-- Other package directories.

+        +-- Other package directories.

All file locations are relative to the package root, which in this - case is ROOT/packages/notes. The following table + case is ROOT/packages/notes. The following table describes in detail what each of the files up in the diagram contain.

A special note on the - PACKAGE-KEY/www/resources + PACKAGE-KEY/www/resources directory. Files in this directory are available at - http://yourserver/resources/PACKAGE-KEY/... + http://yourserver/resources/PACKAGE-KEY/... and are returned without any permissions checking or even checks that the package is installed or mounted. Files are returned directly, so .tcl or .adp files are not sourced in these directories. This makes it suitable for storing icons, css files, javascript, and other static content which can be treated this way. -

Table�11.1.�Package files

File Type Its Use Naming Convention

Package Specification File

The package specification file is an XML file generated and +

Table�11.1.�Package files

File Type	Its Use	Naming Convention
Package Specification File	The package specification file is an XML file generated and maintained by the OpenACS Package Manager (APM). It specifies information about the package including its parameters and its - files.	`notes.info`
Data Model Creation Script	+ files.	`notes.info`
Data Model Creation Script	Contains the SQL that creates the necessary data model and PL/SQL packages (or PL/pgSQL or whatever) to support the package. The name must match the convention below or the package will not be installed correctly. Notice that the script must be under the appropriate directory for the database you are developing your package for (hopefully all OpenACS-supported databases :-)) -	`sql/<database>/notes-create.sql`
Data Model Drop Script	Contains the SQL that removes the data model and PL/SQL +	+ `sql/<database>/notes-create.sql` +
Data Model Drop Script	Contains the SQL that removes the data model and PL/SQL packages generated by the creation script. The name must match the convention below or the package will not be installed correctly. -	`sql/<database>/notes-drop.sql`
Data Model File	Any .sql file that does not match the naming convention above +	+ `sql/<database>/notes-drop.sql` +
Data Model File	Any .sql file that does not match the naming convention above is recognized as a data model file. It is useful to separate the SQL in the creation and drop scripts into several files and then have the scripts source the other data model @@ -148,68 +151,80 @@ scripts. See the Oracle FAQ for examples. In PostgreSQL the same is acomplished by including \i filename. -	`sql/<database>/*.sql`
Data Model Upgrade Scripts	+	+ `sql/<database>/*.sql` +
Data Model Upgrade Scripts	Contain changes to the data model between versions. The APM can automatically load the appropriate upgrade scripts when upgrading to a new version of a package. -	`sql/<database>/upgrade/upgrade-<old>-<new>.sql`
+	+ `sql/<database>/upgrade/upgrade-<old>-<new>.sql` +
SQL92 Query Files	Files with queries that are supported by all databases. These are usually SQL92 queries. Notice that the .xql filename must match the name of the .tcl file that uses those queries. -	`+`	+ `*.xql -`
+ +
Oracle-specific Query Files	Files with queries that are Oracle-specific. Notice that the .xql filename must match the name of the .tcl file that uses those queries. -	`+`	+ `*-oracle.xql -`
+ +
PostgreSQL-specific Query Files	Files with queries that are PostgreSQL-specific. Notice that the .xql filename must match the name of the .tcl file that uses those queries. -	`+`	+ `*-postgresql.xql -`
Tcl Library Files	+ +
Tcl Library Files	The Tcl library files include a set of procedures that provide an application programming interface (API) for the package to utilize. -	`tcl/notes-procs.tcl`
Tcl Initialization	The initialization files are used to run Tcl procedures that +	`tcl/notes-procs.tcl`
Tcl Initialization	The initialization files are used to run Tcl procedures that should only be sourced once on startup. Examples of statements to put here are registered filters or procedures. Tcl initialization files are sourced once on server startup after all of the Tcl library files are sourced. -	`tcl/notes-init.tcl`
Administration UI	The administration UI is used to administer the instances of +	+ `tcl/notes-init.tcl` +
Administration UI	The administration UI is used to administer the instances of the package. For example, the forums administration UI is used to create new forums, moderate postings, and create new - categories for forums postings.	`www/admin/*`
Administration UI Index Page	Every package administration UI must have an index page. In - most cases, this is `index.tcl` but it can be - any file with the name `index`, such as - index.html or index.adp.	`www/admin/index.tcl`
Regression Tests	Every package should have a set of regression tests that + categories for forums postings.	`www/admin/*`
Administration UI Index Page	Every package administration UI must have an index page. In + most cases, this is `index.tcl` but it can be + any file with the name `index`, such as + index.html or index.adp.	`www/admin/index.tcl`
Regression Tests	Every package should have a set of regression tests that verify that it is in working operation. These tests should be able to be run at any time after the package has been installed and report helpful error messages when there is - a fault in the system.	`www/admin/tests/`
Regression Test Index Page	The regression test directory must have an index page that + a fault in the system.	`www/admin/tests/`
Regression Test Index Page	The regression test directory must have an index page that displays all of the tests available and provides information on how to run them. This file can have any extension, as long - as its name is `index`.	`www/admin/tests/index.html`
Documentation	Every package must include a full set of documentation that + as its name is `index`.	`www/admin/tests/index.html`
Documentation	Every package must include a full set of documentation that includes requirements and design documents, and user-level and - developer-level documentation where appropriate.	`www/doc/`
Documentation Index Page	The documentation directory must include a static HTML file with the name - of `index.html`.	`www/doc/index.html`
UI Logic Scripts	Packages provide a UI for users to access the system. The UI + developer-level documentation where appropriate.	`www/doc/`
Documentation Index Page	The documentation directory must include a static HTML file with the name + of `index.html`.	`www/doc/index.html`
UI Logic Scripts	Packages provide a UI for users to access the system. The UI is split into Logic and Templates. The logic scripts perform database queries and prepare variables for - presentation by the associated templates.	`www/*.tcl`
UI Templates	Templates are used to control the presentation of the UI. + presentation by the associated templates.	`www/*.tcl`
UI Templates	Templates are used to control the presentation of the UI. Templates receive a set of data sources from the logic scripts - and prepare them for display to the browser.	`www/*.adp`
UI Index Page	The UI must have an index page composed of a logic script - called `index.tcl` and a template called - `index.adp`.	`www/index.tcl`

The APM

+ and prepare them for display to the browser.

www/*.adp

UI Index Page The UI must have an index page composed of a logic script + called index.tcl and a template called + index.adp. www/index.tcl

The APM

The APM is used to create, maintain, and install packages. It takes care of copying all of the files and registering the package in the system. The APM is responsible for: @@ -237,7 +252,7 @@

We will also discuss how to organize your files and queries so they work with the OpenACS Query Dispatcher. -

Making a Package

Here is how you make a package.

Login as a site-wide administrator on your web service.
Go to the package manager on your server. The URL is /acs-admin/apm. @@ -252,27 +267,27 @@ distinguish it from all the others. It is used as a database key to keep track of the package and as the name of the directory in the file system where all the files related to your package will live. Example - package keys in the current system include: forums, - acs-kernel and so on. For the example application, we - will use the package key notes. + package keys in the current system include: forums, + acs-kernel and so on. For the example application, we + will use the package key notes.
Package Name
This is a short human readable name for your package. For our example, - we will use the name "Notes". + we will use the name "Notes".
Package Plural
If your package name is a nice singular noun, this should be the plural form of it. I assume the plural form is used when multiple instances of the package are used by a single service. We'll talk more about package instances later. Our example apllication doesn't really - have a good plural name. So just make it also be "Notes". + have a good plural name. So just make it also be "Notes".
Package Type
Generally we think of packages as either being applications, meaning that the package is meant primarily for use by end-users, or services meaning that the package is meant to be a reusable - library of code, to be used by other packages. forums is - a good example of an application, while acs-templating is + library of code, to be used by other packages. forums is + a good example of an application, while acs-templating is a good example of a service. Our example is an application, so pick that.
Package URL @@ -288,48 +303,48 @@
Summary and Description
Enter a short summary and longer description of what the Notes - application will do. That is, something like "this application keeps - short textual notes in the database", and so on. + application will do. That is, something like "this application keeps + short textual notes in the database", and so on.

Click the button "Create Package". +
Click the button "Create Package".
At this point, APM will create a directory called - ROOT/packages/notes. + ROOT/packages/notes.
The directory that APM created will be empty except for the - notes.info file. Create a file + notes.info file. Create a file called - ROOT/packages/notes/sql/oracle/notes-create.sql. We'll + ROOT/packages/notes/sql/oracle/notes-create.sql. We'll fill this file with our data model very soon. Create a file called - ROOT/packages/notes/sql/oracle/notes-drop.sql. This + ROOT/packages/notes/sql/oracle/notes-drop.sql. This will contain the instructions to drop the data model. To be complete, you would also create the PostgreSQL versions of these files as well in - ROOT/packages/notes/sql/postgresql/notes-create.sql + ROOT/packages/notes/sql/postgresql/notes-create.sql and - ROOT/packages/notes/sql/postgresql/notes-drop.sql. + ROOT/packages/notes/sql/postgresql/notes-drop.sql.
After you do this, go back to the main APM page. From there, - click the link called "notes" to go to the management - page for the new package. Now click the link called "Manage - file information", then the "Scan the - packages/notes directory for - additional files in this package" link on that page to scan + click the link called "notes" to go to the management + page for the new package. Now click the link called "Manage + file information", then the "Scan the + packages/notes directory for + additional files in this package" link on that page to scan the file system for new files. This will bring you do a page that lists all the files you just added and lets you add them to - the notes package. + the notes package.
- Note that while the .sql files + Note that while the .sql files have been added to the packge, they have not been loaded into the database. For the purposes of development, you have to load the data model by hand, because while OpenACS has automatic mechanisms for loading and reloading - .tcl files for code, it does not + .tcl files for code, it does not do the same thing for data model files. -
Now go back to the main management page for the notes - If your package has parameters, create them using the "Manage - Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install, - instantiate, mount)" link.
The new package has been created and installed in the server. At +
Now go back to the main management page for the notes + If your package has parameters, create them using the "Manage + Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install, + instantiate, mount)" link.
The new package has been created and installed in the server. At this point, you should add your package files to your CVS repository. I'll assume that you have set up your development repository according to the standards described in @@ -342,18 +357,18 @@ % cd sql % cvs add *.sql % cd ROOT/packages/notes -% cvs commit -m "add new package for notes" +% cvs commit -m "add new package for notes"
Now you can start developing the package. In addition to writing code, you should also consider the tasks outlined in the package development tutorial. -

The Site Map and Package Instances

At this point, you are probably excited to see your new package in action. But, we haven't added any user visible pages yet. By convention, user visible pages go in the - ROOT/packages/notes/www directory. So go there and add a - file called hello.html with some text in it. Now we have + ROOT/packages/notes/www directory. So go there and add a + file called hello.html with some text in it. Now we have to make the user pages visible in the site. Since we didn't put the - pages underneath ROOT/www they will not appear on their + pages underneath ROOT/www they will not appear on their own. What we have to do is mount the application into the site map. That is, we have to define the URL from which the application will serve its pages. @@ -366,8 +381,8 @@ us to easily map package instances to URLs. As we said before, each instance of an application has its own set of parameters and runs from its own URL within the site. What this means is that even - though all the code for the notes application lives in - ROOT/packages/notes, the application itself can run from + though all the code for the notes application lives in + ROOT/packages/notes, the application itself can run from any number of locations in the site. This allows developers and administrators to build sites that look to the user like a collection of many indedendent applications that actually run on a single shared @@ -376,27 +391,27 @@ requested by the user at any given time. The page development tutorial shows you how to use this information in your user interface.

- In order to make the new notes application visible to + In order to make the new notes application visible to users, we have to mount it in the site map. You do this by going to the Site Map page, which is by - default available at /acs-admin/site-map. Use the - interface here to add a new sub-folder called notes to - the root of the site, then click "new application" to mount a new - instance of the notes application to the site. Name the - new instance notes-1. + default available at /acs-admin/site-map. Use the + interface here to add a new sub-folder called notes to + the root of the site, then click "new application" to mount a new + instance of the notes application to the site. Name the + new instance notes-1.

- Then type this URL into your browser: http://yourserver/notes/hello.html + Then type this URL into your browser: http://yourserver/notes/hello.html

Now you should see the contents of the page that you added. What has - happened is that all URLs that start with /notes have + happened is that all URLs that start with /notes have been mapped in such a way as to serve content from the directory - ROOT/packages/notes/www. At this point, you can + ROOT/packages/notes/www. At this point, you can experiment with the site map by mounting multiple instances of the not yet written Notes application at various places in the site. In a later document, we'll see how to write your application so that the code can detect from what URL it was invoked. This is the key to supporting subsites. -

Summary

The APM performs the following tasks in an OpenACS site:

Manages creation, installation, and removal of packages from the @@ -411,4 +426,4 @@
Writes out package distribution files for other people to download and install. We'll cover this later. -

Additional Reading

($Id$)

Prev	Home	Next
Chapter�11.�Development Reference	Up	OpenACS Data Models and the Object System

docs@openacs.org

View comments on this page at openacs.org +

Additional Reading

($Id$)

Prev	Home	Next
Chapter�11.�Development Reference	Up	OpenACS Data Models and the Object System

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v diff -u -r1.44.2.2 -r1.44.2.3 --- openacs-4/packages/acs-core-docs/www/parties.html 22 Apr 2007 10:21:56 -0000 1.44.2.2 +++ openacs-4/packages/acs-core-docs/www/parties.html 14 Jul 2007 12:34:47 -0000 1.44.2.3 @@ -1,8 +1,7 @@ - -Parties in OpenACS

Prev	Chapter�11.�Development Reference	Next

Parties in OpenACS

By Rafael H. Schloming

+Parties in OpenACS

Prev	Chapter�11.�Development Reference	Next

Parties in OpenACS

By Rafael H. Schloming

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Introduction

While many applications must deal with individuals and many applications +

Introduction

While many applications must deal with individuals and many applications must deal with groups, most applications must deal with individuals or groups. It is often the case with such applications that @@ -11,20 +10,20 @@ practical way to manage both. This concept is so mundane that there is no need to invent special terminology. This -supertype is called a "party".

A classic example of the "party" supertype is evident +supertype is called a "party".

A classic example of the "party" supertype is evident in address books. A typical address book might contain the address of a doctor, grocery store, and friend. The first field in an entry in the address book is not labeled a person or -company, but a "party". -

The Data Model

The parties developer guide begins with +company, but a "party". +

The Data Model

The parties developer guide begins with an introduction to the parties data model, since OpenACS -community applications likely require using it in some way.

Parties

The central table in the parties data model is the parties table itself. +community applications likely require using it in some way.

Parties

The central table in the parties data model is the parties table itself. Every party has exactly one row in this table. Every party has an optional unique email address and an optional url. A party is an acs object, so permissions may be granted and revoked on parties and auditing information is stored in the acs objects table.

 
-
+
 create table parties (
     party_id    not null
             constraint parties_party_id_fk references
@@ -34,54 +33,54 @@
             constraint parties_email_un unique,
     url     varchar(200)
 );
-
+
 
-

The persons and -groups tables extend the -parties table. A row in the persons table represents the +

The persons and +groups tables extend the +parties table. A row in the persons table represents the most generic form of individual modeled. An individual need not be known to the system as a user. A user is a further specialized form of an individual (discussed later). A row in the groups table represents the most generic form of group modeled, where a group is an aggregation of zero or more -individuals.

Persons

If a party is an individual then there will be a row in the persons table -containing first_names and -last_name +individuals.

Persons

If a party is an individual then there will be a row in the persons table +containing first_names and +last_name for that individual. The -primary key of the persons table (person_id) references the primary key of -the parties table (party_id), so that there is a corresponding row in the +primary key of the persons table (person_id) references the primary key of +the parties table (party_id), so that there is a corresponding row in the parties table when there is a row in the persons table.

 
-create table persons (
+create table persons (
     person_id   not null
             constraint persons_person_id_fk
             references parties (party_id)
             constraint persons_person_id_pk primary key,
     first_names varchar(100) not null,
     last_name   varchar(100) not null
 );
-
+
 
-

Users

The users table is a more -specialized form of persons table. A row -in users table represents an individual that has login access to the +

Users

The users table is a more +specialized form of persons table. A row +in users table represents an individual that has login access to the system. The primary key of the users table references the primary key of the persons table. This guarantees that if there is a row -in users table then there must be a -corresponding row in persons -and parties tables.

Decomposing all the information +in users table then there must be a +corresponding row in persons +and parties tables.

Decomposing all the information associated with a user into the four tables (acs_objects, parties, persons, users) has some immediate benefits. For instance, it is possible to remove access to a user from a live system by removing his entry from the users table, while leaving the rest of his information present (i.e. turning him from a user into a -person).

Wherever possible the OpenACS data model references the persons or -parties table, not the users table. +person).

Wherever possible the OpenACS data model references the persons or +parties table, not the users table. Developers should be careful to only reference the users table in situations where it is clear that the reference is to a user for all cases and not to any other individual for any case.

 
-create table users (
+create table users (
     user_id         not null
                 constraint users_user_id_fk
                 references persons (person_id)
@@ -106,34 +105,34 @@
     password_question   varchar(1000),
     password_answer     varchar(1000)
 );
-
+
 
-

Groups

The final piece of the parties data model is the groups data model. A +

Groups

The final piece of the parties data model is the groups data model. A group is a specialization of a party that represents an aggregation of zero or more other parties. The only extra information directly associated with a group (beyond that in the parties table) is the name of the group:

 
-create table groups (
+create table groups (
     group_id    not null
             constraint groups_group_id_fk
             references parties (party_id)
             constraint groups_group_id_pk primary key,
     group_name  varchar(100) not null
 );
-
+

There is another piece to the groups data model that records relations between parties and groups. -

Group Relations

Two types of group relations are represented in the data model: +

Group Relations

Two types of group relations are represented in the data model: membership relations and composite relations. The full range of sophisticated group structures that exist in the real world can be modelled in OpenACS by these two relationship types.

Membership relations represent direct membership relation between parties and groups. A party may be -a "member" of a group. Direct membership relations are +a "member" of a group. Direct membership relations are common in administrative practices, and do not follow basic set theory rules. If A is a member of B, and B is a member of C, A is -not a member of C. Membership relations are not transitive. +not a member of C. Membership relations are not transitive.

Composition relation represents composite relation between two groups. Composite relation is transitive. That is, it works like @@ -149,11 +148,11 @@ group that is a member of Greenpeace. Now, consider a multinational corporation (MC) that has a U.S. division and a Eurasian division. A member of either the U.S. or Eurasian division is automatically a member of the MC. In this -situation the U.S. and Eurasian divisions are "components" of +situation the U.S. and Eurasian divisions are "components" of the MC, i.e., membership is transitive with respect to composition. Furthermore, a member of a European (or other) office of the MC is automatically a member of the MC. -

Group Membership

Group memberships can be created and manipulated using the membership_rel +

Group Membership

Group memberships can be created and manipulated using the membership_rel package. Only one membership object can be created for a given group, party pair.

@@ -166,7 +165,7 @@ member of a household (indirect membership) at a video rental store.

 
-
+
 # sql code
 create or replace package membership_rel
 as
@@ -208,17 +207,17 @@
 end membership_rel;
 /
 show errors
-
+
 
-

Group Composition

Composition relations can be created or destroyed using the +

Group Composition

Composition relations can be created or destroyed using the composition_rel package. The only restriction on compositions is that there cannot be a reference loop, i.e., a group cannot be a component of itself either directly or indirectly. This constraint is maintained for you by the API. So users do not see some random PL/SQL error message, do not give them the option to create a composition relation that would result in a circular reference.

 
-
+
 # sql code
 create or replace package composition_rel
 as
@@ -239,88 +238,88 @@
 end composition_rel;
 /
 show errors
-
+
 
-

Views

The parties data model does a reasonable job of representing many +

Views

The parties data model does a reasonable job of representing many of the situations one is likely to encounter when modeling organizational structures. We still need to be able to efficiently answer questions like -"what members are in this group and all of its components?", and -"of what groups is this party a member either directly or -indirectly?". Composition relations allow you to describe an arbitrary +"what members are in this group and all of its components?", and +"of what groups is this party a member either directly or +indirectly?". Composition relations allow you to describe an arbitrary Directed Acyclic Graph (DAG) between a group and its components. For these reasons the party system provides a bunch of views that take advantage of the internal representation of group relations to answer questions like these -very quickly.

The group_component_map +very quickly.

The group_component_map view returns all the subcomponents of a group including components of -sub components and so forth. The container_id column is the group_id of the -group in which component_id is directly contained. This allows you to easily +sub components and so forth. The container_id column is the group_id of the +group in which component_id is directly contained. This allows you to easily distinguish whether a component is a direct component or an indirect -component. If a component is a direct component then group_id will be equal -to container_id. You can think of this view as having a primary key of -group_id, component_id, and container_id. The rel_id column points to the row -in acs_rels table that contains the relation object that relates component_id to -container_id. The rel_id might be useful for retrieving or updating standard +component. If a component is a direct component then group_id will be equal +to container_id. You can think of this view as having a primary key of +group_id, component_id, and container_id. The rel_id column points to the row +in acs_rels table that contains the relation object that relates component_id to +container_id. The rel_id might be useful for retrieving or updating standard auditing info for the relation.

 
-create or replace view group_component_map
+create or replace view group_component_map
 as select group_id, component_id, container_id, rel_id
 ...
-
+
 
-

The group_member_map view is similar to group_component_map except for membership relations. +

The group_member_map view is similar to group_component_map except for membership relations. This view returns all membership relations regardless of membership state.

 
-create or replace view group_member_map
+create or replace view group_member_map
 as select group_id, member_id, container_id, rel_id
 ...
-
+
 
-

The group_approved_member_map -view is the same as group_member_map except +

The group_approved_member_map +view is the same as group_member_map except it only returns entries that relate to approved members.

 
-create or replace view group_approved_member_map
+create or replace view group_approved_member_map
 as select group_id, member_id, container_id, rel_id
 ...
-
+
 
-

The group_distinct_member_map +

The group_distinct_member_map view is a useful view if you do not care about the distinction between direct membership and indirect membership. It returns all members of a group including members of components --the transitive closure.

 
-create or replace view group_distinct_member_map
+create or replace view group_distinct_member_map
 as select group_id, member_id
 ...
-
+
 
-

The party_member_map view is the same as group_distinct_member_map, except it includes the +

The party_member_map view is the same as group_distinct_member_map, except it includes the identity mapping. It maps from a party to the fully expanded list of parties represented by that party including the party itself. So if a party is an individual, this view will have exactly one mapping that is from that party to itself. If a view is a group containing three individuals, this view will have four rows for that party, one for each member, and one from the party to itself.

 
-create or replace view party_member_map
+create or replace view party_member_map
 as select party_id, member_id
 ...
-
+
 
-

The party_approved_member_map view is the same as party_member_map except that when it expands groups, it only +

The party_approved_member_map view is the same as party_member_map except that when it expands groups, it only pays attention to approved members.

 
-create or replace view party_approved_member_map
+create or replace view party_approved_member_map
 as select party_id, member_id
 ...
-
+
 
-

Extending The Parties Data Model

The parties data model can represent some fairly sophisticated real +

Extending The Parties Data Model

The parties data model can represent some fairly sophisticated real world situations. Still, it would be foolish to assume that this data model is sufficiently efficient for every application. This section describes some -of the more common ways to extend the parties data model.

Specializing Users

Some applications will want to collect more +of the more common ways to extend the parties data model.

Specializing Users

Some applications will want to collect more detailed information for people using the system. If there can be only one such piece of information per user, then it might make sense to create another type of individual that is a further specialization @@ -331,12 +330,12 @@ have a primary key that references the users table, thereby guaranteeing that each row in the chess_club_users table has a corresponding row in each of the users, persons, parties, and acs_objects tables. This child table could then -store any extra information relevant to the Chess Club community.

Specializing Groups

If one were to build an intranet application on top of the party +store any extra information relevant to the Chess Club community.

Specializing Groups

If one were to build an intranet application on top of the party system, it is likely that one would want to take advantage of the systems efficient representation of sophisticated organizational structures, but there would be much more specialized information associated with each group. In this case it would make sense to specialize the group party type into a -company party type in the same manner as Specializing Users.

Specializing Membership Relations

The final portion of the parties data model that is designed to be +company party type in the same manner as Specializing Users.

Specializing Membership Relations

The final portion of the parties data model that is designed to be extended is the membership relationship. Consider the intranet example again. It is likely that a membership in a company would have more information associated with it than a membership in an ordinary group. An obvious example Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -r1.27.2.1 -r1.27.2.2 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 14 Jan 2007 04:20:10 -0000 1.27.2.1 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 14 Jul 2007 12:34:47 -0000 1.27.2.2 @@ -1,11 +1,10 @@ - -Permissions Design

Prev	Chapter�15.�Kernel Documentation	Next

Permissions Design

By John Prevost and Rafael H. Schloming

+Permissions Design

Prev	Chapter�15.�Kernel Documentation	Next

Permissions Design

By John Prevost and Rafael H. Schloming

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Essentials

Tcl in packages/acs-kernel
OpenACS 4 Permissions Requirements
+

Essentials

Introduction

The goal of the Permissions system is to provide generic means to both +

Introduction

The goal of the Permissions system is to provide generic means to both programmers and site administrators to designate operations (methods) as requiring permissions, and then to check, grant, or revoke permissions via a consistent interface. For example, we might decide that the transaction that @@ -22,66 +21,66 @@ those package objects on which a user has certain permissions.

For site administrators and other authorized users, the Permissions UI provides a means to aggregate the primitive operations (methods) made available by the programmer into logical privileges (like read, write, and -admin) that can be granted and revoked.

Historical Considerations

In earlier versions of the OpenACS, permissions and access control was handled +admin) that can be granted and revoked.

Historical Considerations

In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages read-only, but only allow members of a certain group to make changes. The way this group was determined also varied greatly between modules. Some modules -used "roles", while others did not. Other modules did all access +used "roles", while others did not. Other modules did all access control based simply on coded rules regarding who can act on a given database row based on the information in that row.

Problems resulting from this piecemeal approach to permissions and access control were many, the two major ones being inconsistency, and repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified, consistent permissions system that both programmers and administrators can -readily use.

Competitive Analysis

None available as of 10/2000.

Design Tradeoffs

The core of the permissions data model is quite simple. Unfortunately, the +readily use.

Competitive Analysis

None available as of 10/2000.

Design Tradeoffs

The core of the permissions data model is quite simple. Unfortunately, the hierarchical nature of default permissions entails quite a number of tree queries which could slow the system down. Since every page will have at least one permissions check, a number of views and auxiliary tables (de-normalizations of the data model) have been created to speed up access queries. As a consequence, speed of updates are decreased and requirements -for additional storage space increase.

Data Model Discussion

As described in section V., the core of the permissions data model is +for additional storage space increase.

Data Model Discussion

As described in section V., the core of the permissions data model is simple, though a number of views and auxiliary tables exist to ensure -adequate performance. The core model consists of five tables:

acs_methods +adequate performance. The core model consists of five tables:
acs_methods -
The set of all defined methods.
acs_privileges +
The set of all defined methods.
acs_privileges -
The set of all defined privileges.
acs_privilege_method_rules +
The set of all defined privileges.
acs_privilege_method_rules -
A relation describing the set of methods directly -associated with each privilege.
acs_privilege_hierarchy +
A relation describing the set of methods directly +associated with each privilege.
acs_privilege_hierarchy -
A relation describing which privileges directly -"contain" other privileges.
acs_permissions +
A relation describing which privileges directly +"contain" other privileges.
acs_permissions
A table with one (party, object, privilege) -row for every privilege directly granted on any object in +row for every privilege directly granted on any object in the system - this is a denormalization of -acs_privilege_method_rules and -acs_privilege_hierarchy
There are also a number of views to make it easier to ask specific +acs_privilege_method_rules and +acs_privilege_hierarchy

There are also a number of views to make it easier to ask specific questions about permissions. For example, a number of the above tables -describe "direct" or explicit permissions. Inheritance and default +describe "direct" or explicit permissions. Inheritance and default values can, however, introduce permissions which are not directly specified. (For example, read access on a forum allows read access on all the messages in the forum.)

The following views provide flattened versions of inherited -information:

acs_privilege_method_map +information: acs_privilege_method_map Map of privileges to the methods they contain either directly or because -of another privilege which is included (at any depth). acs_object_grantee_priv_map +of another privilege which is included (at any depth). acs_object_grantee_priv_map Relation on (object, party, privilege) for -privileges from acs_privileges) granted directly on the object, or -on the context of the object (at any depth). acs_object_party_privilege_map +privileges from acs_privileges) granted directly on the object, or +on the context of the object (at any depth). acs_object_party_privilege_map Relation on (object, party, privilege) for -privileges directly from acs_object_grantee_priv_map or also because -a party is a member of a group (at any depth). acs_object_party_method_map +privileges directly from acs_object_grantee_priv_map or also because +a party is a member of a group (at any depth). acs_object_party_method_map Relation with every (object, party, method) -tuple implied by the above trees. In general, only acs_object_party_method_map +tuple implied by the above trees.

In general, only acs_object_party_method_map should be used for queries from other modules. The other views are intermediate steps in building that query.

The data model also includes two simple PL/SQL procedures -(acs_permission.grant_permission and -acs_permission.revoke_permission) for granting and revoking a +(acs_permission.grant_permission and +acs_permission.revoke_permission) for granting and revoking a specific privilege for a specific user on a specific object.

To sum up, the PL/SQL procedures are meant to be used to grant or revoke permissions. The five base tables represent the basic data model of the system, with a set of views provided to convert them into a format suitable @@ -91,50 +90,50 @@ which:

parties get the privileges of any groups they are directly or indirectly a member of
privileges get associated with the methods of any other privileges they have taken methods from (at any level) (see -acs_privilege_hierarchy)
objects get access control from direct grants, or inherit permissions -from their context (unless the "don't inherit" flag is -set)

Legal Transactions

There are three essential areas in which all transactions in the -permissions system fall:

Modification of methods and privileges
Modification of permissions
Queries on permissions

"Modification of methods and privileges." This +acs_privilege_hierarchy)

objects get access control from direct grants, or inherit permissions +from their context (unless the "don't inherit" flag is +set)

Legal Transactions

There are three essential areas in which all transactions in the +permissions system fall:

Modification of methods and privileges
Modification of permissions
Queries on permissions

"Modification of methods and privileges." This refers to actions that happen mainly at package installation time - a package will create a number of methods for its own use, then associate them with the system's standard privileges, or new privileges which the package has created. The association step might also happen later, if the site-wide -administrator chooses to change permissions policy.

These steps involve directly manipulating the acs_methods, -acs_privileges, and acs_privilege_method_rules tables. A +administrator chooses to change permissions policy.

These steps involve directly manipulating the acs_methods, +acs_privileges, and acs_privilege_method_rules tables. A web page for manipulating these features should be limited to site-wide -administrators.

"Modification of permissions" - involves fairly +administrators.

"Modification of permissions" - involves fairly common operations. Users are typically able to administer permissions for objects they themselves create. The two basic operations here are -"grant" and "revoke". Granting permissions is done via -acs_permissions.grant_permission, and revocation via -acs_permissions.revoke_permission. These directly manipulate the -acs_permissions table.

Web pages for making these changes are available to all users, so they +"grant" and "revoke". Granting permissions is done via +acs_permissions.grant_permission, and revocation via +acs_permissions.revoke_permission. These directly manipulate the +acs_permissions table.

Web pages for making these changes are available to all users, so they should not be in an admin area. In order to grant and revoke permissions on -an object, the user must have the administer_privileges method -permission on that object.

"Queries on permissions" - by far the most +an object, the user must have the administer_privileges method +permission on that object.

"Queries on permissions" - by far the most common operation is querying the permissions database. Several kinds of -questions are commonly asked: First, and most commonly, "Can this party -perform this method on this object?" Two Tcl functions are provided to +questions are commonly asked: First, and most commonly, "Can this party +perform this method on this object?" Two Tcl functions are provided to answer this - one which returns a boolean, the other of which results in an error page. These tcl functions directly access the -acs_object_party_method_map.

The second most commonly asked question occurs when a list of objects is +acs_object_party_method_map.

The second most commonly asked question occurs when a list of objects is being displayed, often in order to provide appropriate UI functionality: -"For this party, what methods are available on these objects?" +"For this party, what methods are available on these objects?" Here, the SQL query needs to filter based on whether the party/user can perform some operation on the object. This is done via a join or sub-select -against acs_object_party_method_map, or by calling the Tcl functions +against acs_object_party_method_map, or by calling the Tcl functions for appropriate methods.

Finally, when administering the permissions for an object, a web page needs to know all permissions directly granted on that object. This is done -by querying against acs_permissions.

API

The API to the permissions system consists of a few well-known tables, -plus a pair of PL/SQL procedures and a pair of Tcl functions.

Tables

acs_methods, acs_privileges, and -acs_privilege_method_rules manage the set of permissions in the +by querying against acs_permissions.

API

The API to the permissions system consists of a few well-known tables, +plus a pair of PL/SQL procedures and a pair of Tcl functions.

Tables

acs_methods, acs_privileges, and +acs_privilege_method_rules manage the set of permissions in the system. At installation time, a package will add to these three tables to -introduce new permissions into the system.

The main table for queries is acs_object_party_method_map, which +introduce new permissions into the system.

The main table for queries is acs_object_party_method_map, which contains (object, party, method) triples for all -allowed operations in the system.

Also of interest for queries is acs_permissions, which lists -directly granted privileges. Neither acs_object_party_method_map -(which is a view) nor acs_permissions should be updated -directly.

PL/SQL Procedures

acs_permissions.grant_permission introduces new permissions for +allowed operations in the system.

Also of interest for queries is acs_permissions, which lists +directly granted privileges. Neither acs_object_party_method_map +(which is a view) nor acs_permissions should be updated +directly.

PL/SQL Procedures

acs_permissions.grant_permission introduces new permissions for an object. It should be given an (object, party, privilege) triple, and will always succeed. If the permission is already in the system, no change occurs. The interface for this procedure @@ -144,7 +143,7 @@ grantee_id acs_permissions.grantee_id%TYPE, privilege acs_permissions.privilege%TYPE ); -

acs_permissions.revoke_permission removes a permission entry +

acs_permissions.revoke_permission removes a permission entry given a triple. It always succeeds--if a permission does not exist, nothing changes. The interface for this procedure is:

 procedure revoke_permission (
@@ -153,34 +152,34 @@
   privilege    acs_permissions.privilege%TYPE
 );

These procedures are defined in -permissions-create.sql

Tcl Procedures

Two tcl procedures provide a simple call for the query, "Can this -user perform this method on this object?" One returns true or false, the +permissions-create.sql

Tcl Procedures

Two tcl procedures provide a simple call for the query, "Can this +user perform this method on this object?" One returns true or false, the other presents an error page.

To receive a true or false value, Tcl code should call:

 ad_permission_p $object_id $object_type $method -user_id $user_id
-

If the user_id argument is left out, then the currently logged in +

If the user_id argument is left out, then the currently logged in user is checked. To create an error page, Tcl code should call:

 ad_require_permission $object_id $object_type $method
-

These procedures are defined in acs-permissions-procs.tcl.

User Interface

All users of the permissions system are the same at the user-interface -level. If you have the administer_privileges method permission on an +

These procedures are defined in acs-permissions-procs.tcl.

User Interface

All users of the permissions system are the same at the user-interface +level. If you have the administer_privileges method permission on an object, then you may edit privileges for that object with the UI.

The UI currently provides a list of all granted permissions on the object. If the user wishes to revoke privileges, she may select a set of grants, choose revoke, confirm their deletion, and be returned to the same page after those privileges have been revoked.

Granting permissions currently (as of 10/2000) works by providing a list of all possible permissions and a list of all parties in the system. (For large sites, some future search mechanism will be necessary.) After choosing -privileges to grant, the user is returned to the "edit privileges for -one object" screen.

If it makes sense, the system will also display a checkbox which the user +privileges to grant, the user is returned to the "edit privileges for +one object" screen.

If it makes sense, the system will also display a checkbox which the user may select to toggle whether permissions are inherited from the object's context.

There are a number of potential future enhancements for the permissions -UI, outlined below.

Configuration/Parameters

There are no configuration options for the permissions system.

Future Improvements/Areas of Likely Change

The most important future changes to the Permissions system are likely to +UI, outlined below.

Configuration/Parameters

There are no configuration options for the permissions system.

Future Improvements/Areas of Likely Change

The most important future changes to the Permissions system are likely to be in the UI:

There should be a page displaying a list of all objects for which the current user is allowed to administer privileges.
Users should be able to view the permissions on any object, or perhaps on -objects which they have the "read_permissions" method. This would +objects which they have the "read_permissions" method. This would allow them to see what grants are affecting their objects through -inheritance.

Authors

System creator +inheritance.

Authors

System creator: Rafael H. Schloming
System owner: Rafael H. Schloming
Documentation author -: John Prevost

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/11/2000	John Prevost
0.2	Edited for ACS 4 Beta release	10/04/2000	Kai Wu

Prev	Home	Next
Permissions Requirements	Up	Groups Requirements

docs@openacs.org

View comments on this page at openacs.org +

John Prevost

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/11/2000	John Prevost
0.2	Edited for ACS 4 Beta release	10/04/2000	Kai Wu

Prev	Home	Next
Permissions Requirements	Up	Groups Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -r1.27.2.1 -r1.27.2.2 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 14 Jan 2007 04:20:10 -0000 1.27.2.1 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 14 Jul 2007 12:34:47 -0000 1.27.2.2 @@ -1,11 +1,10 @@ - -Permissions Requirements

Prev	Chapter�15.�Kernel Documentation	Next

Permissions Requirements

By John McClary Prevost

+Permissions Requirements

Prev	Chapter�15.�Kernel Documentation	Next

Permissions Requirements

By John McClary Prevost

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Introduction

This document records requirements for the OpenACS 4 Permissions system, a +

Introduction

This document records requirements for the OpenACS 4 Permissions system, a component of the OpenACS 4 Kernel. The Permissions system is meant to unify and -centralize the handling of access and control on a given OpenACS 4 system.

Vision Statement

Any multi-user software system must address the general problem of -permissions, or "who can do what, on what." On web services, which +centralize the handling of access and control on a given OpenACS 4 system.

Vision Statement

Any multi-user software system must address the general problem of +permissions, or "who can do what, on what." On web services, which typically involve large numbers of users belonging to different groups, permissions handling is a critical need: access to content, services, and information generally must be controlled. The OpenACS 4 Permissions system is @@ -14,78 +13,78 @@ manner reduces both cost and risk: cost, in that less code has to be written and maintained for dealing with recurring permissions situations; risk, in that we need not rely on any single programmer's diligence to ensure -access control is implemented and enforced correctly.

Historical Motivations

In earlier versions of the OpenACS, permissions and access control was handled +access control is implemented and enforced correctly.

Historical Motivations

System Overview

The OpenACS 4 Permissions system has two main pieces: first, an API for +readily use.

System Overview

The OpenACS 4 Permissions system has two main pieces: first, an API for developers to readily handle access control in their applications. The second piece of the system is a UI meant primarily for (subsite) administrators to grant and revoke permissions to system entities under their control.

Consistency is a key characteristic of the Permissions system - both for a common administrative interface, and easily deployed and maintained access control. The system must be flexible enough to support every access model required in OpenACS applications, but not so flexible that pieces will go unused -or fall outside the common administrative interfaces.

Use Cases and User Scenarios

Terminology

The primary question an access control system must answer is a three-way +or fall outside the common administrative interfaces.

Use Cases and User Scenarios

Terminology

The primary question an access control system must answer is a three-way relation, like that between the parts of most simple sentences. A simple sentence generally has three parts, a subject, an object, and a verb - in the -context of OpenACS Permissions, our simple sentence is, "Can this party -perform this operation on this target?" Definitions:

The subject of the sentence is "party" - a +context of OpenACS Permissions, our simple sentence is, "Can this party +perform this operation on this target?" Definitions:

The subject of the sentence is "party" - a distinguishable actor whose access may be controlled, this special word is used because one person may be represented by several parties, and one party -may represent many users (or no users at all).

The object of the sentence is "target" - this +may represent many users (or no users at all).

The object of the sentence is "target" - this is an entity, or object, that the party wishes to perform some action on. An -entity/object here is anything that can be put under access control.

The verb of the sentence is "operation" - a behavior on the OpenACS +entity/object here is anything that can be put under access control.

The verb of the sentence is "operation" - a behavior on the OpenACS system subject to control, this word is used to represent the fact that a single operation may be part of many larger actions the system wants to -perform. If "foo" is an operation, than we sometimes refer to the -foo "privilege" to mean that a user has the privilege to perform +perform. If "foo" is an operation, than we sometimes refer to the +foo "privilege" to mean that a user has the privilege to perform that operation.

Examples of the essential question addressed by the Permissions system: Can jane@attacker.com delete the web security forum? Can the Boston office (a party) within the VirtuaCorp intranet/website create its own news -instance?

Functional Requirements

10.0 Granularity

The system must support access control down to the level of a single +instance?

Functional Requirements

10.0 Granularity

The system must support access control down to the level of a single entity (this would imply down to the level of a row in the OpenACS Objects data -model).

20.0 Operations

The system itself must be able to answer the essential permissions -question as well as several derived questions.

20.10 Basic Access Check
The system must be able to answer the question, "May party P perform -operation O on target T?"

20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may -perform operation O on target T?"

20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may -party P perform on target T?"

20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets -may party P perform operation O?"

Behavioral Requirements

40.0 Scale of Privileges

Privileges must be designed with appropriate scope for a given OpenACS -package. Some privileges are of general utility (e.g. "read" and -"write"). Others are of more limited use (e.g. "moderate" +model).

20.0 Operations

The system itself must be able to answer the essential permissions +question as well as several derived questions.

20.10 Basic Access Check
The system must be able to answer the question, "May party P perform +operation O on target T?"

20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may +perform operation O on target T?"

20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may +party P perform on target T?"

20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets +may party P perform operation O?"

Behavioral Requirements

40.0 Scale of Privileges

Privileges must be designed with appropriate scope for a given OpenACS +package. Some privileges are of general utility (e.g. "read" and +"write"). Others are of more limited use (e.g. "moderate" - applies mainly to a package like forum, where many users are contributing content simultaneously). A package defining its own privileges should do so with moderation, being careful not to overload a privilege like -"read" to mean too many things.

50.0 Aggregation of Operations (Privileges)

For user interface purposes, it can be appropriate to group certain -privileges under others. For example, anyone with the "admin" -privilege may also automatically receive "read", "write", -"delete", etc. privileges.

60.0 Aggregation of Parties (Groups)

The system must allow aggregation of parties. The exact method used for -aggregation will probably be addressed by the OpenACS 4 "Groups" +"read" to mean too many things.

50.0 Aggregation of Operations (Privileges)

For user interface purposes, it can be appropriate to group certain +privileges under others. For example, anyone with the "admin" +privilege may also automatically receive "read", "write", +"delete", etc. privileges.

60.0 Aggregation of Parties (Groups)

The system must allow aggregation of parties. The exact method used for +aggregation will probably be addressed by the OpenACS 4 "Groups" system. Regardless of the exact behavior of aggregate parties, if an aggregate party exists, then access which is granted to the aggregate party -should be available to all members of that aggregate.

70.0 Scope of Access Control

70.10 Context
There must be a method for objects to receive default access control from +should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
There must be a method for objects to receive default access control from some context. For example, if you do not have read access to a forum, you -should not have read access to a message in that forum.
70.20 Overriding
It must be possible to override defaults provided by the context of an -object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they +should not have read access to a message in that forum.
70.20 Overriding
It must be possible to override defaults provided by the context of an +object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they would get by default. (For example, a user does not have the right to edit any message on a forum. But a user does possibly have the right to edit -their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their +their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their inherited privileges would have allowed. (For example, a subdirectory in the file-storage might normally have its parent directory as context. It should -be possible, however, to make a subdirectory private to some group.)
100.0 Efficiency
At least the basic access check (20.10) and the allowed targets check +be possible, however, to make a subdirectory private to some group.)

100.0 Efficiency

At least the basic access check (20.10) and the allowed targets check (20.40) must be efficient enough for general use, i.e. scalable under fairly heavy website traffic. It can be expected that almost every page will contain at least one basic access check, and most pages will contain an allowed -targets check (20.40).

In particular, constraining a SELECT to return only rows the -current user has access to should not be much slower than the SELECT -on its own.

120.0 Ease of Use

Since most SQL queries will contain an allowed target check in the where +targets check (20.40).

In particular, constraining a SELECT to return only rows the +current user has access to should not be much slower than the SELECT +on its own.

120.0 Ease of Use

Since most SQL queries will contain an allowed target check in the where clause, whatever mechanism is used to make checks in SQL should be fairly -small and simple.

In particular, constraining a SELECT to return only rows the -current user has access to should not add more than one line to a query.

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 8/17/2000 John Prevost

0.2 Revised, updated with new terminology 8/25/2000 John Prevost

0.3

Edited, reformatted to conform to requirements template, pending +small and simple.

In particular, constraining a SELECT to return only rows the +current user has access to should not add more than one line to a query.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	8/17/2000	John Prevost
0.2	Revised, updated with new terminology	8/25/2000	John Prevost
0.3	Edited, reformatted to conform to requirements template, pending freeze.	8/26/2000	Kai Wu
0.4	Edited for ACS 4 Beta release.	10/03/2000	Kai Wu

Prev	Home	Next
Object Model Design	Up	Permissions Design

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v diff -u -r1.40.2.2 -r1.40.2.3 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 22 Apr 2007 10:21:56 -0000 1.40.2.2 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 14 Jul 2007 12:34:47 -0000 1.40.2.3 @@ -1,11 +1,10 @@ - -OpenACS Permissions Tediously Explained

Prev	Chapter�11.�Development Reference	Next

OpenACS Permissions Tediously Explained

+OpenACS Permissions Tediously Explained

Prev	Chapter�11.�Development Reference	Next

OpenACS Permissions Tediously Explained

by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello -

The code has been modified since this document was written so it is now out of date. See this forum thread.

Permissions Overview

Who - (grantee_id) can do what - (privilege) on which object - (object_id). -

The code has been modified since this document was written so it is now out of date. See this forum thread.

Permissions Overview

Who + (grantee_id) can do what + (privilege) on which object + (object_id). +

The general permissions system has a flexible (and relatively complex) data model in OpenACS. Developers who have not had the time to learn the internals of the data model may end up writing seemingly correct code that crashes their system in @@ -19,11 +18,11 @@ system internals.

In OpenACS, most of the interesting tables are expected to extend (subtype) - the acs_objects table, i.e. they are expected to have an integer - primary key column that references the object_id column of - acs_objects. + the acs_objects table, i.e. they are expected to have an integer + primary key column that references the object_id column of + acs_objects.

-create table acs_objects (
+create table acs_objects (
       object_id             integer
           not null
           constraint acs_objects_pk primary key,
@@ -47,23 +46,23 @@
 );

This means that items that want to use the features of the - OpenACS object system needs to have an entry in the acs_objects. This + OpenACS object system needs to have an entry in the acs_objects. This allows developers to define relationships between any two entities A and B by defining a relationship between their corresponding entries - in the acs_objects table. One of the applications of this + in the acs_objects table. One of the applications of this powerful capability is the general permissions system.

- At the heart of the permission system are two tables: acs_privileges - and acs_permissions. + At the heart of the permission system are two tables: acs_privileges + and acs_permissions.

-  create table acs_privileges (
+  create table acs_privileges (
       privilege           varchar2(100) not null
           constraint acs_privileges_pk primary key,
       pretty_name         varchar2(100),
       pretty_plural       varchar2(100)
   );

-  create table acs_permissions (
+  create table acs_permissions (
       object_id
           not null
           constraint acs_permissions_on_what_id_fk references acs_objects (object_id),
@@ -77,14 +76,14 @@
           primary key (object_id, grantee_id, privilege)
   );

- The acs_privileges table stores + The acs_privileges table stores named privileges like read, write, delete, create, and - admin. The acs_permissions + admin. The acs_permissions table stores assertions of the form:

- Who (grantee_id) can do what (privilege) - on which object (object_id). + Who (grantee_id) can do what (privilege) + on which object (object_id).

The micromanaging approach to system security would be to require application developers to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users @@ -102,26 +101,44 @@ necessity to explicitly maintain security information for every single object. There are three kinds of hierarchies involved. These are discussed in the following sections. -

Context Hierarchy

Suppose objects A, B, ..., and F form the following hierarchy. -

Table�11.2.�Context Hierarchy Example

A - `object_id=10` -
B - `object_id=20` -		C - `object_id=30` -
D - `object_id=40` -	E - `object_id=50` -	F - `object_id=60` -

Table�11.2.�Context Hierarchy Example

+ A + + `object_id=10` + +
+ B + + `object_id=20` + +		+ C + + `object_id=30` + +
+ D + + `object_id=40` + +	+ E + + `object_id=50` + +	+ F + + `object_id=60` + +

This can be represented in the acs_objects table by the following entries: -

Table�11.3.�acs_objects example data

object_id	context_id
20	10
30	10
40	20
50	20
60	30

Table�11.3.�acs_objects example data

object_id	context_id
20	10
30	10
40	20
50	20
60	30

The first entry tells us that object 20 is the descendant of object 10, and the third entry shows that object 40 is the descendant of object 20. By running a CONNECT BY query, @@ -147,9 +164,9 @@ Despite its potentially great storage costs, maintaining a flattened representation of the context tree is exactly what OpenACS does. The flattened context tree is stored in the - acs_object_context_index table. + acs_object_context_index table.

-  create table acs_object_context_index (
+  create table acs_object_context_index (
       object_id
           not null
           constraint acs_obj_context_idx_obj_id_fk references acs_objects (object_id),
@@ -167,12 +184,12 @@
       an index-organized
       table, which means it is substantially optimized for access by primary key.
       Number two, as the above computations suggest, the size of the table
-      grows polynomially
+      grows polynomially
       with respect to the average number of descendants that an object
-      has, and exponentially
+      has, and exponentially
       with respect to the depth of the context tree. 
     

-      The acs_object_context_index is kept in sync with the
+      The acs_object_context_index is kept in sync with the
       acs_objects
       table by triggers like this: 
     
@@ -205,34 +222,46 @@
 

       One final note about 
       acs_objects. By setting
-      an object's security_inherit_p column to 'f', you can stop permissions
+      an object's security_inherit_p column to 'f', you can stop permissions
       from cascading down the context tree. In the following example, Joe does not have
       the read permissions on C and F. 
-    


-A

-object_id=10

+    

+	      

+A

+object_id=10

 readable�by�Joe

-	������


-B

-object_id=20

+	������
+	    

+	      

+B

+object_id=20

 readable�by�Joe

-�������������� 

-C

-object_id=30

+��������������
+	    
+	      

+C

+object_id=30

 security_inherit_p�=�'f'

 not�readable�by�Joe

-	������


-D

-object_id=40

-	������ 

-E

-object_id=50

-	������ 

-F

-object_id=60

+	������
+	    

+	      

+D

+object_id=40

+	������
+	    
+	      

+E

+object_id=50

+	������
+	    
+	      

+F

+object_id=60

 security_inherit_p�=�'f'

 not�readable�by�Joe

-	������
Privilege Hierarchy

+	������
+

Privilege Hierarchy

Privileges are also organized hierarchically. In addition to the five main system privileges defined in the ACS Kernel data model, application developers may define their own. Note, @@ -247,14 +276,14 @@ admin privilege to which the first four privileges are tied. Privileges are structured as follows.

admin
create	delete	read	write

- Note that admin privileges are + Note that admin privileges are greater than read, write, create and delete privileges combined. Issuing someone read, write, create and delete privileges will not result in the person getting - admin privileges.

The parent-child relationship between privileges is represented in - the acs_privilege_hierarchy table: + admin privileges.

The parent-child relationship between privileges is represented in + the acs_privilege_hierarchy table:

-  create table acs_privilege_hierarchy (
+  create table acs_privilege_hierarchy (
       privilege
           not null
           constraint acs_priv_hier_priv_fk references acs_privileges (privilege),
@@ -268,7 +297,7 @@
       As in the case of the context hierarchy, it is convenient to have a flattened representation
       of this hierarchal structure.  This is accomplished by defining the following view. 
     
-  create or replace view acs_privilege_descendant_map
+  create or replace view acs_privilege_descendant_map
   as
   select
     p1.privilege,
@@ -293,11 +322,19 @@
       reasonably small, there is no pressing need to cache the flattened ansector-descendant
       view of the privilege hierarchy in a specially maintained table like
       it is done in the case of the context hierarchy.
-

Party Hierarchy

Now for the third hierarchy playing a promiment role in the permission system. The party data model is set up as follows. -

parties
persons	groups
users

-  create table parties (
+    

+	      parties
+	    

+	      persons
+	    
+	      groups
+	    

+              users
+	    
+  create table parties (
       party_id
           not null
           constraint parties_party_id_fk references acs_objects (object_id)
@@ -307,7 +344,7 @@
       url                 varchar2(200)
   );
     
-  create table persons (
+  create table persons (
       person_id
           not null
           constraint persons_person_id_fk references parties (party_id)
@@ -318,7 +355,7 @@
           not null
   );
     
-  create table users (
+  create table users (
       user_id
           not null
           constraint users_user_id_fk references persons (person_id)
@@ -327,17 +364,17 @@
       -- other attributes
   );
     
 
-  create table groups (
+  create table groups (
       group_id
           not null
           constraint groups_group_id_fk references parties (party_id)
           constraint groups_pk primary key,
       group_name           varchar2(100) not null
   );
     

-      Recall that the grantee_id column of the
+      Recall that the grantee_id column of the
       acs_permissions table references 
-      parties.party_id.
+      parties.party_id.
       This means that you can grant a privilege on an object to a party, person, user, or group.
       Groups represent aggregations of parties. The most common scenario that you are likely
       to encounter is a group that is a collection of users, although you could also
@@ -348,9 +385,9 @@
       a group named Pranksters, you can assign membership to Pete,
       Poly, and Penelope. The fact that these users are members of the
       Pranksters group will be recorded in the
-      membership_rels and acs_rels tables: 
+      membership_rels and acs_rels tables: 
     
-  create table acs_rels (
+  create table acs_rels (
       rel_id
           not null
           constraint acs_rels_rel_id_fk references acs_objects (object_id)
@@ -368,7 +405,7 @@
           unique (rel_type, object_id_one, object_id_two)
   );
     
-  create table membership_rels (
+  create table membership_rels (
       rel_id
           constraint membership_rel_rel_id_fk references acs_rels (rel_id)
           constraint membership_rel_rel_id_pk primary key,
@@ -380,7 +417,13 @@
     

       The acs_rels
       table entries would look like so: 
-    
rel_type object_one object_two

+    

+              rel_type
+	    
+              object_one
+	    
+	      object_two
+	    

 	      membership_rel
 	    
 	      Pranksters
@@ -398,28 +441,34 @@
 	      Pranksters
 	    
 	      Penelope
-	    
Read acs_rels: right-side is a
+	    
Read acs_rels: right-side is a
         subset of left-side, ie
-        object2 is a part of
-        object1.
+        object2 is a part of
+        object1.
 

       Another way of building up groups is by adding subgroups.  Suppose
       we define Merry Pranksters and Sad Pranksters as subgroups
       of Pranksters.  We say that the Pranksters group
-      is composed of 
+      is composed of 
       groups Merry Pranksters and Sad Pranksters.  This
       information is stored in the acs_rels
-      and composition_rels tables. 
+      and composition_rels tables. 
     
-create table composition_rels (
+create table composition_rels (
     rel_id
         constraint composition_rels_rel_id_fk references acs_rels (rel_id)
         constraint composition_rels_rel_id_pk primary key
 );
     

       The relevant entries in the 
       acs_rels look like so. 
-    
rel_type object_one object_two

+    

+              rel_type
+	    
+              object_one
+	    
+	      object_two
+	    

 	      composition_rel
 	    
 	      Pranksters
@@ -449,7 +498,7 @@
       reducing the performance hit incurred by hierarchical queries is to cache query results in
       a table maintained by triggers.  The OpenACS data model defines two such tables:
     
- create table group_component_index (
+ create table group_component_index (
           group_id        not null
                           constraint group_comp_index_group_id_fk
                           references groups (group_id),
@@ -468,7 +517,7 @@
           primary key (group_id, component_id, rel_id)
   ) organization index;
     
-  create table group_member_index (
+  create table group_member_index (
       group_id
           not null
           constraint group_member_index_grp_id_fk references groups (group_id),
@@ -485,11 +534,11 @@
           primary key (member_id, group_id, rel_id)
   ) organization index;
     

-      The group_component_index table stores a flattened representation of the
+      The group_component_index table stores a flattened representation of the
       group composition hierarchy that is maintained in sync with the acs_rels
-      and composition_rels tables through triggers. 
-    
additional comments

-      As far as the group_member_index table goes, I am not sure I understand its
+      and composition_rels tables through triggers. 
+    
additional comments

+      As far as the group_member_index table goes, I am not sure I understand its
       purpose.  It maintains group-member relationships that are resolved with respect
       to group composition.  Note that information stored in
       group_member_index can be trivially derived by joining
@@ -520,7 +569,7 @@
   mr.rel_id = r.rel_id
   and r.object_id_one = gci.component_id;
     

-      A heuristic way to verify that group_member_view is essentially identical
+      A heuristic way to verify that group_member_view is essentially identical
       to group_member_index is to compute the
       symmetric difference between the two: 
     
@@ -548,16 +597,16 @@
       membership relationship resolution can be computed trivially with no hierarchical
       queries involved. There is no need to keep the view in a denormalized
       table, unless doing so results in substantial performance gains.
-    
Putting It All Together

-      Security information is queried by calling the acs_permission.permission_p
+    
Putting It All Together

+      Security information is queried by calling the acs_permission.permission_p
       function in OpenACS. This is accessible from Tcl via the
-      permission::permission_p procedure. 
+      permission::permission_p procedure. 
     
  
   create or replace package body acs_permission
   as
     -- some stuff removed for the sake of brevity
   
-    function permission_p (
+    function permission_p (
       object_id	 acs_objects.object_id%TYPE,
       party_id	 parties.party_id%TYPE,
       privilege	 acs_privileges.privilege%TYPE
@@ -575,15 +624,15 @@
     end;
 
   end acs_permission;
-    
problem avoidance

+    
problem avoidance

       The function queries 
       acs_object_party_privilege_map,
       which is a humongous view that joins three flattened hierarchies:
       the context tree, the privilege hierarchy,
       the party composition (and membership) hierarchy. 
       It contains an extremely large number of rows. About
       the only kind of query you can run against it is the one
-      performed by the acs_permission.permission_p
+      performed by the acs_permission.permission_p
       function.  Anything other than that would take forever to
       finish or would ultimately result in a query error.
     

@@ -619,7 +668,7 @@
   end;
   /
     

-      The acs_permission.revoke_permission function merely runs a
+      The acs_permission.revoke_permission function merely runs a
       delete statement like so: 
     
  
   delete from
@@ -629,9 +678,15 @@
      and grantee_id = revoke_permission.grantee_id
      and privilege = revoke_permission.privilege;
     

-      Note that in the above example, acs_permissions had only
+      Note that in the above example, acs_permissions had only
       one entry that needed to be deleted: 
-    
object_id grantee_id privilege

+    

+              object_id
+	    
+	      grantee_id
+	    
+	      privilege
+	    

 	      default_context
 	    
 	      registered_users
@@ -640,9 +695,9 @@
 	    

       The above script would never get around to deleting this entry because it had
       to loop through a gazillion rows in the humongous
-      acs_object_party_privilege_map view. 
-    
Appendix: Various View Definitions
-create or replace view acs_object_party_privilege_map
+      acs_object_party_privilege_map view. 
+    
Appendix: Various View Definitions
+create or replace view acs_object_party_privilege_map
 as
 select
   ogpm.object_id,
@@ -661,7 +716,7 @@
 from
   acs_object_grantee_priv_map;
     
-create or replace view acs_object_grantee_priv_map
+create or replace view acs_object_grantee_priv_map
 as
 select
   a.object_id,
@@ -673,7 +728,7 @@
 where
   a.privilege = m.privilege;
     
 
-create or replace view acs_permissions_all
+create or replace view acs_permissions_all
 as
 select
   op.object_id,
@@ -685,7 +740,7 @@
 where
   op.ancestor_id = p.object_id;
     
-create or replace view acs_object_paths
+create or replace view acs_object_paths
 as
 select
   object_id,
@@ -695,7 +750,7 @@
   acs_object_context_index;
     
 
 
-create or replace view group_member_map
+create or replace view group_member_map
 as
 select
   group_id,
Index: openacs-4/packages/acs-core-docs/www/permissions.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v
diff -u -r1.43.2.2 -r1.43.2.3
--- openacs-4/packages/acs-core-docs/www/permissions.html	22 Apr 2007 10:21:56 -0000	1.43.2.2
+++ openacs-4/packages/acs-core-docs/www/permissions.html	14 Jul 2007 12:34:47 -0000	1.43.2.3
@@ -1,12 +1,11 @@
-
-Groups, Context, PermissionsPrev Chapter�11.�Development Reference  Next
Groups, Context, Permissions
By Pete Su
+Groups, Context, PermissionsPrev Chapter�11.�Development Reference  Next
Groups, Context, Permissions
By Pete Su
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Overview

-The OpenACS 5.3.1 Permissions system allows developers and administrators to
+        
Overview

+The OpenACS 5.3.2 Permissions system allows developers and administrators to
 set access control policies at the object level, that is, any
 application or system object represented by a row in the
-acs_objects table can be access-controlled via a
+acs_objects table can be access-controlled via a
 PL/SQL or Tcl interface. The permissions system manages a data model
 that then allows scripts to check permissions using another API call.
 

@@ -20,10 +19,10 @@
 together into larger security domains.
 
The rest of this document discusses each of these parts, and how they fit together with the
 permissions system.
-
Groups

-OpenACS 5.3.1 has an abstraction called a party. Parties have a recursive
+
Groups

+OpenACS 5.3.2 has an abstraction called a party. Parties have a recursive
 definition. We can illustrate how it works with the following
-simplified data model. First, we define the parties
+simplified data model. First, we define the parties
 table, where each party has an email address and a URL for contact
 information.
 
@@ -51,8 +50,8 @@
 )
 
 

-The users table is also defined in this data model as a
-subtype of person. 
+The users table is also defined in this data model as a
+subtype of person. 
 

 Finally, we define two relations, one for group membership and
 one for group composition.  
@@ -71,7 +70,7 @@
 

 The full details of the groups data model is beyond the scope of this
 tutorial. See Parties in OpenACS or OpenACS 4 Groups Design for more details.
-
Permissions

+
Permissions

   NOTE: Much more detailed information about the permissions system
   and how to use it is available in the
   OpenACS Permissions Tediously Explained document.
@@ -84,14 +83,14 @@
 some object. Privileges are the basic units out of which we build access
 control policies.  For example in the Unix filesystem, access is controlled by granting users some combination of
 read, write, or execute privileges on files and directories. In
-OpenACS 5.3.1,
+OpenACS 5.3.2,
 the table of privileges is organized hierarchically so that developers
 can define privileges that aggregate some set of privileges
 together. For example, if we have read, write, create and delete
 privileges, it might be convenient to combine them into a new privilege
-called "admin". Then, when a user is granted "admin" privilege, she is
+called "admin". Then, when a user is granted "admin" privilege, she is
 automatically granted all the child privileges that the privilege
-contains. The OpenACS 5.3.1 kernel data model defines these
+contains. The OpenACS 5.3.2 kernel data model defines these
 privileges:
 
 # 
@@ -117,7 +116,7 @@
 

 To give a user permission to perform a particular operation on a
 particular object you call
-acs_permission.grant_permission like this:
+acs_permission.grant_permission like this:
 
  
 # sql code
@@ -135,12 +134,12 @@
 would become very tedious.
 OpenACS provides a object contexts as a means for controlling permissions of a large group
 of objects at the same time. 
-
Object Context

-In OpenACS 5.3.1, object context is a scoping
-mechanism.  "Scoping" and "scope" are terms best
+
Object Context

+In OpenACS 5.3.2, object context is a scoping
+mechanism.  "Scoping" and "scope" are terms best
 explained by example: consider some hypothetical rows in the
-address_book table:
-
... scope user_id group_id ...
... user 123 � ...
... group � 456 ...
... public � � ...

+address_book table:
+
... scope user_id group_id ...
... user 123  ...
... group  456 ...
... public   ...

 The first row represents an entry in User 123's personal address book,
 the second row represents an entry in User Group 456's shared address
 book, and the third row represents an entry in the site's public
@@ -153,25 +152,25 @@
 another object that represents the security domain to which the object
 belongs. By convention, if an object A does not have any permissions
 explicitly attached to it, then the system will look at the
-context_id column in acs_objects and check
+context_id column in acs_objects and check
 the context object there for permissions. Two things control the scope
 of this search:
the structure of the context hierarchy
 itself, and 
 

-the value of the security_inherit_p
+the value of the security_inherit_p
 flag in each object.
 
If
-security_inherit_p flag is set to 't', then the automatic search
+security_inherit_p flag is set to 't', then the automatic search
 through the context happens, otherwise it does not. You might set this
-field to 'f' if you want to override the default
+field to 'f' if you want to override the default
 permissions in a subtree of some context.
 
For an example of how to use context hierarchy, consider the forums
 application. With only row-level permissions it is not obvious how to
 reasonably initialize the access control list when creating a
 message. At best, we have to explicitly grant various read and write
 privileges whenever we create a message, which is tedious.  
 A reasonable thing to do is to create an object representing a forum,
-and point the context_id field of a new message at the
+and point the context_id field of a new message at the
 forum. Then, suppose we grant every user in the system read-access to
 this forum. By default, they will automatically have read-access to
 the new message we just inserted, since the system automatically
@@ -185,21 +184,21 @@
 hierarchy for a hypothetical site:
 

 The top two contexts in the diagram
-are called "magic" numbers, because in some sense, they are created by default by OpenACS
-for a specific purpose. The object default_context
+are called "magic" numbers, because in some sense, they are created by default by OpenACS
+for a specific purpose. The object default_context
 represents the root of the context hierarchy for the entire site. All
 permission searches walk up the tree to this point and then stop. If
 you grant permissions on this object, then by default those
 permissions will hold for every object in the system, regardless of
 which subsite they happen to live in. The object
-security_context_root has a slightly different role. If
+security_context_root has a slightly different role. If
 some object has no permissions attached to it, and its value for
-security_inherit_p is 'f', or
-context_id is null, this context is used by default.
+security_inherit_p is 'f', or
+context_id is null, this context is used by default.
 
See the package developer tutorials for examples on how to use
 permissions code.
-
Summary

-OpenACS 5.3.1 defines three separate mechanisms for specifying access control
+
Summary

+OpenACS 5.3.2 defines three separate mechanisms for specifying access control
 in applications. 

 The Groups data model allows you to define 
 hierarchical organizations of users and groups of users. 
Index: openacs-4/packages/acs-core-docs/www/postgres.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v
diff -u -r1.44.2.2 -r1.44.2.3
--- openacs-4/packages/acs-core-docs/www/postgres.html	22 Apr 2007 10:21:56 -0000	1.44.2.2
+++ openacs-4/packages/acs-core-docs/www/postgres.html	14 Jul 2007 12:34:47 -0000	1.44.2.3
@@ -1,8 +1,7 @@
-
-Install PostgreSQL
Prev Chapter�3.�Complete Installation  Next
Install PostgreSQL
by Vinod Kurup
+Install PostgreSQLPrev Chapter�3.�Complete Installation  Next
Install PostgreSQL
by Vinod Kurup
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Skip this section if you will run only Oracle.
OpenACS 5.3.1 will run with PostgreSQL 7.3.2, 7.3.3, and 7.3.4 and 7.4.x.  7.4.7 is the recommended version of PostgreSQL.
Special notes for Mac OS X.�If you are running Mac OS X prior to 10.3, you should be
+        
Skip this section if you will run only Oracle.
OpenACS 5.3.2 will run with PostgreSQL 7.3.2, 7.3.3, and 7.3.4 and 7.4.x.  7.4.7 is the recommended version of PostgreSQL.
Special notes for Mac OS X.�If you are running Mac OS X prior to 10.3, you should be
         able to install and use PostGreSQL 7.3.x.  Mac OS X 10.3
         requires PostGreSQL 7.4. 
Special Notes for Debian.�
Debian stable user should install PostGreSQL from source
       as detailed below, or they should use the www.backports.org
@@ -11,78 +10,78 @@
       (but you should double-check that the version of PostGreSQL is
       7.3 or above):
For Debian stable users, you can use backports, by adding
       this line to the /etc/apt/sources.list
-        deb http://www.backports.org/debian stable bison postgresql openssl openssh tcl8.4 courier debconf spamassassin tla diff patch neon chkrootkit
-        
-      
apt-get install postgresql postgresql-dev postgresql-doc
+        deb http://www.backports.org/debian stable bison postgresql openssl openssh tcl8.4 courier debconf spamassassin tla diff patch neon chkrootkit
+        
+      
apt-get install postgresql postgresql-dev postgresql-doc
 ln -s /usr/include/postgresql/ /usr/include/pgsql
 ln -s /var/lib/postgres /usr/local/pgsql
 ln -s /usr/include/pgsql /usr/local/pgsql/include
-su postgres -c "/usr/lib/postgresql/bin/createlang plpgsql template1"
and proceed to Tune postgres.  (OPTIONAL) or to the
+su postgres -c "/usr/lib/postgresql/bin/createlang plpgsql template1"
and proceed to Tune postgres.  (OPTIONAL) or to the
       next section.
Special Notes for Red Hat.�Red Hat users: If you install PostgreSQL 7.3.2 from the Red Hat 9 RPM, you
   can skip a few steps.  These shell commands add some links for compatibility with the directories from a source-based install; start the service; create a new group for web service
   users, and modify the postgres user's
   environment (more
-  information):
[root root]# ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
-[root root]# ln -s /var/lib/pgsql /usr/local/pgsql
-[root root]# ln -s /etc/init.d/postgresql /etc/init.d/postgres
-[root root]# ln -s /usr/bin /usr/local/pgsql/bin
-[root root]# service postgresql start
+  information):
[root root]# ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
+[root root]# ln -s /var/lib/pgsql /usr/local/pgsql
+[root root]# ln -s /etc/init.d/postgresql /etc/init.d/postgres
+[root root]# ln -s /usr/bin /usr/local/pgsql/bin
+[root root]# service postgresql start
 Initializing database:
                                                            [  OK  ]
 Starting postgresql service:                               [  OK  ]
-[root root]# echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
-[root root]# echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
-[root root]# groupadd web
-[root root]# su - postgres
+[root root]# echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
+[root root]# echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
+[root root]# groupadd web
+[root root]# su - postgres
 -bash-2.05b$
 
 ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
 ln -s /var/lib/pgsql /usr/local/pgsql
 ln -s /usr/bin /usr/local/pgsql/bin
 service postgresql start
-echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
-echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
+echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
+echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
 groupadd web
 su - postgres
... and then skip to 8.  Something similar may work for other binary packages as well.
Safe approach: install from source
Unpack PostgreSQL 7.4.7.�If you have not downloaded the postgresql tarball to
-        /var/tmp/postgresql-7.4.7.tar.gz,
-        get it.
[root root]# cd /usr/local/src
-[root src]# tar xzf /var/tmp/postgresql-7.4.7.tar.gz
+        /var/tmp/postgresql-7.4.7.tar.gz,
+        get it.
[root root]# cd /usr/local/src
+[root src]# tar xzf /var/tmp/postgresql-7.4.7.tar.gz
 [root src]# 
 cd /usr/local/src
 tar xzf /var/tmp/postgresql-7.4.7.tar.gz
ALTERNATIVE: Unpack PostgreSQL 7.4.7.�If you have not downloaded the postgresql tarball to
-        /var/tmp/postgresql-7.4.7.tar.bz2,
-        get it.
[root root]# cd /usr/local/src
-[root src]# tar xfj /var/tmp/postgresql-7.4.7.tar.bz2
+        /var/tmp/postgresql-7.4.7.tar.bz2,
+        get it.
[root root]# cd /usr/local/src
+[root src]# tar xfj /var/tmp/postgresql-7.4.7.tar.bz2
 [root src]# 
 cd /usr/local/src
-tar xfj /var/tmp/postgresql-7.4.7.tar.bz2
Install Bison.�Only do this if bison --version is smaller than 1.875 and you install PostgreSQL 7.4 from cvs instead of tarball.
[root root]# cd /usr/local/src
-[root src]# wget http://ftp.gnu.org/gnu/bison/bison-1.875.tar.gz
-[root src]# tar xfz bison-1.875.tar.gz
-[root src]# cd bison-1.875
-[root src]# ./configure
-[root src]# make install
+tar xfj /var/tmp/postgresql-7.4.7.tar.bz2
Install Bison.�Only do this if bison --version is smaller than 1.875 and you install PostgreSQL 7.4 from cvs instead of tarball.
[root root]# cd /usr/local/src
+[root src]# wget http://ftp.gnu.org/gnu/bison/bison-1.875.tar.gz
+[root src]# tar xfz bison-1.875.tar.gz
+[root src]# cd bison-1.875
+[root src]# ./configure
+[root src]# make install
       
Create the Postgres user.�
 	  Create a user and group (if you haven't done so before) for
 	  PostgreSQL. This is the account that PostgreSQL will run as
 	  since it will not run as root.  Since nobody will log in
 	  directly as that user, we'll leave the password blank.
 	

 	  Debian users should probably use adduser instead of
-	  useradd. Type man adduser
-	
[root src]# groupadd web
-[root src]# useradd -g web -d /usr/local/pgsql postgres
-[root src]# mkdir -p /usr/local/pgsql
-[root src]# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
-[root src]# chmod 750 /usr/local/pgsql
+	  useradd. Type man adduser
+	
[root src]# groupadd web
+[root src]# useradd -g web -d /usr/local/pgsql postgres
+[root src]# mkdir -p /usr/local/pgsql
+[root src]# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
+[root src]# chmod 750 /usr/local/pgsql
 [root src]#
 groupadd web
 useradd -g web -d /usr/local/pgsql postgres
 mkdir -p /usr/local/pgsql
 chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
 chmod 750 /usr/local/pgsql
Mac OS X: Do instead:�First make sure the gids and uids below are available (change them if 
-they  are not).To list taken uids and gids:
nireport / /groups name gid | grep "[0123456789][0123456789]"
-nireport / /users name uid | grep "[0123456789][0123456789]"
-          
Now you can install the users
sudo niutil -create / /groups/web
+they  are not).To list taken uids and gids:
nireport / /groups name gid | grep "[0123456789][0123456789]"
+nireport / /users name uid | grep "[0123456789][0123456789]"
+          
Now you can install the userssudo niutil -create / /groups/web
 sudo niutil -createprop / /groups/web gid 201
 sudo niutil -create / /users/postgres
 sudo niutil -createprop / /users/postgres gid 201
@@ -93,46 +92,46 @@
 sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME uid 201
 mkdir -p /usr/local/pgsql
 chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
-chmod 750 /usr/local/pgsql
FreeBSD users:� need to add more parameters.
-          
[root src]# mkdir -p /usr/local/pgsql
-[root src]# pw groupadd -n web
-[root src]# pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash
-[root src]# chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
-[root src]# chmod -R 750 /usr/local/pgsql
+chmod 750 /usr/local/pgsql
FreeBSD users:� need to add more parameters.
+          
[root src]# mkdir -p /usr/local/pgsql
+[root src]# pw groupadd -n web
+[root src]# pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash
+[root src]# chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
+[root src]# chmod -R 750 /usr/local/pgsql
 [root src]#
 mkdir -p /usr/local/pgsql
 pw groupadd -n web
 pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash
 chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
 chmod -R 750 /usr/local/pgsql
Set up postgres's environment variables.�They are necessary for the executable to find its supporting
-	libraries.  Put the following lines into the postgres user's environment.
[root src]# su - postgres
-[postgres ~] emacs ~postgres/.bashrc
Paste this line into .bash_profile:
source $HOME/.bashrc
Paste these lines into .bashrc:
export PATH=/usr/local/bin/:$PATH:/usr/local/pgsql/bin
+	libraries.  Put the following lines into the postgres user's environment.
[root src]# su - postgres
+[postgres ~] emacs ~postgres/.bashrc
Paste this line into .bash_profile:
source $HOME/.bashrc
Paste these lines into .bashrc:
export PATH=/usr/local/bin/:$PATH:/usr/local/pgsql/bin
 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
Test this by logging in as
-	postgres and checking the
-	paths; you should see /usr/local/pgsql/bin somewhere in the output (the total output is system-dependent so yours may vary)
[root src]# su - postgres
-[postgres pgsql]$ env | grep PATH
+	postgres and checking the
+	paths; you should see /usr/local/pgsql/bin somewhere in the output (the total output is system-dependent so yours may vary)
[root src]# su - postgres
+[postgres pgsql]$ env | grep PATH
 LD_LIBRARY_PATH=:/usr/local/pgsql/lib
 PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin
-[postgres pgsql]$ exit
+[postgres pgsql]$ exit
 
Don't continue unless you see correct output from
-      env | grep PATH
Compile and install PostgreSQL.�
-	  Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can
-	  configure PostgreSQL in various ways. For example, if you are installing on "OS X" add the flags  --with-includes=/sw/include/ --with-libraries=/sw/lib. If you want to see what the other possibilities are, run ./configure --help.
-	
On debian woody (stable, 3.0), do ./configure --without-readline --without-zlib.
[root src]# su - postgres
-[postgres pgsql]$ cd /usr/local/src/postgresql-7.4.7
-[postgres postgresql-7.4.7]$ ./configure
+      env | grep PATH
Compile and install PostgreSQL.�
+	  Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can
+	  configure PostgreSQL in various ways. For example, if you are installing on "OS X" add the flags  --with-includes=/sw/include/ --with-libraries=/sw/lib. If you want to see what the other possibilities are, run ./configure --help.
+	
On debian woody (stable, 3.0), do ./configure --without-readline --without-zlib.
[root src]# su - postgres
+[postgres pgsql]$ cd /usr/local/src/postgresql-7.4.7
+[postgres postgresql-7.4.7]$ ./configure
 creating cache ./config.cache
 checking host system type... i686-pc-linux-gnu
 (many lines omitted>
 linking ./src/makefiles/Makefile.linux to src/Makefile.port
 linking ./src/backend/port/tas/dummy.s to src/backend/port/tas.s
-[postgres postgresql-7.4.7]$ make all
+[postgres postgresql-7.4.7]$ make all
 make -C doc all
 make[1]: Entering directory `/usr/local/src/postgresql-7.4.7/doc'
 (many lines omitted)
 make[1]: Leaving directory `/usr/local/src/postgresql-7.4.7/src'
 All of PostgreSQL successfully made. Ready to install.
-[postgres postgresql-7.4.7]$ make install
+[postgres postgresql-7.4.7]$ make install
 make -C doc install
 make[1]: Entering directory `/usr/local/src/postgresql-7.4.7/doc'
 (many lines omitted)
@@ -143,29 +142,29 @@
 ./configure 
 make all
 make install
Start PostgreSQL.�
-	  The initdb command initializes the
-	  database. pg_ctl is used to start up
+	  The initdb command initializes the
+	  database. pg_ctl is used to start up
 	  PostgreSQL. If PostgreSQL is unable to allocate enough memory, see section 11
           Tuning PostgreSQL (below).
-	
[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
-The files belonging to this database system will be owned by user "postgres".
+	
[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+The files belonging to this database system will be owned by user "postgres".
 This user must also own the server process.
 (17 lines omitted)
 or
     /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
-[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
+[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
 postmaster successfully started
 [postgres postgresql-7.4.7]$
 /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
 /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start

 	  PostgreSQL errors will be logged in
-	  /usr/local/pgsql/data/server.log
+	  /usr/local/pgsql/data/server.log
 	
Install Pl/pgSQL.�Set up plpgsq and allow your user to have
 	  access. Plpgsql is a PL/SQL-like language.  We add it to
 	  template1, which is the template from which all new
 	  databases are created.  We can verify that it was created
-	  with the createlang command in list mode.
[postgres postgresql-7.4.7]$ createlang plpgsql template1
-[postgres pgsql]$ createlang -l template1
+	  with the createlang command in list mode.
[postgres postgresql-7.4.7]$ createlang plpgsql template1
+[postgres pgsql]$ createlang -l template1
 Procedural languages
   Name   | Trusted?
 ---------+----------
@@ -175,9 +174,9 @@
 [postgres pgsql-7.4.7]$
 createlang plpgsql template1
 createlang -l template1
Test PostgreSQL (OPTIONAL).�Create a database and try some simple commands. The output should be as shown.
-	
[postgres pgsql]$ createdb mytestdb
+	
[postgres pgsql]$ createdb mytestdb
 CREATE DATABASE
-[postgres pgsql]$ psql mytestdb
+[postgres pgsql]$ psql mytestdb
 Welcome to psql, the PostgreSQL interactive terminal.
 
 Type:  \copyright for distribution terms
@@ -186,24 +185,24 @@
        \g or terminate with semicolon to execute query
        \q to quit
 
-mytestdb=# select current_timestamp;
+mytestdb=# select current_timestamp;
           timestamptz
 -------------------------------
  2003-03-07 22:18:29.185413-08
 (1 row)
 
-mytestdb=# create function test1() returns integer as 'begin return 1; end;' language 'plpgsql';
+mytestdb=# create function test1() returns integer as 'begin return 1; end;' language 'plpgsql';
 CREATE
-mytestdb=# select test1();
+mytestdb=# select test1();
  test1
 -------
      1
 (1 row)
 
-mytestdb=# \q
-[postgres pgsql]$ dropdb mytestdb
+mytestdb=# \q
+[postgres pgsql]$ dropdb mytestdb
 DROP DATABASE
-[postgres pgsql]$ exit
+[postgres pgsql]$ exit
 logout
 
 [root src]#
Set PostgreSQL to start on boot.  First, we copy the
@@ -214,42 +213,42 @@
         changes runlevels, postgresql goes to the appropriate
         state. Red Hat and Debian and SuSE each work a little
         differently.  If you haven't  untarred the OpenACS tarball, you will need to do so now to access the postgresql.txt file.
-	
Red Hat RPM:
The init script is already installed; just turn it on for the appropriate run levels.
[root root]# chkconfig --level 345 postgresql on
-[root root]# 
Red Hat from source:
[root src]# cp /var/tmp/openacs-5.3.1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
-[root src]# chown root.root /etc/rc.d/init.d/postgresql
-[root src]# chmod 755 /etc/rc.d/init.d/postgresql
+	
Red Hat RPM:
The init script is already installed; just turn it on for the appropriate run levels.
[root root]# chkconfig --level 345 postgresql on
+[root root]# 
Red Hat from source:
[root src]# cp /var/tmp/openacs-5.3.2/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+[root src]# chown root.root /etc/rc.d/init.d/postgresql
+[root src]# chmod 755 /etc/rc.d/init.d/postgresql
 [root src]# 
-cp /var/tmp/openacs-5.3.1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+cp /var/tmp/openacs-5.3.2/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 chown root.root /etc/rc.d/init.d/postgresql
-chmod 755 /etc/rc.d/init.d/postgresql
Test the script.
[root root]# service postgresql stop
+chmod 755 /etc/rc.d/init.d/postgresql
Test the script.
[root root]# service postgresql stop
 Stopping PostgreSQL: ok
 [root root]# 
If PostgreSQL successfully stopped, then use the following
 		  command to make sure that the script is run appropriately at boot
 		  and shutdown.  And turn it back on because we'll use
 		  it later.
 
-		
[root root]# chkconfig --add postgresql
-[root root]# chkconfig --level 345 postgresql on
-[root root]# chkconfig --list postgresql
+		
[root root]# chkconfig --add postgresql
+[root root]# chkconfig --level 345 postgresql on
+[root root]# chkconfig --list postgresql
 postgresql      0:off   1:off   2:on    3:on    4:on    5:on    6:off
-[root root]# service postgresql start
+[root root]# service postgresql start
 Starting PostgreSQL: ok
 [root root]#
 chkconfig --add postgresql
 chkconfig --level 345 postgresql on
 chkconfig --list postgresql
-service postgresql start
Debian:
[root ~]# cp /var/tmp/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
-[root ~]# chown root.root /etc/init.d/postgresql
-[root ~]# chmod 755 /etc/init.d/postgresql
+service postgresql start
Debian:
[root ~]# cp /var/tmp/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+[root ~]# chown root.root /etc/init.d/postgresql
+[root ~]# chmod 755 /etc/init.d/postgresql
 [root ~]# 
-cp /var/tmp/openacs-5.3.1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+cp /var/tmp/openacs-5.3.2/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 chown root.root /etc/init.d/postgresql
-chmod 755 /etc/init.d/postgresql
Test the script
[root ~]# /etc/init.d/postgresql stop
+chmod 755 /etc/init.d/postgresql
Test the script
[root ~]# /etc/init.d/postgresql stop
 Stopping PostgreSQL: ok
 [root ~]# 
If PostgreSQL successfully stopped, then use the following
 		  command to make sure that the script is run
 		  appropriately at boot and shutdown.
-[root ~]# update-rc.d postgresql defaults
+[root ~]# update-rc.d postgresql defaults
  Adding system startup for /etc/init.d/postgresql ...
    /etc/rc0.d/K20postgresql -> ../init.d/postgresql
    /etc/rc1.d/K20postgresql -> ../init.d/postgresql
@@ -258,73 +257,73 @@
    /etc/rc3.d/S20postgresql -> ../init.d/postgresql
    /etc/rc4.d/S20postgresql -> ../init.d/postgresql
    /etc/rc5.d/S20postgresql -> ../init.d/postgresql
-[root ~]# /etc/init.d/postgresql start
+[root ~]# /etc/init.d/postgresql start
 Starting PostgreSQL: ok
-[root ~]#
FreeBSD:
[root ~]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
-[root ~]# chown root:wheel /usr/local/etc/rc.d/postgresql.sh
-[root ~]# chmod 755 /usr/local/etc/rc.d/postgresql.sh
+[root ~]#
FreeBSD:
[root ~]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
+[root ~]# chown root:wheel /usr/local/etc/rc.d/postgresql.sh
+[root ~]# chmod 755 /usr/local/etc/rc.d/postgresql.sh
 [root ~]# 
-cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
+cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
 chown root:wheel /usr/local/etc/rc.d/postgresql.sh
-chmod 755 /usr/local/etc/rc.d/postgresql.sh
Test the script
[root ~]# /usr/local/etc/rc.d/postgresql.sh stop
+chmod 755 /usr/local/etc/rc.d/postgresql.sh
Test the script
[root ~]# /usr/local/etc/rc.d/postgresql.sh stop
 Stopping PostgreSQL: ok
 [root ~]# 
If PostgreSQL successfully stopped, then turn it back on because we'll use
-		  it later.
[root root]# /usr/local/etc/rc.d/postgresql.sh start
+		  it later.
[root root]# /usr/local/etc/rc.d/postgresql.sh start
 Starting PostgreSQL: ok
 [root root]#
 /usr/local/etc/rc.d/postgresql.sh start
SuSE:
Note

 
 			I have received reports that SuSE 8.0 is different from
             previous versions. Instead of installing the boot scripts in
-            /etc/rc.d/init.d/, they should
-            be placed in /etc/init.d/. If
+            /etc/rc.d/init.d/, they should
+            be placed in /etc/init.d/. If
             you're using SuSE 8.0, delete the
-            rc.d/ part in each of the
+            rc.d/ part in each of the
             following commands.
 
-          
[root ~]# cp /var/tmp/openacs-5.3.1/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql
-[root ~]# chown root.root /etc/rc.d/init.d/postgresql
-[root ~]# chmod 755 /etc/rc.d/init.d/postgresql

+          
[root ~]# cp /var/tmp/openacs-5.3.2/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql
+[root ~]# chown root.root /etc/rc.d/init.d/postgresql
+[root ~]# chmod 755 /etc/rc.d/init.d/postgresql

 
           Test the script.
 
-        
[root ~]# /etc/rc.d/init.d/postgresql stop
+        
[root ~]# /etc/rc.d/init.d/postgresql stop
 Stopping PostgreSQL: ok

 
           If PostgreSQL successfully stopped, then use the following
           command to make sure that the script is run appropriately at boot
           and shutdown.
 
-        
[root ~]# cd /etc/rc.d/init.d
-root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql K20postgresql
-root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql S20postgresql  
-root:/etc/rc.d/init.d# cp K20postgresql rc2.d
-root:/etc/rc.d/init.d# cp S20postgresql rc2.d
-root:/etc/rc.d/init.d# cp K20postgresql rc3.d
-root:/etc/rc.d/init.d# cp S20postgresql rc3.d
-root:/etc/rc.d/init.d# cp K20postgresql rc4.d
-root:/etc/rc.d/init.d# cp S20postgresql rc4.d 
-root:/etc/rc.d/init.d# cp K20postgresql rc5.d
-root:/etc/rc.d/init.d# cp S20postgresql rc5.d
-root:/etc/rc.d/init.d# rm K20postgresql
-root:/etc/rc.d/init.d# rm S20postgresql
+        
[root ~]# cd /etc/rc.d/init.d
+root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql K20postgresql
+root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql S20postgresql  
+root:/etc/rc.d/init.d# cp K20postgresql rc2.d
+root:/etc/rc.d/init.d# cp S20postgresql rc2.d
+root:/etc/rc.d/init.d# cp K20postgresql rc3.d
+root:/etc/rc.d/init.d# cp S20postgresql rc3.d
+root:/etc/rc.d/init.d# cp K20postgresql rc4.d
+root:/etc/rc.d/init.d# cp S20postgresql rc4.d 
+root:/etc/rc.d/init.d# cp K20postgresql rc5.d
+root:/etc/rc.d/init.d# cp S20postgresql rc5.d
+root:/etc/rc.d/init.d# rm K20postgresql
+root:/etc/rc.d/init.d# rm S20postgresql
 root:/etc/rc.d/init.d# 

 
           Test configuration.
 
-        
root:/etc/rc.d/init.d # cd
-root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start
+        
root:/etc/rc.d/init.d # cd
+root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start
 Starting PostgreSQL: ok
-root:~ # 
Mac OS X 10.3:
Install the startup script:
cd /System/Library/StartupItems/
-tar xfz /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz
-
Mac OS X 10.4 can use Launchd:
Install the startup script:
cd /Library/LaunchDaemons
-cp
+root:~ # 
Mac OS X 10.3:
Install the startup script:
cd /System/Library/StartupItems/
+tar xfz /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz
+
Mac OS X 10.4 can use Launchd:
Install the startup script:
cd /Library/LaunchDaemons
+cp
 /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-launchd-item.txt
-org.postgresql.PostgreSQL.plist
+org.postgresql.PostgreSQL.plist
 
If postgres does not start automatically on reboot, see what
     error you get when manually starting it with:
-$ sudo launchctl load /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist
-$ sudo launchctl start org.postgresql.PostgreSQL

+$ sudo launchctl load /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist
+$ sudo launchctl start org.postgresql.PostgreSQL

 
       From now on, PostgreSQL should start automatically each time you boot
       up and it should shutdown gracefully each time you shut down. (Note:
@@ -334,11 +333,11 @@
       little. This usually isn't a problem as Red Hat defaults to runlevel 3)
 
     
Tune postgres.  (OPTIONAL).�The default values for PostgreSQL are very conservative; we can safely change some of them and improve performance.
Change the kernel parameter for maximum shared memory
-          segment size to 128Mb:
[root root]# echo 134217728 >/proc/sys/kernel/shmmax
+          segment size to 128Mb:
[root root]# echo 134217728 >/proc/sys/kernel/shmmax
 [root root]#
Make that change permanent by editing
-          /etc/sysctl.conf to
+          /etc/sysctl.conf to
           add these lines at the end:
# increase shared memory limit for postgres
-kernel.shmmax = 134217728
Edit the PostgreSQL config file, /usr/local/pgsql/data/postgresql.conf, to use more memory.  These values should improve performance in most cases.  (more information)
#       Shared Memory Size
+kernel.shmmax = 134217728
Edit the PostgreSQL config file, /usr/local/pgsql/data/postgresql.conf, to use more memory.  These values should improve performance in most cases.  (more information)
#       Shared Memory Size
 #
 shared_buffers = 15200      # 2*max_connections, min 16
 
@@ -350,18 +349,18 @@
 #       Write-ahead log (WAL)
 #
 checkpoint_segments = 3     # in logfile segments (16MB each), min 1
-
Restart postgres (service postgresql
-          restart) or
-          (/etc/init.d/postgres
-          restart) so that the changes take effect.
FreeBSD users: See man syctl, man 5 sysctl
-      and man 5 loader.conf.
Performance tuning resources:

+
Restart postgres (service postgresql
+          restart) or
+          (/etc/init.d/postgres
+          restart) so that the changes take effect.
FreeBSD users: See man syctl, man 5 sysctl
+      and man 5 loader.conf.
Performance tuning resources:

         Managing Kernel Resources
         about PostgreSQL shared memory and semaphores with specific operating system notes.
         

         Managing Kernel Resources (development version)
           This information may be experimental.
         

-        Tuning PostgreSQL for performance
more information about PostgreSQL

+        Tuning PostgreSQL for performance
more information about PostgreSQL

 
           Official PostgreSQL
           Docs
Index: openacs-4/packages/acs-core-docs/www/profile-code.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/profile-code.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/profile-code.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/profile-code.html	14 Jul 2007 12:34:47 -0000	1.8.2.2
@@ -1,5 +1,4 @@
-
-Profile your code
Prev Chapter�10.�Advanced Topics  Next
Profile your code
by Jade Rubick
+Profile your codePrev Chapter�10.�Advanced Topics  Next
Profile your code
by Jade Rubick
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
There are several facilities for profiling your code in
Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html	22 Apr 2007 10:21:56 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html	14 Jul 2007 12:34:47 -0000	1.42.2.3
@@ -1,66 +1,65 @@
-
-Programming with AOLserver
Prev Chapter�11.�Development Reference  Next
Programming with AOLserver
By Michael Yoon, Jon Salz and Lars Pind.
+Programming with AOLserverPrev Chapter�11.�Development Reference  Next
Programming with AOLserver
By Michael Yoon, Jon Salz and Lars Pind.
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
The global command

+        
The global command

 When using AOLserver, remember that there are effectively two types
 of global namespace, not one: 
 
Server-global: As you'd expect, there is
 only one server-global namespace per server, and variables set within it can
 be accessed by any Tcl code running subsequently, in any of the server's
-threads. To set/get server-global variables, use AOLserver 3's nsv API
-(which supersedes ns_share from the pre-3.0 API). 
+threads. To set/get server-global variables, use AOLserver 3's nsv API
+(which supersedes ns_share from the pre-3.0 API). 
 
Script-global: Each Tcl script (ADP, Tcl page,
 registered proc, filter, etc.) executing within an AOLserver thread has its
 own global namespace. Any variable set in the top level of a script is, by
 definition, script-global, meaning that it is accessible only by subsequent
 code in the same script and only for the duration of the current script
 execution.

-The Tcl built-in command global
+The Tcl built-in command global
 accesses script-global, not server-global, variables from within a
 procedure. This distinction is important to understand in order to use
-global correctly when programming AOLserver. 
+global correctly when programming AOLserver. 
 
Also, AOLserver purges all script-global variables in a thread (i.e., Tcl
 interpreter) between HTTP requests. If it didn't, that would affect (and
 complicate) our use of script-global variables dramatically, which would then
 be better described as thread-global variables. Given
-AOLserver's behaviour, however, "script-global" is a more
-appropriate term.
Threads and Scheduled Procedures

-ns_schedule_proc and ad_schedule_proc each take a
--thread flag to cause a scheduled procedure to run
+AOLserver's behaviour, however, "script-global" is a more
+appropriate term.
Threads and Scheduled Procedures

+ns_schedule_proc and ad_schedule_proc each take a
+-thread flag to cause a scheduled procedure to run
 asychronously, in its own thread. It almost always seems like a good idea to
 specify this switch, but there's a problem. 
-
It turns out that whenever a task scheduled with ns_schedule_proc
--thread or ad_schedule_proc -thread t is run, AOLserver
+
It turns out that whenever a task scheduled with ns_schedule_proc
+-thread or ad_schedule_proc -thread t is run, AOLserver
 creates a brand new thread and a brand new interpreter, and reinitializes the
 procedure table (essentially, loads all procedures that were created during
 server initialization into the new interpreter). This happens every
 time the task is executed - and it is a very expensive process that
 should not be taken lightly!
The moral: if you have a lightweight scheduled procedure
-which runs frequently, don't use the -thread
+which runs frequently, don't use the -thread
 switch.
Note also that thread is initialized with a copy of what was
 installed during server startup, so if the procedure table have changed since
 startup (e.g. using the APM watch
 facility), that will not be reflected in the scheduled
-thread.
Using return

-The return command in Tcl returns control to the caller procedure.
+thread.
Using return

+The return command in Tcl returns control to the caller procedure.
 This definition allows nested procedures to work properly. However, this
-definition also means that nested procedures cannot use return to
+definition also means that nested procedures cannot use return to
 end an entire thread. This situation is most common in exception conditions
 that can be triggered from inside a procedure e.g., a permission denied
 exception. At this point, the procedure that detects invalid permission wants
 to write an error message to the user, and completely abort execution of the
-caller thread. return doesn't work, because the procedure may be
-nested several levels deep. We therefore use ad_script_abort
-to abort the remainder of the thread. Note that using return instead
-of ad_script_abort may raise some security issues: an attacker could
+caller thread. return doesn't work, because the procedure may be
+nested several levels deep. We therefore use ad_script_abort
+to abort the remainder of the thread. Note that using return instead
+of ad_script_abort may raise some security issues: an attacker could
 call a page that performed some DML statement, pass in some arguments, and
 get a permission denied error -- but the DML statement would still be
-executed because the thread was not stopped. Note that return -code
-return can be used in circumstances where the procedure will only be
+executed because the thread was not stopped. Note that return -code
+return can be used in circumstances where the procedure will only be
 called from two levels deep. 
-
Returning More Than One Value From a Function

-Many functions have a single return value. For instance, empty_string_p
+
Returning More Than One Value From a Function

+Many functions have a single return value. For instance, empty_string_p
 returns a number: 1 or 0. Other functions need to return a composite value.
 For instance, consider a function that looks up a user's name and email
 address, given an ID. One way to implement this is to return a three-element
@@ -75,33 +74,33 @@
 
AOLserver/Tcl generally has three mechanisms that we like, for returning
 more than one value from a function. When to use which depends on the
 circumstances.
Using Arrays and Pass-By-Value

-The one we generally prefer is returning an array
-get-formatted list. It has all the nice properties of
+The one we generally prefer is returning an array
+get-formatted list. It has all the nice properties of
 pass-by-value, and it uses Tcl arrays, which have good native support. 
 
 ad_proc ad_get_user_info { user_id } {
     db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
     return [list \
-        name "$first_names $last_name" \
+        name "$first_names $last_name" \
     email $email \
-    namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" \
-    emaillink "<a href=\"mailto:$email\">$email</a>"]
+    namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" \
+    emaillink "<a href=\"mailto:$email\">$email</a>"]
 }
 
 array set user_info [ad_get_user_info $user_id]
 
-doc_body_append "$user_info(namelink) ($user_info(emaillink))"
+doc_body_append "$user_info(namelink) ($user_info(emaillink))"
 

 You could also have done this by using an array internally and using
-array get: 
+array get: 
 
 
 ad_proc ad_get_user_info { user_id } {
     db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
-    set user_info(name) "$first_names $last_name"
+    set user_info(name) "$first_names $last_name"
     set user_info(email) $email
-    set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
-    set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
+    set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
+    set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
     return [array get user_info]
 }
 
@@ -117,7 +116,7 @@
 milisecond. The time depends almost completely on the number of entries, and
 almost not at all on the size of the entries.

 You implement pass-by-reference in Tcl by taking the name of an array
-as an argument and upvar it. 
+as an argument and upvar it. 
 
 
 ad_proc ad_get_user_info { 
@@ -126,30 +125,30 @@
 } {
     upvar $array user_info
     db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
-    set user_info(name) "$first_names $last_name"
+    set user_info(name) "$first_names $last_name"
     set user_info(email) $email
-    set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
-    set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
+    set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
+    set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>"
 }
 
 ad_get_user_info -array user_info $user_id
 
-doc_body_append "$user_info(namelink) ($user_info(emaillink))"
+doc_body_append "$user_info(namelink) ($user_info(emaillink))"
 
 
We prefer pass-by-value over pass-by-reference. Pass-by-reference makes
 the code harder to read and debug, because changing a value in one place has
 side effects in other places. Especially if have a chain of
-upvars through several layers of the call stack, you'll have
-a hard time debugging.
Multisets: Using ns_sets and Pass-By-Reference

+upvars through several layers of the call stack, you'll have
+a hard time debugging.
Multisets: Using ns_sets and Pass-By-Reference

 An array is a type of set, which means you can't have multiple
 entries with the same key. Data structures that can have multiple entries for
 the same key are known as a multiset or bag. 
 
If your data can have multiple entries with the same key,
-you should use the AOLserver built-in 
-ns_set. You can also do a case-insensitive lookup on an
-ns_set, something you can't easily do on an array. This is
+you should use the AOLserver built-in 
+ns_set. You can also do a case-insensitive lookup on an
+ns_set, something you can't easily do on an array. This is
 especially useful for things like HTTP headers, which happen to have these
-exact properties.
You always use pass-by-reference with ns_sets, since they
+exact properties.
You always use pass-by-reference with ns_sets, since they
 don't have any built-in way of generating and reconstructing themselves
 from a string representation. Instead, you pass the handle to the set.
 
@@ -158,34 +157,34 @@
     user_id
 } {
     db_1row user_info { select first_names, last_name, email from users where user_id = :user_id }
-    ns_set put $set name "$first_names $last_name"
+    ns_set put $set name "$first_names $last_name"
     ns_set put $set email $email
-    ns_set put $set namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
-    ns_set put $set emaillink "<a href=\"mailto:$email\">$email</a>"
+    ns_set put $set namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>"
+    ns_set put $set emaillink "<a href=\"mailto:$email\">$email</a>"
 }
 
 set user_info [ns_set create]
 ad_get_user_info -set $user_info $user_id
 
-doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
+doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
 
 

-We don't recommend ns_set as a general mechanism for passing
+We don't recommend ns_set as a general mechanism for passing
 sets (as opposed to multisets) of data. Not only do they inherently use
 pass-by-reference, which we dis-like, they're also somewhat clumsy to
 use, since Tcl doesn't have built-in syntactic support for them. 
-
Consider for example a loop over the entries in a ns_set as
+
Consider for example a loop over the entries in a ns_set as
 compared to an array:
 
 # ns_set variant
 set size [ns_set size $myset]
 for { set i 0 } { $i < $size } { incr i } {
-    puts "[ns_set key $myset $i] = [ns_set value $myset $i]"
+    puts "[ns_set key $myset $i] = [ns_set value $myset $i]"
 }
 
 # array variant
 foreach name [array names myarray] {
-    puts "$myarray($name) = $myarray($name)"
+    puts "$myarray($name) = $myarray($name)"
 }
 
 

@@ -205,9 +204,9 @@
 ]
 
 

-ns_sets are designed to be lightweight, so memory consumption
-should not be a problem. However, when using ns_set get to
+ns_sets are designed to be lightweight, so memory consumption
+should not be a problem. However, when using ns_set get to
 perform lookup by name, they perform a linear lookup, whereas arrays use a
-hash table, so ns_sets are slower than arrays when the number of
+hash table, so ns_sets are slower than arrays when the number of
 entries is large. 
 
($Id$)
Prev Home  Next
Object Identity Up  Using Form Builder: building html forms dynamically
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v
diff -u -r1.34.2.2 -r1.34.2.3
--- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	22 Apr 2007 10:21:56 -0000	1.34.2.2
+++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	14 Jul 2007 12:34:47 -0000	1.34.2.3
@@ -1,9 +1,8 @@
-
-Add PSGML commands to emacs init file (OPTIONAL)Prev Appendix�B.�Install additional supporting software  Next
Add PSGML commands to emacs init file (OPTIONAL)

+Add PSGML commands to emacs init file (OPTIONAL)
Prev Appendix�B.�Install additional supporting software  Next
Add PSGML commands to emacs init file (OPTIONAL)

 If you plan to write or edit any documentation with emacs, install a
       customized emacs configuration file with DocBook commands in the skeleton
       directory, so it will be used for all new users.  The file also
       fixes the backspace -> help mis-mapping that often occurs in
-      terminals.
[root tmp]# cp /tmp/openacs-5.3.1/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs
-cp: overwrite `/etc/skel/.emacs'? y
-[root tmp]# 
Debian users:
apt-get install psgml
Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless.  In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later.  For debian, apt-get install nxml.
Prev Home  Next
Initialize CVS (OPTIONAL) Up  Install Daemontools (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org
+      terminals.
[root tmp]# cp /tmp/openacs-5.3.2/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs
+cp: overwrite `/etc/skel/.emacs'? y
+[root tmp]# 
Debian users:
apt-get install psgml
Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless.  In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later.  For debian, apt-get install nxml.
Prev Home  Next
Initialize CVS (OPTIONAL) Up  Install Daemontools (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/psgml-mode.html	22 Apr 2007 10:21:56 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/psgml-mode.html	14 Jul 2007 12:34:47 -0000	1.42.2.3
@@ -1,53 +1,52 @@
-
-Using PSGML mode in EmacsPrev Chapter�13.�Documentation Standards  Next
Using PSGML mode in Emacs
By David Lutterkort
+Using PSGML mode in EmacsPrev Chapter�13.�Documentation Standards  Next
Using PSGML mode in Emacs
By David Lutterkort
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Note: nxml mode replaces and/or complements psgml mode.  More information.
What it is
PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It
+        
Note: nxml mode replaces and/or complements psgml mode.  More information.
What it is
PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It
 can parse a DTD and help you insert the right tags in the right place, knows
 about tags' attributes and can tell you in which contexts a tag can be
 used. If you give it the right DTD, that is. But even without a DTD,
-it can save you some typing since pressing C-c/ will close an open
-tag automatically.
Where to get it
Most newer emacsen come with PSGML mode preinstalled. You can find out
-whether your emacs has it with the locate-library command. In Emacs,
-type M-x locate-library and enter psgml. Emacs will tell
+it can save you some typing since pressing C-c/ will close an open
+tag automatically.
Where to get it
Most newer emacsen come with PSGML mode preinstalled. You can find out
+whether your emacs has it with the locate-library command. In Emacs,
+type M-x locate-library and enter psgml. Emacs will tell
 you if it found it or not.
If you don't have PSGML preinstalled in your Emacs, there are two
 things you can do:
On Linux: Get the 
 psgml rpm from RedHat's
 docbook-tools and install it as usual.
On other systems: Get the tarball from the PSGML Website.
-Unpack it and follow the install instructions.
Using CATALOG files
The easiest way to teach PSGML mode about a DTD is by adding it to your
-own CATALOG. Here is an example of how you can set that up for the
+Unpack it and follow the install instructions.
Using CATALOG files
The easiest way to teach PSGML mode about a DTD is by adding it to your
+own CATALOG. Here is an example of how you can set that up for the
 Docbook XML DTD.
Get the Docbook XML DTD
 zip archive from docbook.org
Go somewhere in your working directory and do 
       mkdir -p dtd/docbook-xml
       cd dtd/docbook-xml
       unzip -a <docbook XML DTD zip archive>
    
-
Create a file with the name CATALOG in the dtd
+
Create a file with the name CATALOG in the dtd
 directory and put the line 
-      CATALOG "docbook-xml/docbook.cat"
+      CATALOG "docbook-xml/docbook.cat"
 

-in it. By maintaining your own CATALOG, it is easy to add more
+in it. By maintaining your own CATALOG, it is easy to add more
 DTD's without changing your emacs settings. (How about that HTML 4.01 DTD you
 always wanted to get from W3C ? The
 DTD is in the zip archives and tarballs available on the site.)
That's it. Now you are ready to tell emacs all about PSGML mode and
-that funky CATALOG
What to tell emacs
If you installed PSGML mode in a non-standard location, e.g., somewhere in
-your home directory, you need to add this to the load-path by adding
-this line to your .emacs file:
-      (add-to-list 'load-path "/some/dir/that/contains/psgml.elc")
+that funky CATALOG
What to tell emacs
If you installed PSGML mode in a non-standard location, e.g., somewhere in
+your home directory, you need to add this to the load-path by adding
+this line to your .emacs file:
+      (add-to-list 'load-path "/some/dir/that/contains/psgml.elc")
    
-
To let PSGML mode find your CATALOG and to enable PSGML mode for
-all your editing, add these lines to your .emacs:
+
To let PSGML mode find your CATALOG and to enable PSGML mode for
+all your editing, add these lines to your .emacs:
       (require 'psgml)
 
-      (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode))
-      (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode))
-      (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode))
-      (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode))
+      (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode))
+      (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode))
+      (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode))
+      (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode))
       
-      (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG")
+      (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG")
    
 
If you want font-locking and indentation, you can also add these lines
-into the .emacs file:
+into the .emacs file:
       (setq sgml-markup-faces '((start-tag . font-lock-function-name-face)
                                 (end-tag . font-lock-function-name-face)
                 (comment . font-lock-comment-face)
@@ -59,28 +58,28 @@
       (setq sgml-set-face t)
       (setq-default sgml-indent-data t)
       ;; Some convenient key definitions:
-      (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type)
-      (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info)
-      (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity)
+      (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type)
+      (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info)
+      (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity)
    
-
What is a DOCTYPE ?
All SGML and XML documents that should conform to a DTD have to declare a
-doctype. For the docbook XML, all your .xml files whould start with
+
What is a DOCTYPE ?
All SGML and XML documents that should conform to a DTD have to declare a
+doctype. For the docbook XML, all your .xml files whould start with
 the line
-      <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd">
+      <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd">
    
 
If your document is only part of a larger XML document, you can tell PSGML
 mode about it by appending the following lines to your file. In this
 case, do not include a DOCTYPE declaration in your file.
       <!--
        Local Variables:
-       sgml-parent-document: ("top.xml" "book" "sect1")
+       sgml-parent-document: ("top.xml" "book" "sect1")
        End:
       -->
    
 
Which says that the parent of this document can be found in the file
-top.xml, that the element in the parent that will enclose the
-current document is a book and that the current file's topmost
-element is a sect1.
How to use it
Of course, you should read the emacs texinfo pages that come with PSGML
-mode from start to finish. Barring that, here are some handy commands:
Key Command
C-c C-e Insert an element. Uses completion and only lets you insert elements that
-are valid
C-c C-a Edit attributes of enclosing element.
C-c C-x C-i Show information about the document's DTD.
C-c C-x C-e Describe element. Shows for one element which elements can be parents,
-what its contents can be and lists its attributes.
Further reading
Start with the Section�, “OpenACS Documentation Guide”
($Id$)
Prev Home  Next
OpenACS Documentation Guide Up  Using nXML mode in Emacs
docs@openacs.org
View comments on this page at openacs.org
+top.xml, that the element in the parent that will enclose the
+current document is a book and that the current file's topmost
+element is a sect1.
How to use it
Of course, you should read the emacs texinfo pages that come with PSGML
+mode from start to finish. Barring that, here are some handy commands:
Key Command
C-c C-e Insert an element. Uses completion and only lets you insert elements that
+are valid
C-c C-a Edit attributes of enclosing element.
C-c C-x C-i Show information about the document's DTD.
C-c C-x C-e Describe element. Shows for one element which elements can be parents,
+what its contents can be and lists its attributes.
Further reading
Start with the the section called “OpenACS Documentation Guide”
($Id$)
Prev Home  Next
OpenACS Documentation Guide Up  Using nXML mode in Emacs
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/release-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v
diff -u -r1.48.2.2 -r1.48.2.3
--- openacs-4/packages/acs-core-docs/www/release-notes.html	22 Apr 2007 10:21:56 -0000	1.48.2.2
+++ openacs-4/packages/acs-core-docs/www/release-notes.html	14 Jul 2007 12:34:47 -0000	1.48.2.3
@@ -1,13 +1,16 @@
-
-OpenACS Release NotesPrev Chapter�1.�High level information: What is OpenACS?  Next
OpenACS Release Notes
The ChangeLogs include an annotated list of changes (Section�, “Changelog (most recent release only)”) since the last release and in the
-entire 5.3 release sequence Section�, “Changelog for oacs-5-3”.
Release 5.3.1
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
New Site and Blank master templates and CSS compatible with the .LRN Zen
-	      work.  Compatibility master templates are provided for existing sites.
The ChangeLogs include an annotated list of changes (Section�, “Changelog (most recent release only)”) since the last release and in the
-entire 5.3 release sequence Section�, “Changelog for oacs-5-3”.
Release 5.3.0
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
Release 5.2.0
Bug fixes.
New TIPs implemented.
This release does not include new translations.
Release 5.1.4
Bug fixes.
The missing CR TCL API has been filled in, thanks to Rocael and
-        his team and Dave Bauer.
This release does not include new translations.
Release 5.1.3
Bug fixes, primarily for .LRN compatibility in support of upcoming .LRN 2.1.0 releases. This release does not include new translations since 5.1.2.
-        
Release 5.1.2
Translations syncronized with the translation server.
+OpenACS Release Notes
Prev Chapter�1.�High level information: What is OpenACS?  Next
OpenACS Release Notes
The ChangeLogs include an annotated list of changes (the section called “Changelog (most recent release only)”) since the last release and in the
+entire 5.3 release sequence the section called “Changelog for oacs-5-3”.
Release 5.3.2
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.  One for Oracle fails (error in test)
New Site and Blank master templates and CSS compatible with the .LRN Zen
+	      work.  Compatibility master templates are provided for existing sites.  
+              In 5.3.1, the tabbed master (group-master.*) didn't work correctly, this has been
+              fixed in 5.3.2
The ChangeLogs include an annotated list of changes (the section called “Changelog (most recent release only)”) since the last release and in the
+entire 5.3 release sequence the section called “Changelog for oacs-5-3”.
Release 5.3.1
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
New Site and Blank master templates and CSS compatible with the .LRN Zen
+	      work.  Compatibility master templates are provided for existing sites.
The ChangeLogs include an annotated list of changes (the section called “Changelog (most recent release only)”) since the last release and in the
+entire 5.3 release sequence the section called “Changelog for oacs-5-3”.
Release 5.3.0
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
Release 5.2.0
Bug fixes.
New TIPs implemented.
This release does not include new translations.
Release 5.1.4
Bug fixes.
The missing CR TCL API has been filled in, thanks to Rocael and
+        his team and Dave Bauer.
This release does not include new translations.
Release 5.1.3
Bug fixes, primarily for .LRN compatibility in support of upcoming .LRN 2.1.0 releases. This release does not include new translations since 5.1.2.
+        
Release 5.1.2
Translations syncronized with the translation server.
         Basque and Catalan added.
         
For a complete change list, see the  Change list since
-          5.1.0 in Section�, “Changelog for oacs-5-3”.
Release 5.1.1
This is the first release using the newest adjustment to the versioning convention.  The OpenACS 5.1.1 tag will apply to OpenACS core as well as to the most recent released version of every package, including .LRN.
Translations syncronized with the translation server.
+          5.1.0 in the section called “Changelog for oacs-5-3”.
Release 5.1.1
This is the first release using the newest adjustment to the versioning convention.  The OpenACS 5.1.1 tag will apply to OpenACS core as well as to the most recent released version of every package, including .LRN.
Translations syncronized with the translation server.
         
Bug
             1519 fixed.  This involved renaming all catalog
           files for ch_ZH, TH_TH, AR_EG, AR_LB, ms_my, RO_RO, FA_IR,
@@ -18,21 +21,21 @@
           the files and database before upgrading.)
Other bug fixes since 5.1.0: 1785,
           1793,
       and over a dozen additional bug fixes.
For a complete change list, see the  Change list since
-          5.0.0 in Section�, “Changelog for oacs-5-3”.
Release 5.1.0
Lots of little tweaks and fixes
Complete Change list since 5.0.0 in Changelog
Many Bug fixes
Release 5.0.4
New translations, including for .LRN 2.0.2.
Release 5.0.3
Bug fixes: 1560, #1556. Site becomes unresponsive, requires restart
Release 5.0.2
Bug fixes: #1495. Croatian enabled by default, #1496. APM automated install fails if files have spaces in their names, #1494. automated upgrade crashes (halting the upgrade process)
Complete Change list since 5.0.0 in Changelog
File tagging scheme in CVS changed to follow TIP #46: (Approved) Rules for Version Numbering and CVS tagging of Packages
Release 5.0.1
All work on the translation server from 7 Nov 2003 to 7 Feb 2004 is now included in catalogs.
One new function in acs-tcl, util::age_pretty
Complete Change list since 5.0.0 in Changelog
Many documentation updates and doc bug fixes 
Release 5.0.0

+          5.0.0 in the section called “Changelog for oacs-5-3”.
Release 5.1.0
Lots of little tweaks and fixes
Complete Change list since 5.0.0 in Changelog
Many Bug fixes
Release 5.0.4
New translations, including for .LRN 2.0.2.
Release 5.0.3
Bug fixes: 1560, #1556. Site becomes unresponsive, requires restart
Release 5.0.2
Bug fixes: #1495. Croatian enabled by default, #1496. APM automated install fails if files have spaces in their names, #1494. automated upgrade crashes (halting the upgrade process)
Complete Change list since 5.0.0 in Changelog
File tagging scheme in CVS changed to follow TIP #46: (Approved) Rules for Version Numbering and CVS tagging of Packages
Release 5.0.1
All work on the translation server from 7 Nov 2003 to 7 Feb 2004 is now included in catalogs.
One new function in acs-tcl, util::age_pretty
Complete Change list since 5.0.0 in Changelog
Many documentation updates and doc bug fixes 
Release 5.0.0

 	This is OpenACS 5.0.0.  This version contains no known security, data loss, or crashing bugs, nor any bugs judged release blockers.  This version has received manual testing.  It has passed current automated testing, which is not comprehensive.  This release contains work done on the translation server http://translate.openacs.org through 7 Nov 2003.  
   

 	Please report bugs using our
 	
 	  Bug Tracker at the OpenACS website.
   

 	You may want to begin by reading our installation documentation for
-	Section�, “a Unix-like system”.  Note that the Windows documentation is
-	not current for OpenACS 5.3.1, but an alternative is to use John
+	the section called “a Unix-like system”.  Note that the Windows documentation is
+	not current for OpenACS 5.3.2, but an alternative is to use John
 	Sequeira's Oasis VM
 	project.
   

 	After installation, the full documentation set can be found by visiting
-	http://yourserver/doc.
+	http://yourserver/doc.
   

         New features in this release:       
   

@@ -107,19 +110,539 @@
           PostgreSQL 7.3.
 	

 	   The undocumented special handling of ~ and +variable+ in
-	   formtemplates, found in packages/acs-templating/resources/*,
+	   formtemplates, found in packages/acs-templating/resources/*,
 	   has been removed in favor of using <noparse> and
 	   \@variable\@ (the standard templating mechanisms).  Locally
 	   provided formtemplate styles still using these mechanisms
 	   will break.
         

 	   Serving backup files and files from the CVS directories is turned off by default via the acs-kernel parameter
-     	   ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~")
-	
($Id$)
Release 4.6.3
Release Notes for 4.6.3
Release 4.6.2
Release Notes for 4.6.2
Release 4.6
Release Notes for 4.6
Release 4.5
Release Notes for 4.5
Changelog (most recent release only)
ChangeLog missing
+     	   ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~")
+	
($Id$)
Release 4.6.3
Release Notes for 4.6.3
Release 4.6.2
Release Notes for 4.6.2
Release 4.6
Release Notes for 4.6
Release 4.5
Release Notes for 4.5
Changelog (most recent release only)
ChangeLog missing
 -->
 
 
-Changelog for oacs-5-3
+Changelog for oacs-5-3
+2007-07-13 03:30  donb
+
+	* packages/search/search.info: Made search depend on service
+	  contract package
+
+2007-07-13 02:53  donb
+
+	* packages/acs-subsite/www/: group-master.adp, group-master.tcl:
+	  Hacked this to work with the new master template scheme.  This is
+	  only a temporary solution (see my comments in the code for
+	  details)
+
+2007-07-13 02:31  emmar
+
+	* packages/acs-lang/: tcl/lang-widget-procs.tcl,
+	  www/change-locale-include.tcl: Mark as Selected the current
+	  locale in the select_locale widget
+
+2007-07-10 08:38  carlb
+
+	* packages/acs-subsite/www/shared/whos-online.tcl: Added missing
+	  internationalization
+
+2007-07-10 08:36  carlb
+
+	* packages/acs-subsite/catalog/acs-subsite.en_US.ISO-8859-1.xml:
+	  Made messages more consistent and added missing keys
+
+2007-06-26 01:29  emmar
+
+	* packages/search/search.info: Make search a singleton since it can
+	  be mounted only once. Description updated too.
+
+2007-06-23 15:51  donb
+
+	* packages/: acs-admin/acs-admin.info,
+	  acs-api-browser/acs-api-browser.info,
+	  acs-authentication/acs-authentication.info,
+	  acs-automated-testing/acs-automated-testing.info,
+	  acs-bootstrap-installer/acs-bootstrap-installer.info,
+	  acs-content-repository/acs-content-repository.info,
+	  acs-core-docs/acs-core-docs.info, acs-kernel/acs-kernel.info,
+	  acs-lang/acs-lang.info, acs-mail-lite/acs-mail-lite.info,
+	  acs-messaging/acs-messaging.info,
+	  acs-reference/acs-reference.info,
+	  acs-service-contract/acs-service-contract.info,
+	  acs-subsite/acs-subsite.info, acs-tcl/acs-tcl.info,
+	  acs-templating/acs-templating.info,
+	  acs-translations/acs-translations.info,
+	  ref-timezones/ref-timezones.info, search/search.info: Bump
+	  version numbers to 5.3.2b1
+
+2007-06-15 06:48  daveb
+
+	* packages/acs-templating/tcl/list-procs.tcl: Don't reset filters
+	  if page is changed.
+
+2007-06-14 18:50  daveb
+
+	* packages/acs-templating/tcl/list-procs.tcl: Don't show page in
+	  list of available filters in form
+
+2007-06-14 07:25  emmar
+
+	* packages/acs-mail-lite/tcl/acs-mail-lite-procs.tcl: Remove
+	  duplicated proc with_finally (also exists in
+	  acs-tcl/tcl/utilities-procs.tcl) and remove unnecessary
+	  with_finally block in the sweeper procs
+
+2007-06-14 05:24  emmar
+
+	* packages/acs-mail-lite/tcl/acs-mail-lite-procs.tcl: Catch errors
+	  when sweeping the mail queue to avoid notifications to remain
+	  unsent until the bad message has been manually removed. With the
+	  catch, the bad message remains in the queue and an error message
+	  sent to the log, and the sweeper proceeds with the next ones.
+
+2007-06-14 02:12  emmar
+
+	* packages/acs-templating/www/doc/demo/: list5/add-edit.tcl,
+	  list6/add-edit.tcl, list7/add-edit.tcl, list8/add-edit.tcl,
+	  list9/add-edit.tcl: Remove obsolete wrap attribute (textarea)
+
+2007-06-14 01:52  emmar
+
+	* packages/acs-templating/tcl/richtext-procs.tcl: Fix richtext HTML
+	  to pass 4.01 transitional validation
+
+2007-06-07 03:15  emmar
+
+	* packages/acs-templating/: tcl/element-procs.tcl,
+	  tcl/form-procs.tcl, www/resources/forms.css: Zen: set a default
+	  class for fieldset. Customized styles for fieldset and legend
+	  tags now will be correctly applied.
+
+2007-06-06 11:35  emmar
+
+	* packages/acs-templating/: resources/forms/standard.adp,
+	  tcl/element-procs.tcl, tcl/form-procs.tcl, tcl/tag-init.tcl: Zen:
+	  fieldset/legend tags are not generated anymore if the legend tag
+	  has no text
+
+2007-06-06 05:47  daveb
+
+	* packages/acs-kernel/: acs-kernel.info,
+	  sql/oracle/upgrade/upgrade-5.3.2d1-5.3.2d2.sql,
+	  sql/postgresql/upgrade/upgrade-5.3.2d1-5.3.2d2.sql: Fix upgrade
+	  to parameter datatype check constraint to work with either
+	  variation of the constraint name. Bump version in info file so
+	  upgrade will run.
+
+2007-06-05 08:30  emmar
+
+	* packages/search/www/search.tcl: Return a complain when no
+	  keywords to search for have been entered
+
+2007-06-03 02:47  maltes
+
+	* packages/acs-authentication/tcl/local-procs.tcl: The username is
+	  not always an email. So, lets use the email instead for sending
+	  the mail
+
+2007-06-01 10:47  emmar
+
+	* packages/: acs-tcl/tcl/navigation-procs.tcl,
+	  search/tcl/search-procs.tcl: Removing unused-deprecated
+	  ad_choice_bar (only used in contrib/obsolete-packages/library)
+	  and search::choice_bar (not used) procs
+
+2007-06-01 03:56  emmar
+
+	* packages/search/: search.info, www/search.adp, www/search.tcl,
+	  www/resources/search.css: last shot (for now) of html cleanup.
+	  choice_bar replaced by a multirow to be able to apply styles at
+	  template level and produce valid HTML
+
+2007-05-30 10:21  emmar
+
+	* packages/acs-templating/resources/forms/standard.adp: Added
+	  form_id to section_id to build fieldset ID (was conflicting in
+	  some case with others IDs)
+
+2007-05-28 08:13  maltes
+
+	* packages/acs-templating/resources/forms/standard.adp: Revert
+
+2007-05-28 02:10  maltes
+
+	* packages/acs-templating/resources/forms/standard.adp: Added form
+	  legend div so the sections can remotely look as before...
+
+2007-05-26 05:19  daveb
+
+	* packages/acs-subsite/www/shared/: parameters-oracle.xql,
+	  parameters-postgresql.xql: Get the parameter datatype so we know
+	  what type of form widget to use
+
+2007-05-24 09:19  emmar
+
+	* packages/search/: catalog/search.en_US.ISO-8859-1.xml,
+	  www/search.adp, www/search.tcl, www/resources/search.css: Created
+	  styles for search results page and applied them to the results
+	  list
+
+2007-05-24 06:37  emmar
+
+	* packages/search/www/: search.adp, search.tcl: Removed references
+	  to (non-existent) dotlrn template
+
+2007-05-24 05:16  daveb
+
+	* packages/: acs-subsite/www/shared/parameters.tcl,
+	  acs-admin/www/apm/parameter-add-2.tcl,
+	  acs-admin/www/apm/parameter-add.tcl,
+	  acs-admin/www/apm/parameter-edit-2.tcl,
+	  acs-admin/www/apm/parameter-edit.tcl,
+	  acs-kernel/sql/oracle/apm-create.sql,
+	  acs-kernel/sql/oracle/upgrade/upgrade-5.3.2d1-5.3.2d2.sql,
+	  acs-kernel/sql/postgresql/apm-create.sql,
+	  acs-kernel/sql/postgresql/upgrade/upgrade-5.3.2d1-5.3.2d2.sql:
+	  Allow a new parameter type "text" to show a textarea on the
+	  parmeter form for parmaeter values that don't fit well within a
+	  textbox.
+
+2007-05-24 04:55  daveb
+
+	* packages/acs-tcl/tcl/utilities-procs.tcl: Use meta-refrsh or
+	  javascript to redirect when switching frm HTTPS to HTTP to avoid
+	  security warining in IE
+
+2007-05-24 03:30  emmar
+
+	* packages/search/www/search.adp: First shot of HTML cleanup
+
+2007-05-24 03:12  emmar
+
+	* www/site-master.tcl: Added content-type
+
+2007-05-24 03:10  emmar
+
+	* www/blank-master.adp: Added missing @ for meta.http_equiv
+
+2007-05-24 03:04  emmar
+
+	* www/default-master.tcl: Edited to avoid empty UL when main and
+	  sub navigations are empty (thanks to Lee who provides the code)
+
+2007-05-19 12:55  maltes
+
+	*
+	  packages/acs-content-repository/sql/postgresql/upgrade/upgrade-5.2.1d1-5.2.1d2.sql:
+	  This old version of the view update is superseeded by
+	  upgrade-5.3.0d1, apart from the fact that on none of my sites
+	  moving from pre 5.2 it has been working on an upgrade (usually
+	  fails due to image content type)
+
+2007-05-17 10:52  avni
+
+	* www/default-master.adp: bug fix on 5-3 branch; emma fixed on
+	  HEAD; master had a relative src. making absolute
+
+2007-05-11 17:39  donb
+
+	* packages/acs-tcl/tcl/00-database-procs.tcl: Fixed a caching bug
+	  ...
+
+2007-05-09 03:20  emmar
+
+	* packages/acs-lang/www/admin/set-system-timezone.tcl: Apply new
+	  format from timeanddate.com to retrieve UTC time
+
+2007-05-07 05:52  maltes
+
+	* packages/acs-kernel/acs-kernel.info: I think kernel is mature. At
+	  least this is my hope :-)
+
+2007-04-25 03:27  leed
+
+	* www/: blank-compat.adp, blank-compat.tcl: Added xinha/rte
+	  processing into blank-compat to unbreak .LRN.
+
+2007-04-23 04:10  leed
+
+	* www/: blank-master.adp, blank-master.tcl, site-master.adp,
+	  site-master.tcl: Fixed typo in declared script type which
+	  prevented xinha from loading.
+
+2007-04-22 22:54  victorg
+
+	* packages/:
+	  acs-authentication/catalog/acs-authentication.ar_LB.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.ca_ES.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.da_DK.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.de_DE.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.el_GR.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.en_US.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.es_CO.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.es_ES.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.es_GT.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.eu_ES.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.fa_IR.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.fr_FR.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.gl_ES.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.hi_IN.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.hu_HU.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.ind_ID.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.it_IT.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.ms_MY.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.nl_NL.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.nn_NO.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.no_NO.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.pa_IN.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.pl_PL.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.pt_BR.ISO-8859-1.xml,
+	  acs-authentication/catalog/acs-authentication.ro_RO.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.ru_RU.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.th_TH.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.tr_TR.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.zh_CN.utf-8.xml,
+	  acs-authentication/catalog/acs-authentication.zh_TW.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.ar_EG.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.ar_LB.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.ast_ES.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.ca_ES.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.da_DK.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.de_DE.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.el_GR.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.en_US.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.es_CO.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.es_ES.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.es_GT.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.eu_ES.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.fi_FI.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.fr_FR.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.gl_ES.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.hi_IN.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.hu_HU.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.it_IT.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.ja_JP.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.ko_KR.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.ms_MY.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.nl_NL.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.nn_NO.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.no_NO.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.pa_IN.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.pl_PL.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.pt_BR.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.pt_PT.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.ro_RO.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.ru_RU.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.sv_SE.ISO-8859-1.xml,
+	  acs-kernel/catalog/acs-kernel.tr_TR.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.zh_CN.utf-8.xml,
+	  acs-kernel/catalog/acs-kernel.zh_TW.utf-8.xml,
+	  acs-lang/catalog/acs-lang.ar_EG.utf-8.xml,
+	  acs-lang/catalog/acs-lang.ar_LB.utf-8.xml,
+	  acs-lang/catalog/acs-lang.ast_ES.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.ca_ES.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.da_DK.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.de_DE.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.el_GR.utf-8.xml,
+	  acs-lang/catalog/acs-lang.en_GB.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.en_US.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.es_CO.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.es_ES.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.es_GT.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.eu_ES.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.fa_IR.utf-8.xml,
+	  acs-lang/catalog/acs-lang.fi_FI.utf-8.xml,
+	  acs-lang/catalog/acs-lang.fr_FR.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.gl_ES.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.hi_IN.utf-8.xml,
+	  acs-lang/catalog/acs-lang.hu_HU.utf-8.xml,
+	  acs-lang/catalog/acs-lang.it_IT.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.ja_JP.utf-8.xml,
+	  acs-lang/catalog/acs-lang.ko_KR.utf-8.xml,
+	  acs-lang/catalog/acs-lang.ms_MY.utf-8.xml,
+	  acs-lang/catalog/acs-lang.nl_NL.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.nn_NO.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.no_NO.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.pa_IN.utf-8.xml,
+	  acs-lang/catalog/acs-lang.pl_PL.utf-8.xml,
+	  acs-lang/catalog/acs-lang.pt_BR.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.pt_PT.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.ro_RO.utf-8.xml,
+	  acs-lang/catalog/acs-lang.ru_RU.utf-8.xml,
+	  acs-lang/catalog/acs-lang.sh_HR.utf-8.xml,
+	  acs-lang/catalog/acs-lang.sv_SE.ISO-8859-1.xml,
+	  acs-lang/catalog/acs-lang.th_TH.utf-8.xml,
+	  acs-lang/catalog/acs-lang.tr_TR.utf-8.xml,
+	  acs-lang/catalog/acs-lang.zh_CN.utf-8.xml,
+	  acs-lang/catalog/acs-lang.zh_TW.utf-8.xml,
+	  acs-lang/sql/oracle/ad-locales.sql,
+	  acs-lang/sql/postgresql/ad-locales.sql,
+	  acs-mail-lite/catalog/acs-mail-lite.ca_ES.ISO-8859-1.xml,
+	  acs-mail-lite/catalog/acs-mail-lite.de_DE.ISO-8859-1.xml,
+	  acs-mail-lite/catalog/acs-mail-lite.en_US.ISO-8859-1.xml,
+	  acs-mail-lite/catalog/acs-mail-lite.es_ES.ISO-8859-1.xml,
+	  acs-mail-lite/catalog/acs-mail-lite.gl_ES.ISO-8859-1.xml,
+	  acs-mail-lite/catalog/acs-mail-lite.nl_NL.ISO-8859-1.xml,
+	  acs-mail-lite/catalog/acs-mail-lite.pl_PL.utf-8.xml,
+	  acs-mail-lite/catalog/acs-mail-lite.pt_BR.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.ar_EG.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.ar_LB.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.ast_ES.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.ca_ES.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.da_DK.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.de_DE.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.el_GR.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.en_GB.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.en_US.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.es_CO.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.es_ES.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.es_GT.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.eu_ES.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.fi_FI.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.fr_FR.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.gl_ES.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.hi_IN.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.hu_HU.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.it_IT.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.ja_JP.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.ko_KR.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.ms_MY.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.nl_NL.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.nn_NO.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.no_NO.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.pa_IN.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.pl_PL.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.pt_BR.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.pt_PT.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.ro_RO.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.ru_RU.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.sh_HR.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.sv_SE.ISO-8859-1.xml,
+	  acs-subsite/catalog/acs-subsite.th_TH.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.tr_TR.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.zh_CN.utf-8.xml,
+	  acs-subsite/catalog/acs-subsite.zh_TW.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.ar_EG.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.ar_LB.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.ast_ES.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.ca_ES.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.da_DK.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.de_DE.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.en_US.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.es_CO.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.es_ES.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.es_GT.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.eu_ES.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.fa_IR.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.fi_FI.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.fr_FR.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.gl_ES.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.hi_IN.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.hu_HU.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.ind_ID.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.it_IT.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.ja_JP.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.ko_KR.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.ms_MY.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.nl_NL.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.nn_NO.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.no_NO.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.pl_PL.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.pt_BR.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.pt_PT.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.ro_RO.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.ru_RU.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.sh_HR.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.sv_SE.ISO-8859-1.xml,
+	  acs-tcl/catalog/acs-tcl.tr_TR.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.zh_CN.utf-8.xml,
+	  acs-tcl/catalog/acs-tcl.zh_TW.utf-8.xml,
+	  acs-templating/catalog/acs-templating.ar_LB.utf-8.xml,
+	  acs-templating/catalog/acs-templating.ca_ES.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.da_DK.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.de_DE.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.el_GR.utf-8.xml,
+	  acs-templating/catalog/acs-templating.en_US.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.es_CO.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.es_ES.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.es_GT.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.eu_ES.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.fi_FI.utf-8.xml,
+	  acs-templating/catalog/acs-templating.fr_FR.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.gl_ES.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.hi_IN.utf-8.xml,
+	  acs-templating/catalog/acs-templating.hu_HU.utf-8.xml,
+	  acs-templating/catalog/acs-templating.it_IT.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.ko_KR.utf-8.xml,
+	  acs-templating/catalog/acs-templating.ms_MY.utf-8.xml,
+	  acs-templating/catalog/acs-templating.nl_NL.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.nn_NO.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.no_NO.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.pa_IN.utf-8.xml,
+	  acs-templating/catalog/acs-templating.pt_BR.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.pt_PT.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.ro_RO.utf-8.xml,
+	  acs-templating/catalog/acs-templating.ru_RU.utf-8.xml,
+	  acs-templating/catalog/acs-templating.sh_HR.utf-8.xml,
+	  acs-templating/catalog/acs-templating.sv_SE.ISO-8859-1.xml,
+	  acs-templating/catalog/acs-templating.tr_TR.utf-8.xml,
+	  acs-templating/catalog/acs-templating.zh_CN.utf-8.xml,
+	  acs-templating/catalog/acs-templating.zh_TW.utf-8.xml,
+	  search/catalog/search.de_DE.ISO-8859-1.xml,
+	  search/catalog/search.en_US.ISO-8859-1.xml,
+	  search/catalog/search.es_ES.ISO-8859-1.xml,
+	  search/catalog/search.nl_NL.ISO-8859-1.xml,
+	  search/catalog/search.pl_PL.utf-8.xml,
+	  search/catalog/search.pt_BR.ISO-8859-1.xml: Importing catalog
+	  files from traslate.openacs.org for Openacs Core Packages (5.3.1)
+	  and .LRN Packages (2.3.0).
+
+2007-04-22 03:21  donb
+
+	* packages/acs-core-docs/www/: acs-admin.html, aolserver.html,
+	  aolserver4.html, automated-testing-best-practices.html,
+	  backup-recovery.html, bootstrap-acs.html, complete-install.html,
+	  configuring-configuring-packages.html,
+	  configuring-configuring-permissions.html,
+	  configuring-install-packages.html,
+	  configuring-mounting-packages.html, credits.html,
+	  cvs-guidelines.html, cvs-tips.html, db-api-detailed.html,
+	  db-api.html, docbook-primer.html,
+	  eng-standards-constraint-naming.html,
+	  eng-standards-filenaming.html, eng-standards-plsql.html,
+	  eng-standards-versioning.html, ext-auth-requirements.html,
+	  filename.html, form-builder.html, high-avail.html, how-do-I.html,
+	  i18n-convert.html, index.html, individual-programs.html,
+	  install-cvs.html, install-daemontools.html,
+	  install-full-text-search-openfts.html,
+	  install-full-text-search-tsearch2.html,
+	  install-next-add-server.html, install-next-nightly-vacuum.html,
+	  install-openacs-keepalive.html, install-qmail.html,
+	  install-redhat.html, install-steps.html, ix01.html,
+	  mac-installation.html, maint-performance.html,
+	  maintenance-deploy.html, object-identity.html, objects.html,
+	  openacs-unpack.html, openacs.html, oracle.html, packages.html,
+	  parties.html, permissions-tediously-explained.html,
+	  permissions.html, postgres.html, programming-with-aolserver.html,
+	  psgml-for-emacs.html, psgml-mode.html, release-notes.html,
+	  releasing-openacs-core.html, request-processor.html,
+	  requirements-template.html, security-notes.html,
+	  style-guide.html, subsites.html, tcl-doc.html, templates.html,
+	  tutorial-css-layout.html, tutorial-cvs.html,
+	  tutorial-database.html, tutorial-debug.html,
+	  tutorial-distribute.html, tutorial-etp-templates.html,
+	  tutorial-newpackage.html, tutorial-pages.html,
+	  unix-installation.html, upgrade-4.5-to-4.6.html,
+	  upgrade-openacs-files.html, upgrade-overview.html,
+	  variables.html, win2k-installation.html, xml/variables.ent,
+	  xml/for-everyone/release-notes.xml: Generated documentation for
+	  5.3.1 final
+
+2007-04-22 02:15  donb
+
+	* packages/acs-core-docs/www/xml/for-everyone/release-notes.xml:
+	  Release notes for 5.3.1 final
+
 2007-04-22 01:57  donb
 
 	* packages/: acs-admin/acs-admin.info,
@@ -272,68 +795,68 @@
 	* etc/config.tcl: Added more parameters as they were posted on the
 	  AOLserver list.
 
-2007-03-31 21:58  avni
+2007-03-31 22:58  avni
 
 	* packages/acs-subsite/www/resources/site-master.css: adding 0.4em
 	  padding-left for system name
 
-2007-03-31 21:54  avni
+2007-03-31 22:54  avni
 
 	* www/default-master.adp: improving layout of header
 
-2007-03-31 21:53  avni
+2007-03-31 22:53  avni
 
 	* packages/acs-subsite/www/resources/site-master.css: Cleaning up
 	  css; changing colors; trying to make it more zen
 
-2007-03-30 16:42  donb
+2007-03-30 17:42  donb
 
 	* www/: blank-master.adp, blank-master.tcl: Reluctantly moved the
 	  dotlrn toolbar here so it will work with existing sites.
 
-2007-03-30 03:37  emmar
+2007-03-30 04:37  emmar
 
 	* packages/acs-tcl/tcl/table-display-procs.tcl: Zen: HTML cleanup
 
-2007-03-29 16:20  victorg
+2007-03-29 17:20  victorg
 
 	* packages/acs-api-browser/lib/search.tcl: Typo in var name (
 	  db_doc_serch_query_name )
 
-2007-03-29 06:55  emmar
+2007-03-29 07:55  emmar
 
 	* packages/acs-subsite/www/: shared/whos-online.adp,
 	  user/portrait/comment-edit.adp, user/portrait/upload.adp: Zen:
 	  HTML cleanup
 
-2007-03-27 01:02  emmar
+2007-03-27 02:02  emmar
 
 	* packages/acs-subsite/www/resources/: default-master.css,
 	  site-master.css: Move general styles definition to
 	  site-master.css. default-master.css now contains only styles for
 	  the calendar widget
 
-2007-03-26 23:34  gustafn
+2007-03-27 00:34  gustafn
 
 	* packages/acs-admin/www/install/index.adp: fix: add needed ending
 	  slash in link pointing to http://openacs.org/repository/
 
-2007-03-26 09:49  donb
+2007-03-26 10:49  donb
 
 	* www/site-master.tcl: Removed more link to css titles because the
 	  javascript switcher screws up
 
-2007-03-26 09:45  donb
+2007-03-26 10:45  donb
 
 	* www/blank-master.tcl: Removed title from dev sup css link because
 	  the javascript style switcher is really stupid.
 
-2007-03-25 04:25  emmar
+2007-03-25 05:25  emmar
 
 	* packages/acs-templating/www/resources/lists.css: Remove extra
 	  chars causing silly warning
 
-2007-03-24 17:21  donb
+2007-03-24 18:21  donb
 
 	* packages/: acs-admin/acs-admin.info,
 	  acs-api-browser/acs-api-browser.info,
@@ -352,45 +875,45 @@
 	  ref-timezones/ref-timezones.info, search/search.info: Bumped to
 	  5.3.1a1.  I hope.  I never get this right!
 
-2007-03-24 13:50  donb
+2007-03-24 14:50  donb
 
 	* www/: blank-master.adp, site-master.adp, site-master.tcl: Moved
 	  some stuff to blank master from site master.
 
-2007-03-22 10:14  emmar
+2007-03-22 11:14  emmar
 
 	* packages/acs-subsite/tcl/email-image-procs.tcl: Forgot to escape
 	  quotes in my previous commit
 
-2007-03-22 10:01  emmar
+2007-03-22 11:01  emmar
 
 	* packages/acs-subsite/tcl/email-image-procs.tcl: Zen: class portal
 	  HTML cleanup
 
-2007-03-22 09:37  donb
+2007-03-22 10:37  donb
 
 	* www/: blank-master.adp, blank-master.tcl: Moved devsup here, it's
 	  css must be clashing with something else because the formating is
 	  non-existent.
 
-2007-03-22 09:21  emmar
+2007-03-22 10:21  emmar
 
 	* packages/acs-templating/resources/lists/table.adp: Zen: headers
 	  should refer to existing IDs
 
-2007-03-22 08:03  emmar
+2007-03-22 09:03  emmar
 
 	* packages/acs-templating/resources/forms/standard.adp: Zen: don't
 	  generate label tag if the form mode is 'display'
 
-2007-03-22 03:53  emmar
+2007-03-22 04:53  emmar
 
 	* packages/acs-templating/:
 	  catalog/acs-templating.en_US.ISO-8859-1.xml,
 	  catalog/acs-templating.es_ES.ISO-8859-1.xml,
 	  tcl/richtext-procs.tcl: i18n
 
-2007-03-22 02:13  emmar
+2007-03-22 03:13  emmar
 
 	* packages/: acs-admin/catalog/acs-admin.es_ES.ISO-8859-1.xml,
 	  acs-authentication/catalog/acs-authentication.es_ES.ISO-8859-1.xml,
@@ -402,38 +925,38 @@
 	  acs-templating/catalog/acs-templating.es_ES.ISO-8859-1.xml,
 	  search/catalog/search.es_ES.ISO-8859-1.xml: Spanish translation
 
-2007-03-21 05:48  emmar
+2007-03-21 06:48  emmar
 
 	* packages/acs-templating/resources/lists/table.adp: Zen: add
 	  mandatory ACTION attribute to form tag
 
-2007-03-21 04:27  emmar
+2007-03-21 05:27  emmar
 
 	* packages/acs-subsite/www/resources/core.js: Commas are not valid
 	  char for element identifier. Replaced with a dot in list builder
 	  and acs_ListCheckAll edited to parse correctly the IDs
 
-2007-03-21 04:17  emmar
+2007-03-21 05:17  emmar
 
 	* packages/acs-templating/tcl/list-procs.tcl: Fix typo in checkbox
 	  identifiers
 
-2007-03-21 02:01  avni
+2007-03-21 03:01  avni
 
 	* packages/search/catalog/search.en_US.ISO-8859-1.xml: Zen: version
 	  bump
 
-2007-03-21 01:45  avni
+2007-03-21 02:45  avni
 
 	* packages/acs-tcl/catalog/acs-tcl.en_US.ISO-8859-1.xml: Zen:
 	  version change
 
-2007-03-21 01:45  avni
+2007-03-21 02:45  avni
 
 	* packages/acs-subsite/catalog/acs-subsite.en_US.ISO-8859-1.xml:
 	  Zen: Adding new footer message key (carl)
 
-2007-03-21 01:42  avni
+2007-03-21 02:42  avni
 
 	* packages/:
 	  acs-authentication/catalog/acs-authentication.en_US.ISO-8859-1.xml,
@@ -442,68 +965,68 @@
 	  acs-mail-lite/catalog/acs-mail-lite.en_US.ISO-8859-1.xml: Zen:
 	  version change
 
-2007-03-20 04:52  emmar
+2007-03-20 05:52  emmar
 
 	* www/blank-master.tcl: Call to initRTE was missing
 
-2007-03-20 03:08  emmar
+2007-03-20 04:08  emmar
 
 	* www/blank-master.tcl: Add missing quotes that caused xinha not to
 	  render properly
 
-2007-03-19 17:39  donb
+2007-03-19 18:39  donb
 
 	* www/: blank-master.adp, blank-master.tcl: got this stuff to load
 	  xinha stuff correctly however it's not rendering...
 
-2007-03-19 16:47  donb
+2007-03-19 17:47  donb
 
 	* www/blank-master.tcl: First cut at putting in RTE/Xinha js
 	  (incomplete)
 
-2007-03-19 07:26  emmar
+2007-03-19 08:26  emmar
 
 	* packages/acs-templating/tcl/richtext-procs.tcl: Remove duplicated
 	  NOSCRIPT tags for RTE widget
 
-2007-03-18 15:39  avni
+2007-03-18 16:39  avni
 
 	* packages/acs-templating/tcl/widget-procs.tcl: Zen: adding ID
 	  attributes for input button and file types.
 
-2007-03-18 15:19  avni
+2007-03-18 16:19  avni
 
 	* packages/acs-templating/resources/forms/standard.adp: Zen:
 	  removing label from inform widget type
 
-2007-03-18 14:32  avni
+2007-03-18 15:32  avni
 
 	* packages/acs-templating/tcl/widget-procs.tcl: Zen:
 	  template::widget::block bug fix - there was a th that was closed
 	  with a /td instead of a /th
 
-2007-03-17 15:31  carlb
+2007-03-17 16:31  carlb
 
 	* packages/acs-subsite/catalog/acs-subsite.en_US.ISO-8859-1.xml:
 	  Zen: alt tag and message keys for envelope icons in notfications
 
-2007-03-16 04:41  emmar
+2007-03-16 05:41  emmar
 
 	* packages/acs-templating/resources/forms/standard.adp: Zen: label
 	  should not be used for element widgets that group several form
 	  elements (radio, checkbox, date)
 
-2007-03-14 06:34  daveb
+2007-03-14 07:34  daveb
 
 	*
 	  packages/acs-templating/www/resources/xinha-nightly/plugins/OacsAttach/oacs-attach.js:
 	  Pass selected text as title to insert link popup
 
-2007-03-13 09:50  donb
+2007-03-13 10:50  donb
 
 	* www/blank-master.tcl: Added core.js ...
 
-2007-03-13 08:05  donb
+2007-03-13 09:05  donb
 
 	* www/blank-compat.tcl: Changed blank-compat to always link
 	  forms.css and lists.css as was true in earlier versions.  Decided
@@ -513,33 +1036,33 @@
 	  making this happen is something for a future release.  Therefore
 	  ... blank-compat for now.
 
-2007-03-13 07:50  donb
+2007-03-13 08:50  donb
 
 	* www/blank-master.adp: Removed more xml stuff
 
-2007-03-13 07:44  donb
+2007-03-13 08:44  donb
 
 	* www/: blank-master.adp, blank-master.tcl: More stuff related to
 	  using html transitional rather than xhtml
 
-2007-03-13 07:29  donb
+2007-03-13 08:29  donb
 
 	* www/blank-master.adp: Removed extraneous meta tag, and trailing
-	  "/" chars
+	  "/" chars
 
-2007-03-12 12:52  donb
+2007-03-12 13:52  donb
 
 	* www/: blank-master.adp, blank-master.tcl, default-master.adp:
 	  Removed some xhtml-specific stuff as requested by emma, shouldn't
 	  be there now and when we do xhtml we'll need more than that
 	  minimal stuff so - gone for now.
 
-2007-03-12 12:16  donb
+2007-03-12 13:16  donb
 
 	* www/blank-compat.tcl: Fixed one area of backwards incompatibility
 	  with this backwards compatibility master template :)
 
-2007-03-12 06:58  maltes
+2007-03-12 07:58  maltes
 
 	* etc/config.tcl: Ups. no cognovis should be there...
 
@@ -776,7 +1299,7 @@
 2007-02-21 18:19  donb
 
 	* packages/acs-subsite/www/permissions/perm-include.tcl: The
-	  default perm list didn't include the top-level perm "delete"
+	  default perm list didn't include the top-level perm "delete"
 	  (which is useful when this is called from file-storage, for
 	  instance!)
 
@@ -896,13 +1419,13 @@
 	* packages/acs-mail-lite/tcl/acs-mail-lite-callback-procs.tcl: When
 	  i added documentation blocks to these callbacks, the call back
 	  def code started complaining that the body {\n} is not empty.
-	  Replaced this with the "-" empty body marker.  Interestingly:
+	  Replaced this with the "-" empty body marker.  Interestingly:
 
 	  ad_proc -callback {	  params } { }
 
-	  apparenly does not trigger the "non-empty body" error.
+	  apparenly does not trigger the "non-empty body" error.
 	  Apparently the callback def only checks if there's a docblock
-	  passsed to ad_proc ... a "gotcha".
+	  passsed to ad_proc ... a "gotcha".
 
 2007-02-16 03:21  emmar
 
Index: openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html,v
diff -u -r1.13.2.2 -r1.13.2.3
--- openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html	22 Apr 2007 10:21:57 -0000	1.13.2.2
+++ openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html	14 Jul 2007 12:34:48 -0000	1.13.2.3
@@ -1,7 +1,6 @@
-
-OpenACS Core and .LRNPrev Chapter�16.�Releasing OpenACS  Next
OpenACS Core and .LRN
Update Translations.�Section�, “How to Update the translations”
Rebuild the Changelog.�Rebuild the Changelog.  I use a tool called cvs2cl.  Run this command from the package root to automatically generate a Changelog file  in the same dir.  We generate two changelogs, one for the minor branch and one for the most recent release.  The example below is for OpenACS 5.0.2:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
+OpenACS Core and .LRNPrev Chapter�16.�Releasing OpenACS  Next
OpenACS Core and .LRN
Update Translations.�the section called “How to Update the translations”
Rebuild the Changelog.�Rebuild the Changelog.  I use a tool called cvs2cl.  Run this command from the package root to automatically generate a Changelog file  in the same dir.  We generate two changelogs, one for the minor branch and one for the most recent release.  The example below is for OpenACS 5.0.2:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
 cvs2cl -F oacs-5-0 --delta openacs-5-0-0-final:oacs-5-0 -f ChangeLog
-cvs2cl -F oacs-5-0 --delta openacs-5-0-1-final:oacs-5-0 -f ChangeLog-recent
Update Version Numbers.�The version numbers in the documentation and in the packages must be updated.  This should only happen after a release candidate is approved.
.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree).  My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change.  This model is already broken because following it means that dotlrn-prereqs don't get new translations.Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number.
+cvs2cl -F oacs-5-0 --delta openacs-5-0-1-final:oacs-5-0 -f ChangeLog-recent
Update Version Numbers.�The version numbers in the documentation and in the packages must be updated.  This should only happen after a release candidate is approved.
.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree).  My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change.  This model is already broken because following it means that dotlrn-prereqs don't get new translations.
Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number.
             
Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
 
Regenerate all HTML docs
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml
 make
Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number
Update version number and release date in all of the
@@ -21,7 +20,7 @@
 
Tag the tree.  If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag.  (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)
cd /var/tmp/openacs-4
 cvs tag -F openacs-5-0-0a1
 cvs tag -F openacs-5-0-compat
-
Branching
When we feature-freeze on HEAD as part of the release process, we are blocking new development.  To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time.  Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze.  Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature.  To see the list of old branches, cvs status -v somefile.
cvs tag -b oacs-5-0
If doing .LRN: Since the .LRN packages aren't all in one
+
Branching
When we feature-freeze on HEAD as part of the release process, we are blocking new development.  To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time.  Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze.  Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature.  To see the list of old branches, cvs status -v somefile.
cvs tag -b oacs-5-0
If doing .LRN: Since the .LRN packages aren't all in one
           module, we iterate through all of the modules.  Log in first
           (cvs login) so that you don't have to log in for each
           module.
cd /var/tmp/dotlrn-packages
@@ -30,7 +29,7 @@
 
Note that for the compat tag we use the -F flag which will force the tag to the new version (just in 
           case someone has created the tag already on another version).  Excercise care when doing this since 
           you don't want to inadvertently move a prior release tag.  Also if the tagging goes horribly wrong 
-          for some reason you can delete the tag via "cvs tag -d <symbolic_tag>".
Apply the final tag across the tree.  First, check out the entire OpenACS tree, getting the most recent stable version of each package.  This is most simply done on openacs.org:
cd /var/tmp
+          for some reason you can delete the tag via "cvs tag -d <symbolic_tag>".
Apply the final tag across the tree.  First, check out the entire OpenACS tree, getting the most recent stable version of each package.  This is most simply done on openacs.org:
cd /var/tmp
 cvs -d /cvsroot checkout -r openacs-5-1-compat openacs-4
 cd openacs-4
 cvs tag openacs-5-1-2-final
Make the tarball(s).�
openacs-core.�
Go to a new working space and export the tagged files.
mkdir /var/tmp/tarball
@@ -81,7 +80,7 @@
 BASE=/var/tmp/release-$OACS_VERSION
 mkdir $BASE
 if [ ! -d $BASE ]; then 
-    echo "Failed creating base dir $BASE"
+    echo "Failed creating base dir $BASE"
     exit 1
 fi
 
Index: openacs-4/packages/acs-core-docs/www/releasing-openacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs.html,v
diff -u -r1.22.2.1 -r1.22.2.2
--- openacs-4/packages/acs-core-docs/www/releasing-openacs.html	14 Jan 2007 04:20:11 -0000	1.22.2.1
+++ openacs-4/packages/acs-core-docs/www/releasing-openacs.html	14 Jul 2007 12:34:48 -0000	1.22.2.2
@@ -1,2 +1 @@
-
-Chapter�16.�Releasing OpenACSPrev Part�IV.�For OpenACS Platform Developers  Next
Chapter�16.�Releasing OpenACS
Table of Contents
OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations
Prev Home  Next
External Authentication Requirements Up  OpenACS Core and .LRN
docs@openacs.org
View comments on this page at openacs.org
+Chapter�16.�Releasing OpenACSPrev Part�IV.�For OpenACS Platform Developers  Next
Chapter�16.�Releasing OpenACS
Table of Contents
OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations
Prev Home  Next
External Authentication Requirements Up  OpenACS Core and .LRN
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/releasing-package.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-package.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/releasing-package.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/releasing-package.html	14 Jul 2007 12:34:48 -0000	1.8.2.2
@@ -1,5 +1,4 @@
-
-How to package and release an OpenACS PackagePrev Chapter�16.�Releasing OpenACS  Next
How to package and release an OpenACS Package
In this example, we are packaging and releasing myfirstpackage as version 1.0.0, which is compatible with OpenACS 5.0.x.
Update the version number, release date, and package maturity of your package in the APM.
Make sure all changes are committed.
Tag the updated work.:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage
+How to package and release an OpenACS PackagePrev Chapter�16.�Releasing OpenACS  Next
How to package and release an OpenACS Package
In this example, we are packaging and releasing myfirstpackage as version 1.0.0, which is compatible with OpenACS 5.0.x.
Update the version number, release date, and package maturity of your package in the APM.
Make sure all changes are committed.
Tag the updated work.:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage
 cvs tag myfirstpackages-1-0-0-final
 cvs tag -F openacs-5-0-compat
 
Done.  The package will be added to the repository automatically.  If the correct version does not show up within 24 hours, ask for help on the OpenACS.org development forum.
Prev Home  Next
How to Update the OpenACS.org repository Up  How to Update the translations
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/remote-postgres.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/remote-postgres.html,v
diff -u -r1.7.2.1 -r1.7.2.2
--- openacs-4/packages/acs-core-docs/www/remote-postgres.html	14 Jan 2007 04:20:11 -0000	1.7.2.1
+++ openacs-4/packages/acs-core-docs/www/remote-postgres.html	14 Jul 2007 12:34:48 -0000	1.7.2.2
@@ -1,12 +1,11 @@
-
-Running a PostgreSQL database on another serverPrev Chapter�7.�Database Management  Next
Running a PostgreSQL database on another server
To run a database on a different machine than the
+Running a PostgreSQL database on another server
Prev Chapter�7.�Database Management  Next
Running a PostgreSQL database on another server
To run a database on a different machine than the
       webserver requires changes to the database configuration file
       and access control file, and to the OpenACS service's
       configuration file.
Edit the database configuration file, which in a
-      Reference install is located at /usr/local/pgsql/data/postgresql.conf
+      Reference install is located at /usr/local/pgsql/data/postgresql.conf
       and change
#tcpip_socket = false
to
tcpip_socket = true
Change the access control file for the database to
           permit specific remote clients to access.  Access can be
           controlled ... (add notes from forum post) 
Change the OpenACS service's configuration file to
           point to the remote database.  Edit
-          /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
+          /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
           and change
to 
Prev Home  Next
Chapter�7.�Database Management Up  Deleting a tablespace
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/request-processor.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/request-processor.html	22 Apr 2007 10:21:57 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/request-processor.html	14 Jul 2007 12:34:48 -0000	1.42.2.3
@@ -1,16 +1,15 @@
-
-The Request ProcessorPrev Chapter�11.�Development Reference  Next
The Request Processor
By Pete Su
+The Request ProcessorPrev Chapter�11.�Development Reference  Next
The Request Processor
By Pete Su
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Overview

-This document is a brief introduction to the OpenACS 5.3.1 Request Processor;
+        
Overview

+This document is a brief introduction to the OpenACS 5.3.2 Request Processor;
 more details can be found in the OpenACS 4 Request Processor Design. Here we cover the high level concepts behind the
 system, and implications and usage for the application developer.
-
Request Processor

-The 5.3.1 Request Processor is a global filter and set of Tcl procs that
+
Request Processor

+The 5.3.2 Request Processor is a global filter and set of Tcl procs that
 respond to every incoming URL reaching the server. The following
 diagram summarizes the stages of the request processor assuming a URL
-request like http://someserver.com/notes/somepage.adp.
+request like http://someserver.com/notes/somepage.adp.
 
 

 
@@ -24,7 +23,7 @@
 After looking up the appropriate object, the RP stores the URL, the ID
 of the object it found, and the package and package instance the
 object belongs to into the environment of the connection.  This
-environment can be queried using the ad_conn procedure,
+environment can be queried using the ad_conn procedure,
 which is described in detail in OpenACS 4 Request Processor Design. The page
 development tutorial shows you how to use this interface to make
 your pages aware of which instance was requested.
@@ -36,9 +35,9 @@
 extracts or sets up new session tokens for the user.
 
Stage 3: Authorization

 Next, the Request Processor checks if the user has appropriate access
-privileges to the requested part of the site. In OpenACS 5.3.1, access control
+privileges to the requested part of the site. In OpenACS 5.3.2, access control
 is dictated by the permissions system. In
-this case, the RP checks if the user has "read" priviledges on the
+this case, the RP checks if the user has "read" priviledges on the
 object in the site map specified by the URL. This object is typically
 a package instance, but it could easily be something more granular,
 such as whehter the user can view a particular piece of content within
@@ -47,16 +46,16 @@
 
Stage 4: URL Processing, File Search

 Finally, the Request Processor finds the file we intend to serve,
 searching the filesystem to locate the actual file that corresponds to
-an abstract URL.  It searches for files with predefined "magic"
-extensions, i.e. files that end with: .html,
-.tcl and .adp.  
+an abstract URL.  It searches for files with predefined "magic"
+extensions, i.e. files that end with: .html,
+.tcl and .adp.  
 

 If the RP can't find any matching files with the expected extensions,
-it will look for virtual-url-handler files, or .vuh
-files. A .vuh file will be executed as if it were a Tcl
+it will look for virtual-url-handler files, or .vuh
+files. A .vuh file will be executed as if it were a Tcl
 file, but with the tail end of the URL removed. This allows the code
-in the .vuh file to act like a registered procedure for
-an entire subtree of the URL namespace.  Thus a .vuh file
+in the .vuh file to act like a registered procedure for
+an entire subtree of the URL namespace.  Thus a .vuh file
 can be thought of as a replacement for filters and registered procs,
 except that they integrate cleanly and correctly with the RP's URL
 mapping mechanisms.  The details of how to use these files are
@@ -65,64 +64,64 @@
 Once the appropriate file is found, it is either served directly if
 it's static content, or sent to the template system or the standard
 Tcl interpreter if it's a dynamic page.
-
Basic API

+
Basic API

 Once the flow of control reaches a dynamic page, the Request Processor
 has populated the environment of the request with several pieces of
 useful information. The RP's environment is accessible through the
-ad_conn interface, and the following calls should be
+ad_conn interface, and the following calls should be
 useful to you when developing dynamic pages:
-
[ad_conn user_id]
+
[ad_conn user_id]
 
 

 The ID of the user associated with this request. By convention this is
 zero if there is no user.
-
[ad_conn session_id]
+
[ad_conn session_id]
 
 

 The ID of the session associated with this request.
-
[ad_conn url]
+
[ad_conn url]
 
 

 The URL associated with the request.
-
[ad_conn urlv]
+
[ad_conn urlv]
 
 

 The URL associated with the request, represented as a list instead of
 a single string.
-
[ad_conn file]
+
[ad_conn file]
 
 

 The actual local filesystem path of the file that is being served.
-
[ad_conn object_url]
+
[ad_conn object_url]
 
 

 If the URL refers to a site map object, this is the URL to the root
 of the tree where the object is mounted.
-
[ad_conn package_url]
+
[ad_conn package_url]
 
 

 If the URL refers to a package instance, this is the URL to the root
 of the tree where the package is mounted.
-
[ad_conn extra_url]
+
[ad_conn extra_url]
 
 

 If we found the URL in the site map, this is the tail of the URL
 following the part that matched a site map entry.
-
[ad_conn object_id]
+
[ad_conn object_id]
 
 

 If the URL refers to a site map object, this is the ID of that object.
-
[ad_conn package_id]
+
[ad_conn package_id]
 
 

 If the URL refers to a package instance, this is the ID of that
 package instance.
-
[ad_conn package_key]
+
[ad_conn package_key]
 
 

 If the URL refers to a package instance, this is the unique key name
 of the package.
-
[ad_conn path_info]
+
[ad_conn path_info]
 
 

 In a .vuh file, path_info is the trailing part of the URL not matched
Index: openacs-4/packages/acs-core-docs/www/requirements-template.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/requirements-template.html	22 Apr 2007 10:21:57 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/requirements-template.html	14 Jul 2007 12:34:48 -0000	1.42.2.3
@@ -1,8 +1,7 @@
-
-System/Application Requirements Template
Prev Chapter�13.�Documentation Standards  Next
System/Application Requirements Template
By You
+System/Application Requirements TemplatePrev Chapter�13.�Documentation Standards  Next
System/Application Requirements Template
By You
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Introduction

+        
Introduction

       Briefly explain to the reader what this document is for, whether
 	it records the requirements for a new system, a client application, a
 	toolkit subsystem, etc. Remember your audience: fellow programmers,
@@ -11,50 +10,50 @@
 	everywhere, write clearly and precisely; for requirements
 	documentation, write at a level that any intelligent layperson can
 	understand. 
-    
Vision Statement

+    
Vision Statement

 
 
       Very broadly, describe how the system meets a need of a business,
 	group, the OpenACS as a whole, etc.  Make sure that technical and
 	non-technical readers alike would understand what the system would do
 	and why it's useful.  Whenever applicable, you should explicitly state
 	what the business value of the system is. 
-    
System/Application Overview

+    
System/Application Overview

       Discuss the high-level breakdown of the components that make up
 	the system.  You can go by functional areas, by the main transactions
 	the system allows, etc.  
     

       You should also state the context and dependencies of the system
 	here, e.g. if it's an application-level package for OpenACS 4, briefly
 	describe how it uses kernel services, like permissions or subsites. 
-    
Use-cases and User-scenarios

+    
Use-cases and User-scenarios

       Determine the types or classes of users who would use the
 	system, and what their experience would be like at a high-level.
 	Sketch what their experience would be like and what actions they would
 	take, and how the system would support them.  
-    
Optional: Competitive Analysis

+    
Optional: Competitive Analysis

       Describe other systems or services that are comparable to what
 	you're building.  If applicable, say why your implementation will be
 	superior, where it will match the competition, and where/why it will
 	lack existing best-of-breed capabilities.  This section is also in the
 	Design doc, so write about it where you deem most appropriate.
-    
Related Links
Include all pertinent links to supporting and related material,
-      such as: 
 System/Package "coversheet" - where all documentation for this software is linked off of
 Design document
 Developer's guide
 User's guide
 Other-cool-system-related-to-this-one document
 Test plan 
 Competitive system(s)
Requirements

+    
Related Links
Include all pertinent links to supporting and related material,
+      such as: 
 System/Package "coversheet" - where all documentation for this software is linked off of
 Design document
 Developer's guide
 User's guide
 Other-cool-system-related-to-this-one document
 Test plan 
 Competitive system(s)
Requirements

       The main course of the document, requirements. Break up the
 	requirements sections (A, B, C, etc.) as needed.  Within each section,
 	create a list denominated with unique identifiers that reflect any
 	functional hierarchy present, e.g. 20.5.13. - for the first number,
 	leave generous gaps on the first writing of requirements (e.g. 1, 10,
 	20, 30, 40, etc.) because you'll want to leave room for any missing
 	key requirements that may arise.  
-    
10.0 A Common Solution

+    
10.0 A Common Solution

 	  Programmers and designers should only have to learn a single
 	  system that serves as a UI substrate for all the functionally
 	  specific modules in the toolkit. 
-	
10.0.1

+	
10.0.1

 	    The system should not make any assumptions about how pages should
 	    look or function.
-	  
10.0.5

+	  
10.0.5

 	    Publishers should be able to change the default presentation of
 	    any module using a single methodology with minimal exposure to
 	    code.
@@ -74,11 +73,11 @@
 	  suited to handle combinations of inputs.  
 Flowcharts - easy to draw and understand, suited for event and
 	  decision driven systems.  UML is the industry standard here.
 Entity-Relationship diagrams - a necessary part of Design
 	  documents, sometimes a high-level ER diagram is useful for
-	  requirements as well.
Optional: Implementation Notes

+	  requirements as well.
Optional: Implementation Notes

       Although in theory coding comes after design, which comes after
 	requirements, we do not, and perhaps should not, always follow such a
 	rigid process (a.k.a. the waterfall lifecyle).  Often, there is a
 	pre-existing system or prototype first, and thus you may want to write
 	some thoughts on implementation, for aiding and guiding yourself or
 	other programmers.  
-    
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Created 8/21/2000 Josh Finkler, Audrey McLoghlin
($Id$)
Prev Home  Next
Detailed Design Documentation Template Up  Chapter�14.�Internationalization
docs@openacs.org
View comments on this page at openacs.org
+    
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Created 8/21/2000 Josh Finkler, Audrey McLoghlin
($Id$)
Prev Home  Next
Detailed Design Documentation Template Up  Chapter�14.�Internationalization
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/rp-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v
diff -u -r1.30.2.1 -r1.30.2.2
--- openacs-4/packages/acs-core-docs/www/rp-design.html	14 Jan 2007 04:20:11 -0000	1.30.2.1
+++ openacs-4/packages/acs-core-docs/www/rp-design.html	14 Jul 2007 12:34:48 -0000	1.30.2.2
@@ -1,54 +1,53 @@
-
-Request Processor DesignPrev Chapter�15.�Kernel Documentation  Next
Request Processor Design
By Rafael H. Schloming 
+Request Processor DesignPrev Chapter�15.�Kernel Documentation  Next
Request Processor Design
By Rafael H. Schloming 
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Essentials
OpenACS 4 Request Processor Requirements

+        
Essentials
OpenACS 4 Request Processor Requirements

 /packages/acs-tcl/tcl/request-processor-procs.tcl

 /packages/acs-tcl/tcl/request-processor-init.tcl

 /packages/acs-tcl/tcl/site-nodes-procs.tcl

 /packages/acs-tcl/tcl/site-nodes-init.tcl

-/packages/acs-kernel/sql/site-nodes-create.sql
Introduction
The request processor is the set of procs that responds to every HTTP
+/packages/acs-kernel/sql/site-nodes-create.sql
Introduction
The request processor is the set of procs that responds to every HTTP
 request made to the OpenACS. The request processor must authenticate the
 connecting user, and make sure that he is authorized to perform the given
 request. If these steps succeed, then the request processor must locate the
 file that is associated with the specified URL, and serve the content it
-provides to the browser.
Related Systems
Package Manager Design
Terminology

-pageroot -- Any directory that contains scripts and/or
+provides to the browser.
Related Systems
Package Manager Design
Terminology

+pageroot -- Any directory that contains scripts and/or
 static files intended to be served in response to HTTP requests. A typical
-OpenACS installation is required to serve files from multiple pageroots.
global pageroot
-(/var/lib/aolserver/servicename/www) -- Files appearing under
+OpenACS installation is required to serve files from multiple pageroots.
global pageroot
+(/var/lib/aolserver/servicename/www) -- Files appearing under
 this pageroot will be served directly off the base url
-http://www.servicename.com/
package root
-(/var/lib/aolserver/servicename/packages) -- Each subdirectory of
+http://www.servicename.com/
package root
+(/var/lib/aolserver/servicename/packages) -- Each subdirectory of
 the package root is a package. A typical OpenACS installation will have several
-packages.
package pageroot
-(/var/lib/aolserver/servicename/packages/package_key/www)
--- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is
+packages.
package pageroot
+(/var/lib/aolserver/servicename/packages/package_key/www)
+-- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is
 a global namespace containing variables associated with the current
-request.
abstract URL -- A URL with no extension that doesn't
-directly correspond to a file in the filesystem.
abstract file or abstract path -- A URL
+request.
abstract URL -- A URL with no extension that doesn't
+directly correspond to a file in the filesystem.
abstract file or abstract path -- A URL
 that has been translated into a file system path (probably by prepending the
 appropriate pageroot), but still doesn't have any extension and so does
-not directly correspond to a file in the filesystem.
concrete file or concrete path -- A file
-or path that actually references something in the filesystem.
System Overview
Package Lookup
One of the first things the request processor must do is to determine
+not directly correspond to a file in the filesystem.
concrete file or concrete path -- A file
+or path that actually references something in the filesystem.
System Overview
Package Lookup
One of the first things the request processor must do is to determine
 which package instance a given request references, and based on this
 information, which pageroot to use when searching for a file to serve. During
 this process the request processor divides the URL into two pieces. The first
 portion identifies the package instance. The rest identifies the path into
 the package pageroot. For example if the news package is mounted on
 /offices/boston/announcements/, then a request for
 /offices/boston/announcements/index would be split into the
-package_url (/offices/boston/announcements/), and the
+package_url (/offices/boston/announcements/), and the
 abstract (no extension info) file path (index). The request processor must be
-able to figure out which package_id is associated with a
+able to figure out which package_id is associated with a
 given package_url, and package mountings must be persistent across server
 restarts and users must be able to manipulate the mountings on a live site,
-therefore this mapping is stored in the database.
Authentication and Authorization
Once the request processor has located both the package_id and concrete
+therefore this mapping is stored in the database.
Authentication and Authorization
Once the request processor has located both the package_id and concrete
 file associated with the request, authentication is performed by the session security system. After authentication has
 been performed the user is authorized to have read access for the given
 package by the OpenACS 4 Permissions Design.
 If authorization succeeds then the request is served, otherwise it is
-aborted.
Concrete File Search
To actually serve a file, the request processor generates an ordered list
+aborted.
Concrete File Search
To actually serve a file, the request processor generates an ordered list
 of abstract paths and searches each path for a concrete file. The first path
 searched is composed of the package pageroot with the extra portion of the
 URL appended. The second abstract path consists of the global pageroot with
@@ -59,22 +58,22 @@
 directory. Files take precedence over directory listings, so an index file in
 the global pageroot will be served instead of a directory listing in the
 package pageroot, even though the global pageroot is searched later. If a
-file is found at any of the searched locations then it is served.
Virtual URL Handlers
If no file is found during the concrete file search, then the request
-processor searches the filesystem for a virtual url handler
-(.vuh) file. This file contains normal tcl code, and is in
+file is found at any of the searched locations then it is served.
Virtual URL Handlers
If no file is found during the concrete file search, then the request
+processor searches the filesystem for a virtual url handler
+(.vuh) file. This file contains normal tcl code, and is in
 fact handled by the same extension handling procedure that handles .tcl
 files. The only way this file is treated differently is in how the request
 processor searches for it. When a lookup fails, the request processor
 generates each valid prefix of all the abstract paths considered in the
 concrete file search, and searches these prefixes in order from most specific
 to least specific for a matching .vuh file. If a file is found then the
-ad_conn variable path_info is set to the portion of the url
+ad_conn variable path_info is set to the portion of the url
 not matched by the .vuh script, and the script is sourced. This
 facility is intended to replace the concept of registered procs, since no
 special distinction is required between sitewide procs and package specific
 procs when using this facility. It is also much less prone to overlap and
 confusion than the use of registered procs, especially in an environment with
-many packages installed.
Site Nodes
The request processor manages the mappings from URL patterns to package
+many packages installed.
Site Nodes
The request processor manages the mappings from URL patterns to package
 instances with the site_nodes data model. Every row in the site_nodes table
 represents a fully qualified URL. A package can be mounted on any node in
 this data model. When the request processor performs a URL lookup, it
@@ -87,16 +86,16 @@
 performed by starting with the full request URI and successively stripping
 off the rightmost path components until a match is reached. This way the time
 required to lookup a URL is proportional to the length of the URL, not to the
-number of entries in the mapping.
Request Environment
The request environment is managed by the procedure
-ad_conn. Variables can be set and retrieved through use of
+number of entries in the mapping.
Request Environment
The request environment is managed by the procedure
+ad_conn. Variables can be set and retrieved through use of
 the ad_conn procedure. The following variables are available for public use.
 If the ad_conn procedure doesn't recognize a variable being passed to it
 for a lookup, it tries to get a value using ns_conn. This guarantees that
-ad_conn subsumes the functionality of ns_conn.
Request processor
[ad_conn urlv] A list containing each element of the URL
[ad_conn url] The URL associated with the request.
[ad_conn query] The portion of the URL from the ? on (i.e. GET
-              variables) associated with the request.
[ad_conn file] The filepath including filename of the file being served
[ad_conn request] The number of requests since the server was last started
[ad_conn start_clicks] The system time when the RP starts handling the request
�
Session System Variables: set in
-sec_handler, check security with ad_validate_security_info
[ad_conn session_id] The unique session_id coming from the sequence
-sec_id_seq
[ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is
-blank
[ad_conn sec_validated] This becomes "secure" when the connection uses SSL
�
Database API
[ad_conn db,handles] What are the list of handles available to AOL?
[ad_conn db,n_handles_used] How many database handles are currently used?
[ad_conn db,last_used] Which database handle did we use last?
[ad_conn db,transaction_level,$db] Specifies what transaction level we are in
[ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted
�
APM
[ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once.
-Set in apm_load_xml_packages
�
Packages
[ad_conn package_id] The package_id of the package associated with the URL.
[ad_conn package_url] The URL on which the package is mounted.
�
Miscellaneous
[ad_conn system_p] If true then the request has been made to one of the special directories
+ad_conn subsumes the functionality of ns_conn.
Request processor
[ad_conn urlv] A list containing each element of the URL
[ad_conn url] The URL associated with the request.
[ad_conn query] The portion of the URL from the ? on (i.e. GET
+              variables) associated with the request.
[ad_conn file] The filepath including filename of the file being served
[ad_conn request] The number of requests since the server was last started
[ad_conn start_clicks] The system time when the RP starts handling the request
 
Session System Variables: set in
+sec_handler, check security with ad_validate_security_info
[ad_conn session_id] The unique session_id coming from the sequence
+sec_id_seq
[ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is
+blank
[ad_conn sec_validated] This becomes "secure" when the connection uses SSL
 
Database API
[ad_conn db,handles] What are the list of handles available to AOL?
[ad_conn db,n_handles_used] How many database handles are currently used?
[ad_conn db,last_used] Which database handle did we use last?
[ad_conn db,transaction_level,$db] Specifies what transaction level we are in
[ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted
 
APM
[ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once.
+Set in apm_load_xml_packages
 
Packages
[ad_conn package_id] The package_id of the package associated with the URL.
[ad_conn package_url] The URL on which the package is mounted.
 
Miscellaneous
[ad_conn system_p] If true then the request has been made to one of the special directories
 specified in the config file (somewhere), and no authentication or
-authorization has been performed.
�
Documentation
[ad_conn api_page_documentation_mode_p] �
Prev Home  Next
Request Processor Requirements Up  Documenting Tcl Files: Page Contracts and Libraries
docs@openacs.org
View comments on this page at openacs.org
+authorization has been performed.
 
Documentation
[ad_conn api_page_documentation_mode_p] �
Prev Home  Next
Request Processor Requirements Up  Documenting Tcl Files: Page Contracts and Libraries
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v
diff -u -r1.26.2.1 -r1.26.2.2
--- openacs-4/packages/acs-core-docs/www/rp-requirements.html	14 Jan 2007 04:20:11 -0000	1.26.2.1
+++ openacs-4/packages/acs-core-docs/www/rp-requirements.html	14 Jul 2007 12:34:48 -0000	1.26.2.2
@@ -1,14 +1,13 @@
-
-Request Processor RequirementsPrev Chapter�15.�Kernel Documentation  Next
Request Processor Requirements
By Rafael H. Schloming 
+Request Processor RequirementsPrev Chapter�15.�Kernel Documentation  Next
Request Processor Requirements
By Rafael H. Schloming 
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Introduction
The following is a requirements document for the OpenACS 4.0 request
+        
Introduction
The following is a requirements document for the OpenACS 4.0 request
 processor. The major enhancements in the 4.0 version include a more
 sophisticated directory mapping system that allows package pageroots to be
 mounted at arbitrary urls, and tighter integration with the database to allow
-for flexible user controlled url structures, and subsites.
Vision Statement
Most web servers are designed to serve pages from exactly one static
+for flexible user controlled url structures, and subsites.
Vision Statement
Most web servers are designed to serve pages from exactly one static
 pageroot. This restriction can become cumbersome when trying to build a web
-toolkit full of reusable and reconfigurable components.
System Overview
The request processor's functionality can be split into two main
+toolkit full of reusable and reconfigurable components.
System Overview
The request processor's functionality can be split into two main
 pieces.
Set up the environment in which a server side script expects to run. This
 includes things like:
Initialize common variables associated with a request.
Authenticate the connecting party.
Check that the connecting party is authorized to proceed with the
 request.
Invoke any filters associated with the request URI.
Determine to which entity the request URI maps, and deliver the content
@@ -18,9 +17,9 @@
 for the connecting party. Eventually this may also require determining the
 capabilities of the connecting browser and choosing the most appropriate form
 for the delivered content.
It is essential that any errors that occur during the above steps be
-reported to developers in an easily decipherable manner.
Related Links
OpenACS 4 Request Processor Design
Requirements
10.0 Multiple Pageroots
10.10 Pageroots may be combined into one URL space.
10.20 Pageroots may be mounted at more than one location in the URL
-space.
20.0 Application Context
20.10 The request processor must be able to determine a primary context
+reported to developers in an easily decipherable manner.
Related Links
OpenACS 4 Request Processor Design
Requirements
10.0 Multiple Pageroots
10.10 Pageroots may be combined into one URL space.
10.20 Pageroots may be mounted at more than one location in the URL
+space.
20.0 Application Context
20.10 The request processor must be able to determine a primary context
 or state associated with a pageroot based on it's location within the URL
-space.
30.0 Authentication
30.10 The request processor must be able to verify that the connecting
-browser actually represents the party it claims to represent.
40.0 Authorization
40.10 The request processor must be able to verify that the party the
-connecting browser represents is allowed to make the request.
50.0 Scalability
Prev Home  Next
Security Notes Up  Request Processor Design
docs@openacs.org
View comments on this page at openacs.org
+space.
30.0 Authentication
30.10 The request processor must be able to verify that the connecting
+browser actually represents the party it claims to represent.
40.0 Authorization
40.10 The request processor must be able to verify that the party the
+connecting browser represents is allowed to make the request.
50.0 Scalability
Prev Home  Next
Security Notes Up  Request Processor Design
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/security-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v
diff -u -r1.28.2.1 -r1.28.2.2
--- openacs-4/packages/acs-core-docs/www/security-design.html	14 Jan 2007 04:20:11 -0000	1.28.2.1
+++ openacs-4/packages/acs-core-docs/www/security-design.html	14 Jul 2007 12:34:48 -0000	1.28.2.2
@@ -1,8 +1,7 @@
-
-Security DesignPrev Chapter�15.�Kernel Documentation  Next
Security Design
By Richard Li and Archit Shah
+Security DesignPrev Chapter�15.�Kernel Documentation  Next
Security Design
By Richard Li and Archit Shah
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Essentials
OpenACS 4 Security Requirements
Introduction

+        
Essentials
OpenACS 4 Security Requirements
Introduction

 This document explains security model design for OpenACS 4. The security system
 with the OpenACS core must authenticate users in both secure and insecure
 environments. In addition, this subsystem provides sessions on top of the
@@ -18,15 +17,15 @@
 
SSL with server authentication: SSL v3 
SSL provides the client with a guarantee that the server is
 actually the server it is advertised as being. It also provides a secure
 transport.
-
Design
Sessions

+
Design
Sessions

 A session is defined as a series of clicks in which no two clicks are
 separated by more than some constant. This constant is the parameter
 SessionTimeout. Using the expiration time on the signatures of the signed
 cookies, we can verify when the cookie was issued and determine if two
 requests are part of the same session. It is important to note that the
 expiration time set in the cookie protocol is not trusted. Only the time
 inserted by the signed cookie mechanism is trusted. 
-
Authentication

+
Authentication

 Two levels of access can be granted: insecure and secure. This grant lasts
 for the remainder of the particular session. Secure authentication tokens are
 only issued over secured connections. 
@@ -40,86 +39,86 @@
 password can be sniffed from the system, after which the sniffer can apply
 for a secure authentication token. However, the basic architecture here lays
 the foundation for a secure system and can be easily adapted to a more secure
-authentication system by forcing all logins to occur over HTTPS.
Details
The authentication system issues up to four signed cookies (see below),
-with each cookie serving a different purpose. These cookies are:
name value max-age secure?
ad_session_id session_id,user_id SessionTimeout no
ad_user_login user_id Infinity no
ad_user_login_secure user_id,random Infinity yes
ad_secure_token session_id,user_id,random SessionLifetime yes
ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the
+authentication system by forcing all logins to occur over HTTPS.
Details
The authentication system issues up to four signed cookies (see below),
+with each cookie serving a different purpose. These cookies are:
name value max-age secure?
ad_session_id session_id,user_id SessionTimeout no
ad_user_login user_id Infinity no
ad_user_login_secure user_id,random Infinity yes
ad_secure_token session_id,user_id,random SessionLifetime yes
ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the
 previous hit that received a cookie
is valid only for SessionTimeout seconds
is the canonical source for the session ID in ad_conn
ad_user_login
is used for permanent logins
ad_user_login_secure
is used for permanent secure logins
contains random garbage (ns_time) to prevent attack against the secure
 hash
ad_secure_token
 
is a session-level cookie from the browser's standpoint
its signature expires in SessionLifetime seconds
contains random garbage (ns_time) to prevent attack against the secure
-hash
user_id is extraneous
Authentication Process
The Tcl function (sec_handler) is called by the request
+hash
user_id is extraneous
Authentication Process
The Tcl function (sec_handler) is called by the request
 processor to authenticate the user. It first checks the
-ad_session_id cookie. If there is no valid session in progress,
-a new session is created with sec_setup_session. If the user
-has permanent login cookies (ad_user_login and
-ad_user_login_secure), then they are looked at to determine what
+ad_session_id cookie. If there is no valid session in progress,
+a new session is created with sec_setup_session. If the user
+has permanent login cookies (ad_user_login and
+ad_user_login_secure), then they are looked at to determine what
 user the session should be authorized as. Which cookie is examined is
 determined by whether or not the request is on a secure connection. If
 neither cookie is present, then a session is created without any
-authentication. If the ad_session_id cookie is valid, the
-user_id and session_id are pulled from it and put into ad_conn.
Authenticating Secure Connections
Secure connections are authenticated slightly differently. The function
-ad_secure_conn_p is used to determine whether or not the URL
+authentication. If the ad_session_id cookie is valid, the
+user_id and session_id are pulled from it and put into ad_conn.
Authenticating Secure Connections
Secure connections are authenticated slightly differently. The function
+ad_secure_conn_p is used to determine whether or not the URL
 being accessed is requires a secure login. The function simply checks if the
-location begins with "https". (This is safe because the location is
-set during the server initialization.)
If secure authentication is required, the ad_secure_token
+location begins with "https". (This is safe because the location is
+set during the server initialization.)
If secure authentication is required, the ad_secure_token
 cookie is checked to make sure its data matches the data stored in
-ad_session_id. This is true for all pages except those that are
+ad_session_id. This is true for all pages except those that are
 part of the login process. On these pages, the user can not yet have received
-the appropriate ad_secure_token cookie, so no check against it
+the appropriate ad_secure_token cookie, so no check against it
 is performed. The set of pages that skip that processing are determined by
-determined by ad_login_page. Since the
-ad_secure_token cookie is a session cookie, it is deleted by the
+determined by ad_login_page. Since the
+ad_secure_token cookie is a session cookie, it is deleted by the
 browser when the browser exits. Since an attacker could conceivably store the
 secure cookie in a replay attack (since expiration date is not validated),
 the data in the secure cookie is never used to set any data in ad_conn;
 user_id and session_id is set from the ad_session_id cookie.
It is important to note that the integrity of secure authentication rests
-on the two Tcl function ad_secure_conn_p and
-ad_login_page. If ad_secure_conn_p is false, secure
-authentication is not required. If ad_login_page is false,
-secure authentication is not required.
Login Process
The Tcl function ad_user_login does two things. First it
+on the two Tcl function ad_secure_conn_p and
+ad_login_page. If ad_secure_conn_p is false, secure
+authentication is not required. If ad_login_page is false,
+secure authentication is not required.
Login Process
The Tcl function ad_user_login does two things. First it
 performs the appropriate manipulation of the permanent login cookies, and
 then it updates the current session to reflect the new user_id. The
 manipulation of the permanent login cookies is based on 3 factors:
previous login: other user, same user
permanent: was a permanent login requested?
secure: is this a secure connection?

 Both the secure and insecure permanent login cookie can have one of three
 actions taken on it: 
-
set: cookie with no expiration is set
delete: set to "" with max age of 0, so it is expired
+
set: cookie with no expiration is set
delete: set to "" with max age of 0, so it is expired
 immediately
nothing: if the cookie is present, it remains

 The current state of the permanent login cookies is not taken into account
 when determining the appropriate action. 
-
previous login state permanent login requested secure connection action on insecure action on secure
other y y set set
same y y set set
other y n set delete
same y n set nothing
same n y nothing delete
other n y delete delete
other n n delete delete
same n n delete delete
ad_user_login
-callssec_setup_session which actually calls
-sec_generate_session_id_cookie to generate the
+
previous login state permanent login requested secure connection action on insecure action on secure
other y y set set
same y y set set
other y n set delete
same y n set nothing
same n y nothing delete
other n y delete delete
other n n delete delete
same n n delete delete
ad_user_login
+callssec_setup_session which actually calls
+sec_generate_session_id_cookie to generate the
 new cookie with refer to the appropriate user_id. If the connection is secure
-the ad_secure_token cookie is generated by a
-call to sec_generate_secure_token_cookie. This
+the ad_secure_token cookie is generated by a
+call to sec_generate_secure_token_cookie. This
 function is only called from
-sec_setup_session. Only
-sec_handler and
-sec_setup_session call
-sec_generate_session_id_cookie.
+sec_setup_session. Only
+sec_handler and
+sec_setup_session call
+sec_generate_session_id_cookie.
 
-
ad_user_logout logs the user out by deleting all 4 cookies
-that are used by the authentication system.
Session Creation
The creation and setup of sessions is handled in
-sec_setup_session, which is called either to
-create a new session from sec_handler or from
-ad_user_login when there is a change in
+
ad_user_logout logs the user out by deleting all 4 cookies
+that are used by the authentication system.
Session Creation
The creation and setup of sessions is handled in
+sec_setup_session, which is called either to
+create a new session from sec_handler or from
+ad_user_login when there is a change in
 authorization level. The session management code must do two things: insure that
 session-level data does not float between users, and update the users table
-which has columns for n_sessions,
-last_visit, and
-second_to_last_visit.
If there is no session already setup on this hit, a new session is
-created. This happens when sec_setup_session is
-called from sec_handler. If the login is from a
+which has columns for n_sessions,
+last_visit, and
+second_to_last_visit.
If there is no session already setup on this hit, a new session is
+created. This happens when sec_setup_session is
+called from sec_handler. If the login is from a
 user to another user, a new session is created, otherwise, the current session
 is continued, simply with a higher authorization state. This allows for data
 associated with a session to be carried over when a user logs in.
The users table is updated by
-sec_update_user_session_info which is called
+sec_update_user_session_info which is called
 when an existing session is assigned a non-zero user_id, or when a session is
-created with a non-zero user_id.
Passwords
ad_user_login assumes a password check has already been
+created with a non-zero user_id.
Passwords
ad_user_login assumes a password check has already been
 performed (this will change in the future). The actual check is done by
-ad_check_password. The database stores a salt and a hash of the
+ad_check_password. The database stores a salt and a hash of the
 password concatenated with the salt. Updating the password
-(ad_change_password) simply requires getting a new salt
+(ad_change_password) simply requires getting a new salt
 (ns_time) concatenating and rehashing. Both the salt and the hashed password
-field are updated.
Performance Enhancements
A session is labeled by a session_id sequence. Creating a session merely
+field are updated.
Performance Enhancements
A session is labeled by a session_id sequence. Creating a session merely
 requires incrementing the session_id sequence. We do two things to improve the
 performance of this process. First, sequence values are precomputed and cached
 in the Oracle SGA. In addition, sequence values are incremented by 100 with each
@@ -128,41 +127,41 @@
 command per thread. This minimizes lock contention for the session ID sequence
 and also minimizes the number of DB requests, since each thread can allocate 100
 sessions before requiring another DB hit.  This cache works by keeping two
-counters: tcl_max_value and
-tcl_current_sequence_id.  When
-tcl_current_sequence_id is greater than
-tcl_max_value a new value is requested from the
-db and tcl_max_value is incremented by
+counters: tcl_max_value and
+tcl_current_sequence_id.  When
+tcl_current_sequence_id is greater than
+tcl_max_value a new value is requested from the
+db and tcl_max_value is incremented by
 100. This is done on a per-thread basis so that no locking is required.
 
 
In addition, two procedures are dynamically generated at startup in
-security-init.tcl. These two procedures use
-ad_parameter to obtain the constant value of a given parameter;
+security-init.tcl. These two procedures use
+ad_parameter to obtain the constant value of a given parameter;
 these values are used to dynamically generate a procedure that returns a
 constant. This approach avoids (relatively) expensive calls to
-ad_parameter in sec_handler. The impact of this
+ad_parameter in sec_handler. The impact of this
 approach is that these parameters cannot be dynamically changed at runtime
-and require a server restart.
Session Properties

+and require a server restart.
Session Properties

 Session properties are stored in a single table that maps session IDs to
 named session properties and values. This table is periodically purged. For
 maximum performance, the table is created with nologging turned on and new
 extents are allocated in 50MB increments to reduce fragmentation. This table
-is swept periodically by sec_sweep_session which removes
+is swept periodically by sec_sweep_session which removes
 sessions whose first hit was more than SessionLifetime seconds (1 week by
 default) ago. Session properties are removed through that same process with
 cascading delete. 
-
Secure Session Properties
Session properties can be set as secure. In this case,
-ad_set_client_property will fail if the connection is not
-secure. ad_get_client_property will behave as if the property
-had not been set if the property was not set securely.
Digital Signatures & Signed Cookies

+
Secure Session Properties
Session properties can be set as secure. In this case,
+ad_set_client_property will fail if the connection is not
+secure. ad_get_client_property will behave as if the property
+had not been set if the property was not set securely.
Digital Signatures & Signed Cookies

 Signed cookies are implemented using the generic secure digital signature
 mechanism. This mechanism guarantees that the user can not tamper with (or
 construct a value of his choice) without detection. In addition, it provides
 the optional facility of timing out the signature so it is valid for only a
 certain period of time. This works by simply including an expiration time as
 part of the value that is signed. 
-
The signature produced by ad_sign is the Tcl list of
-token_id,expire_time,hash, where hash =
+
The signature produced by ad_sign is the Tcl list of
+token_id,expire_time,hash, where hash =
 SHA1(value,token_id,expire_time,secret_token). The secret_token is a forty
 character randomly generated string that is never sent to any user agent. The
 scheme consists of one table:
@@ -174,7 +173,7 @@
     token_timestamp             sysdate
 );
 
-
ad_verify_signature takes a value and a signature and
+
ad_verify_signature takes a value and a signature and
 verifies that the signature was generated using that value. It works simply
 by taking the token_id and expire_time from the signature, and regenerating
 the hash using the supplied value and the secret_token corresponding to the
@@ -186,111 +185,111 @@
 signature, RFC 2109 specifies an optional max age that is returned to the
 client. For most cookies, this max age matches the expiration date of the
 cookie's signature. The standard specifies that when the max age is not
-included, the cookie should be "discarded when the user agent
-exits." Because we can not trust the client to do this, we must specify
+included, the cookie should be "discarded when the user agent
+exits." Because we can not trust the client to do this, we must specify
 a timeout for the signature. The SessionLifetime parameter is used for this
 purpose, as it represents the maximum possible lifetime of a single
-session.
RFC 2109 specifies this optional "secure" parameter which
-mandates that the user-agent use "secure means" to contact the
+session.
RFC 2109 specifies this optional "secure" parameter which
+mandates that the user-agent use "secure means" to contact the
 server when transmitting the cookie. If a secure cookie is returned to the
 client over https, then the cookie will never be transmitted over insecure
-means.
Performance
Performance is a key goal of this implementation of signed cookies. To
+means.
Performance
Performance is a key goal of this implementation of signed cookies. To
 maximize performance, we will use the following architecture. At the lowest
-level, we will use the secret_tokens table as the canonical set
+level, we will use the secret_tokens table as the canonical set
 of secret tokens. This table is necessary for multiple servers to maintain
 the same set of secret tokens. At server startup, a random subset of these
 secret tokens will be loaded into an ns_cache called
-secret_tokens. When a new signed cookie is requested, a random
+secret_tokens. When a new signed cookie is requested, a random
 token_id is returned out of the entire set of cached token_ids. In addition,
 a thread-persistent cache called tcl_secret_tokens is maintained on a
 per-thread basis.
Thus, the L2 ns_cache functions as a server-wide LRU cache that has a
-minimum of 100 tokens in it. The cache has a dual purpose:
LRU cache Note that cache misses will only occur in the
+minimum of 100 tokens in it. The cache has a dual purpose:
LRU cache Note that cache misses will only occur in the
 multiple server case, where a user agent may have a signature guaranteed by a
-secret token issued by another server in the cluster.
signature cache Since the cache always maintains a
+secret token issued by another server in the cluster.
signature cache Since the cache always maintains a
 minimum of 100 (set by a parameter) tokens populated at startup, it can be
 used to provide a random token for signature purposes.

 The per-thread cache functions as an L1 cache that indiscriminately caches
-all secret tokens. Note that this is not an LRU cache
+all secret tokens. Note that this is not an LRU cache
 because there is no cache eviction policy per se -- the cache is cleared when
 the thread is destroyed by AOLserver. 
-
Security
Storing information on a client always presents an additional security
+
Security
Storing information on a client always presents an additional security
 risk.
Since we are only validating the information and not trying to protect it
 as a secret, we don't use salt. Cryptographic salt is useful if you are
-trying to protect information from being read (e.g., hashing passwords).
External SSL

+trying to protect information from being read (e.g., hashing passwords).
External SSL

 External SSL mechanisms (firewall, dedicated hardware, etc.) can be used by
 creating two pools of AOLservers. In one pool the servers should be
 configured with the location parameter of nssock module set to
-"https://yourservername". The servers in the other pool are
+"https://yourservername". The servers in the other pool are
 configured as normal. The external SSL agent should direct SSL queries to the
 pool of secure servers, and it should direct non-SSL queries to the insecure
 servers. 
-
PRNG

+
PRNG

 The pseudorandom number generator depends primarily on ns_rand, but is also
 seeded with ns_time and the number of page requests served since the server
 was started. The PRNG takes the SHA1(seed,ns_rand,ns_time,requests,clicks),
 and saves the first 40 bits as the seed for the next call to the PRNG in a
 thread-persistent global variable. The remaining 120 bits are rehashed to
 produce 160 bits of output. 
-
API
Login/Password

-ad_user_login user_id Logs the user in as user
+
API
Login/Password

+ad_user_login user_id Logs the user in as user
 user_id. Optional forever flag determines whether or not permanent
 cookies are issued. 
-
ad_user_logout Logs the user out.
ad_check_password user_id password
-returns 0 or 1.
ad_change_password user_id new
-password
Digital Signatures and Signed Cookies

-ad_sign value Returns the digital signature of this
+
ad_user_logout Logs the user out.
ad_check_password user_id password
+returns 0 or 1.
ad_change_password user_id new
+password
Digital Signatures and Signed Cookies

+ad_sign value Returns the digital signature of this
 value. Optional parameters allow for the specification of the secret
 used, the token_id used and the max_age for the signature.
-ad_verify_signature value signatureReturns
+ad_verify_signature value signatureReturns
 1 or 0 indicating whether or not the signature matches the value specified.
 The secret parameter allows for specification of a different secret
 token to be used. 

-ad_set_signed_cookie name data Sets a
-signed cookie name with value data. 
ad_get_signed_cookie name Gets the signed cookie
+ad_set_signed_cookie name data Sets a
+signed cookie name with value data. 
ad_get_signed_cookie name Gets the signed cookie
 name. It raises an error if the cookie has been tampered with, or if
-its expiration time has passed.
Session Properties
ad_set_client_property module name
-data Sets a session property with name to value
+its expiration time has passed.
Session Properties
ad_set_client_property module name
+data Sets a session property with name to value
 data for the module module. The optional secure flag
 specifies the property should only be set if the client is authorized for
-secure access (ad_secure_conn_p is true). There is also an optional
-session_id flag to access data from sessions other than the current one.
ad_get_client_property module name
-data Gets a session property with name to for the
+secure access (ad_secure_conn_p is true). There is also an optional
+session_id flag to access data from sessions other than the current one.
ad_get_client_property module name
+data Gets a session property with name to for the
 module module. The optional secure flag specifies the property
 should only be retrieved if the client is authorized for secure access
-(ad_secure_conn_p is true). There is also an optional
-session_id flag to access data from sessions other than the current one.
Parameters

-SessionTimeout the maximum time in seconds (default 1200)
-between requests that are part of the same session 
SessionRenew the time in seconds (default 300) between
+(ad_secure_conn_p is true). There is also an optional
+session_id flag to access data from sessions other than the current one.
Parameters

+SessionTimeout the maximum time in seconds (default 1200)
+between requests that are part of the same session 
SessionRenew the time in seconds (default 300) between
 reissue of the session cookie. The minimum time that can pass after a session
 cookie is issued and before it is rejected is (SessionTimeout -
 SessionRenew). This parameter is used so that only one session_id cookie is
 set on a single page even if there are multiple images that are being
-downloaded.
SessionLifetime the maximum possible lifetime of a
-session in seconds (default 604800 = 7 days)
NumberOfCachedSecretTokens the number of secret tokens to
-cache. (default 100)
Future Improvements
PRNG implementation

+downloaded.
SessionLifetime the maximum possible lifetime of a
+session in seconds (default 604800 = 7 days)
NumberOfCachedSecretTokens the number of secret tokens to
+cache. (default 100)
Future Improvements
PRNG implementation

 The pseudorandom number generator used in the OpenACS is cryptographically weak,
-and depends primarily on the randomness of the ns_rand function
+and depends primarily on the randomness of the ns_rand function
 for its randomness. The implementation of the PRNG could be substantially
 improved. 
-
ad_user_login

+
ad_user_login

 Add a password argument. It is non-optimal to make the default behavior to
 assume that the password was provided. 
-
Secret Tokens

+
Secret Tokens

 The secret tokens pool is currently static. Ideally, this pool should be
 changed on a random but regular basis, and the number of secret_tokens
 increased as the number of users come to the web site. 
 
Since the security of the entire system depends on the secret tokens pool,
 access to the secret tokens table should be restricted and accessible via a
 strict PL/SQL API. This can be done by revoking standard SQL permissions on
 the table for the AOLserver user and giving those permissions to a PL/SQL
-package.
Robots

+package.
Robots

 Deferring session to creation until the second hit from a browser seems to be
 a good way of preventing a lot of overhead processing for robots. If we do
 this, send cookie on first hit to test if cookies are accepted, then actually
 allocate on second hit. To preserve a record of the first hit of the session,
 just include any info about that first hit in the probe cookie sent. Look at
 how usca_p (user session cookie attempted) is used in OpenACS 3.x ecommerce. 
-
Client properties

+
Client properties

 Currently there are only session properties. Because sessions have a maximum
 life, properties have a maximum life. It would be nice to expand the
 interface to allow for more persistent properties. In the past, there was a
@@ -303,7 +302,7 @@
 can be shared between concurrent sessions). The applications should have
 control over the deletion patterns, but should not be able to ignore the
 amount of data stored. 
-
Session information

+
Session information

 It would be nice to keep some info about sessions: first hit, last hit, and
 URLs visited come to mind. Both logging and API for accessing this info would
 be nice. WimpyPoint is an application that already wants to use this
@@ -312,7 +311,7 @@
 analyzers (leaving it in server memory for applications to access). Putting
 it into the database at all is probably too big a hammer. Certainly putting
 it into the database on every hit is too big a hammer. 
-
Cookieless Sessions
Two trends drive the requirement for removing cookie dependence. WAP
+
Cookieless Sessions
Two trends drive the requirement for removing cookie dependence. WAP
 browsers that do not have cookies, and publc perceptions of cookies as an
 invasion of privacy. The rely on the cookies mechanism in HTTP to distinguish
 one request from the next, and we trust it to force requests from the same
@@ -331,21 +330,21 @@
 Both of these problems can be mitigated by doing detection of cookie support
 (see the section on robot detection). To help deal with the first problem, One
 could also make the restriction that secure sessions are only allowed over
-cookied HTTP.
Vulnerability Analysis

+cookied HTTP.
Vulnerability Analysis

 This section is not meant to be a comprehensive analysis of the
 vulnerabilities of the security system. Listed below are possible attack
 points for the system; these vulnerabilities are currently theoretical in
 nature. The major cryptographic vulnerability of the system stems from the
 pseudorandom nature of the random number generators used in the system. 
-
Cryptographically weak PRNG see
-above.
Dependence on sample
-SQL command The list of random token that are placed in the secret
+
Cryptographically weak PRNG see
+above.
Dependence on sample
+SQL command The list of random token that are placed in the secret
 tokens cache is randomly chosen by the Oracle
-sample command. This command may not be
+sample command. This command may not be
 entirely random, so predicting the contents of the secret tokens cache may not
-be as difficult as someone may anticipate.
Dependence on
-ns_rand The actual token that is
+be as difficult as someone may anticipate.
Dependence on
+ns_rand The actual token that is
 chosen from the cache to be used is chosen by a call to
-ns_rand.
ad_secure_conn_p
+ns_rand.
ad_secure_conn_p
 As discussed above, the security of the secure sessions authentication system is
 dependent upon this function.
Prev Home  Next
Security Requirements Up  Security Notes
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/security-notes.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/security-notes.html	22 Apr 2007 10:21:57 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/security-notes.html	14 Jul 2007 12:34:48 -0000	1.42.2.3
@@ -1,12 +1,11 @@
-
-Security NotesPrev Chapter�15.�Kernel Documentation  Next
Security Notes
By Richard Li
+Security NotesPrev Chapter�15.�Kernel Documentation  Next
Security Notes
By Richard Li
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         

 The security system was designed for security. Thus, decisions requiring
 trade-offs between ease-of-use and security tend to result in a system that
 may not be as easy to use but is more secure. 
-
HTTPS and the sessions system

+
HTTPS and the sessions system

 
 If a user switches to HTTPS after logging into the system via HTTP, the user
 must obtain a secure token. To insure security, the only way to
@@ -21,21 +20,21 @@
 issues a secure token, the method of authentication must be as strong as the
 method of transmission.
If a developer truly does not want such a level of protection, this system
 can be disabled via source code modification only. This can be accomplished
-by commenting out the following lines in the sec_handler
-procedure defined in security-procs.tcl:
+by commenting out the following lines in the sec_handler
+procedure defined in security-procs.tcl:
 
     if { [ad_secure_conn_p] && ![ad_login_page] } {
-        set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]]
+        set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]]
         
         if { [empty_string_p $s_token_cookie] || [string compare $s_token_cookie [lindex [sec_get_session_info $session_id] 2]] != 0 } {
         # token is incorrect or nonexistent, so we force relogin.
-        ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]"
+        ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]"
         }
     }
 
 
The source code must also be edited if the user login pages have been
 moved out of an OpenACS system. This information is contained by the
-ad_login_page procedure in security-procs.tcl:
+ad_login_page procedure in security-procs.tcl:
 
 ad_proc -private ad_login_page {} {
     
@@ -44,7 +43,7 @@
 } {
 
     set url [ad_conn url]
-    if { [string match "*register/*" $url] || [string match "/index*" $url] } {
+    if { [string match "*register/*" $url] || [string match "/index*" $url] } {
     return 1
     }
 
@@ -54,5 +53,5 @@
 

 The set of string match expressions in the procedure above should be extended
 appropriately for other registration pages. This procedure does not use
-ad_parameter or regular expressions for performance reasons, as
+ad_parameter or regular expressions for performance reasons, as
 it is called by the request processor. 
($Id$)
Prev Home  Next
Security Design Up  Request Processor Requirements
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/security-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v
diff -u -r1.28.2.1 -r1.28.2.2
--- openacs-4/packages/acs-core-docs/www/security-requirements.html	14 Jan 2007 04:20:11 -0000	1.28.2.1
+++ openacs-4/packages/acs-core-docs/www/security-requirements.html	14 Jul 2007 12:34:48 -0000	1.28.2.2
@@ -1,47 +1,46 @@
-
-Security RequirementsPrev Chapter�15.�Kernel Documentation  Next
Security Requirements
By Richard Li
+Security RequirementsPrev Chapter�15.�Kernel Documentation  Next
Security Requirements
By Richard Li
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Introduction

+        
Introduction

 This document lists the requirements for the security system for the OpenACS. 
-
Vision Statement

+
Vision Statement

 Virtually all web sites support personalized content based on user identity.
 The level of personalization may be as simple as displaying the name of the
 user on certain pages or can be as sophisticated as dynamically recommending
 sections of site that the user may be interested in based on prior browsing
 history. In any case, the user's identity must be validated and made
 available to the rest of the system. In addition, sites such as ecommerce
 vendors require that the user identity be securely validated. 
-
Security System Overview

+
Security System Overview

 The security system consists of a number of subsystems. 
-
Signed Cookies

+
Signed Cookies

 Cookies play a key role in storing user information. However, since they are
 stored in plaintext on a user's system, the validity of cookies is an
 important issue in trusting cookie information. Thus, we want to be able to
 validate a cookie, but we also want to validate the cookie without a database
 hit. 
-
10.0 Guaranteed Tamper Detection Any tampering of cookie
-data should be easily detectable by the web server.
10.1 Performance and Scalability Validation and
+
10.0 Guaranteed Tamper Detection Any tampering of cookie
+data should be easily detectable by the web server.
10.1 Performance and Scalability Validation and
 verification of the cookie should be easily scalable and should not require a
-database query on every hit.
Session Properties

+database query on every hit.
Session Properties

 Applications should be able to store session-level properties in a database
 table. 
-
11.0 Storage API Session-level data should be accessible
-via an API.
11.1 Purge Mechanism An efficient pruning mechanism
+
11.0 Storage API Session-level data should be accessible
+via an API.
11.1 Purge Mechanism An efficient pruning mechanism
 should be used to prevent old session level properties from filling up the
-table.
Login

+table.
Login

 The security system should support the concept of persistent user logins.
 This persistence takes several forms. 
-
12.0 Permanent Login Users should be able to maintain a
-permanent user login so that they never need to type their password.
12.1 Session Login The security system should support
+
12.0 Permanent Login Users should be able to maintain a
+permanent user login so that they never need to type their password.
12.1 Session Login The security system should support
 the concept of a session, with authentication tokens that become invalid
-after a certain period of time.
12.2 Session Definition A session is a sequence of
+after a certain period of time.
12.2 Session Definition A session is a sequence of
 clicks by one user from one browser in which no two clicks are separated by
-more than some constant (the session timeout).
12.3 Stateless The security system should not require
+more than some constant (the session timeout).
12.3 Stateless The security system should not require
 state that is stored in the server. Required state may reside only in the
 user request (including cookies), and in the database. A single user should
 be able to log in to the system even if the user is sent to a different
-AOLserver for each step of the login process (e.g., by a load balancer).
12.4 Secure The security system should not store
-passwords in clear text in the database.
13.0 SSL Hardware The system must work when the SSL
+AOLserver for each step of the login process (e.g., by a load balancer).
12.4 Secure The security system should not store
+passwords in clear text in the database.
13.0 SSL Hardware The system must work when the SSL
 processing occurs outside of the web server (in specialized hardware, in a
 firewall, etc.).
Prev Home  Next
OpenACS Internationalization Requirements Up  Security Design
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/snapshot-backup.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/snapshot-backup.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/snapshot-backup.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/snapshot-backup.html	14 Jul 2007 12:34:48 -0000	1.8.2.2
@@ -1,5 +1,4 @@
-
-Manual backup and recoveryPrev Chapter�8.�Backup and Recovery  Next
Manual backup and recovery
This section describes how to make a one-time backup and
+Manual backup and recovery
Prev Chapter�8.�Backup and Recovery  Next
Manual backup and recovery
This section describes how to make a one-time backup and
     restore of the files and database.  This is useful for rolling
     back to known-good versions of a service, such as at initial
     installation and just before an upgrade.  First, you back up the
@@ -8,28 +7,28 @@
     including the AOLserver config files, is then in tree for regular
     file system backup.
Back up the database to a file.�
Oracle.�
 
               Download the backup script. Save the file export-oracle.txt as
-              /var/tmp/export-oracle.txt
+              /var/tmp/export-oracle.txt
               

               Login as root. The following commands will install the export script:
-              
[joeuser ~]$ su -
-[root ~]# cp /var/tmp/export-oracle.txt /usr/sbin/export-oracle
-[root ~]# chmod 700 /usr/sbin/export-oracle

+              
[joeuser ~]$ su -
+[root ~]# cp /var/tmp/export-oracle.txt /usr/sbin/export-oracle
+[root ~]# chmod 700 /usr/sbin/export-oracle

               Setup the export directory; this is the directory where backups will
               be stored. We recommend the directory
-              /ora8/m02/oracle-exports.
[root ~]# mkdir /ora8/m02/oracle-exports
-[root ~]# chown oracle:dba /ora8/m02/oracle-exports
-[root ~]# chmod 770 /ora8/m02/oracle-exports
 
+              /ora8/m02/oracle-exports.
[root ~]# mkdir /ora8/m02/oracle-exports
+[root ~]# chown oracle:dba /ora8/m02/oracle-exports
+[root ~]# chmod 770 /ora8/m02/oracle-exports
 
               Now edit
-              /usr/sbin/export-oracle and
-              change the SERVICE_NAME and
-              DATABASE_PASSWORD fields to
+              /usr/sbin/export-oracle and
+              change the SERVICE_NAME and
+              DATABASE_PASSWORD fields to
               their correct values. If you want to use a directory other than
-              /ora8/m02/oracle-exports, you
+              /ora8/m02/oracle-exports, you
               also need to change the
-              exportdir setting.
+              exportdir setting.
               

                 Test the export procedure by running the command:
-              
[root ~]# /usr/sbin/export-oracle
+              
[root ~]# /usr/sbin/export-oracle
 mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory
 
 Export: Release 8.1.6.1.0 - Production on Sun Jun 11 18:07:45 2000
@@ -64,70 +63,70 @@
   . exporting dimensions
   . exporting post-schema procedural objects and actions
   . exporting statistics
-Export terminated successfully without warnings.
PostgreSQL.�Create a backup file and verify that it was created and has a reasonable size (several megabytes).
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp 
+Export terminated successfully without warnings.
PostgreSQL.�Create a backup file and verify that it was created and has a reasonable size (several megabytes).
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp 
 -rw-rw-r-x    1 $OPENACS_SERVICE_NAME  $OPENACS_SERVICE_NAME   4005995 Feb 21 18:28 /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
 [root root]#
 su - $OPENACS_SERVICE_NAME
 pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp openacs-dev
 ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp
 exit
Back up the file system.�Back up all of the files in the service, including the
           database backup file but excluding the auto-generated
-          supervise directory, which is
-          unneccesary and has complicated permissions.  
In the tar command,
c create a
-            new tar archive
p preserves permissions.
s preserves file sort order
z compresses the output with gzip.
The --exclude clauses skips some daemontools files that
+          supervise directory, which is
+          unneccesary and has complicated permissions.  
In the tar command,
c create a
+            new tar archive
p preserves permissions.
s preserves file sort order
z compresses the output with gzip.
The --exclude clauses skips some daemontools files that
             are owned by root and thus cannot be backed up by the
             service owner.  These files are autogenerated and we don't
-            break anything by omitting them.
The --file clause
+            break anything by omitting them.
The --file clause
             specifies the name of the output file to be generated; we
             manually add the correct extensions.
The last clause,
-            /var/lib/aolserver/$OPENACS_SERVICE_NAME/,
+            /var/lib/aolserver/$OPENACS_SERVICE_NAME/,
             specifies the starting point for backup.  Tar defaults to
-            recursive backup.
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ tar -cpsz --exclude /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/supervise \
-   --file /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz /var/lib/aolserver/$OPENACS_SERVICE_NAME/
+            recursive backup.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ tar -cpsz --exclude /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/supervise \
+   --file /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz /var/lib/aolserver/$OPENACS_SERVICE_NAME/
 tar: Removing leading `/' from member names
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Suffer a catastrophic failure on your production system.�(We'll simulate this step)
[root root]# svc -d /service/$OPENACS_SERVICE_NAME
-[root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost
-[root root]# rm /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Suffer a catastrophic failure on your production system.�(We'll simulate this step)
[root root]# svc -d /service/$OPENACS_SERVICE_NAME
+[root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost
+[root root]# rm /service/$OPENACS_SERVICE_NAME
 rm: remove symbolic link `/service/$OPENACS_SERVICE_NAME'? y
-[root root]# ps -auxw | grep $OPENACS_SERVICE_NAME
+[root root]# ps -auxw | grep $OPENACS_SERVICE_NAME
 root      1496  0.0  0.0  1312  252 ?        S    16:58   0:00 supervise $OPENACS_SERVICE_NAME
-[root root]# kill 1496
-[root root]# ps -auxw | grep $OPENACS_SERVICE_NAME
-[root root]# su - postgres
-[postgres pgsql]$ dropdb $OPENACS_SERVICE_NAME
+[root root]# kill 1496
+[root root]# ps -auxw | grep $OPENACS_SERVICE_NAME
+[root root]# su - postgres
+[postgres pgsql]$ dropdb $OPENACS_SERVICE_NAME
 DROP DATABASE
-[postgres pgsql]$ dropuser $OPENACS_SERVICE_NAME
+[postgres pgsql]$ dropuser $OPENACS_SERVICE_NAME
 DROP USER
-[postgres pgsql]$ exit
+[postgres pgsql]$ exit
 logout
 [root root]#
Recovery.�
Restore the operating system and required software.
             You can do this with standard backup processes or by
             keeping copies of the install material (OS CDs, OpenACS
             tarball and supporting software) and repeating the install
-            guide.  Recreate the service user ($OPENACS_SERVICE_NAME).
Restore the OpenACS files and database backup file.
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver
-[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz
-[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.web $OPENACS_SERVICE_NAME
Restore the database
Oracle.�
Set up a clean Oracle database user and
-                    tablespace with the same names as the ones exported from (more information).
Invoke the import command
imp $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAME FILE=/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/nighty_backup.dmp FULL=Y
Postgres.�If the database user does not already exist, create it.
[root root]# su - postgres
-[postgres ~]$ createuser $OPENACS_SERVICE_NAME
-Shall the new user be allowed to create databases? (y/n) y
-Shall the new user be allowed to create more new users? (y/n) y
+            guide.  Recreate the service user ($OPENACS_SERVICE_NAME).
Restore the OpenACS files and database backup file.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver
+[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz
+[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.web $OPENACS_SERVICE_NAME
Restore the database
Oracle.�
Set up a clean Oracle database user and
+                    tablespace with the same names as the ones exported from (more information).
Invoke the import command
imp $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAME FILE=/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/nighty_backup.dmp FULL=Y
Postgres.�If the database user does not already exist, create it.
[root root]# su - postgres
+[postgres ~]$ createuser $OPENACS_SERVICE_NAME
+Shall the new user be allowed to create databases? (y/n) y
+Shall the new user be allowed to create more new users? (y/n) y
 CREATE USER
-[postgres ~]$ exit
-
Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order.  In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects.  Next, restore the database from the dump file.  The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored.
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME ~]$ createdb $OPENACS_SERVICE_NAME
+[postgres ~]$ exit
+
Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order.  In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects.  Next, restore the database from the dump file.  The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME ~]$ createdb $OPENACS_SERVICE_NAME
 CREATE DATABASE
-[$OPENACS_SERVICE_NAME ~]$ psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/postgresql.sql $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME ~]$ psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/postgresql.sql $OPENACS_SERVICE_NAME
 (many lines omitted)
-[$OPENACS_SERVICE_NAME ~]$ psql $OPENACS_SERVICE_NAME < /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/database-backup.dmp
+[$OPENACS_SERVICE_NAME ~]$ psql $OPENACS_SERVICE_NAME < /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/database-backup.dmp
 (many lines omitted)
-[$OPENACS_SERVICE_NAME ~]$ exit
-[postgres ~]$ exit
-logout
Activate the service
[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools /service/$OPENACS_SERVICE_NAME
-[root root]# sleep 10
-[root root]# svgroup web /service/$OPENACS_SERVICE_NAME
Prev Home  Next
Backup Strategy Up  Automated Backup
docs@openacs.org
View comments on this page at openacs.org
+[$OPENACS_SERVICE_NAME ~]$ exit
+[postgres ~]$ exit
+logout
Activate the service
[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools /service/$OPENACS_SERVICE_NAME
+[root root]# sleep 10
+[root root]# svgroup web /service/$OPENACS_SERVICE_NAME
Prev Home  Next
Backup Strategy Up  Automated Backup
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/style-guide.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/style-guide.html,v
diff -u -r1.21.2.2 -r1.21.2.3
--- openacs-4/packages/acs-core-docs/www/style-guide.html	22 Apr 2007 10:21:57 -0000	1.21.2.2
+++ openacs-4/packages/acs-core-docs/www/style-guide.html	14 Jul 2007 12:34:48 -0000	1.21.2.3
@@ -1,9 +1,6 @@
-
-OpenACS Style GuidePrev Chapter�12.�Engineering Standards  Next
OpenACS Style Guide

+OpenACS Style Guide
Prev Chapter�12.�Engineering Standards  Next
OpenACS Style Guide

     By Jeff Davis
-  
Motivation

+  
Motivation

       Why have coding standards for OpenACS?  And if the code works why change it to
       adhere to some arbitrary rules?
     

@@ -12,7 +9,7 @@
       lines of tcl code, about 460,000 lines of sql (in datamodel
       scripts and .xql files), about 80,000 lines of markup in .adp
       files, and about 100,000 lines of documentation.  All told, just
-      about a million lines of "stuff".  In terms of logical units
+      about a million lines of "stuff".  In terms of logical units
       there are about 160 packages, 800 tables, 2,000 stored
       procedures, about 2,000 functional pages, and about 3,200 tcl
       procedures.
@@ -28,7 +25,7 @@
       over a long period by a lot of different people, OpenACS 
       sometimes lacks this basic guessability and in the interest 
       of bringing it into line we have advanced these guidelines.
-    
Commandments

+    
Commandments

       Here is a short list of the basic rules code contributed to 
       OpenACS should follow...
     
Follow the file naming and the package structure rules.�
@@ -75,8 +72,8 @@
             toolkit more useful for everyone and more easily extended.
           
Make sure your datamodel create/drop scripts work.�
             Break the table creation out from the package/stored
-            procedure creation and use create or
-            replace where possible so that scripts
+            procedure creation and use create or
+            replace where possible so that scripts
             can be sourced more than once.  Make sure your drop script
             works if data has been inserted (and permissioned and
             notifications have been attached etc).
@@ -90,6 +87,6 @@
         
Solicit code reviews.�
             Ask others to look over your code and provide feedback and do 
             the same for others.  
-          
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 12/2003 Jeff Davis
($Id$)
Prev Home  Next
Chapter�12.�Engineering Standards Up  
+          
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 12/2003 Jeff Davis
($Id$)
Prev Home  Next
Chapter�12.�Engineering Standards Up  
     CVS Guidelines
   
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/subsites-design.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v
diff -u -r1.28.2.1 -r1.28.2.2
--- openacs-4/packages/acs-core-docs/www/subsites-design.html	14 Jan 2007 04:20:11 -0000	1.28.2.1
+++ openacs-4/packages/acs-core-docs/www/subsites-design.html	14 Jul 2007 12:34:48 -0000	1.28.2.2
@@ -1,10 +1,9 @@
-
-Subsites Design DocumentPrev Chapter�15.�Kernel Documentation  Next
Subsites Design Document
By Rafael H. Schloming 
+Subsites Design DocumentPrev Chapter�15.�Kernel Documentation  Next
Subsites Design Document
By Rafael H. Schloming 
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
*Note* This document has not gone through the any of the
 required QA process yet. It is being tagged as stable due to high
-demand.
Essentials
OpenACS 4 Subsites Requirements
Introduction
An OpenACS 4 subsite is a managed suite of applications that work together for
+demand.
Essentials
OpenACS 4 Subsites Requirements
Introduction
An OpenACS 4 subsite is a managed suite of applications that work together for
 a particular user community. This definition covers a very broad range of
 requirements: from a Geocities style homepage where a user can install
 whatever available application he wants (e.g. a single user could have their
@@ -17,35 +16,35 @@
 the Request Processor. Since the design and implementation directly
 associated with subsites is actually minimal, a discussion of subsites design
 is, in fact, a discussion of how core OpenACS 4 components implicitly support
-subsites as a whole.
Historical Considerations
The subsites problem actually has several quite diverse origins. It was
+subsites as a whole.
Historical Considerations
The subsites problem actually has several quite diverse origins. It was
 originally recognized as a toolkit feature in the form of
-"scoping". The basic concept behind scoping was to allow one scoped
+"scoping". The basic concept behind scoping was to allow one scoped
 OpenACS installation to behave as multiple unscoped OpenACS installations so that one
 OpenACS install could serve multiple communities. Each piece of application data
-was tagged with a "scope" consisting of the (user_id, group_id,
+was tagged with a "scope" consisting of the (user_id, group_id,
 scope) triple. In practice the highly denormalized data models that this
 method uses produced large amounts of very redundant code and in general made
-it an extremely cumbersome process to "scopify" a module.
Before the advent of scoping there were several cases of client projects
+it an extremely cumbersome process to "scopify" a module.
Before the advent of scoping there were several cases of client projects
 implementing their own version of scoping in special cases. One example being
 the wineaccess multi-retailer ecommerce. (Remember the other examples and get
 details. Archnet?, iluvcamp?)
The requirements of all these different projects vary greatly, but the one
 consistent theme among all of them is the concept that various areas of the
 web site have their own private version of a module. Because this theme is so
 dominant, this is the primary problem that the OpenACS4 implementation of
-subsites addresses.
Competitive Analysis
...
Design Tradeoffs
The current implementation of package instances and subsites allows
+subsites addresses.
Competitive Analysis
...
Design Tradeoffs
The current implementation of package instances and subsites allows
 extremely flexible URL configurations. This has the benefit of allowing
 multiple instances of the same package to be installed in one subsite, but
 can potentially complicate the process of integrating packages with each
 other since it is likely people will want packages that live at non standard
 URLs to operate together. This requirement would cause some packages to have
 more configuration options than normal since hard-coding the URLs would not
-be feasible anymore.
API
This section will cover all the APIs relevant to subsites, and so will
-consist of portions of the APIs of several systems.
Packages
The following package is provided for instantiation of packages. The
+be feasible anymore.
API
This section will cover all the APIs relevant to subsites, and so will
+consist of portions of the APIs of several systems.
Packages
The following package is provided for instantiation of packages. The
 apm_package.new function can be used to create a package of any type known to
 the system. The apm_package_types table can be queried for a list of
 installed packages. (See APM docs for more detail XXX: insert link here)
 
-create or replace package apm_package
+create or replace package apm_package
 as
 
   function new (
@@ -98,9 +97,9 @@
 end apm_package;
 /
 show errors
-
+
 
-
Site Nodes
This data model keeps track of what packages are being served from what
+
Site Nodes
This data model keeps track of what packages are being served from what
 URLs. You can think of this as a kind of rp_register_directory_map on drugs.
 This table represents a fully hierarchical site map. The directory_p column
 indicates whether or not the node is a leaf node. The pattern_p column
@@ -110,7 +109,7 @@
 node URL. The object_id column contains the object mounted on the URL
 represented by the node. In most cases this will be a package instance.
 
-create table site_nodes (
+create table site_nodes (
     node_id     constraint site_nodes_node_id_fk
             references acs_objects (object_id)
             constraint site_nodes_node_id_pk
@@ -134,11 +133,11 @@
     object_id   constraint site_nodes_object_id_fk
             references acs_objects (object_id)
 );
-
+
 
 
The following package is provided for creating nodes.
 
-create or replace package site_node
+create or replace package site_node
 as
 
   -- Create a new site node. If you set directory_p to be 'f' then you
@@ -179,34 +178,34 @@
 end;
 /
 show errors
-
+
 
-
Request Processor
Once the above APIs are used to create packages and mount them on a
+
Request Processor
Once the above APIs are used to create packages and mount them on a
 specific site node, the following request processor APIs can be used to allow
 the package to serve content appropriate to the package instance.
 
-[ad_conn node_id]
+[ad_conn node_id]
 [ad_conn package_id]
 [ad_conn package_url]
-
+
 
-
Data Model Discussion
The subsites implementation doesn't really have it's own data
+
Data Model Discussion
The subsites implementation doesn't really have it's own data
 model, although it depends heavily on the site-nodes data model, and the APM
-data model.
User Interface
The primary elements of the subsite user interface consist of the subsite
+data model.
User Interface
The primary elements of the subsite user interface consist of the subsite
 admin pages. These pages are divided up into two areas: Group administration,
 and the site map. The group administration pages allow a subsite
 administrator to create and modify groups. The site map pages allow a subsite
 administrator to install, remove, configure, and control access to packages.
 The site map interface is the primary point of entry for most of the things a
-subsite administrator would want to do.
Configuration/Parameters
...
Future Improvements/Areas of Likely Change
The current subsites implementation addresses the most basic functionality
+subsite administrator would want to do.
Configuration/Parameters
...
Future Improvements/Areas of Likely Change
The current subsites implementation addresses the most basic functionality
 required for subsites. It is likely that as developers begin to use the
 subsites system for more sophisticated projects, it will become necessary to
 develop tools to help build tightly integrated packages. The general area
-this falls under is "inter-package communication". An actual
+this falls under is "inter-package communication". An actual
 implementation of this could be anything from clever use of configuration
 parameters to lots of package level introspection. Another area that is
-currently underdeveloped is the ability to "tar up" and distribute
+currently underdeveloped is the ability to "tar up" and distribute
 a particular configuration of site nodes/packages. As we build more
 fundamental applications that can be applied in more general areas, this
 feature will become more and more in demand since more problems will be
-solvable by configuration instead of coding.
Authors
rhs@mit.edu
Prev Home  Next
Subsites Requirements Up  Package Manager Requirements
docs@openacs.org
View comments on this page at openacs.org
+solvable by configuration instead of coding.
Authors
rhs@mit.edu
Prev Home  Next
Subsites Requirements Up  Package Manager Requirements
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v
diff -u -r1.27.2.1 -r1.27.2.2
--- openacs-4/packages/acs-core-docs/www/subsites-requirements.html	14 Jan 2007 04:20:11 -0000	1.27.2.1
+++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html	14 Jul 2007 12:34:48 -0000	1.27.2.2
@@ -1,31 +1,30 @@
-
-Subsites RequirementsPrev Chapter�15.�Kernel Documentation  Next
Subsites Requirements
By Rafael H. Schloming and Dennis Gregorovic
+Subsites RequirementsPrev Chapter�15.�Kernel Documentation  Next
Subsites Requirements
By Rafael H. Schloming and Dennis Gregorovic
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Introduction
The following is a requirements document for OpenACS 4 Subsites, part of the
+        
Introduction
The following is a requirements document for OpenACS 4 Subsites, part of the
 OpenACS 4 Kernel. The Subsites system allows one OpenACS server instance to serve
 multiple user communities, by enabling the suite of available OpenACS
-applications to be customized for defined user communities.
Vision Statement
Many online communities are also collections of discrete subcommunities,
+applications to be customized for defined user communities.
Vision Statement
Many online communities are also collections of discrete subcommunities,
 reflecting real-world relationships. For example, a corporate
 intranet/extranet website serves both units within the company (e.g.,
 offices, departments, teams, projects) and external parties (e.g., customers,
 partners, vendors). Subsites enable a single OpenACS instance to provide each
-subcommunity with its own "virtual website," by assembling OpenACS
+subcommunity with its own "virtual website," by assembling OpenACS
 packages that together deliver a feature set tailored to the needs of the
-subcommunity.
System Overview
The OpenACS subsite system allows a single OpenACS installation to serve multiple
+subcommunity.
System Overview
The OpenACS subsite system allows a single OpenACS installation to serve multiple
 communities. At an implementation level this is primarily accomplished by
-having an application "scope" its content to a particular package
+having an application "scope" its content to a particular package
 instance. The request
 processor then figures out which package_id a particular URL references
-and then provides this information through the ad_conn api ([ad_conn
-package_id], [ad_conn package_url]).
The other piece of the subsite system is a subsite package that provides
-subsite admins a "control panel" for administering their subsite.
+and then provides this information through the ad_conn api ([ad_conn
+package_id], [ad_conn package_url]).
The other piece of the subsite system is a subsite package that provides
+subsite admins a "control panel" for administering their subsite.
 This is the same package used to provide all the community core functionality
-available at the "main" site which is in fact simply another
-subsite.
Use-cases and User-scenarios
The Subsites functionality is intended for use by two different classes of
+available at the "main" site which is in fact simply another
+subsite.
Use-cases and User-scenarios
The Subsites functionality is intended for use by two different classes of
 users:
Package programmers (referred to as 'the programmer') must
 develop subcommunity-aware applications.
Site administrators (referred to as 'the administrator') use
-subsites to provide tailored "virtual websites" to different
+subsites to provide tailored "virtual websites" to different
 subcommunities.
Joe Programmer is working on the forum package and wants to make it
 subsite-aware. Using [ad_conn package_id], Joe adds code that only displays
 forum messages associated with the current package instance. Joe is happy to
@@ -40,18 +39,18 @@
 http://www.company.com/offices/boston/forum, and similarly for the Austin
 office. At this point, the Boston and Austin office admins can customize the
 configurations for each of their forums, or they can just use the
-defaults.
Related Links
OpenACS 4 Subsites Design Document
Test plan (Not available yet)
Requirements: Programmer's API
A subsite API is required for programmers to ensure their packages are
-subsite-aware. The following functions should be sufficient for this:
10.10.0 Package creation
The system must provide an API call to create a package, and it must be
-possible for the context (to which the package belongs) to be specified.
10.20.0 Package deletion
The system must provide an API call to delete a package and all related
-objects in the subsite's context.
10.30.0 Object's package information
Given an object ID, the system must provide an API call to determine the
-package (ID) to which the object belongs.
10.40.0 URL from package
Given a package (ID), the system must provide an API call to return the
-canonical URL for that package.
10.50.0 Main subsite's package_id
The system must provide an API call to return a package ID corresponding
-to the main subsite's package ID (the degenerate subsite).
Requirements: The User Interface
The Programmer's User Interface
There is no programmer's UI, other than the API described above.
The Administrator's User Interface
The UI for administrators is a set of HTML pages that are used to drive
+defaults.
Related Links
OpenACS 4 Subsites Design Document
Test plan (Not available yet)
Requirements: Programmer's API
A subsite API is required for programmers to ensure their packages are
+subsite-aware. The following functions should be sufficient for this:
10.10.0 Package creation
The system must provide an API call to create a package, and it must be
+possible for the context (to which the package belongs) to be specified.
10.20.0 Package deletion
The system must provide an API call to delete a package and all related
+objects in the subsite's context.
10.30.0 Object's package information
Given an object ID, the system must provide an API call to determine the
+package (ID) to which the object belongs.
10.40.0 URL from package
Given a package (ID), the system must provide an API call to return the
+canonical URL for that package.
10.50.0 Main subsite's package_id
The system must provide an API call to return a package ID corresponding
+to the main subsite's package ID (the degenerate subsite).
Requirements: The User Interface
The Programmer's User Interface
There is no programmer's UI, other than the API described above.
The Administrator's User Interface
The UI for administrators is a set of HTML pages that are used to drive
 the underlying API for package instance management (i.e. adding, removing, or
 altering packages). It is restricted to administrators of the current subsite
 such that administrators can only manage their own subsites. Of course,
-Site-Wide Administrators can manage all subsites.
20.10.0 Package creation
20.10.1 The administrator should be able to create a
-package and make it available at a URL underneath the subsite.
20.20.0 Package deactivation
20.20.1 The administrator should be able to deactivate
-any package, causing it to be inaccessible to users.
20.20.5 Deactivating a package makes the package no
+Site-Wide Administrators can manage all subsites.
20.10.0 Package creation
20.10.1 The administrator should be able to create a
+package and make it available at a URL underneath the subsite.
20.20.0 Package deactivation
20.20.1 The administrator should be able to deactivate
+any package, causing it to be inaccessible to users.
20.20.5 Deactivating a package makes the package no
 longer accessible, but it does not remove data created within the context of
-that package.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/18/2000 Dennis Gregorovic
0.2 Edited, reviewed 08/29/2000 Kai Wu
Prev Home  Next
Groups Design Up  Subsites Design Document
docs@openacs.org
View comments on this page at openacs.org
+that package.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/18/2000 Dennis Gregorovic
0.2 Edited, reviewed 08/29/2000 Kai Wu
Prev Home  Next
Groups Design Up  Subsites Design Document
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/subsites.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/subsites.html	22 Apr 2007 10:21:57 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/subsites.html	14 Jul 2007 12:34:48 -0000	1.42.2.3
@@ -1,8 +1,7 @@
-
-Writing OpenACS Application PagesPrev Chapter�11.�Development Reference  Next
Writing OpenACS Application Pages
By Rafael H. Schloming and Pete Su
+Writing OpenACS Application PagesPrev Chapter�11.�Development Reference  Next
Writing OpenACS Application Pages
By Rafael H. Schloming and Pete Su
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Overview

+        
Overview

 In this document, we'll examine the user interface pages of the Notes
 application in more detail, covering two separate aspects of page
 development in OpenACS. First, we'll talk about the code needed to make
@@ -11,7 +10,7 @@
 form-based user interfaces in OpenACS. While these seem like unrelated
 topics, they both come up in the example page that we are going to
 look at, so it makes sense to address them at the same time.
-
Application Instances and Subsites

+
Application Instances and Subsites

 As you will recall from the packages tutorial, the Request
 Processor (RP) and Package Manager (APM) allow site
 administrators to define an arbitrary mapping from URLs in the site to
@@ -22,63 +21,63 @@
 particular URL.  The tutorial also showed how a given URL is
 translated into a physical file to serve using the site map. We'll
 repeat this description here, assuming that you have mounted an
-instance of Notes at the URL /notes as we did in the packages-example:
+instance of Notes at the URL /notes as we did in the packages-example:
 

-AOLserver receives your request for the URL /notes/somepage.
+AOLserver receives your request for the URL /notes/somepage.
 

 This URL is passed to the request processor.
 

 The RP looks up the URL in the site map, and sees that the object
-mounted at that location is an instance of the notes
+mounted at that location is an instance of the notes
 application. 
 

 The RP asks the package manager where in the file system the Notes
 package lives. In the standard case, this would be
-ROOT/packages/notes.
+ROOT/packages/notes.
 

 The RP translates the URL to serve a page relative to the page root of
 the application, which is
-ROOT/packages/notes/www/. Therefore, the page that is
-finally served is ROOT/packages/notes/www/hello.html,
+ROOT/packages/notes/www/. Therefore, the page that is
+finally served is ROOT/packages/notes/www/hello.html,
 which is what we wanted.
 

 What is missing from this description is a critical fact for
 application developers: In addition to working out what file to serve,
 the RP also stores information about which package instance the file
 belongs to into the AOLserver connection environment. The following
-ad_conn interfaces can be used to extract this
+ad_conn interfaces can be used to extract this
 information:
-
[ad_conn package_url]

+
[ad_conn package_url]

 If the URL refers to a package instance, this is the URL to the root
 of the tree where the package is mounted.
-
[ad_conn package_id]

+
[ad_conn package_id]

 If the URL refers to a package instance, this is the ID of that
 package instance.
-
[ad_conn package_key]
+
[ad_conn package_key]
 
 

 If the URL refers to a package instance, this is the unique key name
 of the package.
-
[ad_conn extra_url]
+
[ad_conn extra_url]
 
 

 If we found the URL in the site map, this is the tail of the URL
 following the part that matched a site map entry.
 

 In the Notes example, we are particularly interested in the
-package_id field.  If you study the data model and code,
+package_id field.  If you study the data model and code,
 you'll see why. As we said before in the data modeling tutorial, the Notes application points the
-context_id of each Note object that it creates to the
-package instance that created it. That is, the context_id
-corresponds exactly to the package_id that comes in from
+context_id of each Note object that it creates to the
+package instance that created it. That is, the context_id
+corresponds exactly to the package_id that comes in from
 the RP. This is convenient because it allows the administrator and the
 owner of the package to easily define access control policies for all
 the notes in a particular instance just my setting permissions on the
 package instance itself.
 

 The code for adding and editing notes, in
-notes/www/add-edit.tcl, shows how this works. At the top
-of the page, we extract the package_id and use it to do
+notes/www/add-edit.tcl, shows how this works. At the top
+of the page, we extract the package_id and use it to do
 permission checks:
 
 
@@ -87,11 +86,11 @@
 if {[info exists note_id]} {
       permission::require_permission -object_id $note_id -privilege write
 
-      set context_bar [ad_context_bar "Edit Note"]
+      set context_bar [ad_context_bar "Edit Note"]
 } else {
       permission::require_permission -object_id $note_id -privilege create
 
-      set context_bar [ad_context_bar "New Note"]
+      set context_bar [ad_context_bar "New Note"]
 }
 
 

@@ -100,7 +99,7 @@
 for each action.
 

 Later, when we actually create a note, the SQL that we run ensures
-that the context_id is set the right way:
+that the context_id is set the right way:
 
 
 db_dml new_note {
@@ -124,25 +123,25 @@
 without generating a lot of duplicated HTML in your pages. It also
 encapsulates most of the common logic that we use in dealing with
 forms, which we'll discuss next.
-
Using Forms

+
Using Forms

 The forms API is pretty simple: You use calls in the
-template::form namespace in your Tcl script to create
+template::form namespace in your Tcl script to create
 form elements. The final template page then picks this stuff up and
 lays the form out for the user. The form is set up to route submit
 buttons and whatnot back to the same Tcl script that set up the
 form, so your Tcl script will also contain the logic needed to process
 these requests.
 

 So, given this outline, here is a breakdown of how the forms code
-works in the add-edit.tcl page. First, we create a form object
-called new_note:
+works in the add-edit.tcl page. First, we create a form object
+called new_note:
 
 
 template::form create new_note
 
 

 All the forms related code in this page will refer back to this
-object. In addition, the adp part of this page does
+object. In addition, the adp part of this page does
 nothing but display the form object:
 
 
@@ -153,7 +152,7 @@
 <hr>
 
 <center>
-<formtemplate id="new_note"></formtemplate>
+<formtemplate id="new_note"></formtemplate>
 </center>
 
 

@@ -176,9 +175,9 @@
 }
 
 

-The if_request call returns true if we are asking the
+The if_request call returns true if we are asking the
 page to render the form for the first time. That is, we are rendering
-the form to ask the user for input. The tcl part of a
+the form to ask the user for input. The tcl part of a
 form page can be called in 3 different states: the initial request,
 the initial submission, and the validated submission. These states
 reflect the typical logic of a forms based page in OpenACS:
@@ -191,16 +190,16 @@
 Finally, control passes to the page that performs the update in the
 database.
 

-The rest of the if condition figures out if we are
+The rest of the if condition figures out if we are
 creating a new note or editing an existing note. If
-note_id is passed to us from the calling page, we assume
+note_id is passed to us from the calling page, we assume
 that we are editing an existing note. In this case, we do a database
 query to grab the data for the note so we can populate the form with
 it.
 

 The next two calls create form elements where the user can insert or
 edit the title and body of the Note. The interface to
-template::element is pretty straightforward.
+template::element is pretty straightforward.
 

 Finally, the code at the bottom of the page performs the actual
 database updates when the form is submitted and validated:
@@ -234,7 +233,7 @@
     }
   }
 
-  ad_returnredirect "."
+  ad_returnredirect "."
 }
 
 

@@ -243,7 +242,7 @@
 the HTML rendering, input validation and database transaction logic on
 your behalf. This means that you can write pages without duplicating
 all of that code in every set of pages that uses forms.
-
How it All Fits

+
How it All Fits

 To watch all of this work, use the installer to update the Notes
 package with the new code that you grabbed out of CVS or the package
 repository, mount an instance of Notes somewhere in your server and
@@ -254,15 +253,15 @@
 visible to that user. The end result is a site where users can come
 and write notes to themselves.
 

-This is a good example of the leverage available in the OpenACS 5.3.1
+This is a good example of the leverage available in the OpenACS 5.3.2
 system. The code that we have written for Notes is not at all more
 complex than a similar application without access control or site map
 awareness. By adding a small amount of code, we have taken a small,
 simple, and special purpose application to something that has the
 potential to be a very useful, general-purpose tool, complete with
 multi-user features, access control, and centralized administration.
-
Summary

-In OpenACS 5.3.1, application pages and scripts can be aware of the package
+
Summary

+In OpenACS 5.3.2, application pages and scripts can be aware of the package
 instance, or subsite in which they are executing. This is a powerful
 general purpose mechanism that can be used to structure web services
 in very flexible ways.
Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v
diff -u -r1.43.2.2 -r1.43.2.3
--- openacs-4/packages/acs-core-docs/www/tcl-doc.html	22 Apr 2007 10:21:57 -0000	1.43.2.2
+++ openacs-4/packages/acs-core-docs/www/tcl-doc.html	14 Jul 2007 12:34:48 -0000	1.43.2.3
@@ -1,8 +1,7 @@
-
-Documenting Tcl Files: Page Contracts and Libraries
Prev Chapter�15.�Kernel Documentation  Next
Documenting Tcl Files: Page Contracts and Libraries
By Jon Salz on 3 July 2000 
+Documenting Tcl Files: Page Contracts and LibrariesPrev Chapter�15.�Kernel Documentation  Next
Documenting Tcl Files: Page Contracts and Libraries
By Jon Salz on 3 July 2000 
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl
The Big Picture
In versions of the OpenACS prior to 3.4, the standard
+        
Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl
The Big Picture
In versions of the OpenACS prior to 3.4, the standard
 place to document Tcl files (both Tcl pages and Tcl library files) was in
 a comment at the top of the file:
 #
@@ -16,44 +15,44 @@
 #
 

 In addition, the inputs expected by a Tcl page (i.e., form variables) would
-be enumerated in a call to ad_page_variables, in effect,
+be enumerated in a call to ad_page_variables, in effect,
 documenting the page's argument list. 
 
The problem with these practices is that the documentation is only
 accessible by reading the source file itself. For this reason, ACS 3.4
 introduces a new API for documenting Tcl files and, on top of that, a
-web-based user interface for browsing the documentation:
ad_page_contract: Every Tcl page
-has a contract that explicitly defines what inputs the page
-expects (with more precision than ad_page_variables) and
+web-based user interface for browsing the documentation:
ad_page_contract: Every Tcl page
+has a contract that explicitly defines what inputs the page
+expects (with more precision than ad_page_variables) and
 incorporates metadata about the page (what used to live in the top-of-page
-comment). Like ad_page_variables, ad_page_contract
-also sets the specified variables in the context of the Tcl page.
ad_library: To be
+comment). Like ad_page_variables, ad_page_contract
+also sets the specified variables in the context of the Tcl page.
ad_library: To be
 called at the top of every library file (i.e., all files in the
-/tcl/ directory under the server root and
-*-procs.tcl files under /packages/).

+/tcl/ directory under the server root and
+*-procs.tcl files under /packages/).

 This has the following benefits: 
 
Facilitates automatic generation of human-readable documentation.
Promotes security, by introducing a standard and automated way to check
 inputs to scripts for correctness.
Allows graphical designers to determine easily how to customize
 sites' UIs, e.g., what properties are available in templates.
Allows the request processor to be intelligent: a script can specify in
 its contract which type of abstract document it
 returns, and the request processor can transform it automatically into
 something useful to a particular user agent. (Don't worry about this for
-now - it's not complete for ACS 3.4.)
ad_page_contract

-Currently ad_page_contract serves mostly as a replacement for
-ad_page_variables. Eventually, it will be integrated closely
+now - it's not complete for ACS 3.4.)
ad_page_contract

+Currently ad_page_contract serves mostly as a replacement for
+ad_page_variables. Eventually, it will be integrated closely
 with the documents API so that each script's contract will document
 precisely the set of properties available to graphical designers in
 templates. (Document API integration is subject to change, so we don't
 decsribe it here yet; for now, you can just consider
-ad_page_contract a newer, better, documented
-ad_page_variables.) 
-
Let's look at an example usage of ad_page_contract:
+ad_page_contract a newer, better, documented
+ad_page_variables.) 
+
Let's look at an example usage of ad_page_contract:
 
 # /packages/acs-kernel/api-doc/www/package-view.tcl
 ad_page_contract {
     version_id:integer
     public_p:optional
     kind
-    { format "html" }
+    { format "html" }
 } {
     Shows APIs for a particular package.
 
@@ -71,83 +70,83 @@
 
 

 Note that: 
-
By convention, ad_page_contract should be preceded
-by a comment line containing the file's path. The comment is on
+
By convention, ad_page_contract should be preceded
+by a comment line containing the file's path. The comment is on
 line 1, and the contract starts on line 2.
-
ad_page_contract's first argument is
-the list of expected arguments from the HTTP query (version_id,
-public_p, kind, and format). Like
-ad_page_variables, ad_page_contract sets the
+
ad_page_contract's first argument is
+the list of expected arguments from the HTTP query (version_id,
+public_p, kind, and format). Like
+ad_page_variables, ad_page_contract sets the
 corresponding Tcl variables when the page is executed.
-
Arguments can have defaults, specified using the same
-syntax as in the Tcl proc (a two-element list where the first
+
Arguments can have defaults, specified using the same
+syntax as in the Tcl proc (a two-element list where the first
 element is the parameter name and the second argument is the default value).
 
-
Arguments can have flags, specified by following the
+
Arguments can have flags, specified by following the
 name of the query argument with a colon and one or more of the following
-strings (separated by commas): 
optional: the query argument doesn't
+strings (separated by commas): 
optional: the query argument doesn't
 need to be provided; if it's not, the variable for that argument simply
 won't be set. For instance, if I call the script above without a
-public_p in the query, then in the page body [info exists
-public_p] will return 0.
-
integer: the argument must be an integer
-(ad_page_contract will fail and display and error if not). This
+public_p in the query, then in the page body [info exists
+public_p] will return 0.
+
integer: the argument must be an integer
+(ad_page_contract will fail and display and error if not). This
 flag, like the next, is intended to prevent clients from fudging query
 arguments to trick scripts into executing arbitrary SQL. 
 
-
sql_identifier: the argument must be a SQL
-identifier (i.e., [string is wordchar $the_query_var] must
+
sql_identifier: the argument must be a SQL
+identifier (i.e., [string is wordchar $the_query_var] must
 return true). 
 
-
trim: the argument will be [string
+
trim: the argument will be [string
 trim]'ed. 
 
-
multiple: the argument may be specified
+
multiple: the argument may be specified
 arbitrarily many times in the query string, and the variable will be set to a
 list of all those values (or an empty list if it's unspecified). This is
-analogous to the -multiple-list flag to
-ad_page_variables, and is useful for handling form input
-generated by <SELECT MULTIPLE> tags and checkboxes. 
For instance, if dest_user_id:multiple is specified in the
+analogous to the -multiple-list flag to
+ad_page_variables, and is useful for handling form input
+generated by <SELECT MULTIPLE> tags and checkboxes. 
For instance, if dest_user_id:multiple is specified in the
 contract, and the query string is
 
 ?dest_user_id=913&dest_user_id=891&dest_user_id=9
 
 

-then $dest_user_id is set to [list 913 891 9].
+then $dest_user_id is set to [list 913 891 9].
 
 
-
array: the argument may be specified
+
array: the argument may be specified
 arbitrarily many times in the query string, with parameter names with
-suffixes like _1, _2, _3, etc. The
+suffixes like _1, _2, _3, etc. The
 variable is set to a list of all those values (or an empty list if none are
-specified). 
For instance, if dest_user_id:array is specified in the
+specified). 
For instance, if dest_user_id:array is specified in the
 contract, and the query string is
 
 ?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9
 
 

-then $dest_user_id is set to [list 913 891 9].
You can provide structured, HTML-formatted documentation for your
-contract. Note that format is derived heavily from Javadoc: a
+then $dest_user_id is set to [list 913 891 9].
You can provide structured, HTML-formatted documentation for your
+contract. Note that format is derived heavily from Javadoc: a
 general description of the script's functionality, followed optionally by
-a series of named attributes tagged by at symbols (@). You are
+a series of named attributes tagged by at symbols (@). You are
 encouraged to provide: 
 
A description of the functionality of the page. If the description
 contains more than one sentence, the first sentence should be a brief
 summary. 
 
-
A @param tag for each allowable query
+
A @param tag for each allowable query
 argument. The format is 
 
 @param parameter-name description...
 
-
An @author tag for each author. Specify the
-author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the
-script was first created.
A @cvs-id tag containing the page's CVS
-identification string. Just use $Id: tcl-documentation.html,v 1.2
-2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
+
An @author tag for each author. Specify the
+author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the
+script was first created.
A @cvs-id tag containing the page's CVS
+identification string. Just use $Id: tcl-documentation.html,v 1.2
+2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
 substitute an appropriate string when you check the file in.

- These @ tags are optional, but highly recommended!
ad_library

-ad_library provides a replacement for the informal documentation
+ These @ tags are optional, but highly recommended!
ad_library

+ad_library provides a replacement for the informal documentation
 (described above) found at the beginning of every Tcl page. Instead of: 
 
 
@@ -178,11 +177,11 @@
 

 Note that format is derived heavily from Javadoc: a general description of
 the script's functionality, followed optionally by a series of named
-attributes tagged by at symbols (@). HTML formatting is allowed.
+attributes tagged by at symbols (@). HTML formatting is allowed.
 You are encouraged to provide: 
-
An @author tag for each author. Specify the
-author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the
-script was first created.
A @cvs-id tag containing the page's CVS
-identification string. Just use $Id: tcl-documentation.html,v 1.2
-2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
+
An @author tag for each author. Specify the
+author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the
+script was first created.
A @cvs-id tag containing the page's CVS
+identification string. Just use $Id: tcl-documentation.html,v 1.2
+2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
 substitute an appropriate string when you check the file in.
($Id$)
Prev Home  Next
Request Processor Design Up  Bootstrapping OpenACS
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/templates.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/templates.html	22 Apr 2007 10:21:57 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/templates.html	14 Jul 2007 12:34:48 -0000	1.42.2.3
@@ -1,8 +1,7 @@
-
-Using Templates in OpenACSPrev Chapter�11.�Development Reference  Next
Using Templates in OpenACS
By Pete Su
+Using Templates in OpenACSPrev Chapter�11.�Development Reference  Next
Using Templates in OpenACS
By Pete Su
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Overview

+        
Overview

 The OpenACS Template System (ATS) is designed to allow developers to
 cleanly separate application logic from display
 logic. The intent is to have all of the logic related to
@@ -13,12 +12,12 @@
 graphic designers to work more independently.
 

 In ATS, you write two files for every user-visible page in the
-system. One is a plain .tcl file and the other is a
-special .adp file. The .tcl file runs a
+system. One is a plain .tcl file and the other is a
+special .adp file. The .tcl file runs a
 script that sets up a set of name/value bindings that we call data
 sources. These data sources are generally the results of Tcl and/or database queries
 or some combination thereof. The template system automatically makes
-them available to the .adp file, or the display part of
+them available to the .adp file, or the display part of
 the template, which is written in a combination of HTML, special
 template related tags, and data source substitutions.
 

@@ -29,7 +28,7 @@
 actually add notes to the database, how to provide a separate instance
 of the Notes application to every user and how to design appropriate
 access control policies for the system.
-
Entering Notes

+
Entering Notes

 In order for the Notes application to be useful, we have to allow
 users to enter data into the database. Typically, this takes two
 pages: one that displays a form for data entry, and another page that
@@ -39,10 +38,10 @@
 the system since we won't be displaying much data, but we'll cover
 more on that end later.
 

-The .tcl file for the form entry template is pretty
+The .tcl file for the form entry template is pretty
 simple. Here, the only thing we need from the database is a new ID for
 the note object to be inserted. Open up a file called
-note-add.tcl in the ROOT/packages/notes/www
+note-add.tcl in the ROOT/packages/notes/www
 directory, and put the following code in it:
 
 
@@ -69,74 +68,74 @@
     where forum_id = :user_id
 }
 
-set page_title "Add a note for $user_name"
-set submit_label "Add"
-set target "note-add-2"
+set page_title "Add a note for $user_name"
+set submit_label "Add"
+set target "note-add-2"
 set note_id [db_nextval acs_object_id_seq]
 
-ad_return_template "note-add"
+ad_return_template "note-add"
 
 

 Some things to note about this code:
 

 The procedure ad_page_contract is
-always the first thing a .tcl file calls, if it's under
+always the first thing a .tcl file calls, if it's under
 the www/ directory (i.e. not a Tcl library file). It does validation
 of input values from the HTTP request (i.e. form variables) and in
-this case, the -properties clause is used to set up the
-data sources that we will ship over to the .adp part of
+this case, the -properties clause is used to set up the
+data sources that we will ship over to the .adp part of
 the page. In this case, we only use the simplest possible kind of data
-source, called a onevalue, which hold just a single
+source, called a onevalue, which hold just a single
 string value.  Later on, we'll see how to use more powerful kinds of
 data sources for representing multiple rows from an SQL query.  You
 also include overall documentation for the page in the contract, and
 OpenACS has automatic tools that extract this documentation and make it
 browsable.
 

-After being declared in the ad_page_contract, each
+After being declared in the ad_page_contract, each
 property is just a simple Tcl variable. The template system passes the
-final value of the variable to the .adp template when the
-.tcl file is processed.
+final value of the variable to the .adp template when the
+.tcl file is processed.
 

-The call ad_return_template tells the template system
-what .adp template page to fetch to display the
+The call ad_return_template tells the template system
+what .adp template page to fetch to display the
 properties that have been processed. By default, the template system
-will look for a file by the same name as the .tcl file
-that just ran, but with an .adp extension.
+will look for a file by the same name as the .tcl file
+that just ran, but with an .adp extension.
 

-Next we write the corresponding .adp page. This page
+Next we write the corresponding .adp page. This page
 outputs HTML for the form, and also contains placeholders whose values
-are substituted in from the properties set up by the .tcl
-file.  Create a file called note-add.adp in your editor,
+are substituted in from the properties set up by the .tcl
+file.  Create a file called note-add.adp in your editor,
 and insert this text:
 
 
-<master src="master">
-<property name="title">@page_title@</property>
-<property name="context_bar">@context_bar@</property>
+<master src="master">
+<property name="title">@page_title@</property>
+<property name="context_bar">@context_bar@</property>
 
 <form action=@target@>
 <p>Title: 
-<input type="text" name="title" value="">
+<input type="text" name="title" value="">
 </p>
 <p>Body: 
-<input type="text" name="title" value="">
+<input type="text" name="title" value="">
 </p>
 <p>
 <center>
-<input type=submit value="@submit_label@">
+<input type=submit value="@submit_label@">
 </center>
 </p>
 </form>
 
 

 The main point to note here is: when you want to substitute a value
-into a page, you put the name of the data source between two "@"
+into a page, you put the name of the data source between two "@"
 characters. Another point to note is the use of a master template:
 Master templates allow you do centralize display code that is used
 throughout an application in a single file. In this case, we intend to
 have a master template that does the standard page headers and footers
-for us - create the master.adp file, which looks like
+for us - create the master.adp file, which looks like
 this:
 
 
@@ -145,29 +144,29 @@
 <%= [eval ad_context_bar $context_bar] %> 
 <hr> 
 <slave> 
-<br clear="all"> 
+<br clear="all"> 
 <%= [ad_footer] %>
 
 

 The main subtlety in this code is the inline Tcl code for running
 procs to build the header, footer, context bar, etc.  Also, note the
 property substitutions that happen here, the values of which are set
-up in the <property> tags in the slave page.  
+up in the <property> tags in the slave page.  
 

 After putting all these files into
-ROOT/packages/notes/www, you should be able to go to
-/notes/ URL for your server and see the input form.
-
Summary

+ROOT/packages/notes/www, you should be able to go to
+/notes/ URL for your server and see the input form.
+
Summary

 Templates separate application logic from display logic by requiring
 the developer to write pages in two stages, one file for database
 queries and application logic, and another for display. In OpenACS, the
-logic part of the page is just a .tcl that sets up
+logic part of the page is just a .tcl that sets up
 data sources that are used by the display part of the page. The
-display part of the page is an .adp file with some
+display part of the page is an .adp file with some
 special tags and notations for dealing with display logic and
 inserting properties into the text of the page. Later on we'll get
 into templates more deeply, and show how to use database queries as
 data sources.
-
Documentation

+
Documentation

 Templating system documentation
 
($Id$)
Prev Home  Next
The OpenACS Database Access API Up  Groups, Context, Permissions
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html	14 Jul 2007 12:34:48 -0000	1.8.2.2
@@ -1,5 +1,4 @@
-
-Admin PagesPrev Chapter�10.�Advanced Topics  Next
Admin Pages

+Admin Pages
Prev Chapter�10.�Advanced Topics  Next
Admin Pages

      There are at least two flavors of admin user interface:
      
Admins use same pages as all other users, except
        that they are offered admin links and buttons where appropriate.
@@ -10,24 +9,24 @@
        access to data that users aren't interested in or aren't allowed
        to see you will need dedicated admin pages.  The conventional
        place to put those dedicated admin pages is in the
- /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin
+ /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin
  directory.
-      
[$OPENACS_SERVICE_NAME www]$ mkdir admin
[$OPENACS_SERVICE_NAME www]$ cd admin

+      
[$OPENACS_SERVICE_NAME www]$ mkdir admin
[$OPENACS_SERVICE_NAME www]$ cd admin

       Even if your application doesn't need any admin pages of its own you will
       usually need at least one simple page with a bunch of links to existing
       administration UI such as Category Management or standard Parameters UI.
       Adding the link to Category Management is described in the section on
       categories.  The listing below adds a link to the Parameters UI of our
       package.
-      
[$OPENACS_SERVICE_NAME admin]$ vi index.adp
+      
[$OPENACS_SERVICE_NAME admin]$ vi index.adp
 <master>
-<property name="title">@title;noquote@</property>
-<property name="context">@context;noquote@</property>
+<property name="title">@title;noquote@</property>
+<property name="context">@context;noquote@</property>
 
-<ul class="action-links">
-  <li><a href="@parameters_url@" title="Set parameters" class="action_link">Set parameters</a></li>
+<ul class="action-links">
+  <li><a href="@parameters_url@" title="Set parameters" class="action_link">Set parameters</a></li>
 </ul>
-
[$OPENACS_SERVICE_NAME admin]$ vi index.tcl
+
[$OPENACS_SERVICE_NAME admin]$ vi index.tcl
 ad_page_contract {} {
 } -properties {
     context_bar
@@ -41,25 +40,25 @@
 
 set context [list]
 
-set title "Administration"
+set title "Administration"
 
-set parameters_url [export_vars -base "/shared/parameters" {
+set parameters_url [export_vars -base "/shared/parameters" {
   package_id { return_url [ad_return_url] }
 }]
 
 

 Now that you have the first admin page it would be nice to have a link to it
 somewhere in the system so that admins don't have to type in the
-/admin every time they need to reach it.  You
+/admin every time they need to reach it.  You
 could put a static link to the toplevel
-index.adp but that might be distracting for
+index.adp but that might be distracting for
 people who are not admins.  Besides, some people consider it impolite to first
-offer a link and then display a nasty "You don't have permission to access this
-page" message.
+offer a link and then display a nasty "You don't have permission to access this
+page" message.
 

 In order to display the link to the admin page only to users that have admin
 privileges add the following code near the top of
-/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl:
+/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl:
 
 
 set package_id [ad_conn package_id]
@@ -68,14 +67,14 @@
   -privilege admin -party_id [ad_conn untrusted_user_id]]
 
 if { $admin_p } {
-    set admin_url "admin"
+    set admin_url "admin"
     set admin_title Administration
 }
 

 In 
-/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp put:
+/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp put:
 
 <if @admin_p@ ne nil>
-  <a href="@admin_url@">@admin_title@</a>
+  <a href="@admin_url@">@admin_title@</a>
 </if>
 
Prev Home  Next
Adding Comments Up  Categories
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.html,v
diff -u -r1.29.2.1 -r1.29.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	14 Jan 2007 04:20:11 -0000	1.29.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html	14 Jul 2007 12:34:48 -0000	1.29.2.2
@@ -1,5 +1,4 @@
-
-Chapter�10.�Advanced TopicsPrev Part�III.�For OpenACS Package Developers  Next
Chapter�10.�Advanced Topics
Table of Contents
Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics
by Joel Aufrecht
+Chapter�10.�Advanced TopicsPrev Part�III.�For OpenACS Package Developers  Next
Chapter�10.�Advanced Topics
Table of Contents
Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
This tutorial covers topics which are not essential to
Index: openacs-4/packages/acs-core-docs/www/tutorial-caching.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-caching.html,v
diff -u -r1.5.2.1 -r1.5.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-caching.html	14 Jan 2007 04:20:11 -0000	1.5.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-caching.html	14 Jul 2007 12:34:48 -0000	1.5.2.2
@@ -1,8 +1,7 @@
-
-Basic Caching
Prev Chapter�10.�Advanced Topics  Next
Basic Caching
Based on a post by Dave Bauer.
+Basic CachingPrev Chapter�10.�Advanced Topics  Next
Basic Caching
Based on a post by Dave Bauer.
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Implement your proc as my_proc_not_cached
Create a version of your proc called my_proc which wraps the non-cached version in the caching mechanism.  In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on.  The wrapper also uses the list command, to ensure that the arguments get passed correctly and to prevent commands passed in as arguments from being executed.
ad_proc my_proc {-foo} {
+        
Implement your proc as my_proc_not_cached
Create a version of your proc called my_proc which wraps the non-cached version in the caching mechanism.  In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on.  The wrapper also uses the list command, to ensure that the arguments get passed correctly and to prevent commands passed in as arguments from being executed.
ad_proc my_proc {-foo} {
         Get a cached version of my_proc.
 } {
     return [util_memoize [list my_proc_not_cached -foo $foo]]
Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-categories.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-categories.html	14 Jul 2007 12:34:48 -0000	1.8.2.2
@@ -1,13 +1,12 @@
-
-CategoriesPrev Chapter�10.�Advanced Topics  Next
Categories
extended by Nima Mazloumi
+CategoriesPrev Chapter�10.�Advanced Topics  Next
Categories
extended by Nima Mazloumi
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
You can associate any ACS Object with one or more categories.
     In this tutorial we'll show how to equip your application with user
     interface to take advantage of the Categories service.
     

     We'll start by installing the Categories service.  Go to
-    /acs/admin and install it.  This step
+    /acs/admin and install it.  This step
     won't be necessary for the users of your applications because you'll create
     a dependency with the Package Manager which will take care that the
     Categories service always gets installed when your application gets
@@ -29,39 +28,39 @@
           

           The way to achieve this is is to provide a link
           to the Category Management pages.  Add the following snippet to your
-            /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl
+            /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl
           file:
           
-		  set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }]
+		  set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }]
           

           and the following snippet to your
-            /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp
+            /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp
           file:
           
-   			<a href="@category_map_url@"<#categories.Site_wide_Categories#</a>
-          
The link created by the above code (category_map_url) 
+   			<a href="@category_map_url@"<#categories.Site_wide_Categories#</a>
+          
The link created by the above code (category_map_url) 
           will take the admin to the generic
           admin UI where he can pick category trees that make sense for this
           application.  The same UI also includes facilities to build and edit
           category trees.  Notice that the only parameter in this example is
-          package_id so that category trees
+          package_id so that category trees
           will be associated with the object identified by this
-          package_id.  The categorization
+          package_id.  The categorization
           service is actually more general than that: instead of
-          package_id you could use an ID of
-          some other object that serves as a "container" in your application.
+          package_id you could use an ID of
+          some other object that serves as a "container" in your application.
           For example, if your discussion forums application supports multiple
-          forums you would use forum_id to
+          forums you would use forum_id to
           associate category trees with just that one forum rather than the
           entire application instance.
         

           Once the category trees have been selected users need a way
           to categorize items.  The easiest way to do this is by adding the
-          category widget type of the
-          form builder to note-edit.tcl.
-          To achieve this we'll need to use the -extend
-          switch to the ad_form command. Here's the "meat" of the
-          note-edit.tcl page:
+          category widget type of the
+          form builder to note-edit.tcl.
+          To achieve this we'll need to use the -extend
+          switch to the ad_form command. Here's the "meat" of the
+          note-edit.tcl page:
 			    #extend the form to support categories
 			    set package_id [ad_conn package_id]
 			    
@@ -72,117 +71,117 @@
     			} -new_data {
     				....
 					category::map_object -remove_old -object_id $item_id $category_ids
-            		db_dml insert_asc_named_object "insert into acs_named_objects (object_id, object_name, package_id) values ( :item_id, :title, :package_id)"
+            		db_dml insert_asc_named_object "insert into acs_named_objects (object_id, object_name, package_id) values ( :item_id, :title, :package_id)"
 	    		} -edit_data {
             		....
-        			db_dml update_asc_named_object "update acs_named_objects set object_name = :title, package_id = :package_id where object_id = :item_id"
+        			db_dml update_asc_named_object "update acs_named_objects set object_name = :title, package_id = :package_id where object_id = :item_id"
         			category::map_object -remove_old -object_id $item_id $category_ids
     			} -after_submit {
-        				ad_returnredirect "."
+        				ad_returnredirect "."
         				ad_script_abort
     			}
-			
While the category::ad_form::add_widgets proc is taking 
+			
While the category::ad_form::add_widgets proc is taking 
 			care to extend your form with associated categories you need to ensure that your items are mapped 
 			to the corresponding category object yourself. Also since the categories package knows nothing from 
-			your objects you have to keep the acs_named_objects table updated with 
+			your objects you have to keep the acs_named_objects table updated with 
 			any changes taking place. We use the items title so that they are listed in the categories browser by 
 			title.
Make sure that you also delete these entries if your item is delete. Add this to 
 			your corresponding delete page:
-			db_dml delete_named_object "delete from acs_named_objects where object_id = :item_id"
-			
note-edit.tcl requires a
-note_id to determine which record
+			db_dml delete_named_object "delete from acs_named_objects where object_id = :item_id"
+			
note-edit.tcl requires a
+note_id to determine which record
 should be deleted.  It also looks for a confirmation variable, which
 should initially be absert.  If it is absent, we create a form to
 allow the user to confirm the deletion.  Note that in
-entry-edit.tcl we used ad_form to access the Form Template
+entry-edit.tcl we used ad_form to access the Form Template
 commands; here, we call them directly because we don't need the extra
 features of ad_form.  The form calls itself, but
 with hidden variables carrying both
-note_id and
-confirm_p.  If confirm_p is present,
+note_id and
+confirm_p.  If confirm_p is present,
 we delete the record, set redirection back to the index, and abort
-script execution.
The database commands:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?>
+script execution.
The database commands:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?>
 <queryset>
-  <fullquery name="do_delete">
+  <fullquery name="do_delete">
     <querytext>
       select samplenote__delete(:note_id)
     </querytext>
   </fullquery>
-  <fullquery name="get_name">
+  <fullquery name="get_name">
     <querytext>
       select samplenote__name(:note_id)
     </querytext>
   </fullquery>
-</queryset>
And the adp page:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.adp
<master>
-<property name="title">@title@</property>
-<property name="context">{@title@}</property>
+</queryset>
And the adp page:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.adp
<master>
+<property name="title">@title@</property>
+<property name="context">{@title@}</property>
 <h2>@title@</h2>
-<formtemplate id="note-del-confirm"></formtemplate>
+<formtemplate id="note-del-confirm"></formtemplate>
 </form>
The ADP is very simple.  The
-formtemplate tag outputs the HTML
+formtemplate tag outputs the HTML
 form generated by the ad_form command with the matching name.  Test it
       by adding the new files in the APM and then deleting a few
       samplenotes.
We will now make categories optional on package instance level and 
  		  also add a configuration page to allow the package admin to enable/disable 
  		  categories for his package.
- 		  
Go to the APM and create a number parameter with the name "EnableCategoriesP" 
- 		  and the default value "0".
Add the following lines to your index.tcl:
+ 		  
Go to the APM and create a number parameter with the name "EnableCategoriesP" 
+ 		  and the default value "0".
Add the following lines to your index.tcl:
           set return_url [ns_conn url]
-          set use_categories_p [parameter::get -parameter "EnableCategoriesP"]
+          set use_categories_p [parameter::get -parameter "EnableCategoriesP"]
           
Change your to this:
 			<a href=configure?<%=[export_url_vars return_url]%>>Configure</a>
 			<if @use_categories_p@>
-   			<a href="@category_map_url@"<#categories.Site_wide_Categories#</a>
+   			<a href="@category_map_url@"<#categories.Site_wide_Categories#</a>
    			</if>
           
Now create a configure page
           	ad_page_contract {
     			This page allows an admin to change the categories usage mode.
 			} {
-    			{return_url ""}
+    			{return_url ""}
 			}
 
-			set title "Configure category mode"
+			set title "Configure category mode"
 			set context [list $title]
-			set use_categories_p [parameter::get -parameter "EnableCategoriesP"]
+			set use_categories_p [parameter::get -parameter "EnableCategoriesP"]
 
 			ad_form -name categories_mode -form {
     			{enabled_p:text(radio)
-        			{label "Enable Categories"}
+        			{label "Enable Categories"}
         			{options {{Yes 1} {No 0}}}
         			{value $use_categories_p}
     			}
     			{return_url:text(hidden) {value $return_url}}
-    			{submit:text(submit) {label "Set Mode"}}
+    			{submit:text(submit) {label "Set Mode"}}
 			} -on_submit {
-    			parameter::set_value  -parameter "EnableCategoriesP" -value $enabled_p
+    			parameter::set_value  -parameter "EnableCategoriesP" -value $enabled_p
     			if {![empty_string_p $return_url]} {
         			ns_returnredirect $return_url
     			}
 			}
            
and add this to its corresponding ADP page
           	<master>
-			<property name="title">@title@</property>
-			<property name="context">@context@</property>
+			<property name="title">@title@</property>
+			<property name="context">@context@</property>
 
-			<formtemplate id="categories_mode"></formtemplate>
+			<formtemplate id="categories_mode"></formtemplate>
 	      
Reference this page from your admin page
 		#TCL:
 		set return_url [ad_conn url]
 
 		#ADP:
 		<a href=configure?<%=[export_url_vars return_url]%>>Configure</a>
-		
Change the note-edit.tcl:
+		
Change the note-edit.tcl:
 		# Use Categories?
-		set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0]
+		set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0]
 		if { $use_categories_p == 1 } {
 			# YOUR NEW FORM DEFINITION
 		} else {
     		# YOUR OLD FORM DEFINITION
 		}
 	
You can filter your notes using categories. The below example does not support multiple 
  	  filters and displays a category in a flat format.
The first step is to 
- 	  define the optional parameter category_id for 
- 	  index.tcl:
+ 	  define the optional parameter category_id for 
+ 	  index.tcl:
  	  	ad_page_contract {
   		YOUR TEXT
 		} {
@@ -191,18 +190,18 @@
 		}
  	  
Now you have to check whether categories are enabled or not. If this is the case and a 
  	  category id is passed you need to extend your sql select query to support filtering. One 
- 	  way would be to extend the mfp::note::get proc to 
- 	  support two more swiches -where_clause and
- 	  -from_clause.
- 	  	set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0]
+ 	  way would be to extend the mfp::note::get proc to 
+ 	  support two more swiches -where_clause and
+ 	  -from_clause.
+ 	  	set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0]
 
 		if { $use_categories_p == 1 && [exists_and_not_null category_id] } {
 
-			set from_clause "category_object_map com, acs_named_objects nam"
-			set_where_clause "com.object_id = qa.entry_id and
+			set from_clause "category_object_map com, acs_named_objects nam"
+			set_where_clause "com.object_id = qa.entry_id and
 								nam.package_id = :package_id and
 								com.object_id = nam.object_id and
-								com.category_id = :category_id"
+								com.category_id = :category_id"
 			
 			...
 								
@@ -224,14 +223,14 @@
     		if { ![empty_string_p $category_id] } {
         		set category_name [category::get_name $category_id]
         		if { [empty_string_p $category_name] } {
-            		ad_return_exception_page 404 "No such category" "Site-wide \
-          			Category with ID $category_id doesn't exist"
+            		ad_return_exception_page 404 "No such category" "Site-wide \
+          			Category with ID $category_id doesn't exist"
             		return
         		}
         		# Show Category in context bar
         		append context_base_url /cat/$category_id
         		lappend context [list $context_base_url $category_name]
-        		set type "all"
+        		set type "all"
     		}
 
     		# Cut the URL off the last item in the context bar
@@ -251,20 +250,20 @@
 		}
 		
and to the corresponding index ADP page:
 		<if @use_categories_p@>
- 			<multiple name="categories">
+ 			<multiple name="categories">
            		<h2>@categories.tree_name@
-           		<group column="tree_id">
-             		<a href="@package_url@cat/@categories.category_id@?@YOURPARAMS@&category_id=@categories.category_id@">@categories.category_name@
+           		<group column="tree_id">
+             		<a href="@package_url@cat/@categories.category_id@?@YOURPARAMS@&category_id=@categories.category_id@">@categories.category_name@
            		</group>
          	</multiple>
-		<a href="@package_url@view?@YOURPARAMS@">All Items</if>
- 	  
Finally you need a an index.vuh in your 
- 	  www folder to rewrite the URLs correctly, Section�, “Using .vuh files for pretty urls”:
+		<a href="@package_url@view?@YOURPARAMS@">All Items</if>
+ 	  
Finally you need a an index.vuh in your 
+ 	  www folder to rewrite the URLs correctly, the section called “Using .vuh files for pretty urls”:
  	  	set url /[ad_conn extra_url]
 
 		if {[regexp {^/+cat/+([^/]+)/*} $url \
           ignore_whole category_id]} {
           rp_form_put category_id $category_id
 		}
-		rp_internal_redirect "/packages/YOURPACKAGE/www/index" 	  
+		rp_internal_redirect "/packages/YOURPACKAGE/www/index" 	  
  	  
Now when ever the user select a category only notes that belong to this category are displayed.
Prev Home  Next
Admin Pages Up  Profile your code
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-comments.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-comments.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-comments.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-comments.html	14 Jul 2007 12:34:48 -0000	1.8.2.2
@@ -1,14 +1,13 @@
-
-Adding CommentsPrev Chapter�10.�Advanced Topics  Next
Adding Comments
You can track comments for any ACS Object.  Here we'll track
+Adding Comments
Prev Chapter�10.�Advanced Topics  Next
Adding Comments
You can track comments for any ACS Object.  Here we'll track
      comments for notes.  On the note-edit.tcl/adp pair, which is used to
      display individual notes, we want to put a link to add comments at
      the bottom of the screen.  If there are any comments, we want to
      show them.
First, we need to generate a url for adding comments.  In note-edit.tcl:
- set comment_add_url "[general_comments_package_url]comment-add?[export_vars {
+ set comment_add_url "[general_comments_package_url]comment-add?[export_vars {
   { object_id $note_id } 
   { object_name $title } 
-  { return_url "[ad_conn url]?[ad_conn query]"} 
- }]"
+  { return_url "[ad_conn url]?[ad_conn query]"} 
+ }]"
  
This calls a global, public tcl function that the
      general_comments package registered, to get its url. You then
      embed in that url the id of the note and its title, and set the
@@ -19,5 +18,5 @@
      show the contents of the comments, instead of just the fact that
      there are comments. Then you pass the note id, which is also the
      acs_object id.
We put our two new variables in the note-edit.adp
-     page.
<a href="@comment_add_url@">Add a comment</a>
+     page.
<a href="@comment_add_url@">Add a comment</a>
  @comments_html@
Prev Home  Next
OpenACS Edit This Page Templates Up  Admin Pages
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html,v
diff -u -r1.6.2.2 -r1.6.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	22 Apr 2007 10:21:57 -0000	1.6.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	14 Jul 2007 12:34:48 -0000	1.6.2.3
@@ -1,32 +1,31 @@
-
-Laying out a page with CSS instead of tablesPrev Chapter�10.�Advanced Topics  Next
Laying out a page with CSS instead of tables
.LRN home page with table-based layout
A sample of the HTML code (full source)
<table border="0" width="100%">
+Laying out a page with CSS instead of tablesPrev Chapter�10.�Advanced Topics  Next
Laying out a page with CSS instead of tables
.LRN home page with table-based layout
A sample of the HTML code (full source)
<table border="0" width="100%">
   <tr>
-    <td valign="top" width="50%">
-      <table class="element" border=0 cellpadding="0" cellspacing="0" width="100%">
+    <td valign="top" width="50%">
+      <table class="element" border=0 cellpadding="0" cellspacing="0" width="100%">
         <tr> 
-          <td colspan=3 class="element-header-text">
+          <td colspan=3 class="element-header-text">
             <bold>Groups</bold>
          </td>
        </tr>
        <tr>
-         <td colspan=3 class="dark-line" height="0"><img src="/resources/acs-subsite/spacer.gif"></td></tr>
+         <td colspan=3 class="dark-line" height="0"><img src="/resources/acs-subsite/spacer.gif"></td></tr>
           <tr>
-            <td class="light-line" width="1">
-              <img src="/resources/acs-subsite/spacer.gif" width="1">
+            <td class="light-line" width="1">
+              <img src="/resources/acs-subsite/spacer.gif" width="1">
             </td>
-            <td class="element-text" width="100%">
-            <table cellspacing="0" cellpadding="0" class="element-content" width="100%">
+            <td class="element-text" width="100%">
+            <table cellspacing="0" cellpadding="0" class="element-content" width="100%">
               <tr>
                 <td>
-                  <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%">
+                  <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%">
                     <tr>
                       <td class=element-text>
-                        MBA 101
.LRN Home with CSS-based layout
A sample of the HTML code (full source)
<div class="left">
-  <div class="portlet-wrap-shadow">
-    <div class="portlet-wrap-bl">
-      <div class="portlet-wrap-tr">
-        <div class="portlet">
+                        MBA 101
.LRN Home with CSS-based layout
A sample of the HTML code (full source)
<div class="left">
+  <div class="portlet-wrap-shadow">
+    <div class="portlet-wrap-bl">
+      <div class="portlet-wrap-tr">
+        <div class="portlet">
           <h2>Groups</h2>
           <ul>
             <li>
-              <a href="#">Class MBA 101</a>
If the CSS is removed from the file, it looks somewhat different:
Prev Home  Next
Using .vuh files for pretty urls Up  Sending HTML email from your application
docs@openacs.org
View comments on this page at openacs.org
+              <a href="#">Class MBA 101</a>
If the CSS is removed from the file, it looks somewhat different:
Prev Home  Next
Using .vuh files for pretty urls Up  Sending HTML email from your application
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-cvs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-cvs.html,v
diff -u -r1.20.2.2 -r1.20.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-cvs.html	22 Apr 2007 10:21:57 -0000	1.20.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.html	14 Jul 2007 12:34:48 -0000	1.20.2.3
@@ -1,22 +1,21 @@
-
-Add the new package to CVSPrev Chapter�10.�Advanced Topics  Next
Add the new package to CVS
Before you do any more work, make sure that your work is
-      protected by putting it all into cvs.  The cvs
-      add command is not recursive, so you'll have to
+Add the new package to CVS
Prev Chapter�10.�Advanced Topics  Next
Add the new package to CVS
Before you do any more work, make sure that your work is
+      protected by putting it all into cvs.  The cvs
+      add command is not recursive, so you'll have to
       traverse the directory tree manually and add as you go.  (More on
-      CVS)
[$OPENACS_SERVICE_NAME xml]$ cd ..
-[$OPENACS_SERVICE_NAME doc]$ cd ..
-[$OPENACS_SERVICE_NAME www]$ cd ..
-[$OPENACS_SERVICE_NAME myfirstpackage]$ cd ..
-[$OPENACS_SERVICE_NAME packages]$ cvs add myfirstpackage/
+      CVS)
[$OPENACS_SERVICE_NAME xml]$ cd ..
+[$OPENACS_SERVICE_NAME doc]$ cd ..
+[$OPENACS_SERVICE_NAME www]$ cd ..
+[$OPENACS_SERVICE_NAME myfirstpackage]$ cd ..
+[$OPENACS_SERVICE_NAME packages]$ cvs add myfirstpackage/
 Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage added to the repository
-[$OPENACS_SERVICE_NAME packages]$ cd myfirstpackage/
-[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs add www
+[$OPENACS_SERVICE_NAME packages]$ cd myfirstpackage/
+[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs add www
 Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www added to the repository
-[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www
-[$OPENACS_SERVICE_NAME www]$ cvs add doc
+[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www
+[$OPENACS_SERVICE_NAME www]$ cvs add doc
 Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc added to the repository
-[$OPENACS_SERVICE_NAME www]$ cd doc
-[$OPENACS_SERVICE_NAME doc]$ cvs add *
+[$OPENACS_SERVICE_NAME www]$ cd doc
+[$OPENACS_SERVICE_NAME doc]$ cvs add *
 cvs add: cannot add special file `CVS'; skipping
 cvs add: scheduling file `admin-guide.html' for addition
 cvs add: scheduling file `bi01.html' for addition
@@ -41,13 +40,13 @@
 cvs add: scheduling file `user-interface.png' for addition
 Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc/xml added to the repository
 cvs add: use 'cvs commit' to add these files permanently
-[$OPENACS_SERVICE_NAME doc]$ cd xml
-[$OPENACS_SERVICE_NAME xml]$ cvs add Makefile index.xml
+[$OPENACS_SERVICE_NAME doc]$ cd xml
+[$OPENACS_SERVICE_NAME xml]$ cvs add Makefile index.xml
 cvs add: scheduling file `Makefile' for addition
 cvs add: scheduling file `index.xml' for addition
 cvs add: use 'cvs commit' to add these files permanently
-[$OPENACS_SERVICE_NAME xml]$ cd ../../..
-[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs commit -m "new package"
+[$OPENACS_SERVICE_NAME xml]$ cd ../../..
+[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs commit -m "new package"
 cvs commit: Examining .
 cvs commit: Examining www
 cvs commit: Examining www/doc
@@ -59,4 +58,4 @@
 initial revision: 1.1
 done
 (many lines omitted)
-[$OPENACS_SERVICE_NAME myfirstpackage]$
Figure�10.1.�Upgrading a local CVS repository
Prev Home  Next
Write the Requirements and Design Specs Up  OpenACS Edit This Page Templates
docs@openacs.org
View comments on this page at openacs.org
+[$OPENACS_SERVICE_NAME myfirstpackage]$Figure�10.1.�Upgrading a local CVS repository

Prev Home  Next
Write the Requirements and Design Specs Up  OpenACS Edit This Page Templates
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-database.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v
diff -u -r1.37.2.2 -r1.37.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-database.html	22 Apr 2007 10:21:57 -0000	1.37.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-database.html	14 Jul 2007 12:34:48 -0000	1.37.2.3
@@ -1,44 +1,43 @@
-
-Setting Up Database ObjectsPrev Chapter�9.�Development Tutorial  Next
Setting Up Database Objects
by Joel Aufrecht
+Setting Up Database ObjectsPrev Chapter�9.�Development Tutorial  Next
Setting Up Database Objects
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Code the data model
We create all database objects with scripts in the
-      myfirstpackage/sql/ directory.  All
+        
Code the data model
We create all database objects with scripts in the
+      myfirstpackage/sql/ directory.  All
       database scripts are database-specific and are thus in either
-      the myfirstpackage/sql/oracle or
-      myfirstpackage/sql/postgresql directory.
+      the myfirstpackage/sql/oracle or
+      myfirstpackage/sql/postgresql directory.
       Packages can support Oracle, PostgreSQL, or both.  In this
       tutorial, we will be working with PostgreSQL
The first file will be
-      myfirstpackage-create.sql.  The
+      myfirstpackage-create.sql.  The
       package manager requires a file with the name
-      packagekey-create.sql,
+      packagekey-create.sql,
       which it will run automatically when the package in installed.
       This file should create all tables and views.
Our package is going to store all of its information in
-      one table.  It takes more than just a CREATE
-      TABLE command, however, because we want to
+      one table.  It takes more than just a CREATE
+      TABLE command, however, because we want to
       integrate our table with the OpenACS system.  By making each
       record in our table an OpenACS object, we gain access to the
       permissions system and to services that integrate with OpenACS
-      objects, such as general-comments and 
-      notification. The cost is
+      objects, such as general-comments and 
+      notification. The cost is
       that our table creation code must include several functions,
       stored procedures, and is complicated (even for simple tables).
There are many kinds of OpenACS objects in the system.  (You
-      can see them with the psql code:  select object_type from
-      acs_object_types;.)  One such object is the
+      can see them with the psql code:  select object_type from
+      acs_object_types;.)  One such object is the
       content_item, which is part of the content repository system.
       To use it, we will make our data objects children of the content_revision object, 
       which is a child of content_item.  Not only will we gain the benefits of both OpenACS
       Objects and content objects, we can also use some content
       repository functions to simplify our database creation.  (More
       information about ACS Objects.  More information about the
       Content Repository.)
-
Figure�9.2.�Tutorial Data Model
The top of each sql file has some
+
Figure�9.2.�Tutorial Data Model

The top of each sql file has some
       standard comments, including doc tags such as
-      @author which will be picked up
+      @author which will be picked up
       by the API browser.  The string
-      $Id$ will automatically be
-      expanded when the file is checked in to cvs.
[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/sql/postgresql
-[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-create.sql
Paste the text below into the file, save, and close.
Figure�9.3.�The Database Creation Script
-- creation script
+      $Id$ will automatically be
+      expanded when the file is checked in to cvs.
[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/sql/postgresql
+[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-create.sql
Paste the text below into the file, save, and close.
Figure�9.3.�The Database Creation Script
-- creation script
 --
 -- @author joel@aufrecht.org
 -- @cvs-id &Id:$
@@ -56,13 +55,13 @@
 
 -- necessary to work around limitation of content repository:
 select content_folder__register_content_type(-100,'mfp_note','t');
-
The creation script calls a function in PL/pgSQL (PL/pgSQL is a procedural language extention to sql),
-    content_type__create_type, which
+

The creation script calls a function in PL/pgSQL (PL/pgSQL is a procedural language extention to sql),
+    content_type__create_type, which
     in turn creates the necessary database changes to support our data
-    object.  Notice the use of "mfp."  This is derived from "My
-    First Package" and ensures that our object is unlikely to conflict
+    object.  Notice the use of "mfp."  This is derived from "My
+    First Package" and ensures that our object is unlikely to conflict
     with objects from other packages.
Create a database file to drop everything if the package is uninstalled.
-[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-drop.sql
Figure�9.4.�Database Deletion Script
-- drop script
+[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-drop.sql
Figure�9.4.�Database Deletion Script
-- drop script
 --
 -- @author joel@aufrecht.org
 -- @cvs-id &Id:$
@@ -74,19 +73,19 @@
 	   't',
 	   't'
     );
-
(like the creation script the drop script calls a PL/pgSQL function: content_type__drop_type
Run the create script manually to add your tables and functions.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql
+

(like the creation script the drop script calls a PL/pgSQL function: content_type__drop_type
Run the create script manually to add your tables and functions.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql
 psql:myfirstpackage-create.sql:15: NOTICE:  CREATE TABLE / PRIMARY KEY will create implicit index 'mfp_notes_pkey' for table 'mfp_notes'
 psql:myfirstpackage-create.sql:15: NOTICE:  CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s)
  content_type__create_type
 ---------------------------
                          0
 (1 row)
 
-[$OPENACS_SERVICE_NAME postgresql]$
If there are errors, use them to debug the sql file and try again.  If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it.  The drop script will probably have errors since some of the things it's trying to drop may be missing.  They can be ignored.
Once you get the same output as shown above, test the drop script:
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql
+[$OPENACS_SERVICE_NAME postgresql]$
If there are errors, use them to debug the sql file and try again.  If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it.  The drop script will probably have errors since some of the things it's trying to drop may be missing.  They can be ignored.
Once you get the same output as shown above, test the drop script:
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql
 
  content_type__drop_type
 -------------------------
                        0
 (1 row)
 
-[$OPENACS_SERVICE_NAME postgresql]$
Once both scripts are working without errors, run the create script one last time and proceed.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql
Prev Home  Next
Creating an Application Package Up  Creating Web Pages
docs@openacs.org
View comments on this page at openacs.org
+[$OPENACS_SERVICE_NAME postgresql]$Once both scripts are working without errors, run the create script one last time and proceed.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql
Prev Home  Next
Creating an Application Package Up  Creating Web Pages
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.html,v
diff -u -r1.36.2.2 -r1.36.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-debug.html	22 Apr 2007 10:21:57 -0000	1.36.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html	14 Jul 2007 12:34:48 -0000	1.36.2.3
@@ -1,48 +1,47 @@
-
-Debugging and Automated TestingPrev Chapter�9.�Development Tutorial  Next
Debugging and Automated Testing
by Joel Aufrecht
+Debugging and Automated TestingPrev Chapter�9.�Development Tutorial  Next
Debugging and Automated Testing
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Debugging
Developer Support.�The Developer Support package adds several goodies: debug
+        
Debugging
Developer Support.�The Developer Support package adds several goodies: debug
       information for every page; the ability to log comments to the
       page instead of the error log, and fast user switching so that you
       can test pages as anonymous and as dummy users without logging
       in and out.
PostgreSQL.�You can work directly with the database to do debugging
           steps like looking directly at tables and testing stored
           procedures.  Start emacs.  Type
-            M-x sql-postgres.  Press enter for
-            server name and use $OPENACS_SERVICE_NAME for
+            M-x sql-postgres.  Press enter for
+            server name and use $OPENACS_SERVICE_NAME for
             database name.  You can use C-(up arrow) and C-(down arrow)
             for command history.
-
Hint: "Parse error near *" usually means that an xql file
+
Hint: "Parse error near *" usually means that an xql file
       wasn't recognized, because the tcl file is choking on the *SQL*
       placeholder that it falls back on.
Watching the server log.�
To set up real-time monitoring of the AOLserver error
-          log, type 
less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log

+          log, type 
less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log

           
F�to�show�new�log�entries�in�real�time�(like�tail�-f)

 C-c�to�stop�and�F�to�start�it�up�again.�

 G�goes�to�the�end.

 ?�searches�backward�

 /�searches�forward.�

 ����������

-    
Manual testing
Make a list of basic tests to make sure it works
Test Num Action Expected Result
001 Browse to the index page while not logged in and
-            while one or more notes exist. No edit or delete or add links should appear.
002 Browse to the index page while logged in.  An Edit
+    
Manual testing
Make a list of basic tests to make sure it works
Test Num Action Expected Result
001 Browse to the index page while not logged in and
+            while one or more notes exist. No edit or delete or add links should appear.
002 Browse to the index page while logged in.  An Edit
             link should appear.  Click on it.  Fill out the form and
-            click Submit. The text added in the form should be visible on the
-            index page.
API-001 Invoke mfp::note::create with a specific word as the title. Proc should return an object id.
API-002 Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title.
API-003 Given the object id from API-001, invoke mfp::note::delete. Proc should return 0 for success.
Other things to test: try to delete someone else's
+            click Submit. The text added in the form should be visible on the
+            index page.
API-001 Invoke mfp::note::create with a specific word as the title. Proc should return an object id.
API-002 Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title.
API-003 Given the object id from API-001, invoke mfp::note::delete. Proc should return 0 for success.
Other things to test: try to delete someone else's
         note.  Try to delete your own note.  Edit your own note.
-        Search for a note.
Write automated tests
by Simon Carstensen and Joel Aufrecht
+        Search for a note.
Write automated tests
by Simon Carstensen and Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        

+        

     It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it.
Create the directory that will contain the test
-    script and edit the script file.  The directory location and file name are standards which are recognized by the automated testing package:
[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
-[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
-[$OPENACS_SERVICE_NAME test]$ emacs myfirstpackages-procs.tcl
Write the tests.  This is obviously the big step :)  The script should first call ad_library like any normal -procs.tcl file:
ad_library {
+    script and edit the script file.  The directory location and file name are standards which are recognized by the automated testing package:
[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
+[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
+[$OPENACS_SERVICE_NAME test]$ emacs myfirstpackages-procs.tcl
Write the tests.  This is obviously the big step :)  The script should first call ad_library like any normal -procs.tcl file:
ad_library {
     ...
 }
 
To create a test case you call
-aa_register_case test_case_name..   
+aa_register_case test_case_name..   
 Once you've created the test case you start writing the needed logic.
-We'll use the tutorial package, "myfirstpackage," as an example.
+We'll use the tutorial package, "myfirstpackage," as an example.
 Let's say you just wrote an API for adding and deleting notes in the
 notes packages and wanted to test that. You'd probably want to write a
 test that first creates a note, then verifies that it was inserted,
@@ -54,7 +53,7 @@
 call to aa_run_with_teardown which basically means that all the
 inserts, deletes, and updates will be rolled back once the test has
 been executed. A very useful feature. Instead of inserting bogus data
-like:        set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
set name [ad_generate_random_string]
+like:        set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
set name [ad_generate_random_string]
 
Here's how the test case looks so far:
aa_register_case mfp_basic_test {
     My test
 } {
@@ -65,10 +64,10 @@
        }
 }
 
Now let's look at the actual test code. That's the code that
-goes inside -test_code {}.  We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get.  Proc should return the specific word in the title."
+goes inside -test_code {}.  We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get.  Proc should return the specific word in the title."
       set name [ad_generate_random_string]
       set new_id [mfp::note::add -title $name]
-      aa_true "Note add succeeded" [exists_and_not_null new_id]
To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage.  You should see your test case.  Run it and examine the results.
TCLWebtest tests
API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
Example
Now we can add the rest of the API tests, including a test with deliberately bad data.  The complete test looks like:
ad_library {
+      aa_true "Note add succeeded" [exists_and_not_null new_id]
To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage.  You should see your test case.  Run it and examine the results.
TCLWebtest tests
API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
Example
Now we can add the rest of the API tests, including a test with deliberately bad data.  The complete test looks like:
ad_library {
     Test cases for my first package.
 }
 
@@ -84,15 +83,15 @@
             -test_code  {
                 set name [ad_generate_random_string]
                 set new_id [mfp::note::add -title $name]
-                aa_true "Note add succeeded" [exists_and_not_null new_id]
+                aa_true "Note add succeeded" [exists_and_not_null new_id]
                 
                 mfp::note::get -item_id $new_id -array note_array
-                aa_true "Note contains correct title" [string equal $note_array(title) $name]
+                aa_true "Note contains correct title" [string equal $note_array(title) $name]
                 
                 mfp::note::delete -item_id $new_id
                 
                 set get_again [catch {mfp::note::get -item_id $new_id -array note_array}]
-                aa_false "After deleting a note, retrieving it fails" [expr $get_again == 0]
+                aa_false "After deleting a note, retrieving it fails" [expr $get_again == 0]
             }
     }
 
@@ -109,15 +108,15 @@
                 set name {-Bad [BAD] \077 { $Bad}} 
                 append name [ad_generate_random_string]
                 set new_id [mfp::note::add -title $name]
-                aa_true "Note add succeeded" [exists_and_not_null new_id]
+                aa_true "Note add succeeded" [exists_and_not_null new_id]
                 
                 mfp::note::get -item_id $new_id -array note_array
-                aa_true "Note contains correct title" [string equal $note_array(title) $name]
-                aa_log "Title is $name"
+                aa_true "Note contains correct title" [string equal $note_array(title) $name]
+                aa_log "Title is $name"
                 mfp::note::delete -item_id $new_id
                 
                 set get_again [catch {mfp::note::get -item_id $new_id -array note_array}]
-                aa_false "After deleting a note, retrieving it fails" [expr $get_again == 0]
+                aa_false "After deleting a note, retrieving it fails" [expr $get_again == 0]
             }
     }
 
@@ -160,9 +159,9 @@
             
             # Request note-edit page
             set package_uri [apm_package_url_from_key myfirstpackage]
-            set edit_uri "${package_uri}note-edit"
-            aa_log "[twt::server_url]$edit_uri"
-            twt::do_request "[twt::server_url]$edit_uri"
+            set edit_uri "${package_uri}note-edit"
+            aa_log "[twt::server_url]$edit_uri"
+            twt::do_request "[twt::server_url]$edit_uri"
             
             # Submit a new note
 
@@ -177,8 +176,8 @@
             
             # Request index page and verify that note is in listing
             tclwebtest::do_request $package_uri                 
-            aa_true "New note with title \"$note_title\" is found in index page" \
-                [string match "*${note_title}*" [tclwebtest::response body]]
+            aa_true "New note with title \"$note_title\" is found in index page" \
+                [string match "*${note_title}*" [tclwebtest::response body]]
             
             #-------------------------------------------------------------
             # Delete Note
@@ -191,27 +190,27 @@
             # 3) screen-scrape for the ID
             # all options are problematic.  We'll do #1 in this example:
 
-            set note_id [db_string get_note_id_from_name " 
+            set note_id [db_string get_note_id_from_name " 
                 select item_id 
                   from cr_items 
                  where name = :note_title  
                    and content_type = 'mfp_note'
-            " -default 0]
+            " -default 0]
 
-            aa_log "Deleting note with id $note_id"
+            aa_log "Deleting note with id $note_id"
 
-            set delete_uri "${package_uri}note-delete?item_id=${note_id}"
+            set delete_uri "${package_uri}note-delete?item_id=${note_id}"
             twt::do_request $delete_uri
             
             # Request index page and verify that note is in listing
             tclwebtest::do_request $package_uri                 
-            aa_true "Note with title \"$note_title\" is not found in index page after deletion." \
-                ![string match "*${note_title}*" [tclwebtest::response body]]
+            aa_true "Note with title \"$note_title\" is not found in index page after deletion." \
+                ![string match "*${note_title}*" [tclwebtest::response body]]
             
         } -teardown_code {
             
             twt::user::delete -user_id $user_id
         }
     }
 
-
See also Section�, “Automated Testing”.
Prev Home  Next
Creating Web Pages Up  Chapter�10.�Advanced Topics
docs@openacs.org
View comments on this page at openacs.org
+See also the section called “Automated Testing”.
Prev Home  Next
Creating Web Pages Up  Chapter�10.�Advanced Topics
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-distribute.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-distribute.html,v
diff -u -r1.20.2.2 -r1.20.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-distribute.html	22 Apr 2007 10:21:57 -0000	1.20.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.html	14 Jul 2007 12:34:48 -0000	1.20.2.3
@@ -1,11 +1,10 @@
-
-Prepare the package for distribution.Prev Chapter�10.�Advanced Topics  Next
Prepare the package for distribution.
Browse to the package manager.  Click on
-        tutorialapp.
Click on Generate a distribution file
+Prepare the package for distribution.
Prev Chapter�10.�Advanced Topics  Next
Prepare the package for distribution.
Browse to the package manager.  Click on
+        tutorialapp.
Click on Generate a distribution file
         for this package from the
-        filesystem.
+        filesystem.
         
Click on the file size
-        (37.1KB)
-        after the label Distribution
-        File: and save the file to
-        /var/tmp.

+        (37.1KB)
+        after the label Distribution
+        File: and save the file to
+        /var/tmp.

 
Package development guidelines
Prev Home  Next
Profile your code Up  Distributing upgrades of your package
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html,v
diff -u -r1.3.2.2 -r1.3.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html	22 Apr 2007 10:21:57 -0000	1.3.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html	14 Jul 2007 12:34:48 -0000	1.3.2.3
@@ -1,17 +1,16 @@
-
-OpenACS Edit This Page TemplatesPrev Chapter�10.�Advanced Topics  Next
OpenACS Edit This Page Templates
by Nick Carroll
+OpenACS Edit This Page TemplatesPrev Chapter�10.�Advanced Topics  Next
OpenACS Edit This Page Templates
by Nick Carroll
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Goals
Learn about the OpenACS templating system.
Learn about subsites and site-map administration.
Introduction

+        
Goals
Learn about the OpenACS templating system.
Learn about subsites and site-map administration.
Introduction

         The OpenACS templating system allows you to give your site a consistent look and feel. It also promotes code maintainability in the presentation layer, by allowing presentation components to be reused across multiple pages. If you need to change the layout for some reason, then you only need to make that change in one location, instead of across many files.
       

         In this problem set you will familiarise yourself with the templating system in openacs. This will be achieved through customising an existing edit-this-page application template.
       

         Before proceeding, it is strongly advised to read the templating documentation on your openacs installation (http://localhost:8000/doc/acs-templating). The documentation lists the special tags available for ADP files.
-      
Exercise 1: Create a Subsite
Create a subsite called pset3.
A subsite is simply a directory or subdirectory mounted at the end of your domain name. This can be done in one of two places:
http://localhost:8000/admin/site-map
or the subsite admin form on the main site, which is available when you login to your OpenACS installation.
Exercise 2: Checkout and Install edit-this-page (ETP)
Checkout ETP from CVS:
cd ~/openacs/packages
+      
Exercise 1: Create a Subsite
Create a subsite called pset3.
A subsite is simply a directory or subdirectory mounted at the end of your domain name. This can be done in one of two places:
http://localhost:8000/admin/site-map
or the subsite admin form on the main site, which is available when you login to your OpenACS installation.
Exercise 2: Checkout and Install edit-this-page (ETP)
Checkout ETP from CVS:
cd ~/openacs/packages
             cvs -d:pserver:anonymous@openacs.org:/cvsroot login
-            cvs -d:pserver:anonymous@openacs.org:/cvsroot co edit-this-page
Go to the package manager at http://yoursite/acs-admin/apm. And install  the new package: edit-this-page.
Or use the "Add Application" form available on the Main site.
Change ETP Application
Work out how to change the ETP application.
Investigate each of the available ETP templates:
Default
News
FAQ
Exercise 4: Create a New ETP Template
Browse the files for each of the above ETP templates at:
cd ~/openacs/packages/edit-this-page/templates
Use the article template as the basis of our new col2 template.
cp article-content.adp col2-content.adp
+            cvs -d:pserver:anonymous@openacs.org:/cvsroot co edit-this-page
Go to the package manager at http://yoursite/acs-admin/apm. And install  the new package: edit-this-page.
Or use the "Add Application" form available on the Main site.
Change ETP Application
Work out how to change the ETP application.
Investigate each of the available ETP templates:
Default
News
FAQ
Exercise 4: Create a New ETP Template
Browse the files for each of the above ETP templates at:
cd ~/openacs/packages/edit-this-page/templates
Use the article template as the basis of our new col2 template.
cp article-content.adp col2-content.adp
             cp article-content.tcl col2-content.tcl
             cp article-index.adp col2-index.adp
-            cp article-index.tcl col2-index.tcl
The template should provide us with the following ETP layout:
Table�10.1.�table showing ETP layout
Header
Sidebar Main Content Pane
The "Main Content" pane should contain the editable content that ETP provides.
The "Header" should display the title of the page that you set in ETP.
The "Sidebar" should display the extlinks that you add as a content item in ETP.
Exercise 5: Register the col2 Template with ETP
Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.
cd ~/openacs/packages/edit-this-page/tcl
-            emacs etp-custom-init.tcl
Use the function etp::define_application to register your template with ETP
Uncomment the "asc" definition
Set allow_extlinks to true, the rest should be false.
Restart your server for the changes to take effect.
Exercise 6: Configure ETP to use the col2 Template
Configure your ETP instance at /lab4/index to use the col2 template.
Create external links to link to other mounted ETP instances.
Check that your external links show up in the sidebar when you view your ETP application using the col2 template.
Who Wrote This and When
This problem set was originally written by Nick Carroll in August 2004 for the University of Sydney Course EBUS5002.
This material is copyright 2004 by Nick Carroll.  It may be copied, reused, and modified, provided credit is given to the original author.
($Id$)
Prev Home  Next
Add the new package to CVS Up  Adding Comments
docs@openacs.org
View comments on this page at openacs.org
+            cp article-index.tcl col2-index.tclThe template should provide us with the following ETP layout:
Table�10.1.�table showing ETP layout
Header
Sidebar Main Content Pane

The "Main Content" pane should contain the editable content that ETP provides.
The "Header" should display the title of the page that you set in ETP.
The "Sidebar" should display the extlinks that you add as a content item in ETP.
Exercise 5: Register the col2 Template with ETP
Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.
cd ~/openacs/packages/edit-this-page/tcl
+            emacs etp-custom-init.tcl
Use the function etp::define_application to register your template with ETP
Uncomment the "asc" definition
Set allow_extlinks to true, the rest should be false.
Restart your server for the changes to take effect.
Exercise 6: Configure ETP to use the col2 Template
Configure your ETP instance at /lab4/index to use the col2 template.
Create external links to link to other mounted ETP instances.
Check that your external links show up in the sidebar when you view your ETP application using the col2 template.
Who Wrote This and When
This problem set was originally written by Nick Carroll in August 2004 for the University of Sydney Course EBUS5002.
This material is copyright 2004 by Nick Carroll.  It may be copied, reused, and modified, provided credit is given to the original author.
($Id$)
Prev Home  Next
Add the new package to CVS Up  Adding Comments
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html,v
diff -u -r1.11.2.1 -r1.11.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html	14 Jan 2007 04:20:11 -0000	1.11.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html	14 Jul 2007 12:34:48 -0000	1.11.2.2
@@ -1,7 +1,6 @@
-
-Future TopicsPrev Chapter�10.�Advanced Topics  Next
Future Topics
How to enforce security so that users can't
+Future Topics
Prev Chapter�10.�Advanced Topics  Next
Future Topics
How to enforce security so that users can't
       change other users records
How to use the content management tables so that
       ... what?
How to change the default stylesheets for Form
       Builder HTML forms.
How to make your package searchable with OpenFTS/Oracle
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
More on ad_form - data validation, other stuff.
       (plan to draw from Jon Griffin's doc)
partialquery in xql
How to use the html/text entry widget to get the
-      "does this look right" confirm page 
APM package dependencies
See also the OpenACS Programming FAQ
Prev Home  Next
Connect to a second database Up  Chapter�11.�Development Reference
docs@openacs.org
View comments on this page at openacs.org
+      "does this look right" confirm page 
APM package dependencies
See also the OpenACS Programming FAQ
Prev Home  Next
Connect to a second database Up  Chapter�11.�Development Reference
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html,v
diff -u -r1.5.2.1 -r1.5.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html	14 Jan 2007 04:20:11 -0000	1.5.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html	14 Jul 2007 12:34:48 -0000	1.5.2.2
@@ -1,22 +1,21 @@
-
-Hierarchical dataPrev Chapter�10.�Advanced Topics  Next
Hierarchical data
by Jade Rubick
+Hierarchical data
Prev Chapter�10.�Advanced Topics  Next
Hierarchical data
by Jade Rubick
       with help from many people in the OpenACS community
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
One of the nice things about using the OpenACS object system
     is that it has a built-in facility for tracking hierarchical data
     in an efficient way. The algorithm behind this is called
-    tree_sortkey.
Any time your tables are subclasses of the acs_objects
+    tree_sortkey.
Any time your tables are subclasses of the acs_objects
     table, then you automatically get the ability to structure them
     hierarchically. The way you do this is currently via the
-    context_id column of
+    context_id column of
     acs_objects (Note that there is talk of adding in a
-    parent_id column instead, because
-    the use of context_id has been
+    parent_id column instead, because
+    the use of context_id has been
     ambiguous in the past). So when you want to build your hierarchy,
     simply set the context_id values. Then, when you want to make
     hierarchical queries, you can do them as follows:
-      db_multirow categories blog_categories "
+      db_multirow categories blog_categories "
       SELECT
       c.*,
       o.context_id,
@@ -27,9 +26,9 @@
       WHERE
       c.category_id = o.object_id
       ORDER BY
-      o.tree_sortkey"
+      o.tree_sortkey"
     
Note the use of the
-    tree_level() function, which
+    tree_level() function, which
     gives you the level, starting from 1, 2, 3... 
Here's an example, pulling all of the children for a given
   parent:
       SELECT 
@@ -48,8 +47,8 @@
     want the parent's tree_level to start with 0, you'll want the
     subtraction in there. This is a reason you'll commonly see magic
     numbers in tree_sortkey SQL queries, like
-    tree_level(children.tree_sortkey) -
-    4. That is basically an incorrect way to do it,
+    tree_level(children.tree_sortkey) -
+    4. That is basically an incorrect way to do it,
     and subtracting the parent's tree_level is the preferred method.
This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:
       SELECT
       subtree.*,
@@ -60,9 +59,9 @@
       subtree.tree_sortkey between parent.tree_sortkey and tree_right(parent.tree_sortkey)
       and parent.key = :the_parent_key;
     
If you are using the Content Repository, you get a similar
-      facility, but the parent_id
+      facility, but the parent_id
       column is already there. Note you can do joins with
-      tree_sortkey:
+      tree_sortkey:
       SELECT
       p.item_id,
       repeat(:indent_pattern, (tree_level(p.tree_sortkey) - 5)* :indent_factor) as indent,
Index: openacs-4/packages/acs-core-docs/www/tutorial-html-email.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-html-email.html,v
diff -u -r1.5.2.1 -r1.5.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-html-email.html	14 Jan 2007 04:20:11 -0000	1.5.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-html-email.html	14 Jul 2007 12:34:48 -0000	1.5.2.2
@@ -1,22 +1,21 @@
-
-Sending HTML email from your applicationPrev Chapter�10.�Advanced Topics  Next
Sending HTML email from your application
by Jade Rubick
+Sending HTML email from your applicationPrev Chapter�10.�Advanced Topics  Next
Sending HTML email from your application
by Jade Rubick
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
Sending email is fairly simple using the acs-mail-lite
     package. Sending HTML email is only slightly more complicated.
-    set subject "my subject"
+    set subject "my subject"
 
-    set message "<b>Bold</b> not bold"
+    set message "<b>Bold</b> not bold"
 
-    set from_addr "me@myemail.com"
+    set from_addr "me@myemail.com"
 
-    set to_addr "me@myemail.com"
+    set to_addr "me@myemail.com"
 
     # the from to html closes any open tags.
     set message_html [ad_html_text_convert -from html -to html $message]
 
     # some mailers chop off the last few characters.
-    append message_html "   "
+    append message_html "   "
     set message_text [ad_html_text_convert -from html -to text $message]
         
     set message_data [build_mime_message $message_text $message_html]
Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v
diff -u -r1.37.2.2 -r1.37.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	22 Apr 2007 10:21:57 -0000	1.37.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	14 Jul 2007 12:34:48 -0000	1.37.2.3
@@ -1,12 +1,11 @@
-
-Creating an Application PackagePrev Chapter�9.�Development Tutorial  Next
Creating an Application Package
by Joel Aufrecht
+Creating an Application PackagePrev Chapter�9.�Development Tutorial  Next
Creating an Application Package
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
The intended page map
Overview
To start developing new code in OpenACS, we build a new package. A package 
+        
The intended page map
Overview
To start developing new code in OpenACS, we build a new package. A package 
       is a a discrete collection of web pages, tcl code, and database tables and procedures.
-      A package with user interface is called an application; 
+      A package with user interface is called an application; 
       a package which provides functions to other packages and has no direct interface, a
-      service.  A package can be installed, upgraded, and 
+      service.  A package can be installed, upgraded, and 
       removed.  It communicates with other packages through an API.  This chapter walks you through 
       the minimum steps to create a useful package, including writing documentation, setting up 
       database tables and procedures, writing web pages, debugging, and automatic regression testing.
@@ -18,11 +17,11 @@
         right now.  Code that is temporary hackage is clearly marked.
       
In this tutorial, we will make an application package for
     displaying a list of text notes.
-
Before you begin
You will need:
A computer with a working installation of
+
Before you begin
You will need:
A computer with a working installation of
 	  OpenACS.  If you don't have this, see Chapter�2, Installation Overview.
 	  
Example files, which are included in the
-standard OpenACS 5.3.1 distribution.
-	  
Figure�9.1.�Assumptions in this section
Fully qualified domain name of your server yourserver.test
URL of your server http://yourserver.test:8000
Name of development account $OPENACS_SERVICE_NAME
New Package key myfirstpackage
Use the APM to initialize a new package
We use the ACS Package Manager (APM) to add, remove, and
+standard OpenACS 5.3.2 distribution.
+	  
Figure�9.1.�Assumptions in this section
Fully qualified domain name of your server yourserver.test
URL of your server http://yourserver.test:8000
Name of development account $OPENACS_SERVICE_NAME
New Package key myfirstpackage

Use the APM to initialize a new package
We use the ACS Package Manager (APM) to add, remove, and
     upgrade packages.  It handles package meta-data, such as lists of
     files that belong in the package.  Each package is uniquely
     identified by a package key.  To start developing a new
@@ -31,31 +30,31 @@
     the initial directories, meta-information files, and database
     entries for a new package.  (More info on APM)
 
Browse to
-        http://yourserver:8000/acs-admin/apm.
-
Click Create a New Package.
Fill in the fields listed below.   Ignore the rest (and leave the check boxes alone).
+        http://yourserver:8000/acs-admin/apm.
+
Click Create a New Package.
Fill in the fields listed below.   Ignore the rest (and leave the check boxes alone).
         (Some will change automatically.  Don't mess with those.)
 

-              Package Key:
-              myfirstpackage

-              Package Name:
-              My First Package
+              Package Key:
+              myfirstpackage

+              Package Name:
+              My First Package
             

-              Package Plural:
-              My First Package

-              Package Type:
-              Application
+              Package Plural:
+              My First Package

+              Package Type:
+              Application
             
	  
-              Initial Version:
-              0.1d
-            
Summary:
-              This is my first package.
+              Initial Version:
+              0.1d
+            
Summary:
+              This is my first package.
             
At the bottom, click
-        Create Package.
+        Create Package.
         
This creates a package rooted at
-          /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage.
-          This is the "home directory" of our new package, and all
+          /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage.
+          This is the "home directory" of our new package, and all
           files in the package will be within this directory. More on the structure of
-          packages). 
Add an Application Instance to the Server
In order to see your work in progress, you must create a
+          packages). 
Add an Application Instance to the Server
In order to see your work in progress, you must create a
       map between the URL space of incoming requests and the package application instance.
       You do this by adding the application in the main site administration).  This
       creates a link between the incoming URL requests and an
@@ -64,9 +63,9 @@
       code and tables.  This requires that a package be developed
       package-aware.  You'll see how to do that
       in this tutorial.
Browse to
-http://yourserver.test:8000/admin/applications/application-add/.
Choose "My First Package" from the list and click OK (the other fields are optional).
By mounting the package, we've caused all requests to
-      http://yourserver.test:8000/myfirstpackage
-      to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
Quick start
The remainder of the tutorial walks you through each file one at a time as you create the package.  You can skip all this, and get a working package, by doing the following:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial
+http://yourserver.test:8000/admin/applications/application-add/.
Choose "My First Package" from the list and click OK (the other fields are optional).
By mounting the package, we've caused all requests to
+      http://yourserver.test:8000/myfirstpackage
+      to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
Quick start
The remainder of the tutorial walks you through each file one at a time as you create the package.  You can skip all this, and get a working package, by doing the following:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial
 psql $OPENACS_SERVICE_NAME -f myfirstpackage-create.sql
 cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/
 mkdir ../../../../myfirstpackage/lib
Index: openacs-4/packages/acs-core-docs/www/tutorial-notifications.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-notifications.html,v
diff -u -r1.10.2.1 -r1.10.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-notifications.html	14 Jan 2007 04:20:11 -0000	1.10.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.html	14 Jul 2007 12:34:48 -0000	1.10.2.2
@@ -1,5 +1,4 @@
-
-NotificationsPrev Chapter�10.�Advanced Topics  Next
Notifications
by David Bell and Simon Carstensen
+NotificationsPrev Chapter�10.�Advanced Topics  Next
Notifications
by David Bell and Simon Carstensen
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
The notifications package allows you to send notifications through any 
@@ -174,9 +173,9 @@
             -notif_text $new_content
     
This code is placed in the tcl procedure that creates blog
     entries, right after the entry gets created in the code. The
-    $blog(package_id) is the OpenACS
+    $blog(package_id) is the OpenACS
     object_id of the Weblogger instance to which the entry has been
-    posted to and the $new_content is
+    posted to and the $new_content is
     the content of the entry. This example uses the package_id for the
     object_id, which results in setting up notifications for all
     changes for blogger entries in this package. However, if you
@@ -185,7 +184,7 @@
     you can look at it for an example.
The final step is to setup the notification subscription process. In this 
     example we want to let a user find out when a new entry has been posted to the blog. To 
     do this we put a link on the blog that allows them to subscribe to notifications of new 
-    entries. The notifications/requests-new page is very handy in this situation.
Such a link can be created using the notification::display::request_widget 
+    entries. The notifications/requests-new page is very handy in this situation.
Such a link can be created using the notification::display::request_widget 
     proc:
     set notification_chunk [notification::display::request_widget \
         -type lars_blogger_notif \
@@ -196,10 +195,10 @@
     
which will return something like
 
     
-    You may <a href="/notifications/request-new?...">request notification</a> for Weblogger.

+    You may <a href="/notifications/request-new?...">request notification</a> for Weblogger.

 
-    which can be readily put on the blog index page. The pretty_name 
-    parameter is what appears at the end of the text returned (i.e. "... request notification</a> for pretty_name"), 
-    The url parameter should be set to the address we want the user 
+    which can be readily put on the blog index page. The pretty_name 
+    parameter is what appears at the end of the text returned (i.e. "... request notification</a> for pretty_name"), 
+    The url parameter should be set to the address we want the user 
     to be redirected to after they have finished the subscription process.
This should be all you need to implement a notification system. For more examples
     look at the forums package.
Prev Home  Next
Distributing upgrades of your package Up  Hierarchical data
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.html,v
diff -u -r1.37.2.2 -r1.37.2.3
--- openacs-4/packages/acs-core-docs/www/tutorial-pages.html	22 Apr 2007 10:21:57 -0000	1.37.2.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html	14 Jul 2007 12:34:48 -0000	1.37.2.3
@@ -1,51 +1,50 @@
-
-Creating Web PagesPrev Chapter�9.�Development Tutorial  Next
Creating Web Pages
by Joel Aufrecht
+Creating Web PagesPrev Chapter�9.�Development Tutorial  Next
Creating Web Pages
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Install some API
As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files:
-    cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".
Page Map
Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
Figure�9.5.�Page Map
Build the "Index" page
Each user-visible page in your package has, typically,
-      three parts.  The  tcl file
+        
Install some API
As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files:
+    cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".
Page Map
Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
Figure�9.5.�Page Map

Build the "Index" page
Each user-visible page in your package has, typically,
+      three parts.  The  tcl file
       holds the procedural logic for the page, including TCL and
       database-independent SQL code, and does things like
       check permissions, invoke the database queries, and modify
-      variables, and the adp page
-      holds html.  The -postgres.xql
-      and -oracle.xql files contains
+      variables, and the adp page
+      holds html.  The -postgres.xql
+      and -oracle.xql files contains
       database-specific SQL.  The default page in any directory is
-      index, so we'll build that
-      first, starting with the tcl file:
[$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www
-[$OPENACS_SERVICE_NAME www]$ emacs index.tcl
Paste this into the file.
ad_page_contract {
+      index, so we'll build that
+      first, starting with the tcl file:
[$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www
+[$OPENACS_SERVICE_NAME www]$ emacs index.tcl
Paste this into the file.
ad_page_contract {
     This is the main page for the package.  It displays all of the Notes and provides links to edit them and to create new Notes.
 
     @author Your Name (you@example.com)
     @cvs-id $Id$
 }
 
 set page_title [ad_conn instance_name]
-set context [list]
Now index.adp:
<master>
-  <property name="title">@page_title;noquote@</property>
-  <property name="context">@context;noquote@</property>
-<include src="/packages/myfirstpackage/lib/note-list">
The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
-[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
-[$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl
template::list::create \
+set context [list]
Now index.adp:
<master>
+  <property name="title">@page_title;noquote@</property>
+  <property name="context">@context;noquote@</property>
+<include src="/packages/myfirstpackage/lib/note-list">
The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
+[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib
+[$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl
template::list::create \
     -name notes \
     -multirow notes \
-    -actions { "Add a Note" note-edit} \
+    -actions { "Add a Note" note-edit} \
     -elements {
 	edit {
 	    link_url_col edit_url
 	    display_template {
-		<img src="/resources/acs-subsite/Edit16.gif" width="16" height="16" border="0">
+		<img src="/resources/acs-subsite/Edit16.gif" width="16" height="16" border="0">
 	    }
 	    sub_class narrow
 	}
 	title {
-	    label "Title"
+	    label "Title"
 	}
 	delete {
 	    link_url_col delete_url 
 	    display_template {
-		<img src="/resources/acs-subsite/Delete16.gif" width="16" height="16" border="0">
+		<img src="/resources/acs-subsite/Delete16.gif" width="16" height="16" border="0">
 	    }
 	    sub_class narrow
 	}
@@ -62,11 +61,11 @@
                mfp_notesx n
         where  n.revision_id = ci.live_revision
     } {
-	set edit_url [export_vars -base "note-edit" {item_id}]
-	set delete_url [export_vars -base "note-delete" {item_id}]
-    }
[$OPENACS_SERVICE_NAME lib]$ emacs note-list.adp
<listtemplate name="notes"></listtemplate>
You can test your work by viewing the page.
Create the add/edit page.  If note_id is passed in,
-      it display that note, and can change to edit mode if appropriate.  Otherwise, it presents a form for adding notes.
[$OPENACS_SERVICE_NAME lib]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www
-[$OPENACS_SERVICE_NAME www]$ emacs note-edit.tcl
ad_page_contract {
+	set edit_url [export_vars -base "note-edit" {item_id}]
+	set delete_url [export_vars -base "note-delete" {item_id}]
+    }
[$OPENACS_SERVICE_NAME lib]$ emacs note-list.adp
<listtemplate name="notes"></listtemplate>
You can test your work by viewing the page.
Create the add/edit page.  If note_id is passed in,
+      it display that note, and can change to edit mode if appropriate.  Otherwise, it presents a form for adding notes.
[$OPENACS_SERVICE_NAME lib]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www
+[$OPENACS_SERVICE_NAME www]$ emacs note-edit.tcl
ad_page_contract {
     This is the view-edit page for notes.
 
     @author Your Name (you@example.com)
@@ -83,7 +82,7 @@
 } -new_request {
     auth::require_login
     permission::require_permission -object_id [ad_conn package_id] -privilege create
-    set page_title "Add a Note"
+    set page_title "Add a Note"
     set context [list $page_title]
 } -edit_request {
     auth::require_login
@@ -94,7 +93,7 @@
 
     set title $note_array(title)
 
-    set page_title "Edit a Note"
+    set page_title "Edit a Note"
     set context [list $page_title]
 } -new_data {
     mfp::note::add \
@@ -104,15 +103,15 @@
 	-item_id $item_id \
 	-title $title
 } -after_submit {
-    ad_returnredirect "."
+    ad_returnredirect "."
     ad_script_abort
-}
[$OPENACS_SERVICE_NAME www]$ emacs note-edit.adp
<master>
-  <property name="title">@page_title;noquote@</property>
-  <property name="context">@context;noquote@</property>
-  <property name="focus">note.title</property>
+}
[$OPENACS_SERVICE_NAME www]$ emacs note-edit.adp
<master>
+  <property name="title">@page_title;noquote@</property>
+  <property name="context">@context;noquote@</property>
+  <property name="focus">note.title</property>
   
-<formtemplate id="note"></formtemplate>
And the delete page.  Since it has no UI, there is only a
-     tcl page, and no adp page.
[$OPENACS_SERVICE_NAME www]$ emacs note-delete.tcl
ad_page_contract {
+<formtemplate id="note"></formtemplate>
And the delete page.  Since it has no UI, there is only a
+     tcl page, and no adp page.
[$OPENACS_SERVICE_NAME www]$ emacs note-delete.tcl
ad_page_contract {
     This deletes a note
 
     @author Your Name (you@example.com)
@@ -127,7 +126,7 @@
 set title [item::get_title $item_id]
 mfp::note::delete -item_id $item_id
 
-ad_returnredirect "."
+ad_returnredirect "."
 # stop running this code, since we're redirecting
 abort
 
Prev Home  Next
Setting Up Database Objects Up  Debugging and Automated Testing
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-parameters.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-parameters.html,v
diff -u -r1.3.2.1 -r1.3.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-parameters.html	14 Jan 2007 04:20:11 -0000	1.3.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-parameters.html	14 Jul 2007 12:34:48 -0000	1.3.2.2
@@ -1,5 +1,4 @@
-
-Adding in parameters for your packagePrev Chapter�10.�Advanced Topics  Next
Adding in parameters for your package
Each instance of a package can have paramaters associated
+Adding in parameters for your package
Prev Chapter�10.�Advanced Topics  Next
Adding in parameters for your package
Each instance of a package can have paramaters associated
     with it. These are like preferences, and they can be set by the
     administrator for each application to change the behavior of your
     application. 
To add parameters for your package, go to the Automatic
Index: openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html,v
diff -u -r1.4.2.1 -r1.4.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html	14 Jan 2007 04:20:11 -0000	1.4.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html	14 Jul 2007 12:34:48 -0000	1.4.2.2
@@ -1,5 +1,4 @@
-
-Scheduled Procedures
Prev Chapter�10.�Advanced Topics  Next
Scheduled Procedures
Put this proc in a file /packages/myfirstpackage/tcl/scheduled-init.tcl.  Files in /tcl with the -init.tcl ending are sourced on server startup.  This one executes my_proc every 60 seconds:
ad_schedule_proc 60 myfirstpackage::my_proc
+Scheduled ProceduresPrev Chapter�10.�Advanced Topics  Next
Scheduled Procedures
Put this proc in a file /packages/myfirstpackage/tcl/scheduled-init.tcl.  Files in /tcl with the -init.tcl ending are sourced on server startup.  This one executes my_proc every 60 seconds:
ad_schedule_proc 60 myfirstpackage::my_proc
 
This executes once a day, at midnight:
ad_schedule_proc \
     -schedule_proc ns_schedule_daily \
     [list 0 0] \
Index: openacs-4/packages/acs-core-docs/www/tutorial-second-database.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-second-database.html,v
diff -u -r1.4.2.1 -r1.4.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-second-database.html	14 Jan 2007 04:20:11 -0000	1.4.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-second-database.html	14 Jul 2007 12:34:48 -0000	1.4.2.2
@@ -1,14 +1,13 @@
-
-Connect to a second databasePrev Chapter�10.�Advanced Topics  Next
Connect to a second database
It is possible to use the OpenACS TCL database API with
+Connect to a second database
Prev Chapter�10.�Advanced Topics  Next
Connect to a second database
It is possible to use the OpenACS TCL database API with
     other databases.  In this example, the OpenACS site uses a
     PostGre database, and accesses another PostGre database called
     legacy.
Modify config.tcl to accomodate the legacy database, and to
         ensure that the legacy database is not used for standard
         OpenACS queries:
ns_section ns/db/pools
-ns_param   pool1              "Pool 1"
-ns_param   pool2              "Pool 2"
-ns_param   pool3              "Pool 3"
-ns_param   legacy             "Legacy"
+ns_param   pool1              "Pool 1"
+ns_param   pool2              "Pool 2"
+ns_param   pool3              "Pool 3"
+ns_param   legacy             "Legacy"
 
 ns_section ns/db/pool/pool1
 #Unchanged from default
@@ -18,7 +17,7 @@
 ns_param   verbose            $debug
 ns_param   extendedtableinfo  true
 ns_param   logsqlerrors       $debug
-if { $database == "oracle" } {
+if { $database == "oracle" } {
     ns_param   driver             ora8
     ns_param   datasource         {}
     ns_param   user               $db_name
@@ -27,7 +26,7 @@
     ns_param   driver             postgres
     ns_param   datasource         ${db_host}:${db_port}:${db_name}
     ns_param   user               $db_user
-    ns_param   password           ""
+    ns_param   password           ""
 }
 
 ns_section ns/db/pool/pool2
@@ -57,13 +56,13 @@
 ns_param database_names [list main legacy]
 ns_param pools_main [list pool1 pool2 pool3]
 ns_param pools_legacy [list legacy]
To use the legacy database, use the
-          <code>-dbn</code> flag for any of the
-          <code>db_</code> API calls.  For
-          example, suppose there is a table called "foo" in the legacy
-          system, with a field "bar".  List "bar" for all records with
+          -dbn flag for any of the
+          db_ API calls.  For
+          example, suppose there is a table called "foo" in the legacy
+          system, with a field "bar".  List "bar" for all records with
           this tcl file:
db_foreach -dbn legacy get_bar_query {
   select bar from foo
   limit 10
 } {
-  ns_write "<br/>$bar"
+  ns_write "<br/>$bar"
 }
Prev Home  Next
Writing upgrade scripts Up  Future Topics
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-specs.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-specs.html	14 Jul 2007 12:34:48 -0000	1.8.2.2
@@ -1,39 +1,38 @@
-
-Write the Requirements and Design SpecsPrev Chapter�10.�Advanced Topics  Next
Write the Requirements and Design Specs
Before you get started you should make yourself familiar with
+Write the Requirements and Design Specs
Prev Chapter�10.�Advanced Topics  Next
Write the Requirements and Design Specs
Before you get started you should make yourself familiar with
       the tags that are used to write your documentation. For tips on
-        editing SGML files in emacs, see Section�, “OpenACS Documentation Guide”.
It's time to document.  For the tutorial we'll use
+        editing SGML files in emacs, see the section called “OpenACS Documentation Guide”.
It's time to document.  For the tutorial we'll use
       pre-written documentation.  When creating a package
       from scratch, start by copying the documentation template from
-	/var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
+	/var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
 	to
-	myfirstpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the 
+	myfirstpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the 
 	requirements and design sections, generate the html, and start
 	coding.  Store any supporting files, like page maps or schema
-      diagrams, in the www/doc/xml
+      diagrams, in the www/doc/xml
       directory, and store png or jpg versions of supporting files in the
-	www/doc directory.
For this tutorial, you should instead install the
+	www/doc directory.
For this tutorial, you should instead install the
 	pre-written documentation files for the tutorial app.  Log in
       as $OPENACS_SERVICE_NAME, create the standard
-      directories, and copy the prepared documentation:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/
-[$OPENACS_SERVICE_NAME myfirstpackage]$ mkdir -p www/doc/xml
-[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www/doc/xml
-[$OPENACS_SERVICE_NAME xml]$ cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/myfirstpackage/* .
+      directories, and copy the prepared documentation:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/
+[$OPENACS_SERVICE_NAME myfirstpackage]$ mkdir -p www/doc/xml
+[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www/doc/xml
+[$OPENACS_SERVICE_NAME xml]$ cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/myfirstpackage/* .
 [$OPENACS_SERVICE_NAME xml]$
 OpenACS uses DocBook for documentation.  DocBook is
 	an XML standard for semantic markup of documentation.  That
 	means that the tags you use indicate meaning, not intended
 	appearance.  The style sheet will determine appearance.  You
       will edit the text in an xml file, and then process the file
-      into html for reading.
Open the file index.xml
+      into html for reading.
Open the file index.xml
       in emacs.  Examine the file.  Find the version history (look for the tag
-        <revhistory>).  Add a
+        <revhistory>).  Add a
         new record to the document version history.  Look for the
-        <authorgroup> tag and
+        <authorgroup> tag and
         add yourself as a second author.  Save and exit.
Process the xml file to create html documentation.  The
       html documentation, including supporting files such as pictures,
-      is stored in the www/docs/
+      is stored in the www/docs/
       directory.  A Makefile is provided to generate html from the xml, and copy all of the
       supporting files.  If Docbook is set up correctly, all you need
-      to do is:
[$OPENACS_SERVICE_NAME xml]$ make
+      to do is:
[$OPENACS_SERVICE_NAME xml]$ make
 cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
 Writing requirements-introduction.html for chapter(requirements-introduction)
 Writing requirements-overview.html for chapter(requirements-overview)
@@ -50,4 +49,4 @@
 Writing bi01.html for bibliography
 Writing index.html for book
 [$OPENACS_SERVICE_NAME xml]$
Verify that the documentation was generated and reflects
-      your changes by browsing to http://yoursite:8000/myfirstpackage/doc
Prev Home  Next
Chapter�10.�Advanced Topics Up  Add the new package to CVS
docs@openacs.org
View comments on this page at openacs.org
+      your changes by browsing to http://yoursite:8000/myfirstpackage/doc
Prev Home  Next
Chapter�10.�Advanced Topics Up  Add the new package to CVS
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html,v
diff -u -r1.3.2.1 -r1.3.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html	14 Jan 2007 04:20:11 -0000	1.3.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html	14 Jul 2007 12:34:48 -0000	1.3.2.2
@@ -1,5 +1,4 @@
-
-Writing upgrade scriptsPrev Chapter�10.�Advanced Topics  Next
Writing upgrade scripts
by Jade Rubick
+Writing upgrade scriptsPrev Chapter�10.�Advanced Topics  Next
Writing upgrade scripts
by Jade Rubick
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
If your package changes its data model, you have to write an
@@ -13,6 +12,6 @@
     model changes are more serious and fundamental changes than the
     program .tcl files. 
Now use the APM to create a new package version
       1.0b2. Commit all your changes, tag the release 
-      (Section�, “Distributing upgrades of your package”), 
+      (the section called “Distributing upgrades of your package”), 
       and both new installations and upgrades
       will be taken care of.
Prev Home  Next
Adding in parameters for your package Up  Connect to a second database
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html,v
diff -u -r1.3.2.1 -r1.3.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html	14 Jan 2007 04:20:11 -0000	1.3.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html	14 Jul 2007 12:34:48 -0000	1.3.2.2
@@ -1,17 +1,16 @@
-
-Distributing upgrades of your packagePrev Chapter�10.�Advanced Topics  Next
Distributing upgrades of your package
by Jade Rubick
+Distributing upgrades of your packagePrev Chapter�10.�Advanced Topics  Next
Distributing upgrades of your package
by Jade Rubick
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
The OpenACS Package Repository builds a list of packages
     that can be installed on OpenACS installations, and can be used by
     administrators to update their packages. If you are a package
     developer, there are a couple of steps you need to take in order
     to release a new version of your package. 
For the sake of this example, let's assume you are the
-    package owner of the notes
+    package owner of the notes
     package. It is currently at version 1.5, and you are planning on
     releasing version 1.6. It is also located in OpenACS's CVS.
To release your package:
cd /path/to/notes
-cvs commit -m "Update package to version 1.6."
+cvs commit -m "Update package to version 1.6."
 cvs tag notes-1-6-final
 cvs tag -F openacs-5-1-compat
 
Of course, make sure you write upgrade scripts 
-      (Section�, “Writing upgrade scripts”)
Prev Home  Next
Prepare the package for distribution. Up  Notifications
docs@openacs.org
View comments on this page at openacs.org
+      (the section called “Writing upgrade scripts”)
Prev Home  Next
Prepare the package for distribution. Up  Notifications
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/tutorial-vuh.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-vuh.html,v
diff -u -r1.12.2.1 -r1.12.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-vuh.html	14 Jan 2007 04:20:11 -0000	1.12.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-vuh.html	14 Jul 2007 12:34:48 -0000	1.12.2.2
@@ -1,6 +1,5 @@
-
-Using .vuh files for pretty urlsPrev Chapter�10.�Advanced Topics  Next
Using .vuh files for pretty urls
.Vuh files are special cases of .tcl files, used for rewriting incoming urls.  We can use a vuh file to prettify the uri for our notes.  Instead of note-edit?item_id=495, we can use note/495.  To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list.  First, add the vuh:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www
-[$OPENACS_SERVICE_NAME www]$ emacs note.vuh
+Using .vuh files for pretty urlsPrev Chapter�10.�Advanced Topics  Next
Using .vuh files for pretty urls
.Vuh files are special cases of .tcl files, used for rewriting incoming urls.  We can use a vuh file to prettify the uri for our notes.  Instead of note-edit?item_id=495, we can use note/495.  To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list.  First, add the vuh:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www
+[$OPENACS_SERVICE_NAME www]$ emacs note.vuh
 
Paste this into the file:
# Transform requests of type: a/b
 # into this internal request: A?c=b
 # for example, note/495 > note-edit?item_id=496
@@ -15,10 +14,10 @@
 
 rp_form_put item_id $request
 
-set internal_path "/packages/[ad_conn package_key]/www/note-edit"
+set internal_path "/packages/[ad_conn package_key]/www/note-edit"
 
 rp_internal_redirect $internal_path
-
We parse the incoming request and treat everything after the final / as the item id.  Note that this simple redirection will lose any additional query parameters passed in.  Many OpenACS objects maintain a pretty-name, which is a unique, human-readable string, usually derived from title, which makes an even better 'pretty url' than a numeric id; this requires that your display page be able to look up an item based on pretty id.
We use rp_form_put to store the item id in the internal register that the next page is expecting, and then redirects the request in process internally (ie, without a browser refresh).
Next, modify note-list so that its link is of the new form.:
[$OPENACS_SERVICE_NAME www]$ emacs ../lib/note-edit.tcl
+
We parse the incoming request and treat everything after the final / as the item id.  Note that this simple redirection will lose any additional query parameters passed in.  Many OpenACS objects maintain a pretty-name, which is a unique, human-readable string, usually derived from title, which makes an even better 'pretty url' than a numeric id; this requires that your display page be able to look up an item based on pretty id.
We use rp_form_put to store the item id in the internal register that the next page is expecting, and then redirects the request in process internally (ie, without a browser refresh).
Next, modify note-list so that its link is of the new form.:
[$OPENACS_SERVICE_NAME www]$ emacs ../lib/note-edit.tcl
 db_multirow \
     -extend {
 	edit_url
@@ -30,8 +29,8 @@
                mfp_notesx n
         where  n.revision_id = ci.live_revision
     } {
-	set edit_url [export_vars -base "note/$item_id"]
-	set delete_url [export_vars -base "note-delete" {item_id}]
+	set edit_url [export_vars -base "note/$item_id"]
+	set delete_url [export_vars -base "note-delete" {item_id}]
     }
 
You may also need to change some of the links in your
     package. Commonly, you would use ad_conn package_url to build the
Index: openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html,v
diff -u -r1.3.2.1 -r1.3.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html	14 Jan 2007 04:20:11 -0000	1.3.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html	14 Jul 2007 12:34:48 -0000	1.3.2.2
@@ -1,95 +1,94 @@
-
-Enabling WYSIWYG
Prev Chapter�10.�Advanced Topics  Next
Enabling WYSIWYG
by Nima Mazloumi
+Enabling WYSIWYGPrev Chapter�10.�Advanced Topics  Next
Enabling WYSIWYG
by Nima Mazloumi
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
Most of the forms in OpenACS are created using the form builder, see Section�, “Using Form Builder: building html forms dynamically”. For detailed information on the 
-    API take a look here.
The following section shows how you can modify your form to allow WYSIWYG functionalities.
Convert your page to use <code>ad_form</code> (some changes but worth it)
Here an examples. From:
+        
Most of the forms in OpenACS are created using the form builder, see the section called “Using Form Builder: building html forms dynamically”. For detailed information on the 
+    API take a look here.
The following section shows how you can modify your form to allow WYSIWYG functionalities.
Convert your page to use ad_form (some changes but worth it)
Here an examples. From:
 	template::form create my_form
-	template::element create my_form my_form_id -label "The ID" -datatype integer -widget hidden
-	template::element create my_form my_input_field_1 -html { size 30 } -label "Label 1" -datatype text -optional
-	template::element create my_form my_input_field_2 -label "Label 2" -datatype text -help_text "Some Help" -after_html {<a name="#">Anchor</a>}
+	template::element create my_form my_form_id -label "The ID" -datatype integer -widget hidden
+	template::element create my_form my_input_field_1 -html { size 30 } -label "Label 1" -datatype text -optional
+	template::element create my_form my_input_field_2 -label "Label 2" -datatype text -help_text "Some Help" -after_html {<a name="#">Anchor</a>}
 	
To:
 	ad_form -name my_form -form {
 		my_form_id:key(acs_object_id_seq)
  		{my_input_field_1:text,optional
-               {label "Label 1"}
+               {label "Label 1"}
                {html {size 30}}}
       	{my_input_field_2:text
-               {label "Label 2"}
-               {help_text "Some Help"}
+               {label "Label 2"}
+               {help_text "Some Help"}
 	       	   {after_html
-               {<a name="#">Anchor</a>}}}
+               {<a name="#">Anchor</a>}}}
 	} ...
-	
Warning
You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
Convert your textarea widget to a richtext widget and enable htmlarea.
The <code>htmlarea_p</code>-flag can be used to prevent 
+	
Warning
You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
Convert your textarea widget to a richtext widget and enable htmlarea.
The htmlarea_p-flag can be used to prevent 
 	WYSIWYG functionality. Defaults to true if left away.
From:
 	{my_input_field_2:text
 	
To:
 	{my_input_field_2:richtext(richtext)
-			{htmlarea_p "t"}
+			{htmlarea_p "t"}
 	
The richtext widget presents a list with two elements: text and content type.
-	To learn more on existing content types search in Google for "MIME-TYPES" or 
-	take a look at the <code>cr_mime_types</code> table.
Make sure that both values are passed as a list to your 
-	<code>ad_form</code> or you will have problems 
+	To learn more on existing content types search in Google for "MIME-TYPES" or 
+	take a look at the cr_mime_types table.
Make sure that both values are passed as a list to your 
+	ad_form or you will have problems 
 	displaying the content or handling the data manipulation correctly.
Depending on the data model of your package you either support a content format 
-	or don't. If you don't you can assume <code>"text/html"</code> or 
-	<code>"text/richtext"</code> or <code>"text/enhanced"</code>.
The relevant parts in your <code>ad_form</code> definition are the 
-	switches <code>-new_data</code>, <code>-edit_data</code>, 
-	<code>-on_request</code> and <code>-on_submit</code>.
To allow your data to display correctly you need to add an <code>-on_request</code> block. 
-	If you have the format stored in the database pass this as well else use <code>"text/html"</code>:
-	set my_input_field_2 [template::util::richtext::create $my_input_field_2 "text/html"]
+	or don't. If you don't you can assume "text/html" or 
+	"text/richtext" or "text/enhanced".
The relevant parts in your ad_form definition are the 
+	switches -new_data, -edit_data, 
+	-on_request and -on_submit.
To allow your data to display correctly you need to add an -on_request block. 
+	If you have the format stored in the database pass this as well else use "text/html":
+	set my_input_field_2 [template::util::richtext::create $my_input_field_2 "text/html"]
 	
Now make sure that your SQL queries that do the data manipulation retrieve the correct value. 
-	If you simply use <code>my_input_field_2</code> you will store a list. 
-	Thus you need to add an <code>-on_submit</code> block:
+	If you simply use my_input_field_2 you will store a list. 
+	Thus you need to add an -on_submit block:
 	set my_input_field_2 [ template::util::richtext::get_property contents $my_input_field_2]
 	set format [ template::util::richtext::get_property format $my_input_field_2] #This is optional
-	
Now the correct values for <code>my_input_field_2</code> and 
-	<code>format</code> are passed to the <code>-new_data</code> and 
-	<code>-edit_data</code> blocks which don't need to get touched.
To make HTMLArea optional per package instance define a string parameter 
-	<code>UseWysiwygP</code> which defaults <code>0</code> for your 
+	
Now the correct values for my_input_field_2 and 
+	format are passed to the -new_data and 
+	-edit_data blocks which don't need to get touched.
To make HTMLArea optional per package instance define a string parameter 
+	UseWysiwygP which defaults 0 for your 
 	package using the APM.
In your edit page make the following changes
 	# Is WYSIWYG enabled?
-	set use_wysiwyg_p [parameter::get -parameter "UseWysiwygP" -default "f"]
+	set use_wysiwyg_p [parameter::get -parameter "UseWysiwygP" -default "f"]
 	
 	...
 	
 	{htmlarea_p $use_wysiwyg_p}
-	
The <code>-on_request</code> switch should set this value for your form.
+	
The -on_request switch should set this value for your form.
 	set htmlarea_p $use_wysiwyg_p
 	
All you need now is a configuration page where the user can change this setting. Create a 
-	<code>configure.tcl</code> file:
+	configure.tcl file:
 	ad_page_contract {
 
     	This page allows a faq admin to change the UseWysiwygP setting
 
 	} {
-    	{return_url ""}
+    	{return_url ""}
 	}
 
-	set title "Should we support WYSIWYG?"
+	set title "Should we support WYSIWYG?"
 	set context [list $title]
 
 	set use_wysiwyg_p
 
 	ad_form -name categories_mode -form {
     	{enabled_p:text(radio)
-        	{label "Enable WYSIWYG"}
+        	{label "Enable WYSIWYG"}
         	{options {{Yes t} {No f}}}
         	{value $use_wysiwyg_p}
     	}
     	{return_url:text(hidden) {value $return_url}}
-    	{submit:text(submit) {label "Change"}}
+    	{submit:text(submit) {label "Change"}}
 	} -on_submit {
-    	parameter::set_value  -parameter "UseWysiwygP" -value $enabled_p
+    	parameter::set_value  -parameter "UseWysiwygP" -value $enabled_p
     	if {![empty_string_p $return_url]} {
         	ns_returnredirect $return_url
     	}
 	}
 	
In the corresponding ADP file write
 	<master>
-	<property name="title">@title@</property>
-	<property name="context">@context@</property>
+	<property name="title">@title@</property>
+	<property name="context">@context@</property>
 
-	<formtemplate id="categories_mode"></formtemplate>
+	<formtemplate id="categories_mode"></formtemplate>
 	
And finally reference this page from your admin page
 	#TCL:
 	set return_url [ad_conn url]
Index: openacs-4/packages/acs-core-docs/www/tutorial.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial.html,v
diff -u -r1.18.2.1 -r1.18.2.2
--- openacs-4/packages/acs-core-docs/www/tutorial.html	14 Jan 2007 04:20:11 -0000	1.18.2.1
+++ openacs-4/packages/acs-core-docs/www/tutorial.html	14 Jul 2007 12:34:48 -0000	1.18.2.2
@@ -1,2 +1 @@
-
-Chapter�9.�Development TutorialPrev Part�III.�For OpenACS Package Developers  Next
Chapter�9.�Development Tutorial
Table of Contents
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
Prev Home  Next
Part�III.�For OpenACS Package Developers Up  Creating an Application Package
docs@openacs.org
View comments on this page at openacs.org
+Chapter�9.�Development TutorialPrev Part�III.�For OpenACS Package Developers  Next
Chapter�9.�Development Tutorial
Table of Contents
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
Prev Home  Next
Part�III.�For OpenACS Package Developers Up  Creating an Application Package
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/unix-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/unix-installation.html,v
diff -u -r1.27.2.2 -r1.27.2.3
--- openacs-4/packages/acs-core-docs/www/unix-installation.html	22 Apr 2007 10:21:57 -0000	1.27.2.2
+++ openacs-4/packages/acs-core-docs/www/unix-installation.html	14 Jul 2007 12:34:48 -0000	1.27.2.3
@@ -1,8 +1,7 @@
-
-Install a Unix-like system and supporting softwarePrev Chapter�3.�Complete Installation  Next
Install a Unix-like system and supporting software
by Joel Aufrecht
+Install a Unix-like system and supporting softwarePrev Chapter�3.�Complete Installation  Next
Install a Unix-like system and supporting software
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
a Unix-like system
You will need a computer running a unix-like system with the following software installed:
tdom
tcl --if you plan to use the OpenACS installation script
gmake and the compile and build environment.
BSD Note
BSD users: in most places in these instructions, gmake will work better than make.  (more
+        
a Unix-like system
You will need a computer running a unix-like system with the following software installed:
tdom
tcl --if you plan to use the OpenACS installation script
gmake and the compile and build environment.
BSD Note
BSD users: in most places in these instructions, gmake will work better than make.  (more
           information on FreeBSD installation). Also, fetch is a native replacement for wget.
Note: Instructions for installing tDOM and threaded tcl are included with the AOLserver4 installation instructions, 
     if these are not yet installed.
The following programs may be useful or required for some configurations. They are included in most distributions:
emacs
cvs (and initialize it)
ImageMagick (used by some packages for server side image manipulation)
Aspell (more information on spell-checking)
DocBook and supporting software (and install emacs keybindings for DocBook SGML)
daemontools (install from source)
a Mail Transport Agent, such as exim or sendmail (or install qmail from source)
In order to cut and paste the example code into your shell, you must first do Setting a global shell variable for cut and paste.
To install a machine to the specifications of the Reference Platform, do the 
     walkthrough of the Red Hat 8.0 Install for OpenACS.
($Id$)
Prev Home  Next
Chapter�3.�Complete Installation Up  Install Oracle 8.1.7
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/update-repository.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-repository.html,v
diff -u -r1.11.2.1 -r1.11.2.2
--- openacs-4/packages/acs-core-docs/www/update-repository.html	14 Jan 2007 04:20:11 -0000	1.11.2.1
+++ openacs-4/packages/acs-core-docs/www/update-repository.html	14 Jul 2007 12:34:48 -0000	1.11.2.2
@@ -1,8 +1,7 @@
-
-How to Update the OpenACS.org repositoryPrev Chapter�16.�Releasing OpenACS  Next
How to Update the OpenACS.org repository

+How to Update the OpenACS.org repository
Prev Chapter�16.�Releasing OpenACS  Next
How to Update the OpenACS.org repository

           Setup a local OpenACS server running 5.0 or better.
         

-        Edit packages/acs-admin/www/apm/build-repository.tcl and adjust the Configuration Settings.        

+        Edit packages/acs-admin/www/apm/build-repository.tcl and adjust the Configuration Settings.        

           Request /acs-admin/apm/build-repository on your new server.
         

               The page will find all branches in the cvs repository labeled oacs-x-y, and build a repository channel for each of
@@ -11,15 +10,15 @@
             

               For each channel, it'll do an anonymous checkout of packges and contrib/packages, then build .apm files for each package in the checkout.
             

-              The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "[acs_root_dir]/www/repository/".
+              The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "[acs_root_dir]/www/repository/".
             

           If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there.
         
This is automated on OpenACS.org by having a dedicated site just for building the repository, invoked with this shell script.  Since the page circumvents security checks for ease of use, the entire site is limited to local requests.  The script is called daily with a cron job.
#!/bin/sh
 #set -x
 
 STATUS=`wget --output-document - http://127.0.0.1:8002/build-repository.tcl | grep DONE | wc -l`
 
-if [ $STATUS -eq "1" ]
+if [ $STATUS -eq "1" ]
 then
     rm -rf /web/openacs.org/www/repository.old
     mv /web/openacs.org/www/repository /web/openacs.org/www/repository.old
Index: openacs-4/packages/acs-core-docs/www/update-translations.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-translations.html,v
diff -u -r1.10.2.1 -r1.10.2.2
--- openacs-4/packages/acs-core-docs/www/update-translations.html	14 Jan 2007 04:20:11 -0000	1.10.2.1
+++ openacs-4/packages/acs-core-docs/www/update-translations.html	14 Jul 2007 12:34:48 -0000	1.10.2.2
@@ -1,5 +1,4 @@
-
-How to Update the translationsPrev Chapter�16.�Releasing OpenACS  Next
How to Update the translations
Identify any new locales that have been created.
+How to Update the translations
Prev Chapter�16.�Releasing OpenACS  Next
How to Update the translations
Identify any new locales that have been created.
         For each new locale, check the parameters, especially that
         the locale is in the format [two-letter code for
         language, lower-case]_[TWO-LETTER CODE FOR COUNTRY,
@@ -10,10 +9,10 @@
        values ('fa_IR', 'Farsi (IR)', 'fa', 'IR', 'FARSI', 'IRAN', 'AL24UTFFSS', 
         'windows-1256', 't', 'f');
Put this command into the following four files.  For the
         upgrade files, the correct file name will depend on the
-        exact version.
/packages/acs-lang/sql/postgresql/ad-locales.sql
/packages/acs-lang/sql/postgresql/upgrade/upgrade-current-version.sql
/packages/acs-lang/sql/oracle/ad-locales.sql
/packages/acs-lang/sql/oracle/upgrade/upgrade-current-version.sql
Make a backup of the production database.  Restore it as a new database.  For example, if upgrading from OpenACS 5.1.1, and the site name/database name is translate-511, create translate-512b1.
Check out the latest code on the release branch (e.g., oacs-5-1) as a new site, using the new site name (e.g., /var/lib/aolserver/translate-512b1.  Copy over any local settings - usually, /etc/config.tcl and /etc/daemontools/run and modify appropriately.  Also, copy over several translation-server-only files:  
+        exact version.
/packages/acs-lang/sql/postgresql/ad-locales.sql
/packages/acs-lang/sql/postgresql/upgrade/upgrade-current-version.sql
/packages/acs-lang/sql/oracle/ad-locales.sql
/packages/acs-lang/sql/oracle/upgrade/upgrade-current-version.sql
Make a backup of the production database.  Restore it as a new database.  For example, if upgrading from OpenACS 5.1.1, and the site name/database name is translate-511, create translate-512b1.
Check out the latest code on the release branch (e.g., oacs-5-1) as a new site, using the new site name (e.g., /var/lib/aolserver/translate-512b1.  Copy over any local settings - usually, /etc/config.tcl and /etc/daemontools/run and modify appropriately.  Also, copy over several translation-server-only files:  
           
...TBD
           

-          
Shut down the production site and put up a notice (no procedure on how to do this yet.)
Start the new site, and upgrade it.
Go to ACS Lang admin page and click "Import All Messages"
Resolve conflicts, if any, on the provided page.
+          
Shut down the production site and put up a notice (no procedure on how to do this yet.)
Start the new site, and upgrade it.
Go to ACS Lang admin page and click "Import All Messages"
Resolve conflicts, if any, on the provided page.
           
Back on the admin page, click the export link.  If there are conflicts, the messages will be exported anyway and any errors will be shown in the web interface.
Commit the message catalogs to cvs.
From the packages dir, run the acs-lang/bin/check-catalog.sh script.  (This checks for keys no longer in use and some other things.  Until it is rolled into the UI, do it manually and check the results and take whatever steps you can intuit you should do.)
-          
CVS commit the catalog files.  Done
If everything went well, reconfigure the new site to take over the role of the old site (/etc/config.tcl and /etc/daemontools/run).  Otherwise, bring the old site back up while investigating problems, and then repeat.
+          
CVS commit the catalog files.  Done
If everything went well, reconfigure the new site to take over the role of the old site (/etc/config.tcl and /etc/daemontools/run).  Otherwise, bring the old site back up while investigating problems, and then repeat.
           
Prev Home  Next
How to package and release an OpenACS Package Up  Index
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html,v
diff -u -r1.20.2.2 -r1.20.2.3
--- openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html	22 Apr 2007 10:21:57 -0000	1.20.2.2
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html	14 Jul 2007 12:34:48 -0000	1.20.2.3
@@ -1,12 +1,11 @@
-
-Upgrading 4.5 or higher to 4.6.3Prev Chapter�5.�Upgrading  Next
Upgrading 4.5 or higher to 4.6.3
The required platform for OpenACS 4.6 is the same as
-      4.5, with the exception of OpenFTS.  OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL.  If you have OpenFTS 0.2, you'll need to upgrade.  
If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql.  See Bug #632
A computer with OpenACS 4.5.
OpenACS 4.6 tarball or CVS checkout/export.
Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2
Make a Backup.�Back up the database and file system (see Section�, “Manual backup and recovery”).
OPTIONAL: Upgrade OpenFTS.�Section�, “Upgrading OpenFTS from 0.2 to 0.3.2”

+Upgrading 4.5 or higher to 4.6.3
Prev Chapter�5.�Upgrading  Next
Upgrading 4.5 or higher to 4.6.3
The required platform for OpenACS 4.6 is the same as
+      4.5, with the exception of OpenFTS.  OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL.  If you have OpenFTS 0.2, you'll need to upgrade.  
If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql.  See Bug #632
A computer with OpenACS 4.5.
OpenACS 4.6 tarball or CVS checkout/export.
Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2
Make a Backup.�Back up the database and file system (see the section called “Manual backup and recovery”).
OPTIONAL: Upgrade OpenFTS.�the section called “Upgrading OpenFTS from 0.2 to 0.3.2”

             Stop the server
-          
[root root]# svc -d /service/$OPENACS_SERVICE_NAME
Upgrade the file system.�Section�, “Upgrading the OpenACS files”

-            Start the server
-          
[root root]# svc -u /service/$OPENACS_SERVICE_NAME
Use APM to upgrade the database.�
Browse to the package manager, http://yourserver/acs-admin/apm.
Click Install packages.
Select the packages you want to install.  This should
+          
[root root]# svc -d /service/$OPENACS_SERVICE_NAME
Upgrade the file system.�the section called “Upgrading the OpenACS files”

+            Start the server
+          
[root root]# svc -u /service/$OPENACS_SERVICE_NAME
Use APM to upgrade the database.�
Browse to the package manager, http://yourserver/acs-admin/apm.
Click Install packages.
Select the packages you want to install.  This should
               be everything that says
-              upgrade, plus any new
+              upgrade, plus any new
               packages you want.  It's safest to upgrade the kernel by
               itself, and then come back and upgrade the rest of the
-              desired packages in a second pass.
On the next screen, click Install Packages
When prompted, restart the server:
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.
Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.3.1.
Rollback.�If anything goes wrong, roll back to the backup snapshot.
Prev Home  Next
Overview Up  Upgrading OpenACS 4.6.3 to 5.0
docs@openacs.org
View comments on this page at openacs.org
+              desired packages in a second pass.
On the next screen, click Install Packages
When prompted, restart the server:
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.
Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.3.2.
Rollback.�If anything goes wrong, roll back to the backup snapshot.
Prev Home  Next
Overview Up  Upgrading OpenACS 4.6.3 to 5.0
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html,v
diff -u -r1.10.2.1 -r1.10.2.2
--- openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html	14 Jan 2007 04:20:11 -0000	1.10.2.1
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html	14 Jul 2007 12:34:48 -0000	1.10.2.2
@@ -1,12 +1,11 @@
-
-Upgrading OpenACS 4.6.3 to 5.0Prev Chapter�5.�Upgrading  Next
Upgrading OpenACS 4.6.3 to 5.0
Oracle.�This forum posting documents 
+Upgrading OpenACS 4.6.3 to 5.0
Prev Chapter�5.�Upgrading  Next
Upgrading OpenACS 4.6.3 to 5.0
Oracle.�This forum posting documents 
             
             how to upgrade an Oracle installation from OpenACS 4.6.3 to 5
             .
-            
PostGreSQL.�You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3.  See Upgrade PostGreSQL to 7.3; Table�2.2
-            
Back up the database and file system.
Upgrade the file system for packages/acs-kernel.�Section�, “Upgrading the OpenACS files”
Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD).  You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade

-                Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql  $OPENACS_SERVICE_NAME.  Run the scripts in this order (order is tentative, not verified):
+            
PostGreSQL.�You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3.  See Upgrade PostGreSQL to 7.3; Table�2.2, “Version Compatibility Matrix”
+            
Back up the database and file system.
Upgrade the file system for packages/acs-kernel.�the section called “Upgrading the OpenACS files”
Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD).  You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade

+                Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql  $OPENACS_SERVICE_NAME.  Run the scripts in this order (order is tentative, not verified):
               
psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME
 psql -f upgrade-4.6.4-4.6.5.sql $OPENACS_SERVICE_NAME
 psql -f upgrade-4.6.5-4.6.6.sql $OPENACS_SERVICE_NAME
@@ -20,20 +19,20 @@
 psql -f upgrade-5.0.0a4-5.0.0a5.sql $OPENACS_SERVICE_NAME
 psql -f upgrade-5.0.0b1-5.0.0b2.sql $OPENACS_SERVICE_NAME
 psql -f upgrade-5.0.0b2-5.0.0b3.sql $OPENACS_SERVICE_NAME
-psql -f upgrade-5.0.0b3-5.0.0b4.sql $OPENACS_SERVICE_NAME
Upgrade ACS Service Contracts manually:
[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-service-contracts/sql/postgresql/upgrade
+psql -f upgrade-5.0.0b3-5.0.0b4.sql $OPENACS_SERVICE_NAME
Upgrade ACS Service Contracts manually:
[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-service-contracts/sql/postgresql/upgrade
 psql -f upgrade-4.7d2-4.7d3.sql $OPENACS_SERVICE_NAME
-
Load acs-authentication data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME
Load acs-lang data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME
(This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
if {![apm_package_installed_p acs-lang]} {
+
Load acs-authentication data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME
Load acs-lang data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME
(This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
if {![apm_package_installed_p acs-lang]} {
 apm_package_install -enable -mount_path acs-lang [acs_root_dir]/packages/acs-lang/acs-lang.info
-lang::catalog::import -locales [list "en_US"]
+lang::catalog::import -locales [list "en_US"]
 }
 
 if {![apm_package_installed_p acs-authentication]} {
 apm_package_install -enable [acs_root_dir]/packages/acs-authentication/acs-authentication.info
-apm_parameter_register "UsePasswordWidgetForUsername" \
-"Should we hide what the user types in the username
+apm_parameter_register "UsePasswordWidgetForUsername" \
+"Should we hide what the user types in the username
 field, the way we do with the password field? Set
 this to 1 if you are using sensitive information
-such as social security number for username." \
+such as social security number for username." \
 acs-kernel 0 number \
 security 1 1
 parameter::set_value -package_id [ad_acs_kernel_id] -parameter UsePasswordWidgetForUsername -value 0
Index: openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html,v
diff -u -r1.11.2.1 -r1.11.2.2
--- openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html	14 Jan 2007 04:20:11 -0000	1.11.2.1
+++ openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html	14 Jul 2007 12:34:48 -0000	1.11.2.2
@@ -1,2 +1 @@
-
-Upgrading an OpenACS 5.0.0 or greater installationPrev Chapter�5.�Upgrading  Next
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading a stock site.�If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
Upgrading a Custom or CVS site.�If you have custom code, and your site is in a CVS repository, upgrade with these steps:
Upgrade the file system for all packages in use.�Section�, “Upgrading the OpenACS files”
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
Prev Home  Next
Upgrading OpenACS 4.6.3 to 5.0 Up  Upgrading the OpenACS files
docs@openacs.org
View comments on this page at openacs.org
+Upgrading an OpenACS 5.0.0 or greater installationPrev Chapter�5.�Upgrading  Next
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading a stock site.�If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
Upgrading a Custom or CVS site.�If you have custom code, and your site is in a CVS repository, upgrade with these steps:
Upgrade the file system for all packages in use.�the section called “Upgrading the OpenACS files”
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
Prev Home  Next
Upgrading OpenACS 4.6.3 to 5.0 Up  Upgrading the OpenACS files
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html,v
diff -u -r1.20.2.2 -r1.20.2.3
--- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html	22 Apr 2007 10:21:57 -0000	1.20.2.2
+++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html	14 Jul 2007 12:34:48 -0000	1.20.2.3
@@ -1,5 +1,4 @@
-
-Upgrading the OpenACS filesPrev Chapter�5.�Upgrading  Next
Upgrading the OpenACS files
Chosing a Method to Upgrade your Files
OpenACS is distributed in many different ways:
+Upgrading the OpenACS files
Prev Chapter�5.�Upgrading  Next
Upgrading the OpenACS files
Chosing a Method to Upgrade your Files
OpenACS is distributed in many different ways:
         
as a collection of files
 as one big tarball
 via CVS
 via automatic download from within the APM
             (package manager)

       
Upgrades work by first changing the file system (via any
@@ -10,29 +9,29 @@
         using the last method, you can skip this page. This page
         describes whether or not you need to be upgrading using this
         page or not:
-        Section�, “Upgrading an OpenACS 5.0.0 or greater installation”
-      
Methods of upgrading OpenACS files
Upgrading files for a site which is not in a CVS repository.�Unpack the tarball into a new directory and copy its
+        the section called “Upgrading an OpenACS 5.0.0 or greater installation”
+      
Methods of upgrading OpenACS files
Upgrading files for a site which is not in a CVS repository.�Unpack the tarball into a new directory and copy its
           contents on top of your working directory. Or just 'install
           software', select remote repository, and upgrade your files
-          from there.
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver
-[$OPENACS_SERVICE_NAME web]$ tar xzf /var/tmp/openacs-5-1.tar.gz
-[$OPENACS_SERVICE_NAME web]$ cp -r openacs-5-1/* openacs-4
-[$OPENACS_SERVICE_NAME openacs-upgrade]$ exit
+          from there.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver
+[$OPENACS_SERVICE_NAME web]$ tar xzf /var/tmp/openacs-5-1.tar.gz
+[$OPENACS_SERVICE_NAME web]$ cp -r openacs-5-1/* openacs-4
+[$OPENACS_SERVICE_NAME openacs-upgrade]$ exit
 [root root]#
 su - $OPENACS_SERVICE_NAME
 cd /var/lib/aolserver
 tar xzf /var/tmp/openacs-5-1.tgz
 cp -r openacs-5-1/* openacs-4
 exit

-          Upgrading files for a site in a private CVS repository
+          Upgrading files for a site in a private CVS repository
         
Many OpenACS site developers operate their own CVS
         repository to keep track of local customizations. In this
         section, we describe how to upgrade your local CVS repository
         with the latest OpenACS version, without overriding your own
         local customizations. 
This diagram explains the basic idea. However, the
         labels are incorrect. Step 1(a) has been removed, and Step
-        1(b) should be labelled Step 1.
Figure�5.2.�Upgrading a local CVS repository
Step 0: Set up a working CVS checkout.�To get your OpenACS code into your local CVS
+        1(b) should be labelled Step 1.
Figure�5.2.�Upgrading a local CVS repository

Step 0: Set up a working CVS checkout.�To get your OpenACS code into your local CVS
                 repository, you will set up a working CVS checkout of
                 OpenACS. When you want to update your site, you'll
                 update the working CVS checkout, import those changes
@@ -47,62 +46,62 @@
         using OpenACS 5.1,x, you will need a 5.1 checkout. That will
         be good for 5.1, 5.11, 5.12, and so on. But when you want to
         upgrade to OpenACS 5.2, you'll need to check out another
-        branch.
The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package.  Each minor release of OpenACS since 5.0 has this tagging structure.  For example, OpenACS 5.1.x has openacs-5-1-compat.
You will want to separately check out all the
+        branch.
The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package.  Each minor release of OpenACS since 5.0 has this tagging structure.  For example, OpenACS 5.1.x has openacs-5-1-compat.
You will want to separately check out all the
                 packages you are using.
-              
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver
-[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core
-[$OPENACS_SERVICE_NAME aolserver]$ cd openacs-4/packages
-[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2...
-[$OPENACS_SERVICE_NAME aolserver]$ cd ../..
-[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
Make sure your working CVS checkout doesn't have
+              
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver
+[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core
+[$OPENACS_SERVICE_NAME aolserver]$ cd openacs-4/packages
+[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2...
+[$OPENACS_SERVICE_NAME aolserver]$ cd ../..
+[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
Make sure your working CVS checkout doesn't have
               the entire CVS tree from OpenACS. A good way to check
               this is if it has a contrib directory. If it does, you
               probably checked out the entire tree. You might want to
               start over, remove your working CVS checkout, and try
               again.
               
Step 1: Import new OpenACS code.�
-              
Update CVS.�Update your local CVS working checkout (unless
-                      you just set it up). 
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1
-[$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd ChangeLog *.txt bin etc tcl www packages/*
Update a single package via cvs working checkout.�You can add or upgrade a single package at a time, if you already have a cvs working directory.
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/packages/openacs-5-1
-[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -Pd packagename
In the next section, the import must be tailored to just this package.
Step 2: Merge New OpenACS code.�Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur.
Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.
[$OPENACS_SERVICE_NAME openacs-5-1]$  cd /var/lib/aolserver/openacs-5-1
-[$OPENACS_SERVICE_NAME openacs-5-1]$  cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" $OPENACS_SERVICE_NAME OpenACS openacs-5-1
-            
Tip
If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly.  In this example, we are adding the myfirstpackage package.
[root root]# su - $OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-0/package/myfirstpackage
-[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1
Create a new directory as temporary working space to
+              
Update CVS.�Update your local CVS working checkout (unless
+                      you just set it up). 
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1
+[$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd ChangeLog *.txt bin etc tcl www packages/*
Update a single package via cvs working checkout.�You can add or upgrade a single package at a time, if you already have a cvs working directory.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/packages/openacs-5-1
+[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -Pd packagename
In the next section, the import must be tailored to just this package.
Step 2: Merge New OpenACS code.�Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur.
Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.
[$OPENACS_SERVICE_NAME openacs-5-1]$  cd /var/lib/aolserver/openacs-5-1
+[$OPENACS_SERVICE_NAME openacs-5-1]$  cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" $OPENACS_SERVICE_NAME OpenACS openacs-5-1
+            
Tip
If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly.  In this example, we are adding the myfirstpackage package.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-0/package/myfirstpackage
+[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1
Create a new directory as temporary working space to
             reconcile conflicts between the new files and your current
             work.  The example uses the cvs keyword yesterday, making
             the assumption that you haven't checked in new code to
             your local tree in the last day. This section should be
-            improved to use tags instead of the keyword yesterday!
[$OPENACS_SERVICE_NAME openacs-5.1]$  cd /var/lib/aolserver
-[$OPENACS_SERVICE_NAME tmp]$ rm -rf $OPENACS_SERVICE_NAME-upgrade
-[$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade
-[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d $OPENACS_SERVICE_NAME-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1
+            improved to use tags instead of the keyword yesterday!
[$OPENACS_SERVICE_NAME openacs-5.1]$  cd /var/lib/aolserver
+[$OPENACS_SERVICE_NAME tmp]$ rm -rf $OPENACS_SERVICE_NAME-upgrade
+[$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade
+[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d $OPENACS_SERVICE_NAME-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1
 (CVS feedback here)
The file /var/tmp/openacs-upgrade/cvs.txt contains the
             results of the upgrade.  If you changed files that are
             part of the OpenACS tarball and those changes conflict,
             you'll have to manually reconcile them.  Use the emacs
-            command M-x sort-lines
+            command M-x sort-lines
             (you may have to click Ctrl-space at the beginning of the
             file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
Once you've fixed any conflicts, commit the new code
-            to your local tree.  
[$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cvs commit -m "Upgraded to 5.1"
Step 3: Upgrade your local staging site.�Update your working tree with the new files.  The CVS flags ensure that new directories are created and pruned directories destroyed.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
+            to your local tree.  
[$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cvs commit -m "Upgraded to 5.1"
Step 3: Upgrade your local staging site.�Update your working tree with the new files.  The CVS flags ensure that new directories are created and pruned directories destroyed.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
 (CVS feedback)
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
 [root root]# 

-        Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org)
-      
[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
+        Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org)
+      
[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
 (CVS feedback)
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Upgrading a Production Site Safely
If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:
Declare a freeze on new cvs updates - ie, you cannot run cvs update
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Upgrading a Production Site Safely
If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:
Declare a freeze on new cvs updates - ie, you cannot run cvs update
    on the production site

             Make a manual backup of the production site in addition to the
    automated backups
Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of
-   ETP, blogger, and other applications) into a "vendor branch" of the
-   $OPENACS_SERVICE_NAME CVS tree, as described in "Upgrading a local CVS repository", step 1, above. 
+   ETP, blogger, and other applications) into a "vendor branch" of the
+   $OPENACS_SERVICE_NAME CVS tree, as described in "Upgrading a local CVS repository", step 1, above. 
    As soon as we do this, any cvs update command on production might bring new code onto the production site, which
    would be bad.
Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working tree).

             Manually resolve any conflicts in the working upgrade tree
@@ -111,5 +110,5 @@
    have a new website called $OPENACS_SERVICE_NAME-upgrade.
           

             Test the $OPENACS_SERVICE_NAME-upgrade site
-          
If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade.
Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page.
Repeat the upgrade with the most recent database
Test the that the new site is functional.  If so, change the upgraded site to respond to
+          
If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade.
Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page.
Repeat the upgrade with the most recent database
Test the that the new site is functional.  If so, change the upgraded site to respond to
                yourserver.net requests. If not, bring the original production site back up and return to the merge.
Prev Home  Next
Upgrading an OpenACS 5.0.0 or greater installation Up  Upgrading Platform components
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/upgrade-overview.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-overview.html,v
diff -u -r1.20.2.2 -r1.20.2.3
--- openacs-4/packages/acs-core-docs/www/upgrade-overview.html	22 Apr 2007 10:21:57 -0000	1.20.2.2
+++ openacs-4/packages/acs-core-docs/www/upgrade-overview.html	14 Jul 2007 12:34:48 -0000	1.20.2.3
@@ -1,7 +1,6 @@
-
-OverviewPrev Chapter�5.�Upgrading  Next
Overview
Starting with Version 4.5, all OpenACS core packages support
+Overview
Prev Chapter�5.�Upgrading  Next
Overview
Starting with Version 4.5, all OpenACS core packages support
     automatic upgrade.  That means that, if you have OpenACS 4.5
     or better, you should always be able to upgrade all of your core
     packages automatically.  If you haven't changed anything, no
     manual intervention should be required.  If you are running
-    OpenACS prior to 4.5, upgrading will require manual effort.
If all of these conditions are true:
Your OpenACS Core is 5.0.0 or later
You do not keep your OpenACS site in a local CVS repository
You do not have any custom code
then you can upgrade automatically using the automated installer in the OpenACS Package Manager (APM), and you can probably skip the rest of this chapter.  To upgrade directly from the OpenACS repository using the APM:
Browse to the Installer.
Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server.  After restarting the server again, the upgrade is complete.
Figure�5.1.�Upgrading with the APM
It's always a good idea to precede an upgrade attempt with a snapshot backup.
Table�5.1.�Assumptions in this section
name of OpenACS user $OPENACS_SERVICE_NAME
OpenACS server name $OPENACS_SERVICE_NAME
Root of OpenACS file tree /var/lib/aolserver/$OPENACS_SERVICE_NAME
Database backup directory /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup
Prev Home  Next
Chapter�5.�Upgrading Up  Upgrading 4.5 or higher to 4.6.3
docs@openacs.org
View comments on this page at openacs.org
+    OpenACS prior to 4.5, upgrading will require manual effort.
If all of these conditions are true:
Your OpenACS Core is 5.0.0 or later
You do not keep your OpenACS site in a local CVS repository
You do not have any custom code
then you can upgrade automatically using the automated installer in the OpenACS Package Manager (APM), and you can probably skip the rest of this chapter.  To upgrade directly from the OpenACS repository using the APM:
Browse to the Installer.
Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server.  After restarting the server again, the upgrade is complete.
Figure�5.1.�Upgrading with the APM

It's always a good idea to precede an upgrade attempt with a snapshot backup.
Table�5.1.�Assumptions in this section
name of OpenACS user $OPENACS_SERVICE_NAME
OpenACS server name $OPENACS_SERVICE_NAME
Root of OpenACS file tree /var/lib/aolserver/$OPENACS_SERVICE_NAME
Database backup directory /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup

Prev Home  Next
Chapter�5.�Upgrading Up  Upgrading 4.5 or higher to 4.6.3
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/upgrade-supporting.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-supporting.html,v
diff -u -r1.13.2.1 -r1.13.2.2
--- openacs-4/packages/acs-core-docs/www/upgrade-supporting.html	14 Jan 2007 04:20:11 -0000	1.13.2.1
+++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.html	14 Jul 2007 12:34:48 -0000	1.13.2.2
@@ -1,6 +1,5 @@
-
-Upgrading Platform componentsPrev Chapter�5.�Upgrading  Next
Upgrading Platform components
Upgrading OpenFTS from 0.2 to 0.3.2
OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine.  This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time.
Uninstall the old OpenFTS Engine from the $OPENACS_SERVICE_NAME database.
Browse to http://yourserver/openfts.
-            
Click Administration.
Click Drop OpenFTS Engine
Build and install the new OpenFTS driver and supporting tcl procedures.  (This section of shell code is not fully documented; please exercise care.)
cd /usr/local/src/
+Upgrading Platform componentsPrev Chapter�5.�Upgrading  Next
Upgrading Platform components
Upgrading OpenFTS from 0.2 to 0.3.2
OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine.  This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time.
Uninstall the old OpenFTS Engine from the $OPENACS_SERVICE_NAME database.
Browse to http://yourserver/openfts.
+            
Click Administration.
Click Drop OpenFTS Engine
Build and install the new OpenFTS driver and supporting tcl procedures.  (This section of shell code is not fully documented; please exercise care.)
cd /usr/local/src/
           tar xzf /var/tmp/Search-OpenFTS-tcl-0.3.2.tar.gz
           chown -R root.root Search-OpenFTS-tcl-0.3.2/
           cd Search-OpenFTS-tcl-0.3.2/
@@ -18,22 +17,22 @@
           cd tsearch/
           make
           make install
-          exit
In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.
[root root]# su - $OPENACS_SERVICE_NAME
-          [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql
+          exit
In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.
[root root]# su - $OPENACS_SERVICE_NAME
+          [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql
           CREATE
           CREATE
-          [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
+          [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
           BEGIN
           CREATE
           (~30 more lines)
-          [$OPENACS_SERVICE_NAME dev]$ exit
+          [$OPENACS_SERVICE_NAME dev]$ exit
           [root root]# 
           su - $OPENACS_SERVICE_NAME
 psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql
 psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql
 exit
OPTIONAL: Install the new OpenFTS Engine.�If you want to upgrade the OpenFTS Engine, do these
             steps.  (You must have already upgraded the OpenFTS driver to
-            0.3.2.)
Browse to http://yourserver/admin/site-map
On the openfts line, click on set parameters.
Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/
Click Set Parameters
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Browse to http://yourserver/openfts
Click Administration.
Click Initialize OpenFTS Engine
Upgrading from PostGreSQL 7.2 to 7.3
An OpenACS database created in PostGreSQL 7.2 will not
+            0.3.2.)
Browse to http://yourserver/admin/site-map
On the openfts line, click on set parameters.
Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/
Click Set Parameters
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Browse to http://yourserver/openfts
Click Administration.
Click Initialize OpenFTS Engine
Upgrading from PostGreSQL 7.2 to 7.3
An OpenACS database created in PostGreSQL 7.2 will not
       work correctly in PostGreSQL 7.3.  This is because 7.2 truncates
       function names to 31 characters, but 7.3 does not.  This does
       not cause problems in 7.2, because truncation occurs both at
@@ -43,12 +42,12 @@
       are not, and so they don't match.  Also some functions use
       casting commands that no longer work in 7.3 and these functions
       must be recreated.

-      To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3.  Then, dump the database, run the upgrade script /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump.  See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?.  Example:
Back up the database as per PostgreSQL.
Run the upgrade script on the backup file.
[root root]# su - $OPENACS_SERVICE_NAME
-          [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin
-          [$OPENACS_SERVICE_NAME bin]$ ./pg_7.2to7.3_upgrade_helper.pl \
+      To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3.  Then, dump the database, run the upgrade script /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump.  See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?.  Example:Back up the database as per PostgreSQL.Run the upgrade script on the backup file.[root root]# su - $OPENACS_SERVICE_NAME
+          [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin
+          [$OPENACS_SERVICE_NAME bin]$ ./pg_7.2to7.3_upgrade_helper.pl \
           ../database-backup/nightly.dmp \
           ../database-backup/upgrade-7.3.dmp \
-          /var/lib/aolserver/$OPENACS_SERVICE_NAME
+          /var/lib/aolserver/$OPENACS_SERVICE_NAME
           ==================================================================
           looking for function acs_object__check_object_ancest in oacs
           grep result: /var/lib/aolserver/aufrecht-dev/packages/acs-kernel/sql/postgresql/acs-objects-create.sql:create function acs_object__check_object_ancestors (integer,integer,integer)
@@ -57,13 +56,13 @@
 
           (many lines omitted)
           [$OPENACS_SERVICE_NAME bin]$
-          
Use perl to replace timestamp with timestamptz in the dump file.  See example perl code in step two in /contrib/misc/upgrade_4.6_to_5.0.sh
Create a new user for PostgreSQL 7.3.x, as per the
+          
Use perl to replace timestamp with timestamptz in the dump file.  See example perl code in step two in /contrib/misc/upgrade_4.6_to_5.0.sh
Create a new user for PostgreSQL 7.3.x, as per the
           Postgres installation guide. Keep in mind that your
           installation location is different, and your startup script
           (/etc/init.d/postgres73 should be named differently. You
           might even need to edit that file to make the paths
-          correct). You'll also need to add export
-          PGPORT=5434 to the .bashrc and/or
+          correct). You'll also need to add export
+          PGPORT=5434 to the .bashrc and/or
           .bash_profile for the postgres73 user.
           
Install PostgreSQL 7.3.x. Note that you PostgreSQL
           must listen on a different port in order to work
Index: openacs-4/packages/acs-core-docs/www/upgrade.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.html,v
diff -u -r1.24.2.1 -r1.24.2.2
--- openacs-4/packages/acs-core-docs/www/upgrade.html	14 Jan 2007 04:20:11 -0000	1.24.2.1
+++ openacs-4/packages/acs-core-docs/www/upgrade.html	14 Jul 2007 12:34:48 -0000	1.24.2.2
@@ -1,5 +1,4 @@
-
-Chapter�5.�Upgrading
Prev Part�II.�Administrator's Guide  Next
Chapter�5.�Upgrading
Table of Contents
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components
by Joel Aufrecht
+Chapter�5.�UpgradingPrev Part�II.�Administrator's Guide  Next
Chapter�5.�Upgrading
Table of Contents
Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components
by Joel Aufrecht
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
Prev Home  Next
How Do I? Up  Overview
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/uptime.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/uptime.html,v
diff -u -r1.8.2.1 -r1.8.2.2
--- openacs-4/packages/acs-core-docs/www/uptime.html	14 Jan 2007 04:20:11 -0000	1.8.2.1
+++ openacs-4/packages/acs-core-docs/www/uptime.html	14 Jul 2007 12:34:48 -0000	1.8.2.2
@@ -1,2 +1 @@
-
-External uptime validationPrev Chapter�6.�Production Environments  Next
External uptime validation
The OpenACS uptime site can monitor your site and send you an email whenever your site fails to respond.  If you test the url http://yourserver.test/SYSTEM/dbtest.tcl, you should get back the string success.
Prev Home  Next
Set up Log Analysis Reports Up  Diagnosing Performance Problems
docs@openacs.org
View comments on this page at openacs.org
+External uptime validationPrev Chapter�6.�Production Environments  Next
External uptime validation
The OpenACS uptime site can monitor your site and send you an email whenever your site fails to respond.  If you test the url http://yourserver.test/SYSTEM/dbtest.tcl, you should get back the string success.
Prev Home  Next
Set up Log Analysis Reports Up  Diagnosing Performance Problems
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/variables.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.html,v
diff -u -r1.23.2.2 -r1.23.2.3
--- openacs-4/packages/acs-core-docs/www/variables.html	22 Apr 2007 10:21:57 -0000	1.23.2.2
+++ openacs-4/packages/acs-core-docs/www/variables.html	14 Jul 2007 12:34:48 -0000	1.23.2.3
@@ -1,15 +1,14 @@
-
-VariablesPrev Chapter�12.�Engineering Standards  Next
Variables
Date and Time Variables
($Id$)
By joel@aufrecht.org
+VariablesPrev Chapter�12.�Engineering Standards  Next
Variables
Date and Time Variables
($Id$)
By joel@aufrecht.org
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
Starting with OpenACS 5.0 and the introduction of acs-lang,
     we recommend retrieving date/time information from the database in
-    ANSI format and then using lc_time_fmt to format it for display.
Example�12.1.�Getting datetime from the database ANSI-style
db_multirow -extend { mydate_pretty } {
+    ANSI format and then using lc_time_fmt to format it for display.
Example�12.1.�Getting datetime from the database ANSI-style
db_multirow -extend { mydate_pretty } {
     select to_char(mydate, 'YYYY-MM-DD HH24:MI:SS') as mydate_ansi,
           ...
     ...
 } {
     set mydate_ansi [lc_time_system_to_conn $mydate_ansi]
-    set mydate_pretty [lc_time_fmt $mydate_ansi "%x %X"]
+    set mydate_pretty [lc_time_fmt $mydate_ansi "%x %X"]
 }
-
Prev Home  Next
PL/SQL Standards Up  Automated Testing
docs@openacs.org
View comments on this page at openacs.org
+

Prev Home  Next
PL/SQL Standards Up  Automated Testing
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v
diff -u -r1.42.2.2 -r1.42.2.3
--- openacs-4/packages/acs-core-docs/www/win2k-installation.html	22 Apr 2007 10:21:57 -0000	1.42.2.2
+++ openacs-4/packages/acs-core-docs/www/win2k-installation.html	14 Jul 2007 12:34:48 -0000	1.42.2.3
@@ -1,18 +1,17 @@
-
-OpenACS Installation Guide for Windows2000Prev Chapter�3.�Complete Installation  Next
OpenACS Installation Guide for Windows2000
by Matthew Burke and Curtis Galloway
+OpenACS Installation Guide for Windows2000Prev Chapter�3.�Complete Installation  Next
OpenACS Installation Guide for Windows2000
by Matthew Burke and Curtis Galloway
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
-        
NOTE: These instructions were
+        
NOTE: These instructions were
 	valid for ACS v4, but have not been tested with OpenACS and the ArsDigita binary 
 	distributions are no longer available.	
     Currently
-    (10/2003), the best option to get OpenACS 5.3.1 running on Windows
+    (10/2003), the best option to get OpenACS 5.3.2 running on Windows
     is to use VMware and John
     Sequeira's Oasis VM
     distribution
   
Source: http://openacs.org/projects/openacs/download
Bug reports: http://openacs.org/bugtracker/openacs
Philosophy: http://photo.net/wtr/thebook/community
       (the community chapter of Philip and Alex's Guide to Web
-      Publishing)
Technical background: http://photo.net/wtr/thebook/Overview

+      Publishing)
Technical background: http://photo.net/wtr/thebook/
Overview

     With the recent release of a win32 version of AOLserver, it is now
     possible to run the OpenACS on Windows2000 and Windows98. This document
     explains the steps necessary to get the OpenACS installed and running on your
@@ -24,25 +23,25 @@
     for the Win32 platform, which contains patches for several problems we
     have come across in the default AOLserver binary distribution. See the ArsDigita AOLserver 3 distribution page for
     details.
You can download the binary distribution from the ArsDigita download page
-    under "ArsDigita AOLserver 3 Binary Distribution for Win32."
+    under "ArsDigita AOLserver 3 Binary Distribution for Win32."
     Please read the release notes in the distribution for configuration notes
-    specific to the version you are downloading.
Prerequisites
Windows 2000 or Windows 98
WinZip or any tool that can
+    specific to the version you are downloading.
Prerequisites
Windows 2000 or Windows 98
WinZip or any tool that can
       extract gzipped/tarred archives.
zsh (free;
       included in the binary distribution). If this link is broken try http://www.zsh.org.
Oracle 8 relational database
       management system
AOLserver (free)

       Oracle driver for AOLserver (free)
    It is helpful if you have Oracle interMedia Text for full-text searches.
     We're also trying to make our system work with the PLS System,
     available free from http://www.pls.com. 
-
Although the zsh shell is the only command-line tool
+
Although the zsh shell is the only command-line tool
     required to install the OpenACS, if you are a UNIX person used to typing
-    ls instead of dir you'll get along much
+    ls instead of dir you'll get along much
     better with the Cygwin toolkit from RedHat (available at http://sourceware.cygnus.com/cygwin).
     This is a development library and set of tools that gives you a very
     UNIX-like environment under Windows. In particular, it includes
-    bash, gzip and tar, which you can
-    use to perform the OpenACS installation instead of WinZip and zsh.
Your Oracle installation

-    When you install Oracle, a good rule of thumb is "every default
-    setting is wrong." We will not discuss Oracle configuration here
+    bash, gzip and tar, which you can
+    use to perform the OpenACS installation instead of WinZip and zsh.
Your Oracle installation

+    When you install Oracle, a good rule of thumb is "every default
+    setting is wrong." We will not discuss Oracle configuration here
     except to mention that the OpenACS requires Oracle's NLS_DATE_FORMAT
     parameter be set to 'YYYY-MM-DD'. Fixing this depends on whether
     Oracle Administration Assistant for Windows NT (yes,
@@ -52,202 +51,202 @@
       select the Oracle Home for the database you wish to use.
Bring up its properties dialog and add a parameter NLS_DATE_FORMAT
       with value 'YYYY-MM-DD' (without the
       quotes)
Verify the date format by logging into the database using SQL Plus
-      and run the following query: select sysdate from
-      dual;
Otherwise you will need to perform a little registry surgery as
-    follows:
Run regedit and navigate down the registry keys to
-      HKEY_LOCAL_MACHINE\Software\ORACLE.

-        Choose the appropriate subtree; this will be HOME0 if
+      and run the following query: select sysdate from
+      dual;
Otherwise you will need to perform a little registry surgery as
+    follows:
Run regedit and navigate down the registry keys to
+      HKEY_LOCAL_MACHINE\Software\ORACLE.

+        Choose the appropriate subtree; this will be HOME0 if
         you only have on einstallation of Oracle. 
 
         

           If you are an Oracle achiever and have more than one Oracle
-          installation on your machine, you will see HOME0, HOME1,
-          HOME2, etc. Choose the subtree that corresponds to the
+          installation on your machine, you will see HOME0, HOME1,
+          HOME2, etc. Choose the subtree that corresponds to the
           Oracle installtion you wish to use with the OpenACS.
         

-      
If the NLS_DATE_FORMAT key is already present,
+      
If the NLS_DATE_FORMAT key is already present,
       double-click on its value and change it to 'YYYY-MM-DD' 
       (without the quotes). If the key does not
-      exist, choose Edit->New->String Value from the menu
-      and type NLS_DATE_FORMAT for the name of the new value to
+      exist, choose Edit->New->String Value from the menu
+      and type NLS_DATE_FORMAT for the name of the new value to
       create it. Then double-click on the empty value to change it.
Verify the date format by logging into the database using SQL Plus
-      and run the following query: select sysdate from
-      dual;
For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips
-    or search the OpenACS forums. One other note: the "nuke a user" admin page and
-    Intermedia won't run unless you set open_cursors = 500
-    for your database.
The ArsDigita binary installation

-    Extract the ArsDigita AOLserver distribution onto the C:
-    drive into the default aol30 directory. You can install it
+      and run the following query: select sysdate from
+      dual;
For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips
+    or search the OpenACS forums. One other note: the "nuke a user" admin page and
+    Intermedia won't run unless you set open_cursors = 500
+    for your database.
The ArsDigita binary installation

+    Extract the ArsDigita AOLserver distribution onto the C:
+    drive into the default aol30 directory. You can install it
     on any drive, but it will make your life easier if you keep the AOLserver
     binary and your OpenACS instance on the same drive. For the rest of these
-    instructions, we'll assume that you used drive C:. 
-
Untar the OpenACS

-    We recommend rooting webserver content in c:\web. Since most
+    instructions, we'll assume that you used drive C:. 
+
Untar the OpenACS

+    We recommend rooting webserver content in c:\web. Since most
     servers these days are expected to run multiple services from multiple IP
-    addresses, each server gets a subdirectory from c:\web. For
-    example, http://scorecard.org would be rooted at
-    c:\web\scorecard on one of our machines and if
-    http://jobdirect.com were on the same box then it would be
-    at c:\web\jobdirect. 
+    addresses, each server gets a subdirectory from c:\web. For
+    example, http://scorecard.org would be rooted at
+    c:\web\scorecard on one of our machines and if
+    http://jobdirect.com were on the same box then it would be
+    at c:\web\jobdirect. 
 
For the sake of argument, we're going to assume that your service
-    is called "yourdomain", is going to be at
-    http://yourdomain.com and is rooted at
-    c:\web\yourdomain in the Windows 2000 file system. Note that
+    is called "yourdomain", is going to be at
+    http://yourdomain.com and is rooted at
+    c:\web\yourdomain in the Windows 2000 file system. Note that
     you'll find our definitions files starting out with
-    "yourdomain.com".
download the OpenACS (see above) into
-      c:\temp\acs.tar.gz
use WinZip (or equivalent) to extract the files to
-      c:\web\yourdomain
   
- You'll now find that c:\web\yourdomain\www contains the
-    document root and c:\web\yourdomain\tcl contains Tcl scripts
+    "yourdomain.com".
download the OpenACS (see above) into
+      c:\temp\acs.tar.gz
use WinZip (or equivalent) to extract the files to
+      c:\web\yourdomain
   
+ You'll now find that c:\web\yourdomain\www contains the
+    document root and c:\web\yourdomain\tcl contains Tcl scripts
     that are loaded when the AOLserver starts up. 
-
Feeding Oracle the Data Model

+
Feeding Oracle the Data Model

     The entire server will behave in an unhappy manner if it connects to
     Oracle and finds that, for example, the users table does not exist. Thus
     you need to connect to Oracle as whatever user the AOLserver will connect
     as, and feed Oracle the table definitions. 
 

-        load the states, country_codes and
-        counties tables using the load-geo-tables
-        shell script in the c:\web\yourdomain\www\install
+        load the states, country_codes and
+        counties tables using the load-geo-tables
+        shell script in the c:\web\yourdomain\www\install
         directory. You will need to open a console window and run 
 zsh load-geo-tables foo/foopassword
 

-        You most likely will see a slew of "Commit point reached . . .
-        " messages. This does not indicate a problem. 
+        You most likely will see a slew of "Commit point reached . . .
+        " messages. This does not indicate a problem. 
 
         
       

-        cd to c:\web\yourdomain\www\doc\sql and feed Oracle the
+        cd to c:\web\yourdomain\www\doc\sql and feed Oracle the
         .sql files that you find there. There is a meta-loader file,
         load-data-model.sql, that includes the other files in the proper
         order. To use it, open a console window and run 
 
 sqlplus foo/foopassword < load-data-model.sql
 

         If you have interMedia installed, while still in
-        c:\web\yourdomain\www\doc\sql, run 
+        c:\web\yourdomain\www\doc\sql, run 
 
 zsh load-site-wide-search foo foopassword ctxsys-password
 

-        Note that there's no slash between foo and
-        foopassword here. The third argument,
-        ctxsys-password, is the password for interMedia
+        Note that there's no slash between foo and
+        foopassword here. The third argument,
+        ctxsys-password, is the password for interMedia
         Text's special ctxsys user.
-      
Configuring AOLserver
You will need two configuration files. The first is a Tcl file with
+      
Configuring AOLserver
You will need two configuration files. The first is a Tcl file with
     configuration information for AOLserver. This should be called
-    yourdomain and should be located in
-    c:\aolserve3_0. The second is an .ini file that configures
+    yourdomain and should be located in
+    c:\aolserve3_0. The second is an .ini file that configures
     the OpenACS and is discussed below. Note that pathnames in
-    yourdomain must use forward slashes rather than the Windows
-    back slashes. This is also true for the .ini file.
The following items must be defined in yourdomain:
three database pools: main, subquery, and log. They must be named
-      as such. The default pool will be "main".
the auxconfig directory which contains the .ini file:
-      c:\web\yourdomain\parameters
the pageroot: c:\web\yourdomain\www
the directory containing the TclLibrary:
-      c:\web\yourdomain\tcl

+    yourdomain must use forward slashes rather than the Windows
+    back slashes. This is also true for the .ini file.
The following items must be defined in yourdomain:
three database pools: main, subquery, and log. They must be named
+      as such. The default pool will be "main".
the auxconfig directory which contains the .ini file:
+      c:\web\yourdomain\parameters
the pageroot: c:\web\yourdomain\www
the directory containing the TclLibrary:
+      c:\web\yourdomain\tcl

     You can use our template file as a starting
     point (you'll need to save this file with a rather than .txt
     extension). 
-
Configuring OpenACS itself

+
Configuring OpenACS itself

     If you want a system that works, go to
-    c:\web\yourdomain\parameters and copy ad.ini to
-    yourdomain.ini (or any other name different from
-    ad.ini). You don't actually have to delete
-    ad.ini. 
-
Each section of yourdomain.ini has a hardcoded
-    "yourservername" in the name (e.g.
-    [ns/server/yourservername/acs]). This means that the OpenACS
+    c:\web\yourdomain\parameters and copy ad.ini to
+    yourdomain.ini (or any other name different from
+    ad.ini). You don't actually have to delete
+    ad.ini. 
+
Each section of yourdomain.ini has a hardcoded
+    "yourservername" in the name (e.g.
+    [ns/server/yourservername/acs]). This means that the OpenACS
     will ignore your configuration settings unless your AOLserver name
-    happens to be "yourservername". Therefore you must go through
-    yourdomain.ini and change "yourservername" to
+    happens to be "yourservername". Therefore you must go through
+    yourdomain.ini and change "yourservername" to
     whatever you're calling this particular AOLserver (look at the
-    server name in the nsd file for a reference).
Unless you want pages that advertise a community called
-    "Yourdomain Network" owned by
-    "webmaster@yourdomain.com", you'll probably want to edit
-    the text of yourdomain.ini to change system-wide parameters.
+    server name in the nsd file for a reference).
Unless you want pages that advertise a community called
+    "Yourdomain Network" owned by
+    "webmaster@yourdomain.com", you'll probably want to edit
+    the text of yourdomain.ini to change system-wide parameters.
     If you want to see how some of these are used, a good place to look is
-    c:\web\yourdomain\tcl\ad-defs. The Tcl function,
-    ad_parameter, is used to grab parameter values from the .ini
-    file.
Starting the Service

+    c:\web\yourdomain\tcl\ad-defs. The Tcl function,
+    ad_parameter, is used to grab parameter values from the .ini
+    file.
Starting the Service

     Now you're ready to start things up. Before installing as a Windows
     service, you might want to test the setup for configuration errors. Open
-    up a console window and go to c:\aol30. Then run 
+    up a console window and go to c:\aol30. Then run 
 
 bin\nsd -ft yourdomain.tcl
 
 This will print all the AOLserver messages to the console so you can see
     them. 
 
Try to connect to your new server with a web browser. If you see the
-    message "Error in serving group pages", you probably forgot to
-    copy the ad.ini file in c:\web\yourdomain\parameters If
+    message "Error in serving group pages", you probably forgot to
+    copy the ad.ini file in c:\web\yourdomain\parameters If
     everything seems ok, you can kill the server with Control-c and then
     issue the following command to install as a Windows service:
 bin\nsd -I -s yourdomain -t yourdomain.tcl
 
 You can now configure error recovery and other Windows aspects of the
     service from the Services control panel. If you make further changes to
-    yourdomain or yourdomain.ini you should stop
+    yourdomain or yourdomain.ini you should stop
     and start the service from the Services control panel. 
-
Configuring Permissions

+
Configuring Permissions

     Now, you need to protect the proper administration directories of the
     OpenACS. You decide the policy although we recommend requiring the admin
     directories be accessible only via an SSL connection. Here are the
     directories to consider protecting: 
 
/doc (or at least /doc/sql/ since some AOLserver configurations
       will allow a user to execute SQL files)
/admin
any private admin dirs for a module you might have written that are
-      not underneath the /admin directory
Adding Yourself as a User and Making Yourself a Sysadmin

+      not underneath the /admin directory
Adding Yourself as a User and Making Yourself a Sysadmin

     OpenACS will define two users: system and
     anonymous. It will also define a user group of system administrators.
     You'll want to add yourself as a user (at /register/ ) and then add
     yourself as as member of the site-wide administration group. Start by
     logging out as yourself and logging in as the system user (email of
-    "system"). Change the system user's password. Visit the
-    https://yourservername.com/admin/ug/ directory and add your
+    "system"). Change the system user's password. Visit the
+    https://yourservername.com/admin/ug/ directory and add your
     personal user as a site-wide administrator. Now you're bootstrapped! 
 
If you do not know what the system user's password is connect to
     Oracle using SQL Plus and run the following query:
 select password from users where last_name = 'system';
-
Closing Down Access

-    The OpenACS ships with a user named "anonymous" (email
-    "anonymous") to serve as a content owner. If you're
+
Closing Down Access

+    The OpenACS ships with a user named "anonymous" (email
+    "anonymous") to serve as a content owner. If you're
     operating a restricted-access site, make sure to change the anonymous
     user's password. In recent versions of the OpenACS you cannot log into
-    "anonymous" because the account does not have a valid user
+    "anonymous" because the account does not have a valid user
     state. Log in as a sysadmin and change the anonymous user's password
-    from https://yourservername/admin/users. You should read the
+    from https://yourservername/admin/users. You should read the
     documentation for user registration and
     access control and decide what the appropriate user state is for
     anonymous on your site. 
-
Where to Find What

+
Where to Find What

     A few pointers: 
 
the /register directory contains the login and registration
       scripts. You can easily redirect someone to /register/index to have
       them login or register.
the /pvt directory is for user-specific pages. They can only be
-      accessed by people who have logged in.
Making sure that it works

+      accessed by people who have logged in.
Making sure that it works

     Run the acceptance tests in /doc/acceptance-test 
-
Running Multiple Instances of the OpenACS

+
Running Multiple Instances of the OpenACS

     You can run multiple instances of the OpenACS on a physical machine but they
     must each be set up as a separate Windows service. Each instance of the
     OpenACS must have its own:
 
Oracle tablespace and a user account with the appropriate
       permissions on that tablespace. Each of these tablespaces must have the
       OpenACS data model loaded.
file with the appropriate settings including server name,
       auxconfig, ipaddress, and port.
Copy of the acs files in an appropriate directory under
-      c:\web.
    Suppose you wish to run two services: lintcollectors.com and
-    iguanasdirect.com. You would need the following: 
-
an Oracle tablespace, lintcollectors with a user
-      lintcollectors and password secretlint
an Oracle tablespace, iguanasdirect with a user
-      iguanasdirect and password secretiguanas
 For each of these tablespaces/users you would load the OpenACS data model as
-    described above. Then in c:\aolserver3_0
-    create files for each service, i.e. lintcollectors and
-    iguanasdirect. These files would point to their respective
-    pageroots, c:\web\lintcollectors\www and
-    c:\web\iguanasdirect\www; their respective auxconfigdirs,
-    c:\web\lintcollectors\parameters and
-    c:\web\iguanasdirect\parameters; etc. In the respective
-    auxconfigdirs would be the files lintcollectors.ini and
-    iguanasdirect.ini. 
-
Now open a console window and go to c:\aol30. You'll
+      c:\web.
    Suppose you wish to run two services: lintcollectors.com and
+    iguanasdirect.com. You would need the following: 
+
an Oracle tablespace, lintcollectors with a user
+      lintcollectors and password secretlint
an Oracle tablespace, iguanasdirect with a user
+      iguanasdirect and password secretiguanas
 For each of these tablespaces/users you would load the OpenACS data model as
+    described above. Then in c:\aolserver3_0
+    create files for each service, i.e. lintcollectors and
+    iguanasdirect. These files would point to their respective
+    pageroots, c:\web\lintcollectors\www and
+    c:\web\iguanasdirect\www; their respective auxconfigdirs,
+    c:\web\lintcollectors\parameters and
+    c:\web\iguanasdirect\parameters; etc. In the respective
+    auxconfigdirs would be the files lintcollectors.ini and
+    iguanasdirect.ini. 
+
Now open a console window and go to c:\aol30. You'll
     start up the two services as follows:
 bin\nsd -I -s lintcollectors -t lintcollectors.tcl
 bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl
 
 In the services control panel you should see two services:
-    AOLserver-lintcollectors and
-    AOLserver-iguanasdirect. 
-    
($Id$)
Prev Home  Next
Install OpenACS 5.3.1 Up  OpenACS Installation Guide for Mac OS X
docs@openacs.org
View comments on this page at openacs.org
+    AOLserver-lintcollectors and
+    AOLserver-iguanasdirect. 
+    
($Id$)
Prev Home  Next
Install OpenACS 5.3.2 Up  OpenACS Installation Guide for Mac OS X
docs@openacs.org
View comments on this page at openacs.org

Feature	Status	Description
New API
EXT-AUTH-01	A	Extend Authentication/Acct Status API
EXT-AUTH-03	A	Account Creation API
EXT-AUTH-05	A	Password Management API
EXT-AUTH-30	A	Authority Management API

Feature	Status	Description
Login
EXT-AUTH-04	A	Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38	A	ad_form complain feature
EXT-AUTH-19	A	Rewrite password recovery to use API
EXT-AUTH-21	A	Rewrite email verification with API
EXT-AUTH-28	A	Username is email switch

Feature	Status	Description
New API
EXT-AUTH-01	A	Extend Authentication/Acct Status API
EXT-AUTH-03	A	Account Creation API
EXT-AUTH-05	A	Password Management API
EXT-AUTH-30	A	Authority Management API

Feature	Status	Description
Login
EXT-AUTH-04	A	Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38	A	ad_form complain feature
EXT-AUTH-19	A	Rewrite password recovery to use API
EXT-AUTH-21	A	Rewrite email verification with API
EXT-AUTH-28	A	Username is email switch

Feature	Status	Description
create service contract
EXT-AUTH-16	A	Create service contract for Authentication
EXT-AUTH-17	A	Create service contract for Acct. Creation
EXT-AUTH-29	A	Create service contract for Passwd Management

Constraint type	Abbreviation
references (foreign key)	fk
unique	un
primary key	pk
check	ck
not null	nn

Feature	Status	Description
Configuration
EXT-AUTH-07	A	Admin pages to control Ext-Auth parameters

Feature	Status	Description
Synchronizing and linking users
EXT-AUTH-28	A	Create service contract for Batch Sync.
EXT-AUTH-38	A	Batch User Synchronization API
EXT-AUTH-38	A	IMS Synchronization driver
EXT-AUTH-08	A	Automation of batch Synchronization
EXT-AUTH-15	B	On-demand syncronization

Feature	Status	Description
EXT-AUTH-32
EXT-AUTH-32	A	Parameters for Service Contract Implementation
EXT-AUTH-35	A	Make the Authentication API a service contract

Feature	Status	Description
EXT-AUTH-36
EXT-AUTH-36	A	Authenticate against multiple servers

Feature	Status	Description
Implement specific drivers
EXT-AUTH-09	A	Create Auth. drivers for Local Authority
EXT-AUTH-10	A	Create Acct. Creation driver for Local Authority
EXT-AUTH-11	A	Create Auth. driver for PAM
EXT-AUTH-12	X	Create Acct. Creation driver for PAM - this - functionality is explicitly excluded from PAM
EXT-AUTH-13	A	Create Acct. Creation driver for LDAP
EXT-AUTH-14	A	Create Auth. driver for LDAP

Document Revision #	Action Taken, Notes	When?	By Whom?
0.3	Edited further, incorporated feedback from Michael Yoon	9/05/2000	Kai Wu
0.2	Edited	8/22/2000	Kai Wu
0.1	Creation	8/21/2000	Josh Finkler, Audrey McLoghlin

Administrator's Guide

Part�II.�Administrator's Guide

For OpenACS Package Developers

Part�III.�For OpenACS Package Developers

For OpenACS Platform Developers

Part�IV.�For OpenACS Platform Developers

Install Analog web file analyzer

Install Analog web file analyzer

Set up Log Analysis Reports

Set up Log Analysis Reports

Install AOLserver 3.3oacs1

Install AOLserver 3.3oacs1

Install AOLserver 4

Install AOLserver 4

Package Manager Design

Package Manager Design

Essentials

Essentials

Introduction

Introduction

Historical Considerations

Historical Considerations

Competitive Analysis

Competitive Analysis

Design Tradeoffs

Design Tradeoffs

API

API

Data Model Discussion

Data Model Discussion

User Interface

User Interface

Configuration/Parameters

Configuration/Parameters

Future Improvements/Areas of Likely Change

Future Improvements/Areas of Likely Change

Authors

Authors

Revision History

Revision History

Package Manager Requirements

Package Manager Requirements

Introduction

Introduction

Vision Statement

Vision Statement

System Overview

System Overview

Use-cases and User-scenarios

Use-cases and User-scenarios

Related Links

Requirements: Data Model

Related Links

Requirements: Data Model

Requirements: API

Requirements: API

Requirements: Security

Requirements: Security

Requirements: The User Interface

Requirements: The User Interface

Requirements: The Developer's Interface

Requirements: The Developer's Interface

Requirements: The Site-Wide Administrator's Interface

Requirements: The Site-Wide Administrator's Interface

Requirements: The Sub-Site Administrator's Interface

Requirements: The Sub-Site Administrator's Interface

Implementation notes

Implementation notes

Revision History

Revision History

Automated Backup

Automated Backup

Automated Testing

Automated Testing

Chapter�8.�Backup and Recovery

Chapter�8.�Backup and Recovery

Using CVS for backup-recovery

Using CVS for backup-recovery

Bootstrapping OpenACS

Bootstrapping OpenACS

CVS Guidelines -
Prev Chapter�12.�Engineering Standards Next
- CVS Guidelines -
($Id$)
+

+ Each OpenACS package (i.e., directory in `openacs-4/packages/`) is also aliased as a module of the same name. +

+cvs tag -b oacs-5-1
See the section called “How to package and release an OpenACS Package”

The Bell Tolls for `set_variables_after_query`

The Bell Tolls for `set_variables_after_query`